AlEnvironment

Synopsis

#include <AlEnvironment.h>

class AlEnvironment : public AlObject,

virtual	~AlEnvironment();

virtual AlObjectType	type() const;

virtual const char*	name() const;

virtual statusCode	deleteObject();

virtual AlObject*	copyWrapper() const;

AlTexture*	firstTexture() const;

AlTexture*	nextTexture( AlTexture* ) const;

statusCode	nextTextureD( AlTexture* ) const;

statusCode	parameter( const AlShadingFields, double& ) const;

statusCode	setParameter( const AlShadingFields, const double );

AlList*	fields() const;

AlList*	mappedFields() const;

statusCode	addTexture( const char*, const char*, AlTexture** = NULL );

statusCode	removeTexture( const char* );

statusCode	applyIteratorToTextures( AlIterator *, int& );

Description

This class encapsulates the basic functionality for checking and setting the name of an environment. It also encapsulates accessing the textures that a particular environment refers to, and the animation on the environment. When the wire file is read, the environment contained therein are created as an AlEnvironment class object. This environment object is accessible through the AlUniverse class.

An environment object may reference textures. The firstTexture and nextTexture methods are used to access these textures.

firstTexture() returns the first texture that the environment object references. nextTexture() moves from a given referenced texture to the next texture in order, as related to the environment object. (See the similar methods for the AlTexture/AlShader classes.)

The animation on the environment can be accessed through the firstChannel() and nextChannel() methods. All the channels on the environment can be deleted by calling deleteAnimation().

The environment parameters can be accessed through the parameter() and setParameter() methods. Each shader has a specific set of parameters that are valid for it that depend on its type. The full list of environment parameters can be seen in the file AlAnim.h. For example, all parameters specific to the Blinn shader have names of the form kFLD_SHADING_BLINN_*. Parameters common to all shaders have the form kFLD_SHADING_COMMON_*. All parameters are treated as doubles even though this may not necessarily be what they are. This is done to make the interface as simple and consistent as possible.

The user can neither create nor destroy an AlEnvironment class object at this time.

AlEnvironment::~AlEnvironment()

Description

Deletes the AlEnvironment wrapper object. It is not possible to delete an environment.

statusCode AlEnvironment::deleteObject()

Description

It is not possible to delete the environment shader. This method always returns sFailure.

Return Codes

sFailure - always returned

AlObject *AlEnvironment::copyWrapper() const

Description

Creates an exact copy of the AlEnvironment wrapper.

AlObjectType AlEnvironment::type() const

Description

Returns the class identifier ’kEnvironmentType’.

const char* AlEnvironment::name() const

Description

Returns the name of the environment shader (it is constant for now).

statusCode AlEnvironment::parameter( const AlShadingFields field, double& result ) const

Description

Finds the value of a given environment field.

Arguments

< field - environment field type

> result - Returned result of the field

Return Codes

sSuccess - the value of the field was returned

sInvalidArgument - the field was not legal for this environment or result was NULL

sFailure - the value of the field could not be returned

sInvalidObject - the environment was invalid

statusCode AlEnvironment::setParameter( const AlShadingFields field,const double value )

Description

Changes the value of the environment field.

Arguments

< field - environment field type

< value - new value that the environment field is to take

Return Codes

sSuccess - the value of the field was changed

sInvalidArgument - the field was not legal for this environment

sFailure - the value of the field could not be changed

sInvalidObject - the environment was invalid

AlTexture* AlEnvironment::firstTexture() const

Description

Returns the first texture that this environment object references. If there are none then NULL is returned.

AlTexture* AlEnvironment::nextTexture( AlTexture* last_texture ) const

Description

Returns the texture after the given one in the environment’s texture list. Specifying NULL as parameter will return the first texture.

Arguments

< last_texture - the texture from which to walk forward

statusCode AlEnvironment::nextTextureD( AlTexture* last_texture ) const

Description

Destructively points ’last_texture’ to the texture after the given one in the shader’s texture list.

Arguments

<> last_texture - the texture from which to walk forward

Return Codes

sSuccess - ’last_texture’ now points to the next texture

sInvalidArgument - ’last_texture’ was not valid or was NULL

sFailure - there is no next texture

sInvalidObject - the environment was invalid

AlList* AlEnvironment::fields() const

Description

Returns an AlList of AlShadingFieldItems, each of which contains an AlShadingFields value valid for this environment. Note that this list is allocated and must be freed using ’delete AlList*’.

AlList* AlEnvironment::mappedFields() const

Description

Returns an AlList of AlMappedFieldItems, each of which contains a character string identifier identifying a field on this environment which may be texture mapped. Note that these strings are identical to the SDL identifiers and the complete list can be found in the SDL manual.

statusCode AlEnvironment::removeTexture( const char* fieldName )

Description

Removes a texture from a particular field of the AlEnvironment. The first argument is the name of the field which will have the texture applied to it. Only those fields valid for this shader should be provided; any others will cause this method to fail. Valid fields are any returned by the fields() method.

Arguments

< fieldName - name of the field which will have the texture removed from it

Return Codes

sSuccess - the texture was added successfully

sFailure - no texture was present

sCannotDelete - a texture already existed on the field which could not be deleted

sInvalidArgument - the argument was not valid for the shader

sInvalidObject - the shader is invalid

statusCode AlEnvironment::addTexture( const char* fieldName, const char* textureName, AlTexture** returnCreatedTexture )

Description

Adds a texture to a particular field of the AlEnvironment. The first argument is the name of the field that will have the texture applied to it. Only those fields valid for this environment should be provided; any others will cause this method to fail. Valid fields are any returned by the fields() method. The second argument is the name of the texture type to apply to the field. The complete list of names is available in the SDL manual.

Arguments

< fieldName - name of the field which will have the texture applied to it

< textureName - name of the texture type to apply to the field returnCreatedTexture - if not NULL, then the created texture is returned

Return Codes

sSuccess - the texture was added successfully

sFailure - the texture was not added

sCannotDelete - a texture already existed on the field which could not be deleted

sInvalidArgument - either argument was not valid for the environment

sInvalidObject - the environment was invalid

statusCode AlEnvironment::applyIteratorToTextures( AlIterator *iter, int &rc )

Description

Applies the given AlIterator to all textures of this environment. The second argument will be set to the return value of the last application of the iterator’s function. See the AlIterator class for more information.

Arguments

< iter - the iterator to apply to each texture

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the application of the iterator terminated normally

sFailure - the application of the iterator terminated abnormally

sInvalidArgument - the iterator was NULL

sInvalidObject - the environment was not valid