AlLight

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