|
JSR-184 Public Review Draft - Apr. 30, 2003. | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.microedition.m3d.Object3D | +--javax.microedition.m3d.Texture2D
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.
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.
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.
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.
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 = AtCv = Cf
Av = Af Atundefined Cv = Cf
Av = AtCv = Cf
Av = Af AtLUMINANCE
Cv = Ct
Av = AfCv = Cf Ct
Av = Afundefined Cv = Cf (1 - Ct) + Cc Ct
Av = AfCv = Cf + Ct
Av = AfLUMINANCE_ALPHA
Cv = Ct
Av = AtCv = Cf Ct
Av = Af Atundefined Cv = Cf (1 - Ct) + Cc Ct
Av = Af AtCv = Cf + Ct
Av = Af AtRGB
Cv = Ct
Av = AfCv = Cf Ct
Av = AfCv = Ct
Av = AfCv = Cf (1 - Ct) + Cc Ct
Av = AfCv = Cf + Ct
Av = AfRGBA
Cv = Ct
Av = AtCv = Cf Ct
Av = Af AtCv = Cf (1 - At) + Ct At
Av = AfCv = Cf (1 - Ct) + Cc Ct
Av = Af AtCv = Cf + Ct
Av = Af At
Texturing is done according to the OpenGL 1.3 specification, section 3.8, with the following exceptions:
COMBINE
texture environment mode is not supported;INTENSITY
texture image format 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.
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 |
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Constructor Detail |
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:
WRAP_REPEAT
WRAP_REPEAT
FILTER_BASE_LEVEL
FILTER_NEAREST
FUNC_MODULATE
image
- an Image2D object to set as the base level texture image
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 maximumMethod Detail |
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.
image
- an Image2D object to set as the base level texture image
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 maximumgetImage
public Image2D getImage()
Retrieves the current base level (full size) texture image.
setImage
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.
levelFilter
- filtering between mipmap levelsimageFilter
- filtering within a mipmap level
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
public void setWrapping(int wrapS, int wrapT)
Sets the wrapping mode for the S and T texture coordinates.
wrapS
- S texture coordinate wrapping modewrapT
- T texture coordinate wrapping mode
java.lang.IllegalArgumentException
- if wrapS
or wrapT
is not one of WRAP_CLAMP, WRAP_REPEAT
public int getWrappingS()
Returns the current texture wrapping mode for the S texture coordinate.
setWrapping
public int getWrappingT()
Returns the current texture wrapping mode for the T texture coordinate.
setWrapping
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.
func
- the texture blending function to select
java.lang.IllegalArgumentException
- if func
is not one of
FUNC_REPLACE, FUNC_MODULATE, FUNC_DECAL, FUNC_BLEND, FUNC_ADD
getBlending
public int getBlending()
Returns the current texture blend mode for this Texture2D.
setBlending
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.
RGB
- the new texture blend color in 0x00RRGGBB formatgetBlendColor
public int getBlendColor()
Returns the current texture blend color for this Texture2D.
setBlendColor
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).
transform
- transform to copy in as the new texture matrix,
or null to indicate the identity transformgetTransform
public void getTransform(Transform transform)
Returns the current texture transformation for this Texture2D.
transform
- the Transform object to copy the transformation tosetTransform
|
JSR-184 Public Review Draft - Apr. 30, 2003. | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |