Aviatrix3D
2.0 Dev

org.j3d.aviatrix3d
Class Light

java.lang.Object
  extended byorg.j3d.aviatrix3d.SceneGraphObject
      extended byorg.j3d.aviatrix3d.Node
          extended byorg.j3d.aviatrix3d.Leaf
              extended byorg.j3d.aviatrix3d.Light
All Implemented Interfaces:
java.lang.Comparable, Renderable, RenderableComponent
Direct Known Subclasses:
AmbientLight, DirectionalLight, PointLight, SpotLight

public abstract class Light
extends Leaf
implements RenderableComponent

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.

Scoping Rules

Because lights can be very expensive to render, and real lights don't effect everything, lights are typically limited in their effects by scoping rules. The default scoping of lights is to only light anything that is under the light's parent group. Any object in a scenegraph path outside that parent group is not effected by this light instance. Even if the light is part of a shared scene graph, only the shared sections of the scenegraph are effected, not all of the world.

The default scoping rules can be modified through the use of several attributes of this class. They may be global, scoped to the parent grouping structure and/or limited to some specific set of bounds. A global light will effect everything in the scenegraph for this layer. It's position is determined from the transformation heirarchy to this node (or multiples if it is part of a shared scene graph). A bounds scoping allows the user to provide an instance of a BoundingVolume object that defines how the light is to effect geometry. The bounding volume is defined in the local coordinate space of this light. Any geometry that is potentially effected by this light then has its bounds checked for intersection with this light's bounds. If any part of the bounds are found to intersect, then the light is applied to that geometry. Note that this does not imply that only the geometry that intersects with the light's bounds has lighting applied - all the geometry will be lit if any part of the two bounds intersect.

Bounds and global scope can be used together. If the light is set to global scope, and a bounds is set, then the culling will check to see if each item of geometry intersects it's bounds with the bounds of the global light. If there is no interesection, the light is not applied to that geometry. If intersection occurs, the object is lit using the global light.

If the bounds of the light are set to BoundingVoid, it is treated as being off, regardless of any other setting.

All lighting effects are scoped to be local to the scene that they're included in. Lights do not bleed across layers or viewports.

Rendering Implementation Tips

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

Version:
$Revision: 1.19 $
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 globalScope
          Flag indicating whether this should be a global (true) or locally-scoped light (false).
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_NOT_LIVE_MESSAGE, updateHandler, WRITE_TIMING_MSG
 
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.
 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(int bufferId)
          Get the Renderable instance needed to process this object for the given buffer ID.
 void getSpecularColor(float[] col)
          Retrieve the current colour value from the light.
 boolean isEnabled()
          Get the current enabled state of the light.
 boolean isGlobalScope()
          Get the current state of whether this light should have a global scope or not.
 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 setGlobalScope(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, setBounds, setLive, setParent, updateBounds, updateParentBounds
 
Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject
checkForCyclicChild, dataChanged, getUserData, isLive, 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.RenderableComponent
postRender, render
 
Methods inherited from interface org.j3d.aviatrix3d.Renderable
equals
 

Field Detail

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


globalScope

protected boolean globalScope
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 globalScope 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

getRenderable

public Renderable getRenderable(int bufferId)
Get the Renderable instance needed to process this object for the given buffer ID.

Overrides:
getRenderable in class Leaf
Parameters:
bufferId - The ID of the buffer for the renderable to encapsulate
Returns:
The renderable object, or null if nothing to render

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

isEnabled

public boolean isEnabled()
Get the current enabled state of the light.

Returns:
The current state

setGlobalScope

public void setGlobalScope(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

isGlobalScope

public boolean isGlobalScope()
Get the current state of whether this light should have a global scope or not.

Returns:
true for global effects, false otherwise.

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

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.

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

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 callback method
InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener 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

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

Aviatrix3D
2.0 Dev

Latest Info from http://aviatrix3d.j3d.org/
Copyright © 2003 - 2005 j3d.org