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 AtTextureHandle * | AiTextureHandleCreate (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 | |
AI_API void AiTextureParamsSetDefaults | ( | AtTextureParams * | params | ) |
Initialize an AtTextureParams object with default values.
The following are the default values:
[out] | params | A 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.
filename | The name of the texture |
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.sg | The current shading state associated with the look-up | |
handle | The texture handle, created through AiTextureHandleCreate() | |
params | The texture mapping parameters structure | |
[out] | success | If 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. |
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.
handle | The 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).
sg | The current shading state associated with the look-up | |
filename | The name of the texture map | |
params | The texture mapping parameters structure | |
[out] | success | If 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. |
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.
filename | The name of the texture | |
[out] | width | The width of the texture is written here |
[out] | height | The height of the texture is written here |
AI_API bool AiTextureGetNumChannels | ( | const char * | filename, |
unsigned int * | num_channels | ||
) |
Query the number of channels in the specified image.
filename | The name of the texture | |
[out] | num_channels | The number of channels in the image |
AI_API const char* AiTextureGetChannelName | ( | const char * | filename, |
unsigned int | channel_index | ||
) |
Query the name of a channel in the specified image.
filename | The name of the texture |
channel_index | The index of the channel |
AI_API bool AiTextureGetFormat | ( | const char * | filename, |
unsigned int * | format | ||
) |
Query the format of the specified image.
filename | The name of the texture | |
[out] | format | The pixel format of the image, one of AI_TYPE_UINT , AI_TYPE_INT or AI_TYPE_FLOAT |
AI_API bool AiTextureGetBitDepth | ( | const char * | filename, |
unsigned int * | bit_depth | ||
) |
Query the bit depth of the specified image.
filename | The name of the texture | |
[out] | bit_depth | The bit depth of the pixels in the image. For example, a JPEG image will return a bit depth of 8 |
AI_API bool AiTextureGetMatrices | ( | const char * | filename, |
AtMatrix | world_to_screen, | ||
AtMatrix | world_to_camera | ||
) |
Query the matrices associated with the specified texture.
filename | The name of the texture | |
[out] | world_to_screen | World-to-screen matrix describing the full projection of the 3D view onto a [-1...1]x[-1...1] 2D domain. |
[out] | world_to_camera | World-to-camera matrix describing the camera position |