javax.microedition.m3g
Class PolygonMode

java.lang.Object
  javax.microedition.m3g.Object3D
      javax.microedition.m3g.PolygonMode

public class PolygonMode

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.

Winding specifies which side of a polygon is the front face. Winding can be set to either clockwise (CW) or counter-clockwise (CCW). If the screen-space vertices of a polygon are in the order specified by the winding, then the polygon is front-facing. If the vertices are in the reverse order, then the polygon is back-facing.

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, as there are many other ways to make a piece of geometry invisible.

Lighting may operate in either one-sided or two-sided mode. In one-sided mode, a single color is computed for each vertex, based on the vertex normal, light source parameters, and material parameters. The same color is used in shading both the front face and the back face of the polygon. In two-sided mode, the colors for the back face of a polygon are computed separately and with reversed normals (n' = -n). Regardless of the lighting mode, the same set of Material parameters is used for both sides of the polygon. See the Material class description for more information on 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 vertex colors (also known as Gouraud shading), but implementations are also allowed to substitute a more accurate model. Flat shading means that the color computed for the third vertex of a triangle is used across the whole triangle.

If local camera lighting is disabled, the direction vector from the camera to the vertex being lit is approximated with (0 0 -1). If local camera lighting is enabled, the direction is computed based on the true camera position. This results in more accurate specular highlights. Note that local camera lighting only has an effect on the specular component of the lighting equation; the ambient and diffuse components remain unaffected. The local camera lighting flag is only a hint, so some implementations may not respect it. The application may use the getProperties method in Graphics3D to find out if the hint is supported.

Perspective correction is a generic term for techniques that eliminate artifacts caused by the screen-space interpolation of texture coordinates, colors and fog. The lack of perspective correction is especially evident on large textured polygons: the texture is distorted and seems to "crawl" on the surface as the viewing angle changes.

The perspective correction flag is only a hint, so some implementations may not respect it. Also, no particular method of implementing it is mandated or preferred. For example, some implementations may choose to do perspective correction for texture coordinates only. The application may use the getProperties method in Graphics3D to find out if the hint is supported.

See Also:

Binary format

Field Summary

static int	CULL_BACK A parameter to setCulling, specifying that the back-facing side of a polygon is not to be drawn.
static int	CULL_FRONT A parameter to setCulling, specifying that the front-facing side of a polygon is not to be drawn.
static int	CULL_NONE A parameter to setCulling, specifying that both faces of a polygon are to be drawn.
static int	SHADE_FLAT A parameter to setShading, specifying that flat shading is to be used.
static int	SHADE_SMOOTH A parameter to setShading, specifying that smooth shading is to be used.
static int	WINDING_CCW A parameter to setWinding, specifying that a polygon having its vertices in counter-clockwise order in screen space is to be considered front-facing.
static int	WINDING_CW A parameter to setWinding, specifying that a polygon having its vertices in clockwise order in screen space is to be considered front-facing.

Constructor Summary

PolygonMode()
Constructs a PolygonMode object with default values.

Method Summary

int	getCulling() Retrieves the current polygon culling mode.
int	getShading() Retrieves the current polygon shading mode.
int	getWinding() Retrieves the current polygon winding mode.
boolean	isLocalCameraLightingEnabled() Queries whether local camera lighting is enabled.
boolean	isPerspectiveCorrectionEnabled() Queries whether perspective correction is enabled.
boolean	isTwoSidedLightingEnabled() Queries whether two-sided lighting is enabled.
void	setCulling(int mode) Sets the polygon culling mode.
void	setLocalCameraLightingEnable(boolean enable) Enables or disables local camera lighting.
void	setPerspectiveCorrectionEnable(boolean enable) Enables or disables perspective correction.
void	setShading(int mode) Sets the polygon shading mode.
void	setTwoSidedLightingEnable(boolean enable) Enables or disables two-sided lighting.
void	setWinding(int mode) Sets the polygon winding mode to clockwise or counter-clockwise.

Methods inherited from class javax.microedition.m3g.Object3D

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

Field Detail

CULL_BACK

public static final int CULL_BACK

A parameter to setCulling, specifying that the back-facing side of a polygon is not to be drawn.

See Also:

Constant Field Values

CULL_FRONT

public static final int CULL_FRONT

A parameter to setCulling, specifying that the front-facing side of a polygon is not to be drawn.

See Also:

Constant Field Values

CULL_NONE

public static final int CULL_NONE

A parameter to setCulling, specifying that both faces of a polygon are to be drawn.

See Also:

Constant Field Values

SHADE_FLAT

public static final int SHADE_FLAT

A parameter to setShading, specifying that flat shading is to be used.

See Also:

Constant Field Values

SHADE_SMOOTH

public static final int SHADE_SMOOTH

A parameter to setShading, specifying that smooth shading is to be used.

See Also:

Constant Field Values

WINDING_CCW

public static final int WINDING_CCW

A parameter to setWinding, specifying that a polygon having its vertices in counter-clockwise order in screen space is to be considered front-facing.

See Also:

Constant Field Values

WINDING_CW

public static final int WINDING_CW

A parameter to setWinding, specifying that a polygon having its vertices in clockwise order in screen space is to be considered front-facing.

See Also:

Constant Field Values

Constructor Detail

PolygonMode

public PolygonMode()

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

• culling : CULL_BACK
• winding : WINDING_CCW
• shading : SHADE_SMOOTH
• two-sided lighting: false (disabled)
• local camera lighting : false (disabled)
• perspective correction : false (disabled)

Method Detail

setCulling

public void setCulling(int mode)

Sets the polygon culling mode. The culling mode defines which sides of a polygon are culled (that is, not rendered). The winding mode, on the other hand, defines which side is considered to be the front. See the class description for more information.

Parameters:

mode - the culling mode to set: back, front or none

Throws:

java.lang.IllegalArgumentException - if mode is not one of CULL_BACK, CULL_FRONT, CULL_NONE

See Also:

getCulling

getCulling

public int getCulling()

Retrieves the current polygon culling mode.

Returns:

the current culling mode; one of the symbolic constants

See Also:

setCulling

setWinding

public void setWinding(int mode)

Sets the polygon winding mode to clockwise or counter-clockwise. The winding mode defines which side of a polygon is considered to be the front. This and the culling mode together determine which sides of a polygon are rendered. The winding mode has consequences on lighting, as well, if two-sided lighting is enabled. See the class description for more information.

Parameters:

mode - the winding mode to set: clockwise or counter-clockwise

Throws:

java.lang.IllegalArgumentException - if mode is not one of WINDING_CCW, WINDING_CW

See Also:

getWinding

getWinding

public int getWinding()

Retrieves the current polygon winding mode.

Returns:

the current winding mode; one of the symbolic constants

See Also:

setWinding

setShading

public void setShading(int mode)

Sets the polygon shading mode. The shading mode defines whether a single color is assigned to the whole polygon (flat shading) or if a color is computed separately for each pixel (smooth shading). See the class description for more information.

Parameters:

mode - the shading mode to set: flat or smooth

Throws:

java.lang.IllegalArgumentException - if mode is not one of SHADE_FLAT, SHADE_SMOOTH

See Also:

getShading

getShading

public int getShading()

Retrieves the current polygon shading mode.

Returns:

the current shading mode: flat or smooth

See Also:

setShading

setTwoSidedLightingEnable

public void setTwoSidedLightingEnable(boolean enable)

Enables or disables two-sided lighting. If two-sided lighting is enabled, the lit colors for the front and back faces of a polygon are computed differently. Otherwise, both faces are assigned the same color. See the class description for more information.

Parameters:

enable - true to enable two-sided lighting; false to use one-sided lighting

See Also:

isTwoSidedLightingEnabled

isTwoSidedLightingEnabled

public boolean isTwoSidedLightingEnabled()

Queries whether two-sided lighting is enabled.

Returns:

true if two-sided lighting is enabled; false if not

See Also:

setTwoSidedLightingEnable

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

See Also:

isLocalCameraLightingEnabled

isLocalCameraLightingEnabled

public boolean isLocalCameraLightingEnabled()

Queries whether local camera lighting is enabled. Note that the set value is returned, regardless of whether the implementation obeys it or not.

Returns:

true if local camera lighting is enabled; false if not

Since:

M3G 1.1

See Also:

setLocalCameraLightingEnable

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

See Also:

isPerspectiveCorrectionEnabled

isPerspectiveCorrectionEnabled

public boolean isPerspectiveCorrectionEnabled()

Queries whether perspective correction is enabled. Note that the set value is returned, regardless of whether the implementation obeys it or not.

Returns:

true if perspective correction is enabled; false if not

Since:

M3G 1.1

See Also:

setPerspectiveCorrectionEnable