JSR-184 Public Review Draft - Apr. 30, 2003.

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 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 setTexBlendColor, 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 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:

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:

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

JSR-184 Public Review Draft - Apr. 30, 2003.

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