Base
object for representing shader environment data.
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
