Encapsulates the creation, deletion and manipulation of a spot light.
#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);
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.
Constructs an AlSpotLight wrapper object.
Deletes an AlSpotLight wrapper object.
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.
sSuccess - everything was successful
sInsufficientMemory - not enough memory available
Returns the class identifier, kSpotLightType.
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.
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.
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.
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.
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.
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.
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.
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).
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.
< double newDropoff - is the new dropoff value
sSuccess - setting dropoff succeeded
sInvalidObject - not a valid spot light
sFailure - an error occurred
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.
< double newMinBias - is the new minimum bias value
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
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.
< double newMaxBias - is the new maximum bias value
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
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.
< double newSpreadAngle - is the new spread angle
sSuccess - setting spread angle succeeded
sInvalidObject - not a valid spot light
sInvalidArgument - spread angle was less than 0
sFailure - an error occurred
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.
< double newOffset - is the new offset value
sSuccess - setting the offset succeeded
sInvalidObject - not a valid spot light
sFailure - an error occurred
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.
< int newMultFactor - is the new multiplication factor
sSuccess - setting the multiplication factor succeeded
sInvalidObject - not a valid spot light
sFailure - an error occurred
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.
< int newShadowSize - is the new shadow size
sSuccess - setting the shadow size succeeded
sInvalidObject - not a valid spot light
sFailure - an error occurred
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).
< double newPenumbraAngle - is the new penumbra angle
sSuccess - setting the prenumbra succeeded
sInvalidObject - not a valid spot light
sFailure - an error occurred
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.
> 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
sSuccess - getting the direction succeeded
sInvalidObject - not a valid spot light
sFailure - an error occurred
Sets the direction of the spotlight as a vector in x, y, z by altering the position of the lookat node.
> 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
sSuccess - setting the direction succeeded
sInvalidObject - not a valid spot light
sFailure - an error occurred