javax.microedition.m3d
Class Texture2D

java.lang.Object
  |
  +--javax.microedition.m3d.Object3D
        |
        +--javax.microedition.m3d.Texture2D

public class Texture2D

extends Object3D

An Appearance component encapsulating a two-dimensional texture image and a set of attributes specifying how the image is to be applied on submeshes. The attributes include wrapping, filtering, blending, and texture coordinate transformation.

Texture image data

The texture image is stored as a reference to an Image2D. The image may be in any of the formats defined in Image2D, with or without a palette. The width and height of the image must be positive powers of two, but they need not be equal. The maximum allowed size for a texture image is specific to each implementation, and it can be queried with Graphics3D.getProperties().

If the referenced Image2D is modified by the application (by rendering into it), or a new Image2D is bound as the texture image, the modifications are immediately reflected in the host Texture2D. Be aware, however, that changing or updating a texture image may trigger time-consuming operations, such as mipmap level image generation. Note that mipmap level images are always generated automatically from the base level image; it is currently not possible for the application to supply them explicitly.

Texture filtering

There are two independent components in the texture filtering mode: filtering between mipmap levels and filtering within a mipmap level. There are three choices for level filtering and two choices for image filtering, yielding the six combinations listed in the table below.

Level filter	Image filter	Description	OpenGL equivalent
BASE_LEVEL	NEAREST	Point sampling within the base level	NEAREST
BASE_LEVEL	LINEAR	Bilinear filtering within the base level	LINEAR
NEAREST	NEAREST	Point sampling within the nearest mipmap level	NEAREST_MIPMAP_NEAREST
NEAREST	LINEAR	Bilinear filtering within the nearest mipmap level	LINEAR_MIPMAP_NEAREST
LINEAR	NEAREST	Point sampling within two nearest mipmap levels	NEAREST_MIPMAP_LINEAR
LINEAR	LINEAR	Bilinear filtering within two nearest mipmap levels (trilinear filtering)	LINEAR_MIPMAP_LINEAR

Only the first combination (point sampling within the base level) must be supported by all implementations. Any of the other five options may be silently ignored.

Texture transformation

The texture transformation is applied to texture coordinates prior to texture sampling, and the transformed S and T coordinates are used to fetch the actual texel value(s) as specified above.

The texture coordinates S and T are defined such that S increases from left to right in the texture image, and T increases from top to bottom. Note that the T coordinate is reversed with respect to its orientation in OpenGL.

Texture blending

The texture blending mode specifies how to combine the filtered texture color with the incoming fragment color in a texturing unit. This is equivalent to the texture environment mode in OpenGL.

The incoming fragment color C_f = (R_f, G_f, B_f) and alpha A_f for each texture unit are the results of texture application in the previous texture unit, or for texture unit 0, the interpolated vertex color. Similarly, the texture values C_t and A_t are the results of texture sampling and filtering as specified above. For luminance textures, the filtered luminance value L_t is converted to an RGB color as C_t = (L_t, L_t, L_t). In the BLEND mode, the texture blend color C_c, set by setTexBlendColor, is also used.

The input values are combined to output values C_v and A_v depending on the source texture format and the current texture blend mode as shown in the tables below.

Texture format	REPLACE	MODULATE	DECAL	BLEND	ADD
ALPHA	Cv = Cf Av = At	Cv = Cf Av = Af At	undefined	Cv = Cf Av = At	Cv = Cf Av = Af At
LUMINANCE	Cv = Ct Av = Af	Cv = Cf Ct Av = Af	undefined	Cv = Cf (1 - Ct) + Cc Ct Av = Af	Cv = Cf + Ct Av = Af
LUMINANCE_ALPHA	Cv = Ct Av = At	Cv = Cf Ct Av = Af At	undefined	Cv = Cf (1 - Ct) + Cc Ct Av = Af At	Cv = Cf + Ct Av = Af At
RGB	Cv = Ct Av = Af	Cv = Cf Ct Av = Af	Cv = Ct Av = Af	Cv = Cf (1 - Ct) + Cc Ct Av = Af	Cv = Cf + Ct Av = Af
RGBA	Cv = Ct Av = At	Cv = Cf Ct Av = Af At	Cv = Cf (1 - At) + Ct At Av = Af	Cv = Cf (1 - Ct) + Cc Ct Av = Af At	Cv = Cf + Ct Av = Af At

Implementation guidelines

Texturing is done according to the OpenGL 1.3 specification, section 3.8, with the following exceptions:

• 1D, 3D, and cube texture maps are not supported;
• texture borders and the border color are not supported;
• minification and magnification filters cannot be specified separately;
• mipmap level images are generated automatically by the implementation;
• LOD parameters for mipmap level selection are implementation defined;
• The orientation of the T texture coordinate is reversed (as stated above);
• The COMBINE texture environment mode is not supported;
• The INTENSITY texture image format is not supported;
• The secondary color is not supported.

Texture filtering modes, other than point sampling of the base level image, are rendering quality hints that may be ignored by the implementation. However, if they are implemented, the implementation must be according to the OpenGL 1.3 specification.

See Also:

Binary format

Field Summary

static int	FILTER_BASE_LEVEL A level filtering parameter to setFiltering that selects the base level image, even if mipmap levels exist.
static int	FILTER_LINEAR A parameter to setFiltering that selects linear filtering.
static int	FILTER_NEAREST A parameter to setFiltering that selects nearest neighbor filtering.
static int	FUNC_ADD A parameter to setBlending, specifying that the texel color is to be added to the fragment color.
static int	FUNC_BLEND A parameter to setBlending, specifying that the texture blend color is to be blended into the fragment color in proportion to the texel RGB values.
static int	FUNC_DECAL A parameter to setBlending, specifying that the texel color is to be blended into the fragment color in proportion to the texel alpha.
static int	FUNC_MODULATE A parameter to setBlending, specifying that the texel color and/or alpha are to be multiplied with the fragment color and alpha.
static int	FUNC_REPLACE A parameter to setBlending, specifying that the texel color and/or alpha are to replace the fragment color and alpha.
static int	WRAP_CLAMP A parameter to setWrapping, specifying that the texture image is to be repeated only once.
static int	WRAP_REPEAT A parameter to setWrapping, specifying that the texture image is to be repeated indefinitely.

Fields inherited from class javax.microedition.m3d.Object3D

userObject

Constructor Summary

Texture2D(Image2D image)
Constructs a new texture object with the given image, setting the texture attributes to their default values.

Method Summary

int	getBlendColor() Returns the current texture blend color for this Texture2D.
int	getBlending() Returns the current texture blend mode for this Texture2D.
Image2D	getImage() Retrieves the current base level (full size) texture image.
void	getTransform(Transform transform) Returns the current texture transformation for this Texture2D.
int	getWrappingS() Returns the current texture wrapping mode for the S texture coordinate.
int	getWrappingT() Returns the current texture wrapping mode for the T texture coordinate.
void	setBlendColor(int RGB) Sets the texture blend color for this Texture2D.
void	setBlending(int func) Selects the texture blend mode, or blend function, for this Texture2D.
void	setFiltering(int levelFilter, int imageFilter) Selects the filtering mode for this Texture2D.
void	setImage(Image2D image) Sets the given Image2D as the texture image of this Texture2D.
void	setTransform(Transform transform) Sets the texture coordinate transformation to use for this Texture2D by copying in the given Transform.
void	setWrapping(int wrapS, int wrapT) Sets the wrapping mode for the S and T texture coordinates.

Methods inherited from class javax.microedition.m3d.Object3D

addAnimationTrack, animate, clone, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, removeAnimationTrack, setUserID

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FUNC_REPLACE

public static final int FUNC_REPLACE

A parameter to setBlending, specifying that the texel color and/or alpha are to replace the fragment color and alpha.

See Also:

Constant Field Values

FUNC_MODULATE

public static final int FUNC_MODULATE

A parameter to setBlending, specifying that the texel color and/or alpha are to be multiplied with the fragment color and alpha.

See Also:

Constant Field Values

FUNC_BLEND

public static final int FUNC_BLEND

A parameter to setBlending, specifying that the texture blend color is to be blended into the fragment color in proportion to the texel RGB values. The texel alpha is to be multiplied with the fragment alpha.

See Also:

Constant Field Values

FUNC_DECAL

public static final int FUNC_DECAL

A parameter to setBlending, specifying that the texel color is to be blended into the fragment color in proportion to the texel alpha.

See Also:

Constant Field Values

FUNC_ADD

public static final int FUNC_ADD

A parameter to setBlending, specifying that the texel color is to be added to the fragment color. The texel alpha is to be multiplied with the fragment alpha.

See Also:

Constant Field Values

WRAP_REPEAT

public static final int WRAP_REPEAT

A parameter to setWrapping, specifying that the texture image is to be repeated indefinitely. This can be specified independently for the S and T texture coordinates. Formally, repeating the image means that the integer part of the texture coordinate is ignored and only the fractional part is used. This is equivalent to the REPEAT wrap mode in OpenGL.

See Also:

Constant Field Values

WRAP_CLAMP

public static final int WRAP_CLAMP

A parameter to setWrapping, specifying that the texture image is to be repeated only once. This can be specified independently for the S and T texture coordinates. Formally, clamping means that the texture coordinate value is clamped to the range [0,1]. This is equivalent to the CLAMP_TO_EDGE wrap mode in OpenGL.

See Also:

Constant Field Values

FILTER_BASE_LEVEL

public static final int FILTER_BASE_LEVEL

A level filtering parameter to setFiltering that selects the base level image, even if mipmap levels exist. This is not applicable as the imageFilter parameter.

See Also:

Constant Field Values

FILTER_NEAREST

public static final int FILTER_NEAREST

A parameter to setFiltering that selects nearest neighbor filtering. As a level filter parameter, it specifies that the closest mipmap level should be selected. As an image filter parameter, it specifies that the texel that is nearest to (s, t) in Manhattan distance should be selected.

See Also:

Constant Field Values

FILTER_LINEAR

public static final int FILTER_LINEAR

A parameter to setFiltering that selects linear filtering. As a level filter parameter, it specifies that a weighted average of the two closest mipmap levels should be selected. As an image filter parameter, it specifies that a weighted average of the four texels that are nearest to (s, t) in Manhattan distance should be selected.

See Also:

Constant Field Values

Constructor Detail

Texture2D

public Texture2D(Image2D image)

Constructs a new texture object with the given image, setting the texture attributes to their default values. The default values for the wrapping, filtering, blending, and transformation attributes are as follows:

wrapping S : WRAP_REPEAT
wrapping T : WRAP_REPEAT
level filter : FILTER_BASE_LEVEL
image filter : FILTER_NEAREST
blending mode : FUNC_MODULATE
blend color : 0x00000000 (transparent black)
transform : identity

Parameters:

image - an Image2D object to set as the base level texture image

Throws:

java.lang.IllegalArgumentException - if the width or height of image is not a positive power of two (1, 2, 4, 8, 16, etc.)

java.lang.IllegalArgumentException - if the width or height of image exceeds the implementation defined maximum

Method Detail

setImage

public void setImage(Image2D image)

Sets the given Image2D as the texture image of this Texture2D. Mipmap level images are generated automatically from the given Image2D, if and when necessary.

Parameters:

image - an Image2D object to set as the base level texture image

Throws:

java.lang.IllegalArgumentException - if the width or height of image is not a positive power of two (1, 2, 4, 8, 16, etc.)

java.lang.IllegalArgumentException - if the width or height of image exceeds the implementation defined maximum

See Also:

getImage

getImage

public Image2D getImage()

Retrieves the current base level (full size) texture image.

Returns:

the current base level texture image

See Also:

setImage

setFiltering

public void setFiltering(int levelFilter,
                         int imageFilter)

Selects the filtering mode for this Texture2D. The available filtering modes are defined in the class description. Note that this setting is only a hint - implementations may ignore it and choose a filtering method at their own discretion.

Parameters:

levelFilter - filtering between mipmap levels

imageFilter - filtering within a mipmap level

Throws:

java.lang.IllegalArgumentException - if levelFilter is not one of FILTER_BASE_LEVEL, FILTER_NEAREST, FILTER_LINEAR

java.lang.IllegalArgumentException - if imageFilter is not one of FILTER_NEAREST, FILTER_LINEAR

setWrapping

public void setWrapping(int wrapS,
                        int wrapT)

Sets the wrapping mode for the S and T texture coordinates.

Parameters:

wrapS - S texture coordinate wrapping mode

wrapT - T texture coordinate wrapping mode

Throws:

java.lang.IllegalArgumentException - if wrapS or wrapT is not one of WRAP_CLAMP, WRAP_REPEAT

getWrappingS

public int getWrappingS()

Returns the current texture wrapping mode for the S texture coordinate.

Returns:

the current S coordinate wrapping mode

See Also:

setWrapping

getWrappingT

public int getWrappingT()

Returns the current texture wrapping mode for the T texture coordinate.

Returns:

the current T coordinate wrapping mode

See Also:

setWrapping

setBlending

public void setBlending(int func)

Selects the texture blend mode, or blend function, for this Texture2D. The available blending modes are defined in the class description.

Parameters:

func - the texture blending function to select

Throws:

java.lang.IllegalArgumentException - if func is not one of FUNC_REPLACE, FUNC_MODULATE, FUNC_DECAL, FUNC_BLEND, FUNC_ADD

See Also:

getBlending

getBlending

public int getBlending()

Returns the current texture blend mode for this Texture2D.

Returns:

the current texture blending function

See Also:

setBlending

setBlendColor

public void setBlendColor(int RGB)

Sets the texture blend color for this Texture2D. The high order byte of the color value (that is, the alpha component) is ignored.

Parameters:

RGB - the new texture blend color in 0x00RRGGBB format

See Also:

getBlendColor

getBlendColor

public int getBlendColor()

Returns the current texture blend color for this Texture2D.

Returns:

the current texture blend color

See Also:

setBlendColor

setTransform

public void setTransform(Transform transform)

Sets the texture coordinate transformation to use for this Texture2D by copying in the given Transform.

The texture coordinates and the texture transformation are internally treated as a four-component vector and a 4x4 matrix, respectively. After multiplication, the first two (S and T) coordinates of the result are divided by the fourth (Q).

Parameters:

transform - transform to copy in as the new texture matrix, or null to indicate the identity transform

See Also:

getTransform

getTransform

public void getTransform(Transform transform)

Returns the current texture transformation for this Texture2D.

Parameters:

transform - the Transform object to copy the transformation to

See Also:

setTransform