Data Structures | Enumerations | Functions
Texture Mapping API

Texture mapping system. More...

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...
 

Enumerations

enum  AtMakeTxStatus {
  AiTxPending, AiTxError, AiTxUpdated, AiTxUpdate_unneeded,
  AiTxAborted
}
 Status of AiMakeTx jobs.
 

Functions

AI_API void AiTextureParamsSetDefaults (AtTextureParams &params)
 Initialize an AtTextureParams object with default values. More...
 
AI_API AtTextureHandleAiTextureHandleCreate (const char *filename, AtString color_space=AtString())
 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, AtString filename, AtString color_space, const AtTextureParams &params, bool *success=NULL)
 Perform a texture look-up through a filename string. More...
 
AI_API bool AiTextureLoad (const AtString filename, const bool use_float, const unsigned int miplevel, void *image)
 This is currently an EXPERIMENTAL function and might be modified in future Arnold releases. 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 AI_PURE 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...
 
AI_API void AiTextureInvalidate (const char *filename)
 Invalidate a specific texture from the cache. More...
 
AI_API void AiMakeTx (const char *filename, const char *flags)
 Asynchronously runs a maketx job in the background. More...
 
AI_API unsigned AiMakeTxWaitJob (AtMakeTxStatus *&statuses, const char **&source_files, unsigned int &num_submitted_textures)
 This function will block until at least one job has been finished. More...
 
AI_API void AiMakeTxAbort (AtMakeTxStatus *&statuses, const char **&source_files, unsigned int &num_submitted_textures)
 Abort pending maketx jobs. More...
 

Wrapping Modes

Wrap mode describes what happens when texture coordinates describe a value outside the usual [0,1] range in (s,t)-space where a texture is defined.

#define AI_WRAP_PERIODIC   0
 the texture repeats itself outside the [0,1] range
 
#define AI_WRAP_BLACK   1
 return black outside the [0,1] range
 
#define AI_WRAP_CLAMP   2
 clamp to the closest texture edge
 
#define AI_WRAP_MIRROR   3
 mirror the image across the boundaries
 
#define AI_WRAP_FILE   4
 use wrap mode found in the EXR file's metadata
 

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

Texture mapping system.

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,
AtString  color_space 
)

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
color_spaceThe name of the texture's color space, can be set to "auto" to use a reasonable default, or left empty to skip all transformations.
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.

The texture file is kept open after this call in order to speed future queries. Use AiTextureInvalidate() if the file needs to be closed.

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,
AtString  name,
AtString  color_space,
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).

The texture file is kept open after this call in order to speed future queries. Use AiTextureInvalidate() if the file needs to be closed.

Parameters
sgThe current shading state associated with the look-up
filenameThe name of the texture map
color_spaceThe color space of the texture map. Can be set to "auto" to use a reasonable default, or left empty to skip all transformations.
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 AiTextureLoad ( const AtString  filename,
const bool  use_float,
const unsigned int  miplevel,
void *  image 
)

This is currently an EXPERIMENTAL function and might be modified in future Arnold releases.

If you use this, your code might cease to compile with future versions of Arnold should we remove/modify this function.

Do a texture lookup over an entire texture named filename. AiTextureAccess() / AiTextureHandleAccess() should instead be used inside of shader_evaluate. While this function should be used when the entire texture needs to be read in and works even outside of AiBegin() / AiEnd() blocks.

Parameters
filenameThe name of the texture map
use_floattrue if image is of type float*, and false if it is of type unsigned char*
miplevelThe mipmap level to read, with 0 being the highest resolution.
[out]imageResulting image data. Underlying data is allocated by caller. Caller should make sure it has the proper number of channels and resolution. These can be found using AiTextureGetNumChannels() and AiTextureGetResolution().
Returns
true if the lookup was successful.
AI_API bool AiTextureGetResolution ( const char *  filename,
unsigned int *  width,
unsigned int *  height 
)

Query resolution info about a texture.

This can be called from outside AiBegin() / AiEnd()

The texture file is kept open after this call in order to speed future queries. Use AiTextureInvalidate() if the file needs to be closed.

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.

This can be called from outside AiBegin() / AiEnd()

The texture file is kept open after this call in order to speed future queries. Use AiTextureInvalidate() if the file needs to be closed.

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 AI_PURE const char* AiTextureGetChannelName ( const char *  filename,
unsigned int  channel_index 
)

Query the name of a channel in the specified image.

This can be called from outside AiBegin() / AiEnd()

The texture file is kept open after this call in order to speed future queries. Use AiTextureInvalidate() if the file needs to be closed.

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.

This can be called from outside AiBegin() / AiEnd()

The texture file is kept open after this call in order to speed future queries. Use AiTextureInvalidate() if the file needs to be closed.

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.

This can be called from outside AiBegin() / AiEnd()

The texture file is kept open after this call in order to speed future queries. Use AiTextureInvalidate() if the file needs to be closed.

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.

This can be called from outside AiBegin() / AiEnd()

The texture file is kept open after this call in order to speed future queries. Use AiTextureInvalidate() if the file needs to be closed.

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.
AI_API void AiTextureInvalidate ( const char *  filename)

Invalidate a specific texture from the cache.

This will invalidate all associated texture data in the cache and close the file. This can be called from outside AiBegin() / AiEnd()

AI_API void AiMakeTx ( const char *  filename,
const char *  flags 
)

Asynchronously runs a maketx job in the background.

Both AiMakeTx and our supplied maketx binary will already include the flags: " --opaque-detect --constant-color-detect --fixnan box3 --oiio"

Parameters
filenameThe original input texture, such as "my_texture.png". This can also be an empty string and instead the filename is included as part of the flags.
flagsThe remaining flags one would normally pass into maketx. For instance, it could be: "--unpremult --oiio -u"

AiMakeTx(), AiMakeTxWaitJob(), and AiMakeTxAbort() are not thread safe and should not be called from multiple threads at the same time

AI_API unsigned AiMakeTxWaitJob ( AtMakeTxStatus *&  statuses,
const char **&  source_files,
unsigned int &  num_submitted_textures 
)

This function will block until at least one job has been finished.

Parameters
statusesWill end up containing an array of AtMakeTxStatus.
source_filesAn array containing the source filenames that have been submitted to Arnold.
num_submitted_texturesThe size of the above arrays that Arnold used.
Returns
How many textures still need to be generated. If all the textures have been processed, it will return 0. Example usage:
1 for (int i=0; i < num_textures; ++i)
2 {
3  AiMakeTx(textures[i], " -u");
4  printf("submitted %d of %d textures for updating\n", i, num_textures);
5 }
6 AtMakeTxStatus *status;
7 const char** source_filenames;
8 unsigned num_submitted_textures;
9 while (int num_jobs_left = AiMakeTxWaitJob(status, source_filenames, num_submitted_textures))
10  AiMsgInfo("%d of %u texture updates remaining.", num_jobs_left, num_submitted_textures);
11 
12  for (size_t i=0; i < num_submitted_textures; ++i)
13  if (status[i] == AiTxUpdated)
14  printf("%s was updated\n", source_filenames[i]);
15  else if (status[i] == AiTxError)
16  printf("%s could not be updated\n", source_filenames[i]);
17  else if (status[i] == AiTxUpdate_unneeded)
18  printf("%s did not need to be updated\n", source_filenames[i]);
19  else if (status[i] == AiTxAborted)
20  printf("%s was aborted\n", source_filenames[i]);
AI_API void AiMakeTxAbort ( AtMakeTxStatus *&  statuses,
const char **&  source_files,
unsigned int &  num_submitted_textures 
)

Abort pending maketx jobs.

It's possible that currently running maketx jobs (as opposed to jobs that haven't yet been started and are waiting to be run) will not be aborted and instead might finish sometime after AiMakeTxAbort() has already returned. The next call to AiMakeTx() will block until all preexisting jobs have completed.


© 2020 Autodesk, Inc. · All rights reserved · www.arnoldrenderer.com