AlShader

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 -