Construction and manipulation of AtUniverse objects. More...

Data Structures
struct	AtUniverse
	This represents a universe in Arnold. More...

Variables
AtString	AtAOVEntry::name
	AOV name

uint8_t	AtAOVEntry::type
	Data type

int	AtAOVEntry::blend_mode
	Blend mode

AtString	AtAOVEntry::expression
	Optional light path expression.

Methods
AI_API AtUniverse *	AiUniverse ()
	Creates a new universe that can be used independently of the default universe. More...

AI_API void	AiUniverseDestroy (AtUniverse *universe)
	Destroys an existing universe and releases any allocated resources. More...

AI_API bool	AiUniverseCacheFlush (AtUniverse *universe, int cache_flags)
	Flush one or several caches in a given Arnold universe. More...

AI_API AI_PURE AtNode *	AiUniverseGetOptions (const AtUniverse *universe)
	Fetches the global options node for a specific Arnold universe. More...

AI_API AI_DEVICE AI_PURE AtNode *	AiUniverseGetCamera (const AtUniverse *universe)
	Fetches the currently active camera node for a given Arnold universe. More...

AI_API AI_PURE AtBBox	AiUniverseGetSceneBounds (const AtUniverse *universe)
	Returns the bounding box of the given Arnold universe. More...

AI_API AtNodeIterator *	AiUniverseGetNodeIterator (const AtUniverse *universe, unsigned int node_mask)
	Creates a new node iterator for the given Arnold universe and resets it to the first node. More...

AI_API AtNodeEntryIterator *	AiUniverseGetNodeEntryIterator (unsigned int node_mask)
	Creates a new node entry iterator and resets it to the first installed node entry. More...

AI_API AtAOVIterator *	AiUniverseGetAOVIterator (const AtUniverse *universe)
	Creates a new AOV iterator for a specific universe and resets it to the first entry. More...

AI_API void	AiUniverseAddDefaultNodes (AtUniverse universe, const AtParamValueMap params)
	Creates default camera and/or light nodes when they are not present in the scene. More...

AI_API AtRenderSession *	AiUniverseGetRenderSession (const AtUniverse *universe)
	Get the render session using the given universe. More...

AI_API bool	AiUniverseCompare (const AtUniverse universe1, const AtUniverse universe2, unsigned int node_mask=AI_NODE_ALL, AtParamValueMap *diffs=NULL)
	Compare two universes. More...

AI_API uint32_t	AiUniverseGetId (const AtUniverse *universe)
	Returns a 32bit integer ID for a universe. More...

AI_API AtUniverse *	AiUniverseGetFromId (uint32_t universe_id)
	Returns a universe from its 32bit integer ID. More...

Node Iterator API
AI_API void	AiNodeIteratorDestroy (AtNodeIterator *iter)
	Destroys a node iterator when it is no longer needed. More...

AI_API AtNode *	AiNodeIteratorGetNext (AtNodeIterator *iter)
	Returns current node and points node iterator to the next node. More...

AI_API AI_PURE bool	AiNodeIteratorFinished (const AtNodeIterator *iter)
	Returns true if there are no more nodes to iterate over. More...

Node Entry Iterator API
AI_API void	AiNodeEntryIteratorDestroy (AtNodeEntryIterator *iter)
	Destroys a node entry iterator when it is no longer needed. More...

AI_API AtNodeEntry *	AiNodeEntryIteratorGetNext (AtNodeEntryIterator *iter)
	Returns current node entry and points node entry iterator to the next node entry. More...

AI_API AI_PURE bool	AiNodeEntryIteratorFinished (const AtNodeEntryIterator *iter)
	Returns true if there are no more node entries to iterate over. More...

AOV Iterator API
AI_API void	AiAOVIteratorDestroy (AtAOVIterator *iter)
	Destroys a AOV iterator when it is no longer needed. More...

AI_API const AtAOVEntry *	AiAOVIteratorGetNext (AtAOVIterator *iter)
	Returns current AOV entry and points AOV iterator to the next AOV. More...

AI_API AI_PURE bool	AiAOVIteratorFinished (const AtAOVIterator *iter)
	Returns true if there are no more AOV entries to iterate over. More...

Cache Types
#define	AI_CACHE_TEXTURE 0x0001
	Flushes all texturemaps.

#define	AI_CACHE_BACKGROUND 0x0002
	Flushes all skydome importance tables for background.

#define	AI_CACHE_QUAD 0x0004
	Flushes all quad lights importance tables.

#define	AI_CACHE_ALL (AI_CACHE_TEXTURE \| AI_CACHE_BACKGROUND \| AI_CACHE_QUAD)
	Flushes all cache types simultaneously.

Detailed Description

Construction and manipulation of AtUniverse objects.

There is always a default universe, created on AiBegin() and destroyed on AiEnd(). This universe cannot be manually destroyed. As a shortcut, universe API calls can use a null universe pointer to refer to this default universe.

There can also be a number of secondary universes created using AiUniverse(), which can be used for scene import, export and rendering independently from other universes and the default universe.

Note that universes are totally independent, so a node can only belong to a single universe, and it cannot link to or reference nodes in a different universe.

Function Documentation

◆ AiUniverse()

AI_API AtUniverse * AiUniverse ( )

Creates a new universe that can be used independently of the default universe.

AiUniverseDestroy() can be used to destroy this universe on demand. This is not necessary if the universe is used until the end of the Arnold session, because AiEnd() will take care of destroying any existing universes.

Note: A default universe always exists during the Arnold session (between AiBegin() and AiEnd()). This default universe cannot be destroyed manually (it will be released during AiEnd()). You can generally use a NULL pointer to select the default universe in the API.

Returns: pointer to new universe. NULL if called outside of an AiBegin() / AiEnd() block.

◆ AiUniverseDestroy()

AI_API void AiUniverseDestroy ( AtUniverse * universe )

Destroys an existing universe and releases any allocated resources.

This is necessary when a universe has been created for a temporary usage, and needs to be released before AiEnd() is called.

Note: Trying to destroy the default universe, or passing a NULL pointer, will do nothing

Parameters

universe the universe to be destroyed

◆ AiUniverseCacheFlush()

AI_API bool AiUniverseCacheFlush	(	AtUniverse *	universe,
		int	cache_flags
	)

Flush one or several caches in a given Arnold universe.

This function will request the release of the resource. If safe to do so (no other render sessions could be actively using the resource, etc.) the release will finish before the function returns. Otherwise the request is recorded and the flush will happen later when the resource is no longer used (often the start or end of a render).

Parameters

universe	the target universe for the cache flush (NULL for default universe)
cache_flags	a bitmask specifying the cache types to be flushed

Returns: true if the requested cache flushes were executed, false if they were deferred.

◆ AiUniverseGetOptions()

AI_API AI_PURE AtNode * AiUniverseGetOptions ( const AtUniverse * universe )

Fetches the global options node for a specific Arnold universe.

Will return NULL if called outside AiBegin() / AiEnd().

Warning: The universe's options reflects what the user requested, not what is being actually used. For instance, if options.threads=0 (autodetect thread count) this will return 0. If you want the actual number of threads being used, then instead AiRenderSessionGetOptions(AiUniverseGetRenderSession(universe)) should be used.

Parameters

universe the universe to get the options node from (NULL for default universe)

Returns: pointer to the global options node

◆ AiUniverseGetCamera()

AI_API AI_DEVICE AI_PURE AtNode * AiUniverseGetCamera ( const AtUniverse * universe )

Fetches the currently active camera node for a given Arnold universe.

Will return NULL if the universe is not valid, if the camera has not been set or if the linked node is not a camera.

Parameters

universe the universe to get the camera node from (NULL for default universe)

Returns: pointer to the active camera node

◆ AiUniverseGetSceneBounds()

AI_API AI_PURE AtBBox AiUniverseGetSceneBounds ( const AtUniverse * universe )

Returns the bounding box of the given Arnold universe.

Note that this box may be conservative in the presence of "infinite" primitives or procedurals. If the universe given is not valid, this will return an empty box containing the origin.

Parameters

universe the universe to get the bounding box from (NULL for default universe)

Returns: scene bounding box

◆ AiUniverseGetNodeIterator()

AI_API AtNodeIterator * AiUniverseGetNodeIterator	(	const AtUniverse *	universe,
		unsigned int	node_mask
	)

Creates a new node iterator for the given Arnold universe and resets it to the first node.

Parameters

universe	the universe to iterate (NULL for default universe)
node_mask	bitmask of node types, e.g `AI_NODE_ALL`, `AI_NODE_LIGHT` \| `AI_NODE_SHADER`, etc.

Returns: a node iterator over the given type of nodes

See also: AiNodeIteratorDestroy, AiNodeIteratorGetNext

◆ AiUniverseGetNodeEntryIterator()

AI_API AtNodeEntryIterator * AiUniverseGetNodeEntryIterator ( unsigned int node_mask )

Creates a new node entry iterator and resets it to the first installed node entry.

Parameters

node_mask bitmask of node types, e.g AI_NODE_ALL, AI_NODE_LIGHT | AI_NODE_SHADER, etc.

Returns: a node entry iterator over the given type of nodes

See also: AiNodeEntryIteratorDestroy, AiNodeEntryIteratorGetNext

◆ AiUniverseGetAOVIterator()

AI_API AtAOVIterator * AiUniverseGetAOVIterator ( const AtUniverse * universe )

Creates a new AOV iterator for a specific universe and resets it to the first entry.

In case the universe doesn't have a render session associated, this will return NULL.

Parameters

universe universe to get the AOV iterator for (NULL for default universe)

Returns: a AOV iterator over all registered AOVs

See also: AiAOVIteratorDestroy, AiAOVIteratorGetNext

◆ AiUniverseAddDefaultNodes()

AI_API void AiUniverseAddDefaultNodes	(	AtUniverse *	universe,
		const AtParamValueMap *	params
	)

Creates default camera and/or light nodes when they are not present in the scene.

This example code creates a default set of lights:

AtParamValueMap* params = AiParamValueMap();
AiParamValueMapSetBool(params, AtString("default_lights"), true);
AiParamValueMapSetStr(params, AtString("light_type"), AtString("distant_light"));
AiParamValueMapSetStr(params, AtString("light_mode"), AtString("three_point"));
AiUniverseAddDefaultNodes(universe, params); 
AiParamValueMapDestroy(params);

Supported params:

default_camera	BOOLEAN	Set to true to create default camera when none is found
default_lights	BOOLEAN	Set to true to create default lights when none is found
light_type	STRING	Selects type of light to be created for default lights (spot_light, distant_light, ...)
light_mode	STRING	Selects light arrangement to create (three_point, flashlight, skydome_light)

Parameters

universe	universe where nodes will be added (NULL for default universe)
params	list of parameters to modify which nodes are created and how

◆ AiUniverseGetRenderSession()

AI_API AtRenderSession * AiUniverseGetRenderSession ( const AtUniverse * universe )

Get the render session using the given universe.

Parameters

universe Pointer to a universe (NULL for default universe)

Returns: Pointer to the render session using this universe (NULL if no render session is created using this universe)

◆ AiUniverseCompare()

AI_API bool AiUniverseCompare	(	const AtUniverse *	universe1,
		const AtUniverse *	universe2,
		unsigned int	node_mask,
		AtParamValueMap *	diffs
	)

Compare two universes.

This function will compare 2 universes node by node, optionally filtered by a node mask, and returns true only when both universes have the same nodes with the same parameters.

Parameters

universe1	Pointer to a universe (NULL for default universe)
universe2	Pointer to a universe (NULL for default universe)
node_mask	bitmask of node types, e.g `AI_NODE_ALL`, `AI_NODE_LIGHT` \| `AI_NODE_SHADER`, etc.
diffs	Optional list of differences to be returned

Returns: true if universes are equivalent, and false if there is any difference

◆ AiUniverseGetId()

AI_API uint32_t AiUniverseGetId ( const AtUniverse * universe )

Returns a 32bit integer ID for a universe.

Parameters

universe Pointer to a universe (NULL for default universe)

Returns: 32bit integer ID value

◆ AiUniverseGetFromId()

AI_API AtUniverse * AiUniverseGetFromId ( uint32_t universe_id )

Returns a universe from its 32bit integer ID.

Parameters

universe_id 32bit integer ID for universe

Returns: Pointer to the universe with this ID (or NULL if not found)

◆ AiNodeIteratorDestroy()

AI_API void AiNodeIteratorDestroy ( AtNodeIterator * iter )

Destroys a node iterator when it is no longer needed.

Parameters

iter	node iterator that will be deallocated

◆ AiNodeIteratorGetNext()

AI_API AtNode * AiNodeIteratorGetNext ( AtNodeIterator * iter )

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

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

AtNodeIterator *iter = AiUniverseGetNodeIterator(AI_NODE_ALL);
while (!AiNodeIteratorFinished(iter))
{
   AtNode *node = AiNodeIteratorGetNext(iter);
   // do something with node ...
}
AiNodeIteratorDestroy(iter);

Parameters

iter	a node iterator

Returns: the node pointed by the iterator, or NULL if there are no more nodes to iterate over

◆ AiNodeIteratorFinished()

AI_API AI_PURE bool AiNodeIteratorFinished ( const AtNodeIterator * iter )

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

Parameters

iter	a node iterator

Returns: true if the node iterator has moved past the last node

◆ AiNodeEntryIteratorDestroy()

AI_API void AiNodeEntryIteratorDestroy ( AtNodeEntryIterator * iter )

Destroys a node entry iterator when it is no longer needed.

Parameters

iter	node entry iterator that will be deallocated

◆ AiNodeEntryIteratorGetNext()

AI_API AtNodeEntry * AiNodeEntryIteratorGetNext ( AtNodeEntryIterator * iter )

Returns current node entry and points node entry iterator to the next node entry.

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

AtNodeEntryIterator *iter = AiUniverseGetNodeEntryIterator(AI_NODE_ALL);
while (!AiNodeEntryIteratorFinished(iter))
{
   AtNodeEntry *node_entry = AiNodeEntryIteratorGetNext(iter);
   // do something with node_entry ...
}
AiNodeEntryIteratorDestroy(iter);

Parameters

iter	a node entry iterator

Returns: the node entry pointed by the iterator, or NULL if there are no more node entries to iterate over

◆ AiNodeEntryIteratorFinished()

AI_API AI_PURE bool AiNodeEntryIteratorFinished ( const AtNodeEntryIterator * iter )

Returns true if there are no more node entries to iterate over.

Parameters

iter	a node entry iterator

Returns: true if the node entry iterator has moved past the last node entry

◆ AiAOVIteratorDestroy()

AI_API void AiAOVIteratorDestroy ( AtAOVIterator * iter )

Destroys a AOV iterator when it is no longer needed.

Parameters

iter	AOV iterator that will be deallocated

◆ AiAOVIteratorGetNext()

AI_API const AtAOVEntry * AiAOVIteratorGetNext ( AtAOVIterator * iter )

Returns current AOV entry and points AOV iterator to the next AOV.

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

AtAOVIterator* iter = AiUniverseGetAOVIterator();
while (!AiAOVIteratorFinished(iter))
{
   AtAOVEntry* aov_entry = AiAOVIteratorGetNext(iter);
   // do something with aov_entry ...
}
AiAOVIteratorDestroy(iter);

Parameters

iter	AOV iterator

Returns: the AOV pointed by the iterator, or NULL if there are no more AOV entries to iterate over

◆ AiAOVIteratorFinished()

AI_API AI_PURE bool AiAOVIteratorFinished ( const AtAOVIterator * iter )

Returns true if there are no more AOV entries to iterate over.

Parameters

iter	a AOV iterator

Returns: true if the AOV iterator has moved past the last AOV

Data Structures

Variables

Methods

Node Iterator API

Node Entry Iterator API

AOV Iterator API

Cache Types

Detailed Description

Function Documentation

◆ AiUniverse()

◆ AiUniverseDestroy()

◆ AiUniverseCacheFlush()

◆ AiUniverseGetOptions()

◆ AiUniverseGetCamera()

◆ AiUniverseGetSceneBounds()

◆ AiUniverseGetNodeIterator()

◆ AiUniverseGetNodeEntryIterator()

◆ AiUniverseGetAOVIterator()

◆ AiUniverseAddDefaultNodes()

◆ AiUniverseGetRenderSession()

◆ AiUniverseCompare()

◆ AiUniverseGetId()

◆ AiUniverseGetFromId()

◆ AiNodeIteratorDestroy()

◆ AiNodeIteratorGetNext()

◆ AiNodeIteratorFinished()

◆ AiNodeEntryIteratorDestroy()

◆ AiNodeEntryIteratorGetNext()

◆ AiNodeEntryIteratorFinished()

◆ AiAOVIteratorDestroy()

◆ AiAOVIteratorGetNext()

◆ AiAOVIteratorFinished()