javax.microedition.m3d
Class Material

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

public class Material

extends Object3D

An Appearance component encapsulating material attributes for lighting computations. Other attributes required for lighting are defined in Light, World, GeometryMode, 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 the AMBIENT and DIFFUSE material colors are replaced with the per-vertex (or default) color from the VertexBuffer.

Implementation guidelines

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

• the secondary color is not supported;
• the color index mode is not supported;
• the same Material is used for both sides of a triangle;
• vertex color tracking is limited to AMBIENT_AND_DIFFUSE;
• the diffuse and specular intensities of a Light are always equal;
• the ambient intensity of a Light is always zero.

The color that is set in Light corresponds to both the diffuse intensity dcli and the specular intensity scli in the lighting equation. Thus, the diffuse and specular components can not be set separately, and the ambient component is fixed to zero. The global ambient light (specified in World or Graphics3D) corresponds to the light model ambient acs in the equation.

See Also:

Binary format

Field Summary

static int	AMBIENT A parameter for setColor and getColor, specifying that the ambient color component is to be set or retrieved.
static int	DIFFUSE A parameter for setColor and getColor, specifying that the diffuse color component is to be set or retrieved.
static int	EMISSIVE A parameter for setColor and getColor, specifying that the emissive color component is to be set or retrieved.
static int	SPECULAR A parameter for setColor and getColor, specifying that the specular color component is to be set or retrieved.

Fields inherited from class javax.microedition.m3d.Object3D

userObject

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.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

AMBIENT

public static final int AMBIENT

A parameter for 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 for 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 for 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 for 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:

vertex color tracking : false (disabled)
ambient color : 0x00333333 (0.2, 0.2, 0.2, 0.0)
diffuse color : 0xFFCCCCCC (0.8, 0.8, 0.8, 1.0)
emissive color : 0x00000000 (0.0, 0.0, 0.0, 0.0)
specular color : 0x00000000 (0.0, 0.0, 0.0, 0.0)
shininess : 0.0

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]. Larger values of shininess will make specular highlights more concentrated, and smaller values will 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