Data Structures | Typedefs | Functions
Texture Mapping API

Data Structures

struct  AtTextureParams
 Structure that holds all of the available texture map look-up options. More...
 
struct  AtTextureHandle
 Structure that holds a handle for a given texture. More...
 

Typedefs

typedef struct AtTextureParams AtTextureParams
 Structure that holds all of the available texture map look-up options.
 

Functions

AI_API void AiTextureParamsSetDefaults (AtTextureParams *params)
 Initialize an AtTextureParams object with default values. More...
 
AI_API AtTextureHandleAiTextureHandleCreate (const char *filename)
 Create a handle for a given texture filename. More...
 
AI_API AtRGBA AiTextureHandleAccess (const AtShaderGlobals *sg, AtTextureHandle *handle, const AtTextureParams *params, bool *success=NULL)
 Perform a texture look-up through a handle. More...
 
AI_API void AiTextureHandleDestroy (AtTextureHandle *handle)
 Destroy an existing texture handle and its associated resources. More...
 
AI_API AtRGBA AiTextureAccess (const AtShaderGlobals *sg, const char *filename, const AtTextureParams *params, bool *success=NULL)
 Perform a texture look-up through a filename string. More...
 
AI_API bool AiTextureGetResolution (const char *filename, unsigned int *width, unsigned int *height)
 Query resolution info about a texture. More...
 
AI_API bool AiTextureGetNumChannels (const char *filename, unsigned int *num_channels)
 Query the number of channels in the specified image. More...
 
AI_API const char * AiTextureGetChannelName (const char *filename, unsigned int channel_index)
 Query the name of a channel in the specified image. More...
 
AI_API bool AiTextureGetFormat (const char *filename, unsigned int *format)
 Query the format of the specified image. More...
 
AI_API bool AiTextureGetBitDepth (const char *filename, unsigned int *bit_depth)
 Query the bit depth of the specified image. More...
 
AI_API bool AiTextureGetMatrices (const char *filename, AtMatrix world_to_screen, AtMatrix world_to_camera)
 Query the matrices associated with the specified texture. More...
 

Wrapping Modes

Wrap mode describes what happens when texture coordinates describe a value outside the usual [0,1] range where a texture is defined.

#define AI_WRAP_PERIODIC   0x00
 the texture repeats itself outside the [0,1] range in (s,t)-space
 
#define AI_WRAP_BLACK   0x01
 return black outside the [0,1] range
 
#define AI_WRAP_CLAMP   0x02
 clamp to the closest texture edge
 
#define AI_WRAP_MIRROR   0x03
 mirror the image across the boundaries
 
#define AI_WRAP_FILE   0x04
 use the wrap mode found in the file
 

Texture Look-Up/Interpolation Modes

The look-up mode determines how we sample within a mimap level.

#define AI_TEXTURE_CLOSEST   0
 force the closest texel
 
#define AI_TEXTURE_BILINEAR   1
 force bilinear look-up within a mip level
 
#define AI_TEXTURE_BICUBIC   2
 force bicubic look-up within a mip level
 
#define AI_TEXTURE_SMART_BICUBIC   3
 bicubic when maxifying, else use bilinear look-up
 

MIP modes

The MIP mode determines how we sample between mipmap levels.

#define AI_TEXTURE_MIPMODE_DEFAULT   0
 use the default mode (auto-selected)
 
#define AI_TEXTURE_MIPMODE_NONE   1
 use highest-res mip level only
 
#define AI_TEXTURE_MIPMODE_ONE   2
 just use one mip level (closest)
 
#define AI_TEXTURE_MIPMODE_TRILINEAR   3
 trilinear blending of two closest mip levels
 
#define AI_TEXTURE_MIPMODE_ANISOTROPIC   4
 use two closest mip levels with anisotropic filtering
 

Detailed Description

Function Documentation

AI_API void AiTextureParamsSetDefaults ( AtTextureParams params)

Initialize an AtTextureParams object with default values.

The following are the default values:

Parameters
[out]paramsA previously allocated AtTextureParams object that will be filled in with default values
AI_API AtTextureHandle* AiTextureHandleCreate ( const char *  filename)

Create a handle for a given texture filename.

Make sure to release this resource by calling AiTextureHandleDestroy() in the shader's node_finish method.

See Also
AiTextureHandleDestroy()
Parameters
filenameThe name of the texture
Returns
A handle for the texture map
AI_API AtRGBA AiTextureHandleAccess ( const AtShaderGlobals sg,
AtTextureHandle handle,
const AtTextureParams params,
bool *  success 
)

Perform a texture look-up through a handle.

A texture look-up is performed based on the state of the incoming AtShaderGlobals structure. The look-up is performed for the coordinates sg->u and sg->v. The accompanying texture-mapping parameters determine how the look-up is performed, such as the filter/interpolation mode, the mipmap-mode, the wrapping mode, etc...

There are some global options (attached to the 'options' node) which can affect the texturing engine. These are:

  • texture_max_open_files – The maximum number of open files maintained by the texture cache.
  • texture_max_memory_MB – The maximum memory used for the texture cache.
  • texture_searchpath – List of colon-separated optional search paths for locating texture files. Any substring of the form "${FOO}" will replaced by the value of the FOO environment variable.
  • texture_automip – The texture engine will auto-mipmap un-mipmapped files on the fly.
  • texture_autotile – The texture engine will auto-tile any un-tiled images on the fly (this parameter contains the tile size).
  • texture_conservative_lookups – If set to true, then err on the side of blurring as opposed to aliasing.
Parameters
sgThe current shading state associated with the look-up
handleThe texture handle, created through AiTextureHandleCreate()
paramsThe texture mapping parameters structure
[out]successIf non-NULL is passed, the boolean pointed to by this pointer will indicate whether texture access was successful or not. Also, if non-NULL, the function assumes that the user takes control of the error handling and it won't print any error message.
Returns
The color of the texture look-up. In the case of a problem with a look-up, then the color associated with error_color_bad_texture on the 'options' node is returned.
AI_API void AiTextureHandleDestroy ( AtTextureHandle handle)

Destroy an existing texture handle and its associated resources.

Parameters
handleThe handle to destroy
AI_API AtRGBA AiTextureAccess ( const AtShaderGlobals sg,
const char *  filename,
const AtTextureParams params,
bool *  success 
)

Perform a texture look-up through a filename string.

This call is identical to AiTextureHandleAccess() but using a filename string instead of a precomputed texture handle. Because the filename string has to be locked, hashed and mapped to a handle internally anyway, this API is less efficient than its handle-based counterpart. In fact we have seen serious performance degradation when rendering with many threads so we recommend using handles instead. The only situation where it may make sense to use filename-based look-ups is when the filename string is not known in advance and needs to be constructed per shading sample (perhaps coming from a shader network).

Parameters
sgThe current shading state associated with the look-up
filenameThe name of the texture map
paramsThe texture mapping parameters structure
[out]successIf non-NULL is passed, the boolean pointed to by this pointer will indicate whether texture access was successful or not. Also, if non-NULL, the function assumes that the user takes control of the error handling and it won't print any error message in the log file.
Returns
The color of the texture look-up. In the case of a problem with a look-up, then the color associated with error_color_bad_texture on the 'options' node is returned.
AI_API bool AiTextureGetResolution ( const char *  filename,
unsigned int *  width,
unsigned int *  height 
)

Query resolution info about a texture.

Parameters
filenameThe name of the texture
[out]widthThe width of the texture is written here
[out]heightThe height of the texture is written here
Returns
True if the resolution was successfully queried.
AI_API bool AiTextureGetNumChannels ( const char *  filename,
unsigned int *  num_channels 
)

Query the number of channels in the specified image.

Parameters
filenameThe name of the texture
[out]num_channelsThe number of channels in the image
Returns
True if the number of channels were successfully queried.
AI_API const char* AiTextureGetChannelName ( const char *  filename,
unsigned int  channel_index 
)

Query the name of a channel in the specified image.

Parameters
filenameThe name of the texture
channel_indexThe index of the channel
Returns
NULL if the channel doesn't exist, otherwise the name as a string.
AI_API bool AiTextureGetFormat ( const char *  filename,
unsigned int *  format 
)

Query the format of the specified image.

Parameters
filenameThe name of the texture
[out]formatThe pixel format of the image, one of AI_TYPE_UINT, AI_TYPE_INT or AI_TYPE_FLOAT
Returns
True if the format was successfully queried.
AI_API bool AiTextureGetBitDepth ( const char *  filename,
unsigned int *  bit_depth 
)

Query the bit depth of the specified image.

Parameters
filenameThe name of the texture
[out]bit_depthThe bit depth of the pixels in the image. For example, a JPEG image will return a bit depth of 8
Returns
True if the bit depth was successfully queried.
AI_API bool AiTextureGetMatrices ( const char *  filename,
AtMatrix  world_to_screen,
AtMatrix  world_to_camera 
)

Query the matrices associated with the specified texture.

Parameters
filenameThe name of the texture
[out]world_to_screenWorld-to-screen matrix describing the full projection of the 3D view onto a [-1...1]x[-1...1] 2D domain.
[out]world_to_cameraWorld-to-camera matrix describing the camera position
Returns
True if the matrices were successfully queried.

© 2009-2013 Solid Angle SL · all rights reserved · www.solidangle.com