AlTexture

Synopsis

#include <AlTexture.h>

class AlTexture : public AlObject,

virtual	~AlTexture();

virtual statusCode	deleteObject();

virtual AlObject	*copyWrapper() const;

virtual AlObjectType	type() const;

virtual const char*	name() const;

virtual statusCode	setName(const char *);

AlTexture*	firstTexture() const;

AlTexture*	nextTexture( const AlTexture* ) const;

statusCode	nextTextureD( AlTexture* );

const char*	textureType() const;

const char*	fieldType() const;

statusCode	parameter( const AlShadingFields, double& ) const;

statusCode	setParameter( const AlShadingFields, const double );

/* this section is only for file textures */

const char*	filename() const;

statusCode	setFilename( const char* );

const char*	firstPerObjectPixEntry();

const char*	nextPerObjectPixEntry( const char *);

const char*	getPerObjectPixFilename( const char*) const;

statusCode	setPerObjectPixFilename( const char*, const char*);

statusCode	addPerObjectPixEntry( const char*, const char*);

statusCode	removePerObjectPixEntry( const char* );

boolean	isParametric( void ) const;

statusCode	eval( double, double, double, double, double, double, double, double, double, double, double*, double*, double*, double*, boolean = TRUE, double = 1.0, double = 0.0, char *objectname = NULL ) const;

AlList*	fields() const;

AlList*	mappedFields() const;

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

statusCode	removeTexture( const char* );

AlTextureNode*	textureNode() const;

statusCode	applyIteratorToTextures( AlIterator*, int& );

/* for environment textures only */

statusCode	environmentPixMap( AlPixel *, int, boolean );

Description

Encapsulates the basic functionality for checking and setting the name of a texture as well as accessing the textures that this texture refers to, and the animation on this texture. These texture objects can be obtained from the AlShader class and the AlEnvironment class.

A texture object itself may also reference other textures. For this reason the firstTexture() and nextTexture() methods are used.

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

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

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

New AlTextures cannot be created by allocating a new AlTexture object because an AlTexture must be associated with a shader. Use the AlShader::addTexture() method to create the new AlTexture.

AlTexture::~AlTexture()

Description

Deletes an AlTexture wrapper object.

statusCode AlTexture::deleteObject()

Description

Deletes the AlTexture and the AlTextures hanging off of the texture. If an AlTextureNode is attached to this texture, it will be deleted as well. Note that after this operation any pointers to AlTextures that had been part of this texture will no longer be valid.

Return Codes

sSuccess - the object was deleted

sInvalidObject - the object is invalid

sFailure - the object could not be deleted

AlObject *AlTexture::copyWrapper() const

Description

Returns an exact duplicate of this AlTexture wrapper.

AlObjectType AlTexture::type() const

Description

Returns the class identifier ’kTextureType’.

const char* AlTexture::name() const

Description

Returns the name of the texture.

statusCode AlTexture::setName( const char *newName )

Description

Changes the name of the texture to a new name. If the given name is not a unique one or contains illegal characters, then a unique name is generated based on the given name and assigned to the texture. 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

sFailure - the name was not set

sInvalidArgument - the name was NULL

sInvalidObject - the texture is invalid

sNameChangedToUniqueOne - name was changed to be a unique version of the given name

AlTexture* AlTexture::firstTexture() const

Description

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

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

Description

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

Arguments

< last_texture - Texture from which to walk forward

statusCode AlTexture::nextTextureD( AlTexture* last_texture )

Description

Destructively points the given texture wrapper to the next texture.

Arguments

< last_texture - texture from which to walk forward

Return Codes

sSuccess - the wrapper now points to the next object in the list

sFailure - there is no next texture

sInvalidObject - the texture is invalid

sInvalidArgument - the given texture is invalid

const char* AlTexture::textureType() const

Description

Returns a string which indicates the "name" of the texture type. Note that these strings are identical to those output to SDL.

const char* AlTexture::fieldType() const

Description

Returns a string which indicates which field of the parent object (AlShader, AlTexture, AlEnvironment) that this texture is mapped to. Note that the returned strings are identical to the field names written out to SDL. The SDL manual gives a complete list of possible return values for this function.

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

Description

Finds the value of a given texture field.

Arguments

< field - texture field type

> result - returned result of the field

Return Codes

sSuccess - field was returned

sInvalidArgument - field was not legal for this texture

sFailure - field could not be returned

sInvalidObject - the texture is invalid

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

Description

Changes the value of the texture field.

Arguments

< field - texture field type

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

Return Codes

sSuccess - field was changed

sInvalidArgument - field was not legal for this texture

sFailure - field could not be changed

sInvalidObject - the texture is invalid

const char* AlTexture::filename() const

Description

If the texture is a file texture, this method returns the path and name to the image file used for the texture. If the texture is any other type, NULL is returned.

statusCode AlTexture::setFilename(const char* filename)

Description

If the texture is a file texture, this method sets the path and name to the image file used for the texture. If the texture is any other type, sFailure is returned. Note that the string provided is duplicated, so you are responsible for the space allocated for the original copy.

Arguments

< filename - the filename to set in the texture

Return Codes

sSuccess - the path name was set

sFailure - the name was not set

sInvalidObject - the texture is invalid

const char* AlTexture::firstPerObjectPixEntry()

Description

If the texture is a file texture, this method returns the name of the first object in the Per Object Pix list of the file texture. If the list is empty, or if the texture is not a file texture, then NULL is returned.

const char* AlTexture::nextPerObjectPixEntry( const char* prev_objname )

Description

If the texture is a file texture and the objname is in the per object pix file list of the texture, this method returns the name of the next object after prev_objname. If no such object exists, or if the texture is not a file texture, then NULL is returned.

const char* AlTexture::getPerObjectPixFilename( const char* objname ) const

Description

If the texture is a file texture and the objname is in the "per object pix file" list of the texture, this method returns the image file used for the objname object (object meaning an Alias geometry). If the object is not in the list, then the image file used will be AlTexture::filename() which contains the texture that is applied to all objects that are not specifically mentioned in the "per object pix file" list. If the return value of getPerObjectPixFilename() is NULL, then the object is not textured.

Arguments

< objname - the name of the object to query for a filename

statusCode AlTexture::setPerObjectPixFilename( const char* objname,const char* filename )

Description

If the texture is a file texture and the objname exists in the per obj pix list, this method sets the name of the image file use for that object (object in the sense of an Alias geometry). Otherwise, sFailure is returned (not file texture or object doesn’t exist). The filename string is duplicated, so you are responsible for the space allocated for the original copy

Arguments

< objname - name of the object whose filename is to be set

< filename - the name of the image to fill objname’s filename field

Return Codes

sSuccess - the path name was set

sFailure - the name was not set

sInvalidObject - the texture is invalid

statusCode AlTexture::addPerObjectPixEntry( const char* objname,const char* filename )

Description

If the texture is a file texture, this method adds a per object pix entry to the texture. If the texture is any other type, sFailure is returned. If the objname object is not already in the per object pix entry list, it is added. If the objname object does exist in the list, its filename field is modified to contain the given filename.

Arguments

< objname - name of the object whose filename is to be set

< filename - the name of the image to fill objname’s filename field

Return Codes

sSuccess - the path name was set

sFailure - the name was not set

sInvalidObject - the texture is invalid

statusCode AlTexture::removePerObjectPixEntry( const char* objname )

Description

If the texture is a file texture and the objname object is found in the per object pix list, this method will delete that item from the per object pick list. If the texture is not a file texture, sFailure is returned.

Arguments

< objname - specifies the name of the object in the per object pix list to delete

Return Codes

sSuccess - the path name was set

sFailure - the name was not set

sInvalidObject - the texture is invalid

boolean AlTexture::isParametric() const

Description

Indicates whether the texture is a parametric texture or a solid/environment texture. TRUE is returned if the texture is parametric.

AlList* AlTexture::fields() const

Description

Returns an AlList of AlShadingFieldItems, each of which contains an AlShadingFields value valid for this texture.

AlList* AlTexture::mappedFields() const

Description

Returns an AlList of AlMappedFieldItems, each of which contains a character string identifier identifying a field on this texture that 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 AlTexture::removeTexture( const char* fieldName )

Description

Removes a texture to a particular field of the AlTexture. The first argument is the name of the field that will have the texture applied to it. Only those fields valid for this texture 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 removed successfully

sFailure - there was no texture on the field

sInvalidObject - the texture is invalid

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

sInvalidArgument - the argument was not valid for the texture

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

Description

Adds a texture to a particular field of the AlTexture. The first argument is the name of the field which will have the texture applied to it. Only those fields valid for this texture 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

sInvalidObject - the texture is invalid

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

sInvalidArgument - either argument was not valid for the texture

AlTextureNode* AlTexture::textureNode() const

Description

Returns a pointer to the transformation AlTextureNode on solid textures. If the texture is not a solid texture or there is no AlTextureNode, this method returns NULL.

statusCode AlTexture::eval( double u, double v, double x, double y, double z, double nx, double ny, double nz, double usize, double vsize, double *r, double *g, double *b, double *a, boolean initialize, double blurmult, double bluroffset, char *objectname ) const

Description

Evaluates a texture at the passed location. The initialize flag specifies whether the texture transforms should be initialized. Note that this is a costly operation, so initialize only when necessary, generally on the first call.

This routine allows you to find out for a given location what color the texture would return if that location was shaded by the renderer. The location of the color is specified by either u, v coordinates in parametric space for a 2D texture, or x, y, z coordinates in world space for a 3D texture

As some textures also require the normal at that point to be provided the user supplies the normal in the nx, ny, and nz fields. The usize and vsize are used to express the extent of the point in parametric space. This has the effect of blurring the texture with larger usize,vsize.

The value is returned in *r, *g, *b, *a. This is a color value. The *r, *g, *b, *a values should be set before calling Eval to the color you wish returned if the texture is not to be applied (for instance if the texture alpha value is 0).

The blurmult and bluroffset fields specify the amount of blurring to apply to the texture as per the controls in the interactive package.

The object name field is used to determine which texture should be used in file type textures that have more than one specific object/texture file pair. These textures may typically be created using Alias paint features.

Arguments

< u, v - specify the parametric location at the evaluated point

< x, y, z - specify the world space location at the evaluated point

< nx, ny, nz - specify the normal at the evaluated point

< usize, vsize - specify the parametric extent of the point

< > *r, *g, *b, *a - will contain the resultant color

< initialize - initialize this texture. Must be initialized before first use.

< blurmult - how much to blur the sample by

< bluroffset - how much to offset the blur by

< objectname - optionally, the name of the object being textured. Used to texture objects using file textures with per object texture maps.

Return Codes

sSuccess - the texture was evaluated successfully

sFailure - the texture was not evaluated

sInvalidObject - the texture is invalid

sInvalidArgument - one of the pointer arguments was NULL

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

Description

Applies the given AlIterator to all textures in the texture. 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 - a pointer to the iterator

> rc - the result 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 texture is invalid

statusCode AlTexture::environmentPixMap( AlPixel *pixArray, int resolution, boolean imageMap )

Description:

Converts an environment texture to a square pix map. The AlPixel structure can be used in conjunction with the AlPixFile class to output the pix file.

Note: if this texture is not an environment map, this method will fail.

Arguments:

< pixArray - AlPixel array of size resolution * resolution

< resolution - row/column size of the pix array

< imageMap -

Return Codes:

sSuccess - the pix array was set

sFailure - internal failure

sInvalidArgument - pixArray is NULL or resolution < 0

sInvalidObject - the texture is invalid