javax.microedition.m3g
Class Texture2D

java.lang.Object
  javax.microedition.m3g.Object3D
      javax.microedition.m3g.Transformable
          javax.microedition.m3g.Texture2D

public class Texture2D

extends Transformable

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. The width and height of the image must be non-negative 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().

Mipmap level images are generated automatically by repeated filtering of the base level image. No particular method of filtering is mandated, but a 2x2 box filter is recommended. It is not possible for the application to supply the mipmap level images explicitly.

If the referenced Image2D is modified by the application, or a new Image2D is bound as the texture image, the modifications are immediately reflected in the Texture2D. Be aware, however, that switching to another texture image or updating the pre-existing image may trigger expensive operations, such as mipmap level image generation or (re)allocation of memory. It is therefore recommended that texture images not be updated unnecessarily.

Texture mapping

Transformation

The first step in applying a texture image onto a submesh is to apply the texture transformation to the texture coordinates of each vertex of that submesh. The transformation is defined in the Texture2D object itself, while the texture coordinates are obtained from the VertexBuffer object associated with that submesh.

The incoming texture coordinates may have either two or three components (see VertexBuffer), but for the purposes of multiplication with a 4x4 matrix they are augmented to have four components. If the third component is not given, it is implicitly set to zero. The fourth component is always assumed to be 1.

The texture transformation is very similar to the node transformation. They both consist of translation, orientation and scale components, as well as a generic 4x4 matrix component. The order of concatenating the components is the same. The only difference is that the bottom row of the matrix part must be (0 0 0 1) in case of a node transformation but not in case of a texture transformation. The methods to manipulate the individual transformation components of both node and texture transformations are defined in the base class, Transformable.

Formally, a homogeneous vector p = (s, t, r, 1), representing a point in texture space, is transformed to a point p' = (s', t', r', q') as follows:

p' = T R S M p

where T, R and S denote the translation, orientation and scale components, respectively, and M is the generic 4x4 matrix.

The translation, orientation and scale components of the texture transformation can be animated independently from each other. The matrix component is not animatable at all; it can only be changed using the setTransform method.

Projection

The texture transformation described above yields the transformed texture coordinates (s', t', r', q') for each vertex of a triangle. The final texture coordinates for each rasterized fragment, in turn, are computed in two steps: interpolation and projection.

• Interpolation. The per-vertex texture coordinates are interpolated across the triangle to obtain the "un-projected" texture coordinate for each fragment. If the implementation supports perspective correction and the perspective correction flag in PolygonMode is enabled, this interpolation must perform some degree of perspective correction; otherwise, simple linear interpolation may (but does not have to) be used.

• Projection. The first three components of the interpolated texture coordinate are divided by the fourth component. Formally, the interpolated texture coordinate p' = (s', t', r', q') is transformed into p'' = (s'', t'', r'', 1) as follows:

  p'' = p'/q' = (s'/q', t'/q', r'/q', 1)

  Again, if perspective correction is either not supported or not enabled, the implementation may do the projection on a per-vertex basis and interpolate the projected values instead of the original values. Otherwise, some degree of perspective correction must be applied. Ideally, the perspective divide would be done for each fragment separately.

The r'' component of the result may be ignored, because 3D texture images are not supported in this version of the API; only the first two components are required to index a 2D image.

Texel fetch

The transformed, interpolated and projected s'' and t'' texture coordinates of a fragment are used to fetch texel(s) from the texture image according to the selected wrapping and filtering modes.

The coordinates s'' and t'' relate to the texture image such that (0, 0) is the upper left corner of the image and (1, 1) is the lower right corner. Thus, s'' increases from left to right and t'' increases from top to bottom. The REPEAT and CLAMP texture wrapping modes define the treatment of coordinate values that are outside of the [0, 1] range.

Note that the t'' coordinate is reversed with respect to its orientation in OpenGL; however, the texture image orientation is reversed as well. As a net result, there is no difference in actual texture coordinate values between this API and OpenGL in common texturing operations. The only difference arises when rendering to a texture image that is subsequently mapped onto an object. In that case, the t texture coordinates of the object need to be reversed (t' = 1 - t). If this is not done at the modeling stage, it can be done at run-time using the texture transformation. Of course, the whole issue of texture coordinate orientation is only relevant in cases where existing OpenGL code and meshes are ported to this API.

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 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 setBlendColor, 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 table below.

Texture format	Blending mode
	REPLACE	MODULATE	DECAL	BLEND	ADD
ALPHA	Cv = Cf Av = At	Cv = Cf Av = Af At	undefined	Cv = Cf Av = Af 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
LUM_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 are not supported (border width is always zero);
• The T texture coordinate and the texture image are both reversed;
• 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 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.

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.
int	getImageFilter() Returns the current texture image filter.
int	getLevelFilter() Returns the current texture level filter.
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	setWrapping(int wrapS, int wrapT) Sets the wrapping mode for the S and T texture coordinates.

Methods inherited from class javax.microedition.m3g.Transformable

getCompositeTransform, getOrientation, getScale, getTransform, getTranslation, postRotate, preRotate, scale, setOrientation, setScale, setTransform, setTranslation, translate

Methods inherited from class javax.microedition.m3g.Object3D

addAnimationTrack, animate, duplicate, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, getUserObject, removeAnimationTrack, setUserID, setUserObject

Field Detail

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_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

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

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

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_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_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

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 mode, with a border width of zero, in OpenGL.

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 mode in OpenGL.

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 and blending 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)

Parameters:

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

Throws:

java.lang.NullPointerException - if image is null

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.NullPointerException - if image is null

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

See Also:

getLevelFilter, getImageFilter

getLevelFilter

public int getLevelFilter()

Returns the current texture level filter. Note that the set value is returned, even if the implementation only supports a subset of the available filtering methods.

Returns:

the current filtering between mipmap levels

Since:

M3G 1.1

See Also:

setFiltering

getImageFilter

public int getImageFilter()

Returns the current texture image filter. Note that the set value is returned, even if the implementation only supports a subset of the available filtering methods.

Returns:

the current filtering within a mipmap level

Since:

M3G 1.1

See Also:

setFiltering

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

See Also:

getWrappingS, getWrappingT

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. The high order byte of the color value (that is, the alpha component) is guaranteed to be zero.

Returns:

the current texture blend color in 0x00RRGGBB format

See Also:

setBlendColor