Encapsulates the functionality common to all volume lights.
Synopsis
#include <AlVolumeLight.h>
class AlVolumeLight: public AlLight
virtual ~AlVolumeLight();
virtual AlObject* copyWrapper() const;
virtual AlObjectType type() const;
boolean shadows() const;
boolean specular() const;
boolean turbulenceAnimated() const;
boolean turbulenceDirectional() const;
int turbulenceSpaceRes() const;
int turbulenceTimeRes() const;
double intensity() const;
double decay() const;
double decayStart() const;
double directionality() const;
double concentric() const;
double directional() const;
double radial() const;
double dropoff() const;
double dropoffStart() const;
double turbulenceIntensity() const;
double turbulenceSpread() const;
double turbulencePersistance() const;
double turbulenceGranularity() const;
double turbulenceRoughness() const;
double turbulenceVariability() const;
statusCode setShadows(boolean);
statusCode setSpecular(boolean);
statusCode setTurbulenceAnimated(boolean);
statusCode setTurbulenceDirectional(boolean);
statusCode setTurbulenceSpaceRes(int);
statusCode setTurbulenceTimeRes(int);
statusCode setIntensity( double );
statusCode setDecay(double);
statusCode setDecayStart(double);
statusCode setDirectionality(double);
statusCode setConcentric(double);
statusCode setDirectional(double);
statusCode setRadial(double);
statusCode setDropoff(double);
statusCode setDropoffStart(double);
statusCode setTurbulenceIntensity(double);
statusCode setTurbulenceSpread(double);
statusCode setTurbulencePersistance(double);
statusCode setTurbulenceGranularity(double);
statusCode setTurbulenceRoughness(double);
statusCode setTurbulenceVariability(double);
Description
There are two ways that this class is used. If the user instantiates and calls the create method on an AlVolumeLight, the
resulting object is a box volume light. This light has all the special effects parameters in a cubic volume.
Alternatively, the user could instantiate and create an AlSphereLight, AlCylinderLight, AlTorusLight, AlConeLight or AlBoxLight
(which are all considered "volume" and which are all derived from this light class).
Note that volume lights differ in their shape, the way that their direction components are interpreted with respect to that
shape, and the way that dropoff and decay are applied.
AlVolumeLight::~AlVolumeLight()
Description
Deletes an AlVolumeLight wrapper object.
AlObjectType AlVolumeLight::type() const
Description
Returns the class identifier, kVolumeLightType.
boolean AlVolumeLight::shadows() const
Description
Returns the volume light’s shadow flag (that is, does the light cast shadows). This method returns FALSE if the light is not
valid.
boolean AlVolumeLight::specular() const
Description
Returns the volume light’s specular flag (that is, will this light contribute to specular component). This method returns
FALSE if the light is not valid.
boolean AlVolumeLight::turbulenceAnimated() const
Description
Returns the turbulence Animated flag. If the flag is TRUE, then a 4D turbulence table is built. Otherwise a 3D table is built.
This method returns FALSE if the light is not valid.
boolean AlVolumeLight::turbulenceDirectional() const
Description
Returns the turbulence Directional flag. If the flag is TRUE, then turbulence will be relative to the local light direction.
This method returns FALSE if the light is not valid.
int AlVolumeLight::turbulenceSpaceRes() const
Description
Returns the turbulence space Resolution (the size of the turbulence table in each dimension). -1 is returned if the light
is not valid.
int AlVolumeLight::turbulenceTimeRes() const
Description
Returns the turbulence time Resolution (the size of the turbulence table in time dimension). -1 is returned if the light is
not valid.
double AlVolumeLight::intensity() const
Description
Returns the volume light’s intensity. -1 is returned if the light is not valid.
double AlVolumeLight::decay() const
Description
Returns the volume light’s decay. -1 is returned if the light is not valid.
double AlVolumeLight::decayStart() const
Description
Returns the proportion of the distance from the center where the decay starts. -1 is returned if the light is not valid.
double AlVolumeLight::directionality() const
Description
Returns the volume light’s directionality. -1 is returned if the light is not valid.
double AlVolumeLight::concentric() const
Description
Returns the relative strength of the concentric component of the light. -1 is returned if the light is not valid.
double AlVolumeLight::directional() const
Description
Returns the relative strength of the directional component of the light. -1 is returned if the light is not valid.
double AlVolumeLight::radial() const
Description
Returns the relative strength of the radial component of the light. -1 is returned if the light is not valid.
double AlVolumeLight::dropoff() const
Description
Returns the volume light’s dropoff. -1 is returned if the light is not valid.
double AlVolumeLight::dropoffStart() const
Description
Returns the portion of the distance from the center to where the dropoff starts. -1 is returned if the light is not valid.
double AlVolumeLight::turbulenceIntensity() const
Description
Returns the light’s turbulence intensity. -1 is returned if the light is not valid.
double AlVolumeLight::turbulenceSpread() const
Description
Returns the light’s turbulence spread (space scale). -1 is returned if the light is not valid.
double AlVolumeLight::turbulencePersistance() const
Description
Returns the light’s turbulence Persistence (time scale). -1 is returned if the light is not valid.
double AlVolumeLight::turbulenceGranularity() const
Description
Returns the light’s turbulence granularity (high-pass cutoff). -1 is returned if the light is not valid.
double AlVolumeLight::turbulenceRoughness() const
Description
Returns the light’s turbulence Roughness (low-pass space cutoff). -1 is returned if the light is not valid.
double AlVolumeLight::turbulenceVariability() const
Description
Returns the light’s turbulence Variability (low-pass time cutoff). -1 is returned if the light is not valid.
statusCode AlVolumeLight::setShadows(boolean shadows)
Description
Sets the shadows flag.
Arguments
< shadows - TRUE if shadows are to be cast
Return Codes
sSuccess - setting shadows succeeded
sInvalidObject - not a valid volume light
statusCode AlVolumeLight::setSpecular(boolean specular)
Description
Sets the volume light’s specular flag (that is, will this light contribute to specular component).
Arguments
< specular - TRUE if the light contributes to the specular component
Return Codes
sSuccess - setting specular succeeded
sInvalidObject - not a valid volume light
sFailure - setting failed
statusCode AlVolumeLight::setTurbulenceAnimated(boolean animated)
Description
Sets the turbulence Animated flag.
Arguments
< animated - TRUE if a 4D turbulence table is to be built
- FALSE if a 3D table is to be built
Return Codes
sSuccess - setting the animated succeeded
sInvalidObject - not a valid volume light
sFailure - setting failed
statusCode AlVolumeLight::setTurbulenceDirectional(boolean directional)
Description
Sets the turbulence Directional flag.
Arguments
< directional - TRUE if turbulence is relative to the local light direction
Return Codes
sSuccess - setting the turbulence flag succeeded
sInvalidObject - not a valid volume light
sFailure - setting failed
statusCode AlVolumeLight::setTurbulenceSpaceRes(int space_res)
Description
Sets the turbulence space Resolution.
Note that the product time_res*space_res should be <= 256 or you risk running out of swap space and patience.
Arguments
< space_res - the size of the turbulence table in each direction
Return Codes
sSuccess - setting space resolution succeeded
sInvalidObject - not a valid volume light
sInvalidArgument - space_res out of range 1..32
sFailure - setting failed
statusCode AlVolumeLight::setTurbulenceTimeRes(int time_res)
Description
Sets the turbulence time Resolution.
Note that the product time_res*space_res should be <= 256 or you risk running out of swap space and patience.
Arguments
< time_res - the size of the turbulence table in the time dimension
Return Codes
sSuccess - setting time resolution succeeded
sInvalidObject - not a valid volume light
sInvalidArgument - time_res out of range 1..32
sFailure - setting failed
statusCode AlVolumeLight::setIntensity(double intensity)
Description
Sets the volume light’s intensity.
Arguments
< intensity - the intensity of the light
Return Codes
sSuccess - setting the intensity succeeded
sInvalidObject - the light is not valid
sFailure - setting failed
statusCode AlVolumeLight::setDecay(double decay)
Description
Sets the volume light’s decay (please see the volume light documentation in the Menu Book; this decay is significantly different
from the standard light decay).
Arguments
< decay - the decay of the light (from 0 to 1)
Return Codes
sSuccess - setting decay succeeded
sInvalidObject - not a valid volume light
sInvalidArgument - decay out of range 0..1
sFailure - setting failed
statusCode AlVolumeLight::setDecayStart(double decay_start)
Description
Sets the proportion of the distance from the center to where the decay starts.
Arguments
< decay_start - proportion of the distance from the center to the start
Return Codes
sSuccess - setting decay succeeded
sInvalidObject - not a valid volume light
sInvalidArgument - decay out of range 0..1
sFailure - setting failed
statusCode AlVolumeLight::setDirectionality(double directionality)
Description
Sets the volume light’s directionality.
Arguments
< directionality - this is from 0 to 1
Return Codes
sSuccess - setting directionality succeeded
sInvalidObject - not a valid volume light
sInvalidArgument - the directionality was out of the range 0..1
sFailure - setting failed
statusCode AlVolumeLight::setConcentric(double concentric)
Description
Sets the relative strength of the concentric component of the light.
Arguments
< concentric - relative strength from 0 to 1
Return Codes
sSuccess - setting specular succeeded
sInvalidObject - not a valid volume light
sInvalidArgument - concentric out of range 0..1
sFailure - setting failed
statusCode AlVolumeLight::setDirectional(double directional)
Description
Sets the relative strength of the directional component of the light.
Arguments
< directional - the strength from 0 to 1
Return Codes
sSuccess - setting directional succeeded
sInvalidObject - not a valid volume light
sInvalidArgument - directional out of range 0..1
sFailure - setting failed
statusCode AlVolumeLight::setRadial(double radial)
Description
Sets the relative strength of the radial component of the light.
Arguments
< radial - the strength from 0 to 1
Return Codes
sSuccess - setting radial succeeded
sInvalidObject - not a valid volume light
sInvalidArgument - radial out of range 0..1
sFailure - setting failed
statusCode AlVolumeLight::setDropoff(double dropoff)
Description
Sets the volume light’s dropoff.
Arguments
< dropoff - the dropoff from 0 to 50
Return Codes
sSuccess - setting volume succeeded
sInvalidObject - not a valid volume light
sInvalidArgument - volume out of range 0..50
sFailure - setting failed
statusCode AlVolumeLight::setDropoffStart(double dropoff_start)
Description
Sets the portion of the distance from the center to where the dropoff starts.
Arguments
< dropoff_start - the distance from 0 to 1
Return Codes
sSuccess - setting dropoff succeeded
sInvalidObject - not a valid volume light
sInvalidArgument - dropoff out of range 0..1
sFailure - setting failed
statusCode AlVolumeLight::setTurbulenceIntensity(double intensity)
Description
Sets the turbulence intensity.
Arguments
< intensity - the intensity to set
Return Codes
sSuccess - setting intensity succeeded
sInvalidObject - not a valid volume light
sFailure - setting failed
statusCode AlVolumeLight::setTurbulenceSpread(double spread)
Description
Sets the turbulence spread (on the space scale).
Arguments
< spread - the spread to set
Return Codes
sSuccess - setting spread succeeded
sInvalidObject - not a valid volume light
sFailure - setting failed
statusCode AlVolumeLight::setTurbulencePersistance(double persistance)
Description
Sets the turbulence Persistence (on the time scale).
Arguments
< persistence - persistence to set
Return Codes
sSuccess - setting the Persistence succeeded
sInvalidObject - not a valid volume light
sFailure - setting failed
statusCode AlVolumeLight::setTurbulenceGranularity(double granularity)
Description
Sets the turbulence granularity (high-pass cutoff).
Arguments
< granularity - granularity to set
Return Codes
sSuccess - setting granularity succeeded
sInvalidObject - not a valid volume light
sFailure - setting failed
statusCode AlVolumeLight::setTurbulenceRoughness(double roughness)
Description
Sets the turbulence Roughness (low-pass space cutoff).
Arguments
< roughness - the roughness to set
Return Codes
sSuccess - setting roughness succeeded
sInvalidObject - not a valid volume light
sFailure - setting failed
statusCode AlVolumeLight::setTurbulenceVariability(double variability)
Description
Sets the turbulence Variability (low-pass time cutoff).
Arguments
< variability - the variability to set
Return Codes
sSuccess - setting Variability succeeded
sInvalidObject - not a valid volume light
sFailure - setting failed
