Base object for representing texture data.
#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 );
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.
Deletes an AlTexture wrapper object.
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.
sSuccess - the object was deleted
sInvalidObject - the object is invalid
sFailure - the object could not be deleted
Returns an exact duplicate of this AlTexture wrapper.
Returns the class identifier ’kTextureType’.
Returns the name of the texture.
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
< newName - new name of the object
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
Returns the first texture that this texture object references. If there are none then NULL is returned.
Returns the texture after the given one in the texture’s list of subtextures. Specifying NULL as a parameter will return the first texture.
< last_texture - Texture from which to walk forward
Destructively points the given texture wrapper to the next texture.
< last_texture - texture from which to walk forward
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
Returns a string which indicates the "name" of the texture type. Note that these strings are identical to those output to SDL.
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.
Finds the value of a given texture field.
< field - texture field type
> result - returned result of the field
sSuccess - field was returned
sInvalidArgument - field was not legal for this texture
sFailure - field could not be returned
sInvalidObject - the texture is invalid
Changes the value of the texture field.
< field - texture field type
< value - new value that the texture field is to take
sSuccess - field was changed
sInvalidArgument - field was not legal for this texture
sFailure - field could not be changed
sInvalidObject - the texture is invalid
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.
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.
< filename - the filename to set in the texture
sSuccess - the path name was set
sFailure - the name was not set
sInvalidObject - the texture is invalid
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.
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.
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.
< objname - the name of the object to query for a filename
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
< objname - name of the object whose filename is to be set
< filename - the name of the image to fill objname’s filename field
sSuccess - the path name was set
sFailure - the name was not set
sInvalidObject - the texture is invalid
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.
< objname - name of the object whose filename is to be set
< filename - the name of the image to fill objname’s filename field
sSuccess - the path name was set
sFailure - the name was not set
sInvalidObject - the texture is invalid
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.
< objname - specifies the name of the object in the per object pix list to delete
sSuccess - the path name was set
sFailure - the name was not set
sInvalidObject - the texture is invalid
Indicates whether the texture is a parametric texture or a solid/environment texture. TRUE is returned if the texture is parametric.
Returns an AlList of AlShadingFieldItems, each of which contains an AlShadingFields value valid for this texture.
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.
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.
< fieldName - name of the field which will have the texture removed from it
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
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.
< 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
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
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.
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.
< 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.
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
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.
< iter - a pointer to the iterator
> rc - the result of the last application of the iterator
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
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.
< pixArray - AlPixel array of size resolution * resolution
< resolution - row/column size of the pix array
< imageMap -
sSuccess - the pix array was set
sFailure - internal failure
sInvalidArgument - pixArray is NULL or resolution < 0
sInvalidObject - the texture is invalid