JSR-184 Public Review Draft - Apr. 30, 2003.

javax.microedition.m3d
Class Light

java.lang.Object
  |
  +--javax.microedition.m3d.Object3D
        |
        +--javax.microedition.m3d.Node
              |
              +--javax.microedition.m3d.Light

public class Light
extends Node

The Light node represents different kinds of light sources.

Light sources are used to determine the final color of objects according to their Material attributes, as described in the Material class documentation. 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) its color components. The resulting intensity is used as both the diffuse and the specular component in the lighting calculations.

The position of the light source in the Light's local coordinate system is always (0, 0, 0), and the direction for spot and directional lights is (0, 0, -1). The application can change the position and direction with the node transformation. With directional lights, spot parameters and attenuation are ignored. Note that directional lights are essentially treated as if the light source were positioned infinitely far away in the positive direction of the local Z axis of the Light node.

The set of Nodes affected by a Light can be limited using a scope mask for the Light and scope ID's for the Nodes. Only Lights with a suitable scope mask are considered in the lighting of each Node. If the number of Lights affecting a single Node is greater than the number of concurrent lights the implementation can support N (as reported by Graphics3D.getProperties), the implementation must use a suitable heuristic to select the N lights that have the most effect on the rendered appearance of the Node. This selection must be made separately for each Node. For best results, the implementation may select the lights separately for each submesh of a Node.

See Also:
Binary format, Material

Field Summary
 
Fields inherited from class javax.microedition.m3d.Node
NONE, ORIGIN, X_AXIS, Y_AXIS, Z_AXIS
 
Fields inherited from class javax.microedition.m3d.Object3D
userObject
 
Constructor Summary
Light()
          Constructs a new Light with default values.
 
Method Summary
 int getColor()
          Retrieves the current specular and diffuse color components 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.
 float getQuadraticAttenuation()
          Retrieves the current quadratic attenuation coefficient for this Light.
 int getScopeMask()
          Retrieves the current scope mask for this Light.
 float getSpotAngle()
          Retrieves the current spot angle for this Light.
 float getSpotExponent()
          Retrieves the current spot exponent for this Light.
 boolean isDirectional()
          Queries whether this Light is directional or positional.
 void setAttenuation(float constant, float linear, float quadratic)
          Sets the attenuation coefficients for this Light.
 void setColor(int RGB)
          Sets the specular and diffuse color components of this light.
 void setDirectionalEnable(boolean mode)
          Makes this Light directional or positional.
 void setIntensity(float intensity)
          Sets the intensity of this Light.
 void setScopeMask(int mask)
          Sets the scope mask for 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.m3d.Node
getAlphaFactor, getOrientation, getParent, getScale, getScopeID, getTransform, getTransformTo, getTranslation, isEnabled, setAlignment, setAlphaFactor, setEnable, setOrientation, setScale, setScopeID, setTransform, setTranslation
 
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
 

Constructor Detail

Light

public Light()

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

The default scope mask of -1 (0xFFFFFFFF) implies that this Light will illuminate all Nodes having a nonzero scope ID.

Method Detail

setScopeMask

public void setScopeMask(int mask)

Sets the scope mask for this Light. This Light is only considered in the lighting calculations for a Node if the scope ID of that Node matches with the scope mask. A scope ID is defined to match with a mask if and only if scopeID & mask != 0, where & denotes bitwise AND.

Parameters:
mask - a bitmask specifying which Nodes to illuminate with this Light
See Also:
getScopeMask

getScopeMask

public int getScopeMask()

Retrieves the current scope mask for this Light.

Returns:
the current scope mask
See Also:
setScopeMask

setIntensity

public void setIntensity(float intensity)

Sets the intensity of this Light. Note that while 1.0 is a nominal "full" intensity, many applications will typically use values higher than that for more control over highlights, for example.

Parameters:
intensity - the new light intensity
See Also:
getIntensity

getIntensity

public float getIntensity()

Retrieves the current intensity of this Light.

Returns:
the current light intensity
See Also:
setIntensity

setColor

public void setColor(int RGB)

Sets the specular and diffuse color components of this light. The high order byte of the color value is ignored. The final RGB intensity of the specular and diffuse components is obtained by linearly mapping the color values in [0x00, 0xFF] to [0.0, 1.0] and then multiplying them with the intensity, which is set by setIntensity.

Parameters:
RGB - the new specular and diffuse color in 0x00RRGGBB format
See Also:
getColor

getColor

public int getColor()

Retrieves the current specular and diffuse color components of this Light.

Returns:
the current specular and diffuse color in 0x00RRGGBB format
See Also:
setColor

setDirectionalEnable

public void setDirectionalEnable(boolean mode)

Makes this Light directional or positional. Positional (or point) lights take into account the location of the Light relative to the lighted Node, whereas directional lights do not and are therefore less expensive performance-wise. The spot angle and exponent parameters do not apply for directional lights.

Parameters:
mode - true to make this Light directional; false to make it positional
See Also:
isDirectional

isDirectional

public boolean isDirectional()

Queries whether this Light is directional or positional.

Returns:
true if this Light is directional; false if it's not
See Also:
setDirectionalEnable

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. Setting the spot angle to 180 degrees yields an omnidirectional light that illuminates equally in all directions.

Note that this setting has no effect if this Light is directional.

Parameters:
angle - the spot angle to set
Throws:
java.lang.IllegalArgumentException - if angle is not in [0, 90] or 180
See Also:
getSpotAngle

getSpotAngle

public float getSpotAngle()

Retrieves the current spot angle for this Light.

Returns:
the current spot angle
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, as specified in the OpenGL 1.3 specification, section 2.13.1.

Note that this setting has no effect if this Light is directional, or if the spot angle is set to 180 degrees.

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
See Also:
setSpotExponent

setAttenuation

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

Sets the attenuation coefficients for this Light. Attenuation is considered in the lighting calculations as specified in the OpenGL 1.3 specification, section 2.13.1.

Note that this setting has no effect if this Light is directional.

Parameters:
constant - constant attenuation coefficient
linear - linear attenuation coefficient
quadratic - quadratic attenuation coefficient
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 constant attenuation coefficient
See Also:
setAttenuation

getLinearAttenuation

public float getLinearAttenuation()

Retrieves the current linear attenuation coefficient for this Light.

Returns:
the linear attenuation coefficient
See Also:
setAttenuation

getQuadraticAttenuation

public float getQuadraticAttenuation()

Retrieves the current quadratic attenuation coefficient for this Light.

Returns:
the quadratic attenuation coefficient
See Also:
setAttenuation

JSR-184 Public Review Draft - Apr. 30, 2003.

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