Base object for representing shader data.
#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 );
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.
Constructs an AlShader wrapper object. Use the create() method to initialize an AlShader.
Deletes an AlShader wrapper object.
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.
sSuccess - creation succeeded
sInsufficientMemory - not enough memory available
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.
sSuccess - shader was deleted
sFailure - shader was not deleted
sInvalidObject - the shader was invalid
Returns an exact duplicate of this AlShader wrapper.
Returns the class identifier ’kShaderType’.
Returns the name of the shader.
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
< newName - new name of the object
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
Finds the value of a given shader field.
< field - shader field type
> result - returned result of the field
sSuccess - field was returned
sInvalidArgument - field was not legal for this shader
sFailure - field could not be returned
sInvalidObject - the shader is invalid
Changes the value of the shader field. If the given field is not valid then a status code of sInvalidArgument is returned.
< field - shader field type
< value - new value that the shader field is to take
sSuccess - field was changed
sInvalidArgument - field was not legal for this shader
sFailure - field could not be changed
sInvalidObject - the shader is invalid
Returns a string representing the shading model. The returned string will be one of BLINN, PHONG, LAMBERT, or LIGHTSOURCE.
Tries to set the shading model of the shader. The model must be one of LIGHTSOURCE, LAMBERT, BLINN, or PHONG.
sSuccess - the shading model was successfully set
sInvalidArgument - the given string is not a shading model
sInvalidObject - the shader is not valid
Returns the first texture that this shader object references. If there are none then NULL is returned.
Returns the texture after the given one in the shader’s texture list. Specifying NULL as parameter will return the first texture.
< last_texture - texture from which to walk forward
Destructively points the last_texture wrapper to the next texture after the given one in the shader’s texture list.
<> last_texture - texture from which to walk forward
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
Returns an AlList of AlShadingFieldItems, each of which contains an AlShadingFields value valid for this shader.
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.
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.
< fieldName - name of the field which will have the texture removed from it
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
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" )
< 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
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
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.
< iter - the iterator to apply
> rc - the return value of the last application of the iterator
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
Copies this AlShader returning a pointer to the new copy or NULL if the copy failed.
Returns TRUE if the shader is being used by another object. Return value is FALSE otherwise.
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.
< user_type - user type of the data desired
> size - number of characters in the block of data
> data - address of the block of data
sSuccess - blind data retrieved
sFailure - blind data not retrieved
sInvalidObject - the polygon was invalid
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.
< user_type - user type of the blind data desired
< size - number of characters in the block
< data - address of the block of data
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
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.
< user_type - user type of the blind desired
sSuccess - everything is okay
sFailure - no such blind data existed
sInvalidObject - the given object was not valid
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
< 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
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.
< resolution - x & y size of output pix map
< pixFileName - where to place the converted file
< map -