Base
object for representing shader data.
Synopsis
#include <AlShader.h>
class AlShader : public AlObject , public AlAnimatable
AlShader();
virtual ~AlShader();
virtual statusCode deleteObject();
virtual AlObject *copyWrapper() const;
statusCode create();
virtual AlObjectType type() const;
virtual const char* name() const;
virtual statusCode setName( const char * );
statusCode parameter( const AlShadingFields, double& ) const;
statusCode setParameter( const AlShadingFields, const double );
statusCode blindData( int, long& , const char*& );
statusCode setBlindData( int, long, const char* );
statusCode removeBlindData( int user_type );
const char* shadingModel() const;
statusCode setShadingModel( const char* );
AlTexture* firstTexture() const;
AlTexture* nextTexture( const AlTexture* ) const;
statusCode nextTextureD( AlTexture* ) const;
AlList* fields() const;
AlList* mappedFields() const;
statusCode addTexture( const char*, const char*, AlTexture** returnedTexture = NULL );
statusCode removeTexture( const char* );
statusCode applyIteratorToTextures( AlIterator*, int& );
AlShader* copyObject();
boolean isUsed();
AlShader* convertSolidToFileTexture( AlDagNode *, int ,boolean , const char * );
AlShader* convertEnvironmentToFileTexture( int , const char *, AlPixFile::Format, boolean );
Description
This class encapsulates
the basic functionality for checking and setting the name of a shader
as well as accessing the textures that a particular shader refers
to, and the animation on the shader. Shader objects are accessible
through both the AlUniverse class and the objects that reference
them (AlSurface and AlFace classes).
A shader object may reference
textures. The firstTexture() and nextTexture() methods are used
to access these textures.
firstTexture() returns
the first texture that the shader object references. nextTexture() moves
from a given referenced texture to the next texture in order, as
related to the shader object. (See the similar methods for the AlTexture/AlEnvironment classes.)
The animation on a shader
can be accessed through the firstChannel() and nextChannel() methods.
All the channels on the shader can be deleted by calling deleteAnimation().
The shader 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 shader parameters can
be seen in the file AlShadingFields.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.
AlShader::AlShader()
Description
Constructs an AlShader wrapper object. Use
the create() method to initialize an AlShader.
AlShader::~AlShader()
Description
Deletes an AlShader wrapper object.
statusCode AlShader::create()
Description
Does
any initialization and allocation of data for an AlShader. Allocates
space for this AlShader and adds it to the global list of shaders
in AlUniverse. The shader is initialized as the Alias default
shader.
Return Codes
sSuccess - creation succeeded
sInsufficientMemory -
not enough memory available
statusCode AlShader::deleteObject()
Description
Deletes
the AlShader and the AlTextures hanging off of the shader. All objects
that were assigned this shader will be assigned the default shader.
Note that after this operation, any pointers to AlTextures that
had been part of this shader will no longer be valid.
Return Codes
sSuccess - shader was
deleted
sFailure - shader was
not deleted
sInvalidObject - the
shader was invalid
AlObject *AlShader::copyWrapper()
const
Description
Returns
an exact duplicate of this AlShader wrapper.
AlObjectType AlShader::type()
const
Description
Returns
the class identifier ’kShaderType’.
const char* AlShader::name()
const
Description
Returns
the name of the shader.
statusCode AlShader::setName(
const char *newName)
Description
Changes the name of the shader
to a new name. If the given name is not a unique one or contains
illegal characters, then a new unique name is generated based on
the given name and assigned to the shader. In this case, a status
code of sNameChangedToUniqueOne is returned. It is illegal for the
new name to be NULL. #, digits, upper case letters, lower case letters,
and _ are valid characters
Arguments
< newName - new name
of the object
Return Codes
sSuccess - name was changed
sInvalidArgument - ’newName’
was NULL
sInvalidObject - the
shader is invalid
sNameChangedToUniqueOne
- name was changed to be a unique version of the given name
sFailure - name was not
changed
statusCode AlShader::parameter(
const AlShadingFields field,double& result )const
Description
Finds
the value of a given shader field.
Arguments
< field - shader field
type
> result - returned
result of the field
Return Codes
sSuccess - field was
returned
sInvalidArgument - field
was not legal for this shader
sFailure - field could
not be returned
sInvalidObject - the
shader is invalid
statusCode AlShader::setParameter(
const AlShadingFields field,const double value )
Description
Changes
the value of the shader field. If the given field is not valid then
a status code of sInvalidArgument is returned.
Arguments
< field - shader field
type
< value - new value
that the shader field is to take
Return Codes
sSuccess - field was
changed
sInvalidArgument - field
was not legal for this shader
sFailure - field could
not be changed
sInvalidObject - the
shader is invalid
const char* AlShader::shadingModel()
const
Description
Returns
a string representing the shading model. The returned string will
be one of BLINN, PHONG, LAMBERT, or LIGHTSOURCE.
statusCode AlShader::setShadingModel(
const char* model )
Description
Tries to set the shading model of
the shader. The model must be one of LIGHTSOURCE, LAMBERT, BLINN,
or PHONG.
Return Codes
sSuccess - the shading
model was successfully set
sInvalidArgument - the
given string is not a shading model
sInvalidObject - the
shader is not valid
AlTexture* AlShader::firstTexture()
const
Description
Returns
the first texture that this shader object references. If there are
none then NULL is returned.
AlTexture* AlShader::nextTexture(
const AlTexture* last_texture ) const
Description
Returns the texture
after the given one in the shader’s texture list. Specifying NULL
as parameter will return the first texture.
Arguments
< last_texture - texture
from which to walk forward
statusCode AlShader::nextTextureD(
AlTexture* last_texture ) const
Description
Destructively points
the last_texture wrapper to the next texture after the given one
in the shader’s texture list.
Arguments
<> last_texture
- texture from which to walk forward
Return Codes
sSuccess - the wrapper
points to the next texture
sInvalidArgument - ’last_texture’
was invalid or NULL
sFailure - there is no
next texture
sInvalidObject - the
shader is invalid
AlList* AlShader::fields()
const
Description
Returns
an AlList of AlShadingFieldItems, each of which contains an AlShadingFields value
valid for this shader.
AlList* AlShader::mappedFields()
const
Description
Returns
an AlList of AlMappedFieldItems, each of which contains a character
string identifier identifying a field on this shader 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 AlShader::removeTexture(
const char* fieldName )
Description
Removes a texture from a particular
field of the AlShader. 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 AlShader::addTexture(
const char* fieldName, const char* textureName, AlTexture** returnCreatedTexture
)
Description
Adds a texture to a particular field of the AlShader.
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. 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.
Note: most of these names
are also found on the widgets themselves (for example, ’sRock’ or
’Fractal’)
For example, to add shaders
to the ’color’ fields, one would use commands such as
shader->addTexture( "color", "sRock" ) shader->addTexture( "color", "Fractal" )
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
- returns the created texture if not NULL
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 shader
sInvalidObject - the
shader is invalid
statusCode AlShader::applyIteratorToTextures(
AlIterator *iter, int &rc )
Description
Applies the given AlIterator
to all textures in the shader. 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
> 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
sInvalidObject - the
shader is invalid
sInvalidArgument - the
iterator was NULL
AlShader *AlShader::copyObject()
Description
Copies
this AlShader returning a pointer to the new copy or NULL if the
copy failed.
boolean AlShader::isUsed()
Description
Returns
TRUE if the shader is being used by another object. Return value
is FALSE otherwise.
statusCode AlShader::blindData(
int user_type, long& size, const char *& data )
Description
Obtains the size and
address of a block of data associated with the object. If there
is no data, then the size will be zero and the address of the data
is NULL.
User_types between 0
and 13099 are reserved. If you would like to reserve a block of "user_types"
please contact us.
Arguments
< user_type - user
type of the data desired
> size - number of
characters in the block of data
> data - address of
the block of data
Return Codes
sSuccess - blind data
retrieved
sFailure - blind data
not retrieved
sInvalidObject - the
polygon was invalid
statusCode AlShader::setBlindData(
int user_type, long size, const char * data )
Description
Associates
a block of data with the object. If a block of data is already associated
with this object and this user_type, the old block is replaced by
a reference to the new block. The old block of data is not deleted.
Arguments
< user_type - user
type of the blind data desired
< size - number of
characters in the block
< data - address of
the block of data
Return Codes
sSuccess - everything
is okay
sInsufficientMemory -
not enough memory to allocate a new block
sFailure - create has
not been called on this object yet
sInvalidObject - the
polygon is invalid
statusCode AlShader::removeBlindData(
int user_type )
Description
Removes the block of
data of the given type from the object.
Note that the user is
still responsible for the memory associated with this block of data.
Arguments
< user_type - user
type of the blind desired
Return Codes
sSuccess - everything
is okay
sFailure - no such blind
data existed
sInvalidObject - the
given object was not valid
AlShader* AlShader::convertSolidToFileTexture(
AlDagNode *dagNode, int resolution, boolean antiAlias, const char
* pixFilename )
Description
If the current shader
has a solid texture, this method copies this shader and converts
the solid texture to a file texture for the specified dag node object.
A pix file is created for the file texture using the resolution
and anti-aliasing parameters specified. On failure, this method
returns NULL.
Notes:
1. Valid resolutions
are 8 .. 1024
2. This method will fail
if either dagNode or pixFilename are NULL
3. dagNode should be
a valid API pointer
Arguments
< dagNode - dag node
that the solid texture is applied to
< resolution - size
of output pix map
< antiAlias - either
TRUE or FALSE
< pixFileName - where
to place the converted file
AlShader* AlShader::convertEnvironmentToFileTexture(int resolution,
const char * pixFilename, AlPixFile::Format pixFmt, boolean imageMap
)
Description
If the current shader
has an environment texture, this method copies this shader and converts
the environment texture to a file texture. A pix file is created
for the file texture using the resolution parameter specified. On
failure, this method returns NULL.
Arguments
< resolution - x &
y size of output pix map
< pixFileName - where
to place the converted file
< map -
