M3G 1.1 -- Jun 22, 2005

javax.microedition.m3g
Class Texture2D

java.lang.Object
  extended byjavax.microedition.m3g.Object3D
      extended byjavax.microedition.m3g.Transformable
          extended byjavax.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:

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.

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 Cf = (Rf, Gf, Bf) and alpha Af 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 Ct and At are the results of texture sampling and filtering as specified above. For luminance textures, the filtered luminance value Lt is converted to an RGB color as Ct = (Lt, Lt, Lt). In the BLEND mode, the texture blend color Cc, set by setBlendColor, is also used.

The input values are combined to output values Cv and Av 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:

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:

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

M3G 1.1 -- Jun 22, 2005

Copyright © 2005 Nokia Corporation. See the Copyright Notice for details.