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:

color : 0x00FFFFFF (1.0, 1.0, 1.0)
intensity : 1.0
scope mask : -1
directional : true
spot angle : 180.0
spot exponent : 0.0
attenuation : (1, 0, 0)

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