javax.microedition.m3d
Class GeometryMode

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

public class GeometryMode

extends Object3D

An Appearance component encapsulating polygon-level attributes. This includes settings related to back/front face culling, polygon winding, lighting computations, perspective correction, and shading.

Culling determines which side of a polygon is removed from processing prior to rasterization: the back face, the front face, or neither. Culling both faces is not allowed; there are other ways to make a certain piece of geometry to be invisible. Winding determines which side of a polygon is the front face. If the vertices of a polygon (in screen space) are in clockwise order and winding is set to clockwise, then the polygon is front-facing, and vice versa. Note that winding affects not only culling, but also lighting.

There are two choices for polygon shading, smooth and flat. Smooth shading means that a color is computed separately for each pixel. This may be done by linear interpolation between vertices, but implementations are allowed to substitute a more accurate model. Flat shading means that the color of the third vertex of a triangle is used across the whole triangle. Shading is applied prior to texture mapping, fogging, blending, and any other per-pixel operations. As a result, shading is unnecessary and may be skipped by implementations in certain cases; for example, if the texturing mode is REPLACE.

Two-sided lighting is necessary in order for two-sided polygons to be lit properly. Polygons pertaining to this GeometryMode object are two-sided if and only if the culling mode is set to CULL_NONE. If the current culling mode is CULL_BACK or CULL_FRONT, two-sided lighting is not necessary. Note that one-sided lighting can be used with two-sided polygons, but then the result may not be what the developer expects.

Local camera lighting means that the camera position is taken into account when computing direction vectors from the vertices to the camera. Different vertices will thus have different direction vectors. If local camera lighting is disabled, the camera is assumed to be infinitely far away from the object, that is, the vertex-to-camera vector will be constant across vertices. This results in less realistic specular highlights, but is computationally simpler. Implementations may choose to enable or disable local camera lighting at their own discretion.

Perspective correction: Implementations may choose to ignore this request, or perform perspective correction at their own discretion. For example, some implementations may apply correction at every few pixels and interpolate linearly in between. Similarly, some implementations may only correct for texture coordinates, while others may correct for fog and color as well. Some implementations may choose to do no perspective correction at all.

See Also:

Binary format

Field Summary

static int	CULL_BACK Specifies that the back-facing side of a polygon is not drawn.
static int	CULL_FRONT Specifies that the front-facing side of a polygon is not drawn.
static int	CULL_NONE Specifies that both sides of a polygon are rendered.
static int	LIGHT_ONE_SIDED Specifies one-sided lighting.
static int	LIGHT_TWO_SIDED Specifies two-sided lighting.
static int	SHADE_FLAT Specifies flat shading.
static int	SHADE_SMOOTH Specifies smooth shading.
static int	WINDING_CCW Specifies counter-clockwise polygon winding.
static int	WINDING_CW Specifies clockwise polygon winding.

Fields inherited from class javax.microedition.m3d.Object3D

userObject

Constructor Summary

GeometryMode()
Constructs a GeometryMode object with default values.

Method Summary

int	getModes() Retrieves the current culling, winding, shading and lighting modes.
void	setLocalCameraLightingEnable(boolean enable) Enables or disables local camera lighting.
void	setModes(int modeBits) Sets culling, winding, shading, and/or lighting modes.
void	setPerspectiveCorrectionEnable(boolean enable) Enables or disables perspective correction.

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

CULL_BACK

public static final int CULL_BACK

Specifies that the back-facing side of a polygon is not drawn. This is mutually exclusive with CULL_FRONT and CULL_NONE.

See Also:

Constant Field Values

CULL_FRONT

public static final int CULL_FRONT

Specifies that the front-facing side of a polygon is not drawn. This is mutually exclusive with CULL_BACK and CULL_NONE.

See Also:

Constant Field Values

CULL_NONE

public static final int CULL_NONE

Specifies that both sides of a polygon are rendered. This is mutually exclusive with CULL_BACK and CULL_FRONT.

See Also:

Constant Field Values

WINDING_CCW

public static final int WINDING_CCW

Specifies counter-clockwise polygon winding. This is mutually exclusive with WINDING_CW.

See Also:

Constant Field Values

WINDING_CW

public static final int WINDING_CW

Specifies clockwise polygon winding. This is mutually exclusive with WINDING_CCW.

See Also:

Constant Field Values

SHADE_FLAT

public static final int SHADE_FLAT

Specifies flat shading. This is mutually exclusive with SHADE_SMOOTH.

See Also:

Constant Field Values

SHADE_SMOOTH

public static final int SHADE_SMOOTH

Specifies smooth shading. This is mutually exclusive with SHADE_FLAT.

See Also:

Constant Field Values

LIGHT_ONE_SIDED

public static final int LIGHT_ONE_SIDED

Specifies one-sided lighting. This is mutually exclusive with LIGHT_TWO_SIDED.

See Also:

Constant Field Values

LIGHT_TWO_SIDED

public static final int LIGHT_TWO_SIDED

Specifies two-sided lighting. Two-sided lighting must be enabled in order for two-sided polygons to be lit properly. See the class description for further discussion on two-sided lighting. This is mutually exclusive with LIGHT_ONE_SIDED.

See Also:

Constant Field Values

Constructor Detail

GeometryMode

public GeometryMode()

Constructs a GeometryMode object with default values. The default values are as follows:

polygon culling : CULL_BACK
polygon winding : WINDING_CCW
polygon shading : SHADE_SMOOTH
polygon lighting : LIGHT_ONE_SIDED
local camera lighting : false (disabled)
perspective correction : false (disabled)

Method Detail

setModes

public void setModes(int modeBits)

Sets culling, winding, shading, and/or lighting modes. The modeBits parameter is an OR bitmask of modes to be set; unspecified modes are not changed. Culling modes are mutually exclusive, so setting one of them will disable the others; similarly for winding, shading, and lighting. For example, specifying (CULL_NONE | LIGHT_TWO_SIDED) disables culling and enables two-sided lighting, but leaves winding and shading untouched. See the class description for further discussion on the various modes.

Parameters:

modeBits - an OR bitmask of culling, winding, shading, and lighting selectors

Throws:

java.lang.IllegalArgumentException - if modeBits is not an OR mask of the symbolic constants listed above, or if any two mutually exclusive bits are set

See Also:

getModes

getModes

public int getModes()

Retrieves the current culling, winding, shading and lighting modes.

Returns:

an OR bitmask of the current modes

See Also:

setModes

setLocalCameraLightingEnable

public void setLocalCameraLightingEnable(boolean enable)

Enables or disables local camera lighting. Note that this is only a hint: the implementation may or may not obey it. See the class description for further discussion on local camera lighting.

Parameters:

enable - true to enable local camera lighting; false to disable it

setPerspectiveCorrectionEnable

public void setPerspectiveCorrectionEnable(boolean enable)

Enables or disables perspective correction. Note that this is only a hint: the implementation may or may not obey it. See the class description for further discussion on perspective correction.

Parameters:

enable - true to enable perspective correction; false to disable it