AlVolumeLight

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