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	AtImage
	Structure that holds infromation for reading, writing and resizing images. More...
struct	AtTextureHandle
	Structure that holds a handle for a given texture. More...

Variables
float	AtTextureParams::fill
	value for nonexistent channels (e.g. More...
uint8_t	AtTextureParams::filter: 2
	texture look-up mode
uint8_t	AtTextureParams::wrap_s: 3
	wrap mode for S coordinate
uint8_t	AtTextureParams::wrap_t: 3
	wrap mode for T coordinate
uint8_t	AtTextureParams::start_channel
	starting channel index to read from
int8_t	AtTextureParams::mipmap_bias
	mipmap level bias
uint8_t	AtTextureParams::mipmap_mode: 3
	mode for mipmap blending and filtering
bool	AtTextureParams::single_channel: 1
	treat image as single channel
bool	AtTextureParams::flip_s: 1
	flip S coordinate
bool	AtTextureParams::flip_t: 1
	flip T coordinate
bool	AtTextureParams::swap_st: 1
	enable swapping of S and T coordinates
float	AtTextureParams::scale_s
	scale S coordinate
float	AtTextureParams::scale_t
	scale T coordinate
float	AtTextureParams::width_s
	multiplicative widening of look-ups on the S axis
float	AtTextureParams::width_t
	multiplicative widening of look-ups on the T axis
float	AtTextureParams::blur_s
	additive blur in look-ups along the S axis
float	AtTextureParams::blur_t
	additive blur in look-ups along the T axis
void *	AtImage::buffer = nullptr
	pixel values
int	AtImage::width = 0
	width of the image in pixels
int	AtImage::height = 0
	height of the image in pixels
int	AtImage::full_width = 0
	width of the full display window in pixels
int	AtImage::full_height = 0
	height of the full display window in pixels
int	AtImage::x = 0
	origin (upper left corner) of pixel data
int	AtImage::y = 0
	origin (upper left corner) of pixel data
int	AtImage::channels = 0
	number of channels per pixel
uint8_t	AtImage::format = 0
	data type of pixels AI_TYPE_(BYTE, USHORT, HALF, UINT, FLOAT)
AtArray *	AtImage::aov_names = nullptr
	AtArray of AtStrings of aov names

MIP modes
The MIP mode determines how we sample between mipmap levels.
enum	AtMakeTxStatus {   AiTxPending , AiTxError , AiTxUpdated , AiTxUpdate_unneeded ,   AiTxAborted }
	Status of AiMakeTx jobs.
AI_API void	AiTextureParamsSetDefaults (AtTextureParams &params)
	Initialize an AtTextureParams object with default values. More...
AI_API AtTextureHandle *	AiTextureHandleCreate (const char *filename, AtString texture_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 texture_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 AtString	AiTextureGetTxFileName (const char *filename, AtString texture_color_space, AtString render_color_space, const AtUniverse *universe)
	Return the name of the TX filename that would be generated from the source texture by auto TX. More...
AI_API AtString	AiTextureGetTxSourceFileName (const char *tx_filename)
	Return filename of the source texture used to generate a given TX file. More...
AI_API AtString	AiTextureAutoTxFlags (const char *texture_file, AtString texture_color_space, const AtUniverse *universe)
	Return the flags passed to the "maketx" command during auto TX generation. More...
AI_API bool	AiTextureTxFileNeedsUpdate (const char *texture_file, const char *tx_filename, const char *flags)
	Return true if the TX file needs to be regenerated. More...
AI_API bool	AiReadImage (const char *filename, const uint8_t format, AtImage &image, AtParamValueMap *params=nullptr)
	Read in the image at filename into image . More...
AI_API bool	AiWriteImage (const char *filename, const AtImage &image, AtParamValueMap *params=nullptr)
	Write the image in image out to the file specified by filename. More...
AI_API bool	AiResizeImage (const AtImage &inImage, AtImage &outImage, AtParamValueMap *params=nullptr)
	Resize the image in inImage into outImage , overwrites the buffer of outImage. More...
AI_DEPRECATED bool	AiLoadImage (const char *filename, const uint8_t format, AtImage &image)
AI_API void	AiMakeTx (const char *filename, const char *flags, const AtUniverse *universe=NULL)
	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...
#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

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

Detailed Description

Texture mapping system.

Function Documentation

AiTextureParamsSetDefaults()

AI_API void AiTextureParamsSetDefaults

(

AtTextureParams &

params

)

Initialize an AtTextureParams object with default values.

The following are the default values:

• filter = AI_TEXTURE_SMART_BICUBIC
• mipmap_mode = AI_TEXTURE_MIPMODE_DEFAULT
• mipmap_bias = 0
• single_channel = false
• fill = 1.0
• flip_s/t = false
• swap_st = false
• scale_s/t = 1.0
• wrap_s/t = AI_WRAP_PERIODIC
• width_s/t = 1.0
• blur_s/t = 0

Parameters

[out]

params

A previously allocated AtTextureParams object that will be filled in with default values

AiTextureHandleCreate()

AI_API AtTextureHandle * AiTextureHandleCreate	(	const char *	filename,
		AtString	texture_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

filename	The name of the texture
texture_color_space	The 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

AiTextureHandleAccess()

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

	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.

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.

AiTextureHandleDestroy()

AI_API void AiTextureHandleDestroy

(

AtTextureHandle *

handle

)

Destroy an existing texture handle and its associated resources.

Parameters

handle

The handle to destroy

AiTextureAccess()

AI_API AtRGBA AiTextureAccess	(	const AtShaderGlobals *	sg,
		AtString	name,
		AtString	texture_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

	sg	The current shading state associated with the look-up
	filename	The name of the texture map
	texture_color_space	The color space of the texture map. Can be set to "auto" to use a reasonable default, or left empty to skip all transformations.
	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.

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.

AiTextureLoad()

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

	filename	The name of the texture map
	use_float	true if image is of type float*, and false if it is of type unsigned char*
	miplevel	The mipmap level to read, with 0 being the highest resolution.
[out]	image	Resulting 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.

AiTextureGetResolution()

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

	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

Returns

True if the resolution was successfully queried.

AiTextureGetNumChannels()

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

	filename	The name of the texture
[out]	num_channels	The number of channels in the image

Returns

True if the number of channels were successfully queried.

AiTextureGetChannelName()

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

filename	The name of the texture
channel_index	The index of the channel

Returns

NULL if the channel doesn't exist, otherwise the name as a string.

AiTextureGetFormat()

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

	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

Returns

True if the format was successfully queried.

AiTextureGetBitDepth()

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

	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

Returns

True if the bit depth was successfully queried.

AiTextureGetMatrices()

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

	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

Returns

True if the matrices were successfully queried.

AiTextureInvalidate()

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(), but it is not allowed while a universe is being rendered, in which case it will emit a warning and do nothing.

AiTextureGetTxFileName()

AI_API AtString AiTextureGetTxFileName	(	const char *	filename,
		AtString	texture_color_space,
		AtString	render_color_space,
		const AtUniverse *	universe
	)

Return the name of the TX filename that would be generated from the source texture by auto TX.

Parameters

filename	The name of the texture
texture_color_space	Color space used by the texture
render_color_space	Color space used as target for rendering
universe	Universe containing a color manager used for color conversion (NULL for default universe)

Returns

Name of the TX file that would be generated

AiTextureGetTxSourceFileName()

AI_API AtString AiTextureGetTxSourceFileName

(

const char *

tx_filename

)

Return filename of the source texture used to generate a given TX file.

Parameters

tx_filename

The name of the TX file

Returns

Name of the original source texture, empty if there was any error

AiTextureAutoTxFlags()

AI_API AtString AiTextureAutoTxFlags	(	const char *	texture_file,
		AtString	texture_color_space,
		const AtUniverse *	universe
	)

Return the flags passed to the "maketx" command during auto TX generation.

Parameters

texture_file	The name of the texture
texture_color_space	Color space used by the texture
universe	Universe containing the color manager that will be used for color conversion

Returns

A string with all flags passed to maketx

AiTextureTxFileNeedsUpdate()

AI_API bool AiTextureTxFileNeedsUpdate	(	const char *	texture_file,
		const char *	tx_filename,
		const char *	flags
	)

Return true if the TX file needs to be regenerated.

Parameters

texture_file	The name of the source texture file
tx_filename	The name of the target TX file
flags	Flags to be used for TX file generation

Returns

True if the TX file needs to be regenerated. False otherwise

AiReadImage()

AI_API bool AiReadImage	(	const char *	filename,
		const uint8_t	format,
		AtImage &	image,
		AtParamValueMap *	params
	)

Read in the image at filename into image .

Parameters

	filename	Name of the image to be loaded
	format	Pixel format of the image, one of AI_TYPE_BYTE, AI_TYPE_USHORT, AI_TYPE_HALF, AI_TYPE_UINT or AI_TYPE_FLOAT
[out]	image	Resulting image data
	params	optional parameters

Returns

true if the image was loaded successfully.

AiWriteImage()

AI_API bool AiWriteImage	(	const char *	filename,
		const AtImage &	image,
		AtParamValueMap *	params
	)

Write the image in image out to the file specified by filename.

Parameters

filename	The name of the file to be writen to
image	The image to be writen out
params	optional parameters

Returns

true if the image was writen to the file.

AiResizeImage()

AI_API bool AiResizeImage	(	const AtImage &	inImage,
		AtImage &	outImage,
		AtParamValueMap *	params
	)

Resize the image in inImage into outImage , overwrites the buffer of outImage.

Parameters

	inImage	Image to be resized
[out]	outImage	Resulting resized image.
	params	optional parameters

Returns

true if the resize was successful.

AiMakeTx()

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

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 --monochrome-detect --fixnan box3 --oiio --attrib tiff:half 1"

Parameters

filename	The 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.
flags	The remaining flags one would normally pass into maketx. For instance, it could be: "--unpremult --oiio -u"
universe	Universe that contains the color manager to be used (null for default universe)

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

AiMakeTxWaitJob()

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

statuses	Will end up containing an array of AtMakeTxStatus.
source_files	An array containing the source filenames that have been submitted to Arnold.
num_submitted_textures	The 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:

for (int i=0; i < num_textures; ++i)
{
   AiMakeTx(textures[i], " -u");
   printf("submitted %d of %d textures for updating\n", i, num_textures);
}
AtMakeTxStatus *status;
const char** source_filenames;
unsigned num_submitted_textures;
while (int num_jobs_left = AiMakeTxWaitJob(status, source_filenames, num_submitted_textures))
   AiMsgInfo("%d of %u texture updates remaining.", num_jobs_left, num_submitted_textures);
 
 for (size_t i=0; i < num_submitted_textures; ++i)
   if (status[i] == AiTxUpdated)
      printf("%s was updated\n", source_filenames[i]);
   else if (status[i] == AiTxError)
      printf("%s could not be updated\n", source_filenames[i]);
   else if (status[i] == AiTxUpdate_unneeded)
      printf("%s did not need to be updated\n", source_filenames[i]);
   else if (status[i] == AiTxAborted)
      printf("%s was aborted\n", source_filenames[i]);

AiMakeTxAbort()

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.

Variable Documentation

fill

float AtTextureParams::fill

value for nonexistent channels (e.g.

alpha)