M3G 1.1 -- Jun 22, 2005

javax.microedition.m3g
Class Light

java.lang.Object
  extended byjavax.microedition.m3g.Object3D
      extended byjavax.microedition.m3g.Transformable
          extended byjavax.microedition.m3g.Node
              extended byjavax.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.

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:

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

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

M3G 1.1 -- Jun 22, 2005

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