AtAsset API

Creation, manipulation and operation with assets. More...

AtAsset Methods
AI_API AtAsset *	AiAsset (const char *filename, AtFileType type=AtFileType::Custom)
	Creates a new asset instance. More...
AI_API void	AiAssetDestroy (AtAsset *asset)
	Destroys an asset instance. More...
AI_API void	AiAssetAddReference (AtAsset *asset, const AtString reference, const AtString node_name, const AtString parameter)
	Adds a scene reference to an asset. More...
AI_API AI_PURE AtString	AiAssetGetFilename (const AtAsset *asset)
	Returns the asset file path. More...
AI_API AI_PURE AtFileType	AiAssetGetFileType (const AtAsset *asset)
	Returns the asset file type, such as Asset (texture, procedural), OSL, Plugin, etc. More...
AI_API AI_PURE bool	AiAssetGetIgnoreMissing (const AtAsset *asset)
	Returns true if the asset should be ignored when the file does not exist. More...
AI_API void	AiAssetSetIgnoreMissing (AtAsset *asset, bool ignore_missing)
	Sets the 'ignore missing' flag of the asset. More...
AI_API AI_PURE uint32_t	AiAssetGetNumReferences (const AtAsset *asset)
	Returns the number of references the given asset has in the scene. More...
AI_API AI_PURE AtString	AiAssetGetReference (const AtAsset *asset, uint32_t reference_idx)
	Returns the string that represents the file in the scene description. More...
AI_API AI_PURE AtString	AiAssetReferenceGetNodeName (const AtAsset *asset, uint32_t reference_idx)
	Returns the name of the Arnold node that defines a given asset reference. More...
AI_API AI_PURE AtString	AiAssetReferenceGetParameter (const AtAsset *asset, uint32_t reference_idx)
	Returns the name of the Arnold node parameter that defines a given asset reference. More...

AtAssetIterator Methods
AI_API void	AiAssetIteratorDestroy (AtAssetIterator *iter)
	Destroys an asset iterator when it is no longer needed. More...
AI_API const AtAsset *	AiAssetIteratorGetNext (AtAssetIterator *iter)
	Returns current asset and points the iterator to the next asset. More...
AI_API bool	AiAssetIteratorFinished (const AtAssetIterator *iter)
	Returns true if there are no more assets to iterate over. More...

Detailed Description

Creation, manipulation and operation with assets.

The AtAsset object represents a file dependency in the scene. Its API offers easy-to-use accessor functions for creating and modifying AtAsset objects and iterate over a list of assets. An asset is specified by a file path, a file type and a number of scene references. An asset can be referenced multiple times in the scene, for instance the same texture file can be referenced by multiple image nodes.

Function Documentation

AiAsset()

AI_API AtAsset * AiAsset	(	const char *	filename,
		AtFileType	type = AtFileType::Custom
	)

Creates a new asset instance.

An asset represents a single file dependency.

Parameters

filename	The resolved absolute path of the asset, or the relative reference if the path could not be resolved
type	Asset file type, such as Asset (texture, procedural), OSL, Plugin, etc.

Returns

The new asset instance

AiAssetDestroy()

AI_API void AiAssetDestroy

(

AtAsset *

asset

)

Destroys an asset instance.

Parameters

asset

The asset

AiAssetAddReference()

AI_API void AiAssetAddReference	(	AtAsset *	asset,
		const AtString	reference,
		const AtString	node_name,
		const AtString	parameter
	)

Adds a scene reference to an asset.

Parameters

asset	The asset
reference	The string that represents the file in the scene. For instance "mytexture.exr" or "body_<UDIM>.exr"
node_name	Name of the Arnold node that defines the asset
parameter	Name of the Arnold node parameter that defines the asset

AiAssetGetFilename()

AI_API AI_PURE AtString AiAssetGetFilename

(

const AtAsset *

asset

)

Returns the asset file path.

The path is either the resolved absolute path, or the relative reference if the path could not be resolved.

Parameters

asset

The asset

Returns

The asset file path

AiAssetGetFileType()

AI_API AI_PURE AtFileType AiAssetGetFileType

(

const AtAsset *

asset

)

Returns the asset file type, such as Asset (texture, procedural), OSL, Plugin, etc.

Parameters

asset

The asset

Returns

The asset type

AiAssetGetIgnoreMissing()

AI_API AI_PURE bool AiAssetGetIgnoreMissing

(

const AtAsset *

asset

)

Returns true if the asset should be ignored when the file does not exist.

For instance textures in image shaders can be ignored, which means the render does not fail if the texture is missing.

Parameters

asset

The asset

Returns

True if the asset should be ignored when missing

AiAssetSetIgnoreMissing()

AI_API void AiAssetSetIgnoreMissing	(	AtAsset *	asset,
		bool	ignore_missing
	)

Sets the 'ignore missing' flag of the asset.

This flag shows if the asset should be ignored when the file does not exist.

For instance textures in image shaders can be ignored, which means the render does not fail if the texture is missing.

Parameters

asset	The asset
ignore_missing	Ignore the asset if missing

AiAssetGetNumReferences()

AI_API AI_PURE uint32_t AiAssetGetNumReferences

(

const AtAsset *

asset

)

Returns the number of references the given asset has in the scene.

A reference is a string that represents the file in the scene description, for instance the value of an Arnold node parameter. The same asset can be referenced multiple times in a scene. For instance the same texture file can be referenced by multiple image nodes.

Parameters

asset

The asset

Returns

The number of references this asset has in the scene

AiAssetGetReference()

AI_API AI_PURE AtString AiAssetGetReference	(	const AtAsset *	asset,
		uint32_t	reference_idx
	)

Returns the string that represents the file in the scene description.

For instance the value of an Arnold node parameter, like the filename in an image shader, or the value of a prim attribute in a USD scene. Normally an absolute or relative path, but could be a file name containing environment variables or texture tokens, like "mytexture_<UDIM>.exr" or "mytexture_<attr:color>.exr".

Parameters

asset	The asset
reference_idx	Index of the requested reference (between 0 and AiAssetGetNumReferences()-1)

Returns

The reference string

AiAssetReferenceGetNodeName()

AI_API AI_PURE AtString AiAssetReferenceGetNodeName	(	const AtAsset *	asset,
		uint32_t	reference_idx
	)

Returns the name of the Arnold node that defines a given asset reference.

Parameters

asset	The asset
reference_idx	Index of the requested reference (between 0 and AiAssetGetNumReferences()-1)

Returns

The Arnold node name that defines the reference

AiAssetReferenceGetParameter()

AI_API AI_PURE AtString AiAssetReferenceGetParameter	(	const AtAsset *	asset,
		uint32_t	reference_idx
	)

Returns the name of the Arnold node parameter that defines a given asset reference.

Parameters

asset	The asset
reference_idx	Index of the requested reference (between 0 and AiAssetGetNumReferences()-1)

Returns

The Arnold node parameter name that defines the reference

AiAssetIteratorDestroy()

AI_API void AiAssetIteratorDestroy

(

AtAssetIterator *

iter

)

Destroys an asset iterator when it is no longer needed.

Parameters

iter	asseet iterator that will be deallocated

AiAssetIteratorGetNext()

AI_API const AtAsset * AiAssetIteratorGetNext

(

AtAssetIterator *

iter

)

Returns current asset and points the iterator to the next asset.

This function is designed to be used inside a loop, as illustrated by the following example:

AtAssetIterator *iter = AiUniverseGetAssetIterator(universe);
while (!AiAssetIteratorFinished(iter))
{
   AtAsset *asset = AiAssetIteratorGetNext(iter);
   // do something with asset ...
}
AiAssetIteratorDestroy(iter);

Parameters

iter	an asset iterator

Returns

the asset pointed by the iterator, or NULL if there are no more assets to iterate over

AiAssetIteratorFinished()

AI_API bool AiAssetIteratorFinished

(

const AtAssetIterator *

iter

)

Returns true if there are no more assets to iterate over.

Parameters

iter	an asset iterator

Returns

true if the asset iterator has moved past the last node