Encapsulates
methods common to all lights.
Synopsis
#include <AlLight.h>
class AlLight : public AlObject , public AlAnimatable
virtual ~AlLight();
virtual statusCode deleteObject();
virtual AlObjectType type() const;
virtual const char* name() const;
virtual statusCode setName( const char* );
statusCode parameter( const AlLightFields, double& ) const;
statusCode setParameter( const AlLightFields, const double );
AlLightNode* lightNode() const;
virtual AlLightNode* lookAtNode() const;
virtual AlLightNode* upNode() const;
boolean hasLinkedObjects() const;
AlObject* firstLinkedObject() const;
AlObject* nextLinkedObject( AlObject * ) const;
statusCode applyIteratorToLinkedObjects( AlIterator *iter, int& rc );
statusCode linkObjectToLight( AlObject * );
statusCode unlinkObjectFromLight( AlObject * );
boolean exclusivity() const;
statusCode setExclusivity( boolean );
statusCode color( double&, double&, double& ) const;
statusCode setColor( double, double, double );
statusCode worldPosition( double&, double&, double& ) const;
Description
This virtual class contains
methods which are common to all types of lights. This includes color,
linkage to objects and exclusivity.
To create a light, the
user must instantiate and call the create method of a specific type
of light (eg. a point light or a spot light). When a light is created,
three light nodes are created, grouped under a group node, which
is inserted into the universe’s DAG. These light nodes represent
the position, "look at" and "up" points of the light.
Even though three light
nodes are created for all lights, only the spot light class uses
the information in the "look at" and "up" nodes. All other classes
either don’t have a direction or store direction in a different
manner. The direction vector of a spot light is the vector between
its position point and its "look at" point. The "up" direction
vector of a spot light is the vector between its position point
and its "up" point.
There are two ways to
delete a light object. When an AlLight object is deleted, its three light
nodes are deleted. Alternatively, when a light node is deleted,
its associated light (and other light nodes) are deleted. The group
node that originally grouped the position, "look at" and "up" nodes
is not deleted.
The light classes are
derived as follows, where a class inherits the functionality defined in
the class above it. The user can only instantiate ambient, point,
direction, spot, linear and area lights.
For directional lights,
the light positions are (in Z-up coordinate system) position at (0,0,0),
view at (0,0,-1), and up at (0,1,-1). For linear lights, the axis
by default starts at the position point and extends (2,0,0). For
area lights, the short axis starts at the position point and extends
(0,1,0); the long axis starts at the position point and extends
(2,0,0).
All lights have an "exclusive"
flag. If this flag is TRUE, then the light will only illuminate objects
to which it is linked. If the flag is FALSE, the light will illuminate
objects that have no light links. The default for new lights is
FALSE.
AlLight::~AlLight()
Description
Deletes an AlLight wrapper object.
statusCode AlLight::deleteObject()
Description
Deletes
the light’s associated nodes (for position, look at and up) and
deletes the light. A light can be deleted in two ways. If AlLight::deleteObject()
is called, it deletes the associated AlLightNodes.
If AlLightNode::deleteObject()
is called, it deletes the associated AlLight.
Return Codes
sSuccess - the light
and its associated light nodes were deleted
sInvalidObject - light
was invalid
sFailure - the light
could not be deleted
AlObjectType AlLight::type()
const
Description
Returns
the class identifier, which could be any one of kAmbientLightType,
kAreaLightType, kSpotLightType, kPointLightType, kDirectionLightType,
kLinearLightType.
const char* AlLight::name()
const
Description
Returns
a pointer to this light’s name.
statusCode AlLight::setName(const
char *newName)
Description
Changes the camera DAG node’s name to
the given name. If the given name is not unique, then a unique name
is generated based on the given name and assigned to the camera.
In this case, a status code of sNameChangedToUniqueOne is returned.
Arguments
< cost char* newName
- the name to be assigned to this light
Return Codes
sSuccess - everything
was successful
sInsufficientMemory -
not enough memory available
sInvalidObject - the
light was invalid
sNameChangedToUniqueOne
- the object’s name was changed to be a unique version of the given
name
statusCode AlLight::parameter(
const AlLightFields field, double& result ) const
Description
Finds
the value of a given light field.
Arguments
< field - light field
type
> result - returned
result of the field
Return code
sSuccess - field was
returned
sInvalidArgument - field
was not legal for this light
sFailure - field could
not be returned
sInvalidObject - the
light was invalid
statusCode AlLight::setParameter(
const AlLightFields field,const double value)
Description
Changes
the value of the light field. If the given field is not valid then
a status code of sFailure is returned.
Arguments
< field - light field
type
< value - new value
that the light field is to take
Return Codes
sSuccess - field was
changed
sInvalidArgument - field
was not legal for this light
sFailure - field could
not be changed
sInvalidObject - the
light was invalid
AlLightNode *AlLight::lightNode()
const
Description
Returns
a pointer to the DAG node that represents the light’s position.
AlLightNode *AlLight::lookAtNode()
const
Description
Returns
a pointer to the ’look at’ node attached to this light. This method
does not apply to all lights (eg. a point light doesn’t have a ’look
at’ direction).
AlLightNode *AlLight::upNode()
const
Description
Returns
a pointer to the ’up’ node attached to this light. This method
doesn’t apply to all lights (eg. a point light doesn’t have a ’up’
direction).
statusCode AlLight::color(
double &r, double &g, double &b) const
Description
Returns
the color of the light in r,g & b, (for red, green and blue).
Valid values for r,g & b are between 0.0 and 255.0.
Arguments
> r - is the current
red value of the light
> g - is the current
green value of the light
> b - is the current
blue value of the light
Return Codes
sSuccess - color retrieved
sInvalidObject - object
is invalid
boolean AlLight::exclusivity()
const
Description
Returns
TRUE if the exclusive flag of this light is TRUE. Otherwise, returns
FALSE. If a light’s exclusive flag is TRUE, then the light will
only illuminate objects to which it is linked. If the flag is FALSE,
the light will illuminate objects that have no light links. Default
is FALSE.
statusCode AlLight::setColor(
double r, double g, double b)
Description
Sets the color of the
light to be r,g & b (for red, green and blue). Valid values
for r,g & b are between 0.0 and 255.0.
Arguments
< r - is the new red
value
< g - is the new green
value
< b - is the new blue
value
Return Codes
sSuccess - the color
was set
sInvalidObject - invalid
light
sInvalidArgument - color
out of range
boolean AlLight::hasLinkedObjects()
const
Description
Returns
TRUE if this light has any objects linked to it. Otherwise, returns
FALSE.
AlObject* AlLight::firstLinkedObject()
const
Description
Returns
a pointer to the first object that is linked to this light. If there
are no objects linked to this light, then NULL is returned. Only
objects with 3D geometry can be linked to a light. Cameras, lights,
curves and CVs cannot be linked to a light. Surfaces and faces can be
linked to a light.
AlObject* AlLight::nextLinkedObject(
AlObject* toThis ) const
Description
Returns a pointer to the object
following the given object that is linked to this light. NULL is
returned if there is no following object. NULL is returned if the
given AlObject wasn’t found in the light list. Only objects with
3D geometry can be linked to a light. Cameras, lights, curves and
CVs cannot be linked to a light. Surfaces and faces can be linked
to a light.
Arguments
< toThis - the object
whose following linked object is returned.
statusCode AlLight::applyIteratorToLinkedObjects(
AlIterator *iter, int& rc )
Description
Applies an iterator
to each linked object.
Arguments
< iter - the iterator
to apply
> rc - the return
value of the last application of the iterator
Return Codes
sSuccess - the iterator
was successfully applied to each object
sInvalidArgument - ’iter’
was NULL
statusCode AlLight::linkObjectToLight(
AlObject *obj )
Description
Links the given object to the light.
If the light’s exclusive flag is on, then the light will only illuminate
objects to which it is linked. Only objects with 3D geometry can
be linked to a light. Cameras, lights, curves and CVs cannot be
linked to a light. Surfaces, faces, and shells can be linked to
a light.
Arguments
< obj - the object
to link to the light
Return Codes
sSuccess - linking object
to this light was successful
sAlreadyCreated - this
object was already linked to this light
sInvalidObject - light
is invalid
sInvalidArgument - object
was NULL or not a face, surface, or shell
statusCode AlLight::unlinkObjectFromLight(
AlObject *obj )
Description
Unlinks the given object from the light.
If the light’s exclusive flag is on, then the light will only illuminate
objects to which it is linked.
Arguments
< AlObject *obj -
the object to link to the light
Return Codes
sSuccess - linking object
to this light was successful
sObjectNotFound - this
object wasn’t linked to this light
sInvalidObject - light
is invalid
sInvalidArgument - object
was NULL or not a face, surface, or shell
statusCode AlLight::setExclusivity(
boolean newExclusive )
Description
Sets the exclusive flag of this
light. If a light’s exclusive flag is TRUE, then the light will only
illuminate objects to which it is linked. If the flag is FALSE,
the light will illuminate objects that have no light links. Default
is FALSE.
Arguments
< newExclusive - is
the new value of the exclusive flag
Return Codes
sSuccess - exclusivity
set
sInvalidObject - object
invalid
statusCode AlLight::worldPosition(
double &x, double &y, double &z ) const
Description
Returns the
point in world space where this light is positioned. This is the
same as the position of the position light node.
Arguments
> x - the x coordinate
of the light position
> y - the y coordinate
of the light position
> z - the z coordinate
of the light position
Return Codes
sSuccess - world Position
retrieved
sInvalidObject - object
invalid
sFailure - an error occurred
