Encapsulates the creation, deletion and manipulation of a spot light.

Synopsis

#include <AlSpotLight.h>
class AlSpotLight: public AlDirectionLight
AlSpotLight();
virtual    ~AlSpotLight();
virtual AlObject*    copyWrapper() const;
statusCode    create();
AlObjectType    type() const;
double    dropOff() const;
double    minBias() const;
double    maxBias() const;
double    spreadAngle() const;
int    offset() const;
int    multFactor() const;
int    shadowSize() const;
double    penumbra() const;
virtual statusCode    direction( double&, double&, double& ) const;
virtual statusCode    setDirection( double, double, double );
statusCode    setDropOff( double );
statusCode    setMinBias( double );
statusCode    setMaxBias( double );
statusCode    setSpreadAngle( double );
statusCode    setOffset( int );
statusCode    setMultFactor( int );
statusCode    setShadowSize( int );
statusCode    setPenumbra( double);

Description

To create a spot light, the user must instantiate and call the create method on an AlSpotLight object. (For more information on lights in general, see the Class Description of the AlDirectionLight object.)

The spot light is the only light that uses the ’look at’ and ’up’ nodes of a light. The direction vector of a spot light is the vector between the spot light’s position point and ’look at’ point. The up direction vector is the vector between the spot light’s position point and the ’up’ point.

Other spot light parameters that can be manipulated are spread angle, dropoff, shadows, exclusivity, multiplication factor, offset, size, bias, and penumbra.

AlSpotLight::AlSpotLight()

Description

Constructs an AlSpotLight wrapper object.

AlSpotLight::~AlSpotLight()

Description

Deletes an AlSpotLight wrapper object.

statusCode AlSpotLight::create()

Description

Creates all the DAG nodes for this light and adds them to the universe. The DAG nodes are for ’position’, ’look at’ and ’up’, and another DAG node that groups these three together.

Return Codes

sSuccess - everything was successful

sInsufficientMemory - not enough memory available

AlObjectType AlSpotLight::type() const

Description

Returns the class identifier, kSpotLightType.

double AlSpotLight::dropOff() const

Description

Returns the spot light’s dropoff value. Dropoff is the rate at which light intensity decreases from the center to the edge of the spotlight beam. There are no numerical limits. Values of 1.0 and below give practically identical results; that is, no intensity dropoff along the radius of the spotlight beam: all intensity variation is due to basic distance effects and is controlled by decay. Default dropoff value is 0.0.

double AlSpotLight::minBias() const

Description

Returns the spot light’s minimum bias value. Minimum and maximum bias define the range for which each surface point is randomly moved towards the eye before it is determined whether or not it is in a shadow. The minimum must be smaller than the maximum.

double AlSpotLight::maxBias() const

Description

Returns the spot light’s maximum bias value. Minimum and maximum bias define the range for which each surface point is randomly moved towards the eye before it is determined whether or not it is in a shadow. The maximum must be larger than the minimum.

double AlSpotLight::spreadAngle() const

Description

Returns the spot light’s spread angle. This is also referred to as the ’cut off’ value. Valid range is from 0.0 to infinity. Spread angle is the measure in degrees of the angle from the edge to edge of the spotlight’s beam. Resolution problems may occur when the spread is set to a number greater than 170 degrees: some objects are small enough to not produce a shadow with that large a light spread. -1 is returned if the light is not valid.

int AlSpotLight::offset() const

Description

Returns the spot light’s offset value. (This is similar to blur offset for textures.) Offset modifies the sampling region of the depth map. Offset adds a specified amount to the pixel area of the sampling region. The default sampling region is 4 by 4 pixels in the depth map. The formula used to calculate the sample region is:

numPixels = (4 * multFactor) + offset 

The value of numPixels must always be greater than 0. Offset is ignored for spotlights if the shadows flag is FALSE.

int AlSpotLight::multFactor() const

Description

Returns the spot light’s multiplication factor. (This is similar to blur factor for textures.) The multiplication factor is a scaling factor for the size of the sample region for the depth map. Values lower than 0.5 (without using offset) are prone to aliasing and banding. The default sampling region is 4 by 4 pixels in the depth map. The formula used to calculate the sample region is:

numPixels = (4 * multFactor) + offset 

The value of numPixels must always be greater than 0.

int AlSpotLight::shadowSize() const

Description

Returns the spot light’s shadow size. Shadow size defines the resolution of depth maps used to cast shadows when ray casting. Increasing the size will provide more detailed shadows and will also increase the rendering time and amount of memory used. A size of 512 uses 1 Mbyte of memory, 1024 uses 4 Mbytes of memory.

double AlSpotLight::penumbra() const

Description

Returns the spot light’s penumbra angle. Penumbra is used to define how ’sharp’ or ’soft’ the spot light’s edges are. As penumbra angle moves closer to zero (either from the positive or negative side), the spot light edge becomes sharper. As penumbra angle moves away from zero in a positive direction, the edge becomes softer outside of the area defined by the spread angle. If penumbra angle moves in a negative direction, then the edge becomes softer towards the centre of the spot light beam. The penumbra angle should not be less than: -1 * (spreadAngle/2) and should not be more than: (90 degrees - spreadAngle/2).

statusCode AlSpotLight::setDropOff( double newDropoff )

Description

Sets the spot light’s dropoff value. Dropoff is the rate at which light intensity decreases from the center to the edge of the spotlight beam. There are no numerical limits. Values of 1.0 and below give practically identical results; that is, no intensity dropoff along the radius of the spotlight beam: all intensity variation is due to basic distance effects and is controlled by decay. Default dropoff value is 0.0.

Arguments

< double newDropoff - is the new dropoff value

Return Codes

sSuccess - setting dropoff succeeded

sInvalidObject - not a valid spot light

sFailure - an error occurred

statusCode AlSpotLight::setMinBias( double newMinBias )

Description

Sets the spot light’s minimum bias value. To be valid, newMinBias must be smaller than the current max Bias. Minimum and maximum bias define the range for which each surface point is randomly moved towards the eye before it is determined whether or not it is in a shadow. The minimum must be smaller than the maximum.

Arguments

< double newMinBias - is the new minimum bias value

Return Codes

sSuccess - setting min bias succeeded

sInvalidObject - not a valid spot light

sInvalidArgument - new min bias was greater than current max bias

sFailure - an error occurred

statusCode AlSpotLight::setMaxBias( double newMaxBias )

Description

Sets the spot light’s maximum bias value. To be valid, newMaxBias must be larger than the current min Bias. Minimum and maximum bias define the range for which each surface point is randomly moved towards the eye before it is determined whether or not it is in a shadow. The minimum must be smaller than the maximum.

Arguments

< double newMaxBias - is the new maximum bias value

Return Codes

sSuccess - setting max bias succeeded

sInvalidObject - not a valid spot light

sInvalidArgument - new max bias was less than current min bias

sFailure - an error occurred

statusCode AlSpotLight::setSpreadAngle( double newSpreadAngle )

Description

Sets the spot light’s spread angle. This is also referred to as ’cut off’. Valid range is from 0.0 to infinity. Spread angle is the measure in degrees of the angle from the edge to edge of the spotlight’s beam. Resolution problems may occur when the spread is set to a number greater than 170 degrees: some objects will not produce shadows with that large of a spread angle.

Arguments

< double newSpreadAngle - is the new spread angle

Return Codes

sSuccess - setting spread angle succeeded

sInvalidObject - not a valid spot light

sInvalidArgument - spread angle was less than 0

sFailure - an error occurred

statusCode AlSpotLight::setOffset( int newOffset )

Description

Sets the spot light’s offset value. (This is similar to blur offset for textures.) Offset modifies the sampling region of the depth map. Offset adds a specified amount to the pixel area of the sampling region. The default sampling region is 4 by 4 pixels in the depth map. The formula used to calculate the sample region is:

numPixels = (4 * multFactor) + offset 

The value of numPixels must always be greater than 0. Offset is ignored for spotlights if the shadows flag is FALSE.

Arguments

< double newOffset - is the new offset value

Return Codes

sSuccess - setting the offset succeeded

sInvalidObject - not a valid spot light

sFailure - an error occurred

statusCode AlSpotLight::setMultFactor( int newMultFactor )

Description

Sets the spot light’s multiplication factor. (This is similar to blur factor for textures.) The multiplication factor is a scaling factor for the size of the sample region for the depth map. Values lower than 0.5 (without using offset) are prone to aliasing and banding. The default sampling region is 4 by 4 pixels in the depth map. The formula used to calculate the sample region is:

numPixels = (4 * multFactor) + offset 

The value of numPixels must always be greater than 0.

Arguments

< int newMultFactor - is the new multiplication factor

Return Codes

sSuccess - setting the multiplication factor succeeded

sInvalidObject - not a valid spot light

sFailure - an error occurred

statusCode AlSpotLight::setShadowSize( int newShadowSize )

Description

Sets the spot light’s shadow size. Shadow size defines the resolution of depth maps used to cast shadows when ray casting. Increasing the size will provide more detailed shadows and will also increase the rendering time and amount of memory used. A size of 512 uses 1 Mbyte of memory, 1024 uses 4 Mbytes of memory.

Arguments

< int newShadowSize - is the new shadow size

Return Codes

sSuccess - setting the shadow size succeeded

sInvalidObject - not a valid spot light

sFailure - an error occurred

statusCode AlSpotLight::setPenumbra( double newPenumbraAngle )

Description

Sets the spot light’s penumbra angle. Penumbra is used to define how ’sharp’ or ’soft’ the spot light edges are. As penumbra angle moves closer to zero (either from the positive or negative side), the spot light edge becomes sharper. As penumbra angle moves away from zero in a positive direction, the edge becomes softer outside of the area defined by the spread angle. If penumbra angle moves in a negative direction, then the edge becomes softer towards the centre of the spot light beam. The penumbra angle should not be less than: -1 * (spreadAngle/2) and should not be more than: 90 degrees - spreadAngle/2).

Arguments

< double newPenumbraAngle - is the new penumbra angle

Return Codes

sSuccess - setting the prenumbra succeeded

sInvalidObject - not a valid spot light

sFailure - an error occurred

statusCode AlSpotLight::direction( double &x, double &y, double &z ) const

Description

Returns the direction of the spotlight as a vector in x, y, z. The vector returned is really just the vector between the world position of this light and its lookat node.

Arguments

> double &x - is the direction of the light in x

> double &y - is the direction of the light in y

> double &z - is the direction of the light in z

Return Codes

sSuccess - getting the direction succeeded

sInvalidObject - not a valid spot light

sFailure - an error occurred

statusCode AlSpotLight::setDirection( double x, double y, double z )

Description

Sets the direction of the spotlight as a vector in x, y, z by altering the position of the lookat node.

Arguments

> double x - is the direction of the light in x

> double y - is the direction of the light in y

> double z - is the direction of the light in z

Return Codes

sSuccess - setting the direction succeeded

sInvalidObject - not a valid spot light

sFailure - an error occurred