org.j3d.aviatrix3d
Class Light

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.Node
          org.j3d.aviatrix3d.Leaf
              org.j3d.aviatrix3d.Light

All Implemented Interfaces:

java.lang.Comparable, CascadeRenderable, ComponentRenderable, Cullable, EffectRenderable, LeafCullable, Renderable

Direct Known Subclasses:

AmbientLight, DirectionalLight, PointLight, SpotLight

public abstract class Light
extends Leaf
implements LeafCullable, ComponentRenderable, EffectRenderable

Base representation of a light source that corresponds to the base set of capabilities that all lights in OpenGL have.

By default a light is not enabled and the colour is set to black. Lights also have a secondary specular value that can be provided. By default it is black (ie has no effect). An ambient component can also be provided with this light source in addition to it's derived effects.

Rendering Implementation Tips

The external data passed to the ComponentRenderable calls shall be an Integer instance that represents the GL identifier of the Light (GL_LIGHT0 + i) this instance is working with.

See the EffectRenderable interface for definition of the scoping and effects bounds.

Internationalisation Resource Names

• redComponentRangeMsg: Error message when red component is not [0,1]
• greenComponentRangeMsg: Error message when green component is not [0,1]
• blueComponentRangeMsg: Error message when blue component is not [0,1]
• alphaComponentRangeMsg: Error message when alpha component is not [0,1]

Version:

$Revision: 1.24 $

Author:

Justin Couch

Field Summary

protected static int	AMBIENT_TYPE Internal type to describe that this is a pure ambient light type
protected float[]	ambientColor The colour of the light
protected float[]	diffuseColor The colour of the light
protected static int	DIRECTIONAL_TYPE Internal type to describe that this is a directional light type
protected BoundingVolume	effectBounds A bounding volume used to restrict the scope of what the light effects.
protected boolean	enabled The enabled state
protected boolean	globalOnly Flag indicating whether this should be a global (true) or locally-scoped light (false).
protected static java.lang.String	INVALID_ALPHA_PROP Message when the drawing mode is not a valid value
protected static java.lang.String	INVALID_BLUE_PROP Message when the drawing mode is not a valid value
protected static java.lang.String	INVALID_GREEN_PROP Message when the drawing mode is not a valid value
protected static java.lang.String	INVALID_RED_PROP Message when the drawing mode is not a valid value
protected static int	POINT_TYPE Internal type to describe that this is a point light type
protected float[]	specularColor The colour of the light
protected static int	SPOT_TYPE Internal type to describe that this is a spotlight light type

Fields inherited from class org.j3d.aviatrix3d.Node

bounds, implicitBounds, INVALID_BOUNDS, parent

Fields inherited from class org.j3d.aviatrix3d.SceneGraphObject

alive, LISTENER_SET_TIMING_ERR_PROP, updateHandler

Fields inherited from interface org.j3d.aviatrix3d.rendering.LeafCullable

AUDIO_CULLABLE, CLIP_CULLABLE, FOG_CULLABLE, GEOMETRY_CULLABLE, LIGHT_CULLABLE, OVERRIDE_CULLABLE

Constructor Summary

protected	Light(int type) Creates a light with the colour and specular colour set to black.
protected	Light(int type, float[] diffuse) Create a light with the given base diffuse colour.Colour must be in the range [0, 1] otherwise an exception is generated.

Method Summary

protected int	compareColor3(float[] a, float[] b) Compare 2 color arrays of length 3 for equality
int	compareTo(Light l) Compares this object with the specified object for order.
int	compareTo(java.lang.Object o) Compares this object with the specified object for order.
void	getAmbientColor(float[] col) Retrieve the current colour value from the light.
int	getCullableType() Get the type that this cullable represents.
void	getDiffuseColor(float[] col) Retrieve the current diffuse colour value from the light.
BoundingVolume	getEffectBounds() Get the current bounding volume that this light effects.
Renderable	getRenderable() Get the child renderable of this object.
void	getSpecularColor(float[] col) Retrieve the current colour value from the light.
boolean	isEnabled() Get the current enabled state of the light.
boolean	isGlobalOnly() Get the current setting of the global-only flag.
void	setAmbientColor(float[] col) Set the ambient colour to the new value.
void	setDiffuseColor(float[] col) Set the diffuse colour component to the new value.
void	setEffectBounds(BoundingVolume bounds) Set the bounds that will effect the range of this light.
void	setEnabled(boolean state) Set the enabled state of the light.
void	setGlobalOnly(boolean state) Set the global scope state of the light.
void	setSpecularColor(float[] col) Set the colour to the new value.

Methods inherited from class org.j3d.aviatrix3d.Node

boundsChanged, checkForCyclicParent, getBounds, getParent, markBoundsDirty, recomputeBounds, removeParent, requestBoundsUpdate, setBounds, setParent, updateBounds, updateParentBounds

Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject

checkForCyclicChild, dataChanged, getAppUpdateWriteTimingMessage, getBoundsWriteTimingMessage, getDataWriteTimingMessage, getUserData, isLive, setLive, setUpdateHandler, setUserData

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.j3d.aviatrix3d.rendering.LeafCullable

getBounds

Methods inherited from interface org.j3d.aviatrix3d.rendering.ComponentRenderable

postRender, render

Methods inherited from interface org.j3d.aviatrix3d.rendering.Renderable

equals

Field Detail

INVALID_RED_PROP

protected static final java.lang.String INVALID_RED_PROP

Message when the drawing mode is not a valid value

See Also:

Constant Field Values

INVALID_GREEN_PROP

protected static final java.lang.String INVALID_GREEN_PROP

Message when the drawing mode is not a valid value

See Also:

Constant Field Values

INVALID_BLUE_PROP

protected static final java.lang.String INVALID_BLUE_PROP

Message when the drawing mode is not a valid value

See Also:

Constant Field Values

INVALID_ALPHA_PROP

protected static final java.lang.String INVALID_ALPHA_PROP

Message when the drawing mode is not a valid value

See Also:

Constant Field Values

SPOT_TYPE

protected static final int SPOT_TYPE

Internal type to describe that this is a spotlight light type

See Also:

Constant Field Values

POINT_TYPE

protected static final int POINT_TYPE

Internal type to describe that this is a point light type

See Also:

Constant Field Values

DIRECTIONAL_TYPE

protected static final int DIRECTIONAL_TYPE

Internal type to describe that this is a directional light type

See Also:

Constant Field Values

AMBIENT_TYPE

protected static final int AMBIENT_TYPE

Internal type to describe that this is a pure ambient light type

See Also:

Constant Field Values

ambientColor

protected float[] ambientColor

The colour of the light

diffuseColor

protected float[] diffuseColor

The colour of the light

specularColor

protected float[] specularColor

The colour of the light

enabled

protected boolean enabled

The enabled state

globalOnly

protected boolean globalOnly

Flag indicating whether this should be a global (true) or locally-scoped light (false). By default it is local only.

effectBounds

protected BoundingVolume effectBounds

A bounding volume used to restrict the scope of what the light effects. If this is set, any object that intersects with this bounds will be effected by this light. Deciding what to intersect will depend on the setting of the globalOnly state. The bounds are in the local coordinate system of this light.

Constructor Detail

Light

protected Light(int type)

Creates a light with the colour and specular colour set to black.

Parameters:

type - The type of light that this one is

Light

protected Light(int type,
                float[] diffuse)
         throws java.lang.IllegalArgumentException

Create a light with the given base diffuse colour.Colour must be in the range [0, 1] otherwise an exception is generated.

Parameters:

type - The type of light that this one is

diffuse - The diffuse colour value to use

Throws:

java.lang.IllegalArgumentException - The colour value is out of range

Method Detail

getCullableType

public int getCullableType()

Get the type that this cullable represents.

Specified by:

getCullableType in interface LeafCullable

Returns:

One of the _CULLABLE constants

getRenderable

public Renderable getRenderable()

Get the child renderable of this object.

Specified by:

getRenderable in interface LeafCullable

Returns:

an array of nodes

isEnabled

public boolean isEnabled()

Get the current enabled state of the light.

Specified by:

isEnabled in interface CascadeRenderable

Returns:

The current state

isGlobalOnly

public boolean isGlobalOnly()

Get the current setting of the global-only flag.

Specified by:

isGlobalOnly in interface EffectRenderable

Returns:

true if for global use only, false otherwise

getEffectBounds

public BoundingVolume getEffectBounds()

Get the current bounding volume that this light effects. If the light is to effect everything for infinite distance, then this will return null.

Specified by:

getEffectBounds in interface EffectRenderable

Returns:

A bounding volume if there is to be bounds, null for none.

compareTo

public int compareTo(java.lang.Object o)
              throws java.lang.ClassCastException

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Derived classes should extend this one to add the extra comparisons needed.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - The object to be compared

Returns:

-1, 0 or 1 depending on order

Throws:

java.lang.ClassCastException - The specified object's type prevents it from being compared to this Object

setEnabled

public void setEnabled(boolean state)
                throws InvalidWriteTimingException

Set the enabled state of the light. Can use this to turn it on and off in a general fashion.

Parameters:

state - The new state of the light

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

setGlobalOnly

public void setGlobalOnly(boolean state)
                   throws InvalidWriteTimingException

Set the global scope state of the light. We can use this to turn define whether this light should effect everything or just those scoped to the same group as the parent of this light.

Parameters:

state - The new state of the light

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

setEffectBounds

public void setEffectBounds(BoundingVolume bounds)
                     throws InvalidWriteTimingException

Set the bounds that will effect the range of this light. The bounds are used as a secondary scoping capability to define which objects should or should not be effected based on whether their bounding volumes intersect with this volume. If the light is to effect everything then this value should be set to null, otherwise it defines the bounds in the local coordinate system of the light.

Parameters:

bounds - A volume to use or null to clear

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

setAmbientColor

public void setAmbientColor(float[] col)
                     throws java.lang.IllegalArgumentException,
                            InvalidWriteTimingException

Set the ambient colour to the new value. Colour must be in the range [0, 1] otherwise an exception is generated.

Parameters:

col - The new colour value to use

Throws:

java.lang.IllegalArgumentException - The colour value is out of range

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

getAmbientColor

public void getAmbientColor(float[] col)

Retrieve the current colour value from the light.

Parameters:

col - An array to copy the colour value into

setDiffuseColor

public void setDiffuseColor(float[] col)
                     throws java.lang.IllegalArgumentException,
                            InvalidWriteTimingException

Set the diffuse colour component to the new value. Colour must be in the range [0, 1] otherwise an exception is generated.

Parameters:

col - The new colour value to use

Throws:

java.lang.IllegalArgumentException - The colour value is out of range

InvalidWriteTimingException

getDiffuseColor

public void getDiffuseColor(float[] col)

Retrieve the current diffuse colour value from the light.

Parameters:

col - An array to copy the colour value into

setSpecularColor

public void setSpecularColor(float[] col)
                      throws java.lang.IllegalArgumentException,
                             InvalidWriteTimingException

Set the colour to the new value. Colour must be in the range [0, 1] otherwise an exception is generated.

Parameters:

col - The new colour value to use

Throws:

java.lang.IllegalArgumentException - The colour value is out of range

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener data changed callback method

getSpecularColor

public void getSpecularColor(float[] col)

Retrieve the current colour value from the light.

Parameters:

col - An array to copy the colour value into

compareTo

public int compareTo(Light l)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Parameters:

l - The light instance to be compared

Returns:

-1, 0 or 1 depending on order

compareColor3

protected int compareColor3(float[] a,
                            float[] b)

Compare 2 color arrays of length 3 for equality

Parameters:

a - The first colour array to check

b - The first colour array to check

Returns:

-1 if a[i] < b[i], +1 if a[i] > b[i], otherwise 0