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
