javax.microedition.m3g
Class Appearance

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

public class Appearance

extends Object3D

A set of component objects that define the rendering attributes of a Mesh or Sprite3D.

Appearance attributes are grouped into component objects, each encapsulating a set of properties that are functionally and logically related to each other. This division helps applications to conserve memory by sharing component objects across multiple meshes and sprites. The Appearance component classes and a summary of their contents are presented in the figure below.

All components of a newly created Appearance object are initialized to null. It is completely legal for any or all of the components to be null even when rendering. The behavior when each of the components is null is as follows:

• If a Texture2D is null, the corresponding texturing unit is disabled.
• If the PolygonMode is null, default values are used.
• If the CompositingMode is null, default values are used.
• If the Material is null, lighting is disabled.
• If the Fog is null, fogging is disabled.

Using a null Appearance on a submesh (or sprite) disables rendering and picking of that submesh (or sprite). An Appearance must always be provided for an object in order to make it visible.

Implementation guidelines

By default, everything in Appearance works exactly the same way as in OpenGL 1.3. As a general exception, the color index (palette) mode is not supported. Other than that, any deviations from the OpenGL 1.3 specification are documented explicitly in the individual Appearance component classes.

See Also:

Binary format

Constructor Summary

Appearance()
Constructs an Appearance object with default values.

Method Summary

CompositingMode	getCompositingMode() Returns the current CompositingMode for this Appearance.
Fog	getFog() Returns the current fogging attributes for this Appearance.
int	getLayer() Gets the current rendering layer for this Appearance.
Material	getMaterial() Returns the current Material for this Appearance.
PolygonMode	getPolygonMode() Returns the current PolygonMode for this Appearance.
Texture2D	getTexture(int index) Retrieves the current texture image and its attributes for the given texturing unit.
void	setCompositingMode(CompositingMode compositingMode) Sets the CompositingMode to use for this Appearance.
void	setFog(Fog fog) Sets the fogging attributes to use for this Appearance.
void	setLayer(int layer) Sets the rendering layer for this Appearance.
void	setMaterial(Material material) Sets the Material to use when lighting this Appearance.
void	setPolygonMode(PolygonMode polygonMode) Sets the PolygonMode to use for this Appearance.
void	setTexture(int index, Texture2D texture) Sets the texture image and its attributes for the given texturing unit.

Methods inherited from class javax.microedition.m3g.Object3D

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

Constructor Detail

Appearance

public Appearance()

Constructs an Appearance object with default values. The default values are:

• rendering layer : 0
• polygon mode : null (use defaults)
• compositing mode : null (use defaults)
• all textures : null (all texturing units disabled)
• material : null (lighting disabled)
• fog : null (fogging disabled)

Method Detail

setLayer

public void setLayer(int layer)

Sets the rendering layer for this Appearance. When rendering a World, Group or Mesh, submeshes and sprites are guaranteed to be rendered in the order of ascending layers. That is, all submeshes and sprites with an appearance at a lower layer are rendered prior to any submeshes or sprites at the higher layers. Furthermore, all opaque submeshes and sprites at a specific layer are rendered prior to any blended submeshes or sprites at the same layer. A submesh or a sprite is defined to be opaque if it uses the REPLACE blending mode (see CompositingMode), and blended otherwise.

Implementations are free to do any additional state sorting as long as the aforementioned constraints are met. To allow implementations to operate as efficiently as possible, applications should only use layering constraints when required. As a result of the rules above, the default layer of zero should be sufficient for most uses. Cases where non-zero layers may be useful include background geometry, sky boxes, lens flares, halos, and other special effects.

Note that the rendering layer has no effect on picking.

Parameters:

layer - the rendering layer for submeshes and sprites having this Appearance

Throws:

java.lang.IndexOutOfBoundsException - if layer is not in [-63, 63]

See Also:

getLayer, Mesh

getLayer

public int getLayer()

Gets the current rendering layer for this Appearance.

Returns:

the current rendering layer; this is always in the range [-63, 63]

See Also:

setLayer

setFog

public void setFog(Fog fog)

Sets the fogging attributes to use for this Appearance. If the Fog object is set to null, fogging is disabled.

Parameters:

fog - a Fog object, or null to disable fogging

See Also:

getFog

getFog

public Fog getFog()

Returns the current fogging attributes for this Appearance.

Returns:

the current Fog object, or null if fogging is disabled

See Also:

setFog

setPolygonMode

public void setPolygonMode(PolygonMode polygonMode)

Sets the PolygonMode to use for this Appearance. If the PolygonMode is set to null, the default values are used.

Parameters:

polygonMode - a PolygonMode object, or null to use the defaults

See Also:

getPolygonMode

getPolygonMode

public PolygonMode getPolygonMode()

Returns the current PolygonMode for this Appearance.

Returns:

the current PolygonMode object, or null if no PolygonMode is set

See Also:

setPolygonMode

setCompositingMode

public void setCompositingMode(CompositingMode compositingMode)

Sets the CompositingMode to use for this Appearance. If the CompositingMode is set to null, the default values are used.

Parameters:

compositingMode - a CompositingMode object, or null to use the defaults

See Also:

getCompositingMode

getCompositingMode

public CompositingMode getCompositingMode()

Returns the current CompositingMode for this Appearance.

Returns:

the current CompositingMode object, or null if no CompositingMode is set

See Also:

setCompositingMode

setTexture

public void setTexture(int index,
                       Texture2D texture)

Sets the texture image and its attributes for the given texturing unit. If the texture object is set to null, the specified texturing unit is disabled.

Parameters:

index - texturing unit index

texture - a texture object for the specified texturing unit, or null to disable the unit

Throws:

java.lang.IndexOutOfBoundsException - if index is not a valid texturing unit index

See Also:

getTexture

getTexture

public Texture2D getTexture(int index)

Retrieves the current texture image and its attributes for the given texturing unit.

Parameters:

index - texturing unit index

Returns:

the current texture object of the specified texturing unit, or null if the unit is disabled

Throws:

java.lang.IndexOutOfBoundsException - if index is not a valid texturing unit index

See Also:

setTexture

setMaterial

public void setMaterial(Material material)

Sets the Material to use when lighting this Appearance. If the Material is set to null, lighting is disabled. See the Material class description for more information.

Parameters:

material - a Material object, or null to disable lighting

See Also:

getMaterial

getMaterial

public Material getMaterial()

Returns the current Material for this Appearance.

Returns:

the current Material object, or null if lighting is disabled

See Also:

setMaterial