M3G 1.1 -- Jun 22, 2005

javax.microedition.m3g
Class Material

java.lang.Object
  extended byjavax.microedition.m3g.Object3D
      extended byjavax.microedition.m3g.Material

public class Material
extends Object3D

An Appearance component encapsulating material attributes for lighting computations. Other attributes required for lighting are defined in Light, PolygonMode and VertexBuffer.

The diagram below illustrates how the final, lit color is obtained for a vertex. Lighting is disabled for a submesh if it has a null Material, and enabled otherwise. If lighting is disabled, the final vertex color is taken from the associated VertexBuffer as such. If lighting is enabled, the final color is computed according to the OpenGL 1.3 lighting equation (p. 48), using the material colors specified here. Finally, if vertex color tracking is enabled, the AMBIENT and DIFFUSE material colors are replaced with the per-vertex colors or the default color obtained from the VertexBuffer.

Implementation guidelines

Lighting is computed according to the OpenGL 1.3 specification, section 2.13.1, with the following exceptions:

See Also:
Binary format

Field Summary
static int AMBIENT
          A parameter to setColor and getColor, specifying that the ambient color component is to be set or retrieved.
static int DIFFUSE
          A parameter to setColor and getColor, specifying that the diffuse color component is to be set or retrieved.
static int EMISSIVE
          A parameter to setColor and getColor, specifying that the emissive color component is to be set or retrieved.
static int SPECULAR
          A parameter to setColor and getColor, specifying that the specular color component is to be set or retrieved.
 
Constructor Summary
Material()
          Creates a Material object with default values.
 
Method Summary
 int getColor(int target)
          Gets the value of the specified color component of this Material.
 float getShininess()
          Gets the current shininess of this Material.
 boolean isVertexColorTrackingEnabled()
          Queries whether vertex color tracking is enabled.
 void setColor(int target, int ARGB)
          Sets the given value to the specified color component(s) of this Material.
 void setShininess(float shininess)
          Sets the shininess of this Material.
 void setVertexColorTrackingEnable(boolean enable)
          Enables or disables vertex color tracking.
 
Methods inherited from class javax.microedition.m3g.Object3D
addAnimationTrack, animate, duplicate, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, getUserObject, removeAnimationTrack, setUserID, setUserObject
   

Field Detail

AMBIENT

public static final int AMBIENT

A parameter to setColor and getColor, specifying that the ambient color component is to be set or retrieved.

See Also:
Constant Field Values

DIFFUSE

public static final int DIFFUSE

A parameter to setColor and getColor, specifying that the diffuse color component is to be set or retrieved.

See Also:
Constant Field Values

EMISSIVE

public static final int EMISSIVE

A parameter to setColor and getColor, specifying that the emissive color component is to be set or retrieved.

See Also:
Constant Field Values

SPECULAR

public static final int SPECULAR

A parameter to setColor and getColor, specifying that the specular color component is to be set or retrieved.

See Also:
Constant Field Values
Constructor Detail

Material

public Material()

Creates a Material object with default values. The default values are:

Note that even though the alpha component can be set for all color components, it is ignored for all but the diffuse component.

Method Detail

setColor

public void setColor(int target,
                     int ARGB)

Sets the given value to the specified color component(s) of this Material. The color components to set are specified as an inclusive OR of one or more of the symbolic constants listed above. The color is given in ARGB format, but the alpha component is ignored for all but the diffuse color.

Parameters:
target - a bitmask of color component identifiers
ARGB - color for the target property (or properties) in 0xAARRGGBB format
Throws:
java.lang.IllegalArgumentException - if target has a value other than an inclusive OR of one or more of AMBIENT, DIFFUSE, EMISSIVE, SPECULAR
See Also:
getColor

getColor

public int getColor(int target)

Gets the value of the specified color component of this Material. The alpha component of the returned value is guaranteed to be zero for all but the diffuse color component.

Parameters:
target - exactly one of AMBIENT, DIFFUSE, EMISSIVE, SPECULAR
Returns:
the current color of the target property in 0xAARRGGBB format
Throws:
java.lang.IllegalArgumentException - if target has a value other than one of those listed above
See Also:
setColor

setShininess

public void setShininess(float shininess)

Sets the shininess of this Material. Shininess is the specular exponent term in the lighting equation, and it can take on values between [0, 128]. Large values of shininess make the specular highlights more concentrated, and small values make them more spread out.

Parameters:
shininess - the specular exponent value to set for this Material
Throws:
java.lang.IllegalArgumentException - if shininess is not in [0, 128]
See Also:
getShininess

getShininess

public float getShininess()

Gets the current shininess of this Material.

Returns:
the current specular exponent value of this Material
See Also:
setShininess

setVertexColorTrackingEnable

public void setVertexColorTrackingEnable(boolean enable)

Enables or disables vertex color tracking. When enabled, the AMBIENT and DIFFUSE material colors will take on color values from the associated VertexBuffer on a per-vertex basis. The ambient and diffuse color values of this Material are ignored in that case.

Parameters:
enable - true to turn vertex color tracking on; false to turn it off

isVertexColorTrackingEnabled

public boolean isVertexColorTrackingEnabled()

Queries whether vertex color tracking is enabled.

Returns:
true if vertex color tracking is enabled; false if it's disabled

M3G 1.1 -- Jun 22, 2005

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