Data Structures
Universe API

Construction and manipulation of AtUniverse objects. More...

Data Structures

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

Methods

AI_API AtUniverseAiUniverse ()
 Creates a new secondary universe that can be used independently of the main default universe. More...
 
AI_API void AiUniverseDestroy (AtUniverse *universe)
 Destroys an existing secondary universe and releases any allocated resources. More...
 
AI_API AI_PURE bool AiUniverseIsActive ()
 Check whether the default universe is active or not. More...
 
AI_API bool AiUniverseCacheFlush (const AtUniverse *universe, int cache_flags)
 Flush one or several caches in a given Arnold universe. More...
 
AI_API AI_PURE AtNodeAiUniverseGetOptions (const AtUniverse *universe)
 Fetches the global options node for a specific Arnold universe. More...
 
AI_API AI_PURE AtNodeAiUniverseGetCamera (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 ()
 Creates a new AOV iterator 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_DEPRECATED bool AiUniverseCacheFlush (int cache_flags)
 Flush one or several caches in the default universe. More...
 
AI_DEPRECATED AtNodeAiUniverseGetOptions ()
 Fetches the global options node for the default Arnold universe. More...
 
AI_DEPRECATED AtNodeAiUniverseGetCamera ()
 Fetches the currently active camera node for the default Arnold universe. More...
 
AI_DEPRECATED AtBBox AiUniverseGetSceneBounds ()
 Returns the bounding box of the default Arnold universe. More...
 
AI_DEPRECATED AtNodeIterator * AiUniverseGetNodeIterator (unsigned int node_mask)
 Creates a new node iterator for the default Arnold universe and resets it to the first node. More...
 

Node Iterator API

AI_API void AiNodeIteratorDestroy (AtNodeIterator *iter)
 Destroys a node iterator when it is no longer needed. More...
 
AI_API AtNodeAiNodeIteratorGetNext (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 AtNodeEntryAiNodeEntryIteratorGetNext (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 AtAOVEntryAiAOVIteratorGetNext (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   0xFFFF
 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(). There can also be a number of secondary universes created using AiUniverse().

Note
Rendering is currently supported ONLY on the default universe. No rendering or render related operation can be applied to secondary universes yet. This will be implemented in a future release.

Function Documentation

AI_API AtUniverse* AiUniverse ( )

Creates a new secondary universe that can be used independently of the main 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 secondary 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 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.
AI_API void AiUniverseDestroy ( AtUniverse universe)

Destroys an existing secondary 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
AI_API AI_PURE bool AiUniverseIsActive ( )

Check whether the default universe is active or not.

This function is typically used to detect whether we are inside an AiBegin() / AiEnd() block.

Returns
true if the default universe is active. This can only be false if called outside of an AiBegin() / AiEnd() block.
AI_API bool AiUniverseCacheFlush ( const AtUniverse universe,
int  cache_flags 
)

Flush one or several caches in a given Arnold universe.

This function will release all memory associated with a cached resource. The next time that the resource is accessed, it will get reloaded or recomputed. This is useful in interactive rendering; occasionally, a texture map would need to be modified or updated in the middle of a relighting session.

Parameters
cachea bitmask specifying the cache types to be flushed
Returns
true if the cache was flushed succesfully, false if rendering is still in progress
AI_API AI_PURE AtNode* AiUniverseGetOptions ( const AtUniverse universe)

Fetches the global options node for a specific Arnold universe.

Will return NULL if the given universe is not valid.

Returns
pointer to the global options node
AI_API 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.

Returns
pointer to the active camera node
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.

Returns
scene bounding box
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
node_maskbitmask 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
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_maskbitmask 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
AI_API AtAOVIterator* AiUniverseGetAOVIterator ( )

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

Returns
a AOV iterator over all registered AOVs
See also
AiAOVIteratorDestroy, AiAOVIteratorGetNext
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:

1 AtParamValueMap* params = AiParamValueMap();
2 AiParamValueMapSetBool(params, AtString("default_lights"), true);
3 AiParamValueMapSetStr(params, AtString("light_type"), AtString("distant_light"));
4 AiParamValueMapSetStr(params, AtString("light_mode"), AtString("three_point"));
5 AiUniverseAddDefaultNodes(universe, params);
6 AiParamValueMapDestroy(params);

Supported params:

default_cameraBOOLEANSet to true to create default camera when none is found
default_lightsBOOLEANSet to true to create default lights when none is found
light_typeSTRINGSelects type of light to be created for default lights (spot_light, distant_light, ...)
light_modeSTRINGSelects light arrangement to create (three_point, flashlight, skydome_light)
Parameters
universeuniverse where nodes will be added (only default universe supported for now)
paramslist of parameters to modify which nodes are created and how
AI_API bool AiUniverseCacheFlush ( int  cache_flags)
inline

Flush one or several caches in the default universe.

This function will release all memory associated with a cached resource. The next time that the resource is accessed, it will get reloaded or recomputed. This is useful in interactive rendering; occasionally, a texture map would need to be modified or updated in the middle of a relighting session.

Parameters
cachea bitmask specifying the cache types to be flushed
Returns
true if the cache was flushed succesfully, false if rendering is still in progress
AI_API AtNode * AiUniverseGetOptions ( )
inline

Fetches the global options node for the default Arnold universe.

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

Returns
pointer to the global options node
AI_API AtNode * AiUniverseGetCamera ( )
inline

Fetches the currently active camera node for the default Arnold universe.

Will return NULL if called outside AiBegin() / AiEnd(), if the camera has not been set or if the linked node is not a camera.

Returns
pointer to the active camera node
AI_API AtBBox AiUniverseGetSceneBounds ( )
inline

Returns the bounding box of the default Arnold universe.

Note that this box may be conservative in the presence of "infinite" primitives or procedurals. If called outside AiBegin()/AiEnd(), this will return an empty box containing the origin.

Returns
scene bounding box
AI_API AtNodeIterator * AiUniverseGetNodeIterator ( unsigned int  node_mask)
inline

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

Parameters
node_maskbitmask 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
AI_API void AiNodeIteratorDestroy ( AtNodeIterator *  iter)

Destroys a node iterator when it is no longer needed.

Parameters
iternode iterator that will be deallocated
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:

1 AtNodeIterator *iter = AiUniverseGetNodeIterator(AI_NODE_ALL);
2 while (!AiNodeIteratorFinished(iter))
3 {
4  AtNode *node = AiNodeIteratorGetNext(iter);
5  // do something with node ...
6 }
7 AiNodeIteratorDestroy(iter);
Parameters
itera node iterator
Returns
the node pointed by the iterator, or NULL if there are no more nodes to iterate over
AI_API AI_PURE bool AiNodeIteratorFinished ( const AtNodeIterator *  iter)

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

Parameters
itera node iterator
Returns
true if the node iterator has moved past the last node
AI_API void AiNodeEntryIteratorDestroy ( AtNodeEntryIterator *  iter)

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

Parameters
iternode entry iterator that will be deallocated
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:

1 AtNodeEntryIterator *iter = AiUniverseGetNodeEntryIterator(AI_NODE_ALL);
2 while (!AiNodeEntryIteratorFinished(iter))
3 {
4  AtNodeEntry *node_entry = AiNodeEntryIteratorGetNext(iter);
5  // do something with node_entry ...
6 }
7 AiNodeEntryIteratorDestroy(iter);
Parameters
itera node entry iterator
Returns
the node entry pointed by the iterator, or NULL if there are no more node entries to iterate over
AI_API AI_PURE bool AiNodeEntryIteratorFinished ( const AtNodeEntryIterator *  iter)

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

Parameters
itera node entry iterator
Returns
true if the node entry iterator has moved past the last node entry
AI_API void AiAOVIteratorDestroy ( AtAOVIterator *  iter)

Destroys a AOV iterator when it is no longer needed.

Parameters
iterAOV iterator that will be deallocated
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:

1 AtAOVIterator* iter = AiUniverseGetAOVIterator();
2 while (!AiAOVIteratorFinished(iter))
3 {
4  AtAOVEntry* aov_entry = AiAOVIteratorGetNext(iter);
5  // do something with aov_entry ...
6 }
7 AiAOVIteratorDestroy(iter);
Parameters
iterAOV iterator
Returns
the AOV pointed by the iterator, or NULL if there are no more AOV entries to iterate over
AI_API AI_PURE bool AiAOVIteratorFinished ( const AtAOVIterator *  iter)

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

Parameters
itera AOV iterator
Returns
true if the AOV iterator has moved past the last AOV

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