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.
double AlSpotLight::dropOff() const
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::spreadAngle() const
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
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
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
int AlSpotLight::shadowSize() const
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
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 )
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.
statusCode AlSpotLight::setMinBias( double newMinBias )
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.
statusCode AlSpotLight::setMaxBias( double newMaxBias )
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.
statusCode AlSpotLight::setSpreadAngle( double newSpreadAngle )
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.
statusCode AlSpotLight::setOffset( int newOffset )
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.
statusCode AlSpotLight::setMultFactor( int newMultFactor )
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
statusCode AlSpotLight::setShadowSize( int newShadowSize )
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.
statusCode AlSpotLight::setPenumbra( double newPenumbraAngle )
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).
statusCode AlSpotLight::direction( double &x, double &y, double &z ) const
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.
statusCode AlSpotLight::setDirection( double x, double y, double z )
Sets the direction of the spotlight as a vector in x, y, z by altering the position of the lookat node.
