javax.microedition.m3g
Class Light

java.lang.Object
  javax.microedition.m3g.Object3D
      javax.microedition.m3g.Transformable
          javax.microedition.m3g.Node
              javax.microedition.m3g.Light

public class Light

extends Node

A scene graph node that represents different kinds of light sources.

Light sources are used to determine the color of each object according to its Material attributes, as described in more detail in the Material class documentation.

Light source types

Four types of light sources are available. In the order of increasing computational complexity, these are the ambient light, directional light, omnidirectional light and spot light. Their characteristics are described below.

• An ambient light source illuminates all objects in the scene from all directions. The intensity of light coming from an ambient light source is the same everywhere in the scene. The position and direction of an ambient light source therefore have no effect.
• A directional light source corresponds to sunlight in the real world. It illuminates all objects in the scene from the same direction, and with a constant intensity. Similar to ambient light, the position of a directional light source has no effect. The direction of the light is along the negative Z axis of the Light node's local coordinate system.
• An omnidirectional light source, also known as a point light, casts equal illumination in all directions from the origin of the Light node's local coordinate system. The intensity of light coming from an omnidirectional light source can be attenuated with distance. The orientation of an omnidirectional Light node has no effect; only the position matters.
• A spot light source casts a cone of light centered around the direction of its negative Z axis. The concentration of light within the cone can be adjusted with the spot exponent. The intensity of light coming from a spot light can be attenuated with distance from the source. Both the orientation and the position of the Light node have an effect with spot lights.

The type of a light source can be changed at any time. This is useful for switching to a simpler lighting model when the distance to an object increases over a certain threshold, for example.

Light color and intensity

The RGB intensity contributed to the lighting calculation by a Light is (IR, IG, IB), where I is the intensity of the Light and (R, G, B) is its color. Note that while 1.0 is a nominal full intensity, applications may use values higher than that for more control over highlights, for example. The intensity may also be set to negative to specify an "antilight" or "dark".

In the case of an ambient light source, the final RGB intensity represents the ambient color component only; the diffuse and specular components are implicitly set to zero. In the case of a directional, omni or spot light, the final intensity represents both the diffuse and specular components, while the ambient component is correspondingly set to zero.

Light source selection

The set of meshes affected by a Light can be limited using the scope of the Light and each Mesh. A Light node is only included in the lighting calculations for a mesh if the scope of the mesh matches the scope of the Light. See the Node class description for more information.

Lights can be turned on and off using Node.setRenderingEnable(boolean). The corresponding picking enable flag has no effect, because Lights are always ignored when picking.

Implementation guidelines

The number of Lights matching with a single Mesh may be greater than the maximum number of concurrent lights that the implementation can support (N). In this case, the implementation may choose any N lights, as long as the selection is deterministic. For best results, the implementation may use a suitable heuristic to select the N lights that have the most effect on the rendered appearance of the mesh. The light selection may even be done separately for each submesh. The maximum number of concurrent lights can be queried from getProperties.

See Also:

Binary format, Material

Field Summary

static int	AMBIENT A parameter to setMode, specifying an ambient light source.
static int	DIRECTIONAL A parameter to setMode, specifying a directional light source.
static int	OMNI A parameter to setMode, specifying an omnidirectional light source.
static int	SPOT A parameter to setMode, specifying a spot light source.

Fields inherited from class javax.microedition.m3g.Node

NONE, ORIGIN, X_AXIS, Y_AXIS, Z_AXIS

Constructor Summary

Light()
Constructs a new Light with default values.

Method Summary

int	getColor() Retrieves the current color of this Light.
float	getConstantAttenuation() Retrieves the current constant attenuation coefficient for this Light.
float	getIntensity() Retrieves the current intensity of this Light.
float	getLinearAttenuation() Retrieves the current linear attenuation coefficient for this Light.
int	getMode() Retrieves the current type of this Light.
float	getQuadraticAttenuation() Retrieves the current quadratic attenuation coefficient for this Light.
float	getSpotAngle() Retrieves the current spot angle of this Light.
float	getSpotExponent() Retrieves the current spot exponent for this Light.
void	setAttenuation(float constant, float linear, float quadratic) Sets the attenuation coefficients for this Light.
void	setColor(int RGB) Sets the color of this Light.
void	setIntensity(float intensity) Sets the intensity of this Light.
void	setMode(int mode) Sets the type of this Light.
void	setSpotAngle(float angle) Sets the spot cone angle for this Light.
void	setSpotExponent(float exponent) Sets the spot exponent for this Light.

Methods inherited from class javax.microedition.m3g.Node

align, getAlignmentReference, getAlignmentTarget, getAlphaFactor, getParent, getScope, getTransformTo, isPickingEnabled, isRenderingEnabled, setAlignment, setAlphaFactor, setPickingEnable, setRenderingEnable, setScope

Methods inherited from class javax.microedition.m3g.Transformable

getCompositeTransform, getOrientation, getScale, getTransform, getTranslation, postRotate, preRotate, scale, setOrientation, setScale, setTransform, setTranslation, translate

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 setMode, specifying an ambient light source.

See Also:

Constant Field Values

DIRECTIONAL

public static final int DIRECTIONAL

A parameter to setMode, specifying a directional light source.

See Also:

Constant Field Values

OMNI

public static final int OMNI

A parameter to setMode, specifying an omnidirectional light source.

See Also:

Constant Field Values

SPOT

public static final int SPOT

A parameter to setMode, specifying a spot light source.

See Also:

Constant Field Values

Constructor Detail

Light

public Light()

Constructs a new Light with default values. The default values are as follows:

• mode: DIRECTIONAL
• color : 0x00FFFFFF (1.0, 1.0, 1.0)
• intensity : 1.0
• attenuation : (1, 0, 0)
• spot angle : 45 degrees
• spot exponent : 0.0

Method Detail

setMode

public void setMode(int mode)

Sets the type of this Light. See the class description for more information.

Parameters:

mode - the mode to set; one of the symbolic constants listed above

Throws:

java.lang.IllegalArgumentException - if mode is not one of AMBIENT, DIRECTIONAL, OMNI, SPOT

See Also:

getMode

getMode

public int getMode()

Retrieves the current type of this Light.

Returns:

the current mode of this Light; one of the symbolic constants listed above

See Also:

setMode

setIntensity

public void setIntensity(float intensity)

Sets the intensity of this Light. The RGB color of this Light is multiplied component-wise with the intensity before computing the lighting equation. See the class description for more information.

Parameters:

intensity - the intensity to set; may be negative or zero

See Also:

getIntensity

getIntensity

public float getIntensity()

Retrieves the current intensity of this Light.

Returns:

the current intensity of this Light

See Also:

setIntensity

setColor

public void setColor(int RGB)

Sets the color of this Light. Depending on the type of light, this represents either the ambient color or both the diffuse and specular colors. See the class description for more information. The high order byte of the color value (that is, the alpha component) is ignored.

Parameters:

RGB - the color to set for this Light in 0x00RRGGBB format

See Also:

getColor

getColor

public int getColor()

Retrieves the current color of this Light. The high order byte of the color value (that is, the alpha component) is guaranteed to be zero.

Returns:

the current color of this Light in 0x00RRGGBB format

See Also:

setColor

setSpotAngle

public void setSpotAngle(float angle)

Sets the spot cone angle for this Light. The effect of this Light is restricted to a cone of angle degrees around the negative Z axis of the Light.

Note that this setting has no effect unless the type of this Light is (or is later set to) SPOT.

Parameters:

angle - the spot angle to set, in degrees

Throws:

java.lang.IllegalArgumentException - if angle is not in [0, 90]

See Also:

getSpotAngle

getSpotAngle

public float getSpotAngle()

Retrieves the current spot angle of this Light.

Returns:

the current spot angle of this Light

See Also:

setSpotAngle

setSpotExponent

public void setSpotExponent(float exponent)

Sets the spot exponent for this Light. The spot exponent controls the distribution of the intensity of this Light within the spot cone, such that larger values yield a more concentrated cone. The default spot exponent is 0.0, resulting in a uniform light distribution.

Note that this setting has no effect unless the type of this Light is (or is later set to) SPOT.

Parameters:

exponent - the spot light exponent to set

Throws:

java.lang.IllegalArgumentException - if exponent is not in [0, 128]

See Also:

getSpotExponent

getSpotExponent

public float getSpotExponent()

Retrieves the current spot exponent for this Light.

Returns:

the current spot exponent of this Light

See Also:

setSpotExponent

setAttenuation

public void setAttenuation(float constant,
                           float linear,
                           float quadratic)

Sets the attenuation coefficients for this Light. The attenuation factor is

1 / (c + l d + q d²)

where d is the distance between the light and the vertex being lighted, and c, l, q are the constant, linear, and quadratic coefficients. The default attenuation coefficients are (1, 0, 0), resulting in no attenuation.

Note that this setting has no effect unless the type of this Light is (or is later set to) OMNI or SPOT.

Parameters:

constant - the constant attenuation coefficient to set

linear - the linear attenuation coefficient to set

quadratic - the quadratic attenuation coefficient to set

Throws:

java.lang.IllegalArgumentException - if any of the parameter values are negative

java.lang.IllegalArgumentException - if all of the parameter values are zero

getConstantAttenuation

public float getConstantAttenuation()

Retrieves the current constant attenuation coefficient for this Light.

Returns:

the current constant attenuation coefficient

See Also:

setAttenuation

getLinearAttenuation

public float getLinearAttenuation()

Retrieves the current linear attenuation coefficient for this Light.

Returns:

the current linear attenuation coefficient

See Also:

setAttenuation

getQuadraticAttenuation

public float getQuadraticAttenuation()

Retrieves the current quadratic attenuation coefficient for this Light.

Returns:

the current quadratic attenuation coefficient

See Also:

setAttenuation