Data Structures | Functions
Scene File API

Scene file loading and writing using multiple formats. More...

Data Structures

struct  AtSceneFormatIterator
 Allows iterating over the list of supported scene formats. More...
 
struct  AtSceneFormatExtensionIterator
 Allows iterating over the list of supported extensions for a given scene format. More...
 
struct  AtSceneFormatData
 Provides access to information about the scene format. More...
 

Functions

AI_API bool AiSceneLoad (AtUniverse *universe, const char *filename, const AtParamValueMap *params)
 Load all nodes from a scene file into a specific Arnold universe. More...
 
AI_API bool AiSceneWrite (AtUniverse *universe, const char *filename, const AtParamValueMap *params, const AtMetadataStore *mds=NULL)
 Write all nodes in the given universe to a scene file. More...
 
AI_API bool AiSceneFormatSupported (const char *extension)
 Check if the scene format corresponding to a given filename extension is supported. More...
 

Node Iterator API

AI_API AtSceneFormatIteratorAiSceneFormatIterator ()
 Get new scene format iterator. More...
 
AI_API void AiSceneFormatIteratorDestroy (AtSceneFormatIterator *iter)
 Destroys scene format iterator and releases any allocated memory. More...
 
AI_API const AtSceneFormatDataAiSceneFormatIteratorGetNext (AtSceneFormatIterator *iter)
 Gets the next supported scene format. More...
 
AI_API AI_PURE bool AiSceneFormatIteratorFinished (const AtSceneFormatIterator *iter)
 Check if there are more scene formats to iterate over. More...
 
AI_API AtSceneFormatExtensionIteratorAiSceneFormatGetExtensionIterator (const AtSceneFormatData *format_data)
 Get an iterator over all supported extensions for this scene format. More...
 
AI_API void AiSceneFormatExtensionIteratorDestroy (AtSceneFormatExtensionIterator *iter)
 Destroys scene format extension iterator and releases any allocated memory. More...
 
AI_API const char * AiSceneFormatExtensionIteratorGetNext (AtSceneFormatExtensionIterator *iter)
 Gets the next supported scene format extension. More...
 
AI_API AI_PURE bool AiSceneFormatExtensionIteratorFinished (const AtSceneFormatExtensionIterator *iter)
 Check if there are more scene formats extensions to iterate over. More...
 
AI_API AI_PURE const char * AiSceneFormatGetName (const AtSceneFormatData *format_data)
 Get the name of the scene format. More...
 
AI_API AI_PURE const char * AiSceneFormatGetDescription (const AtSceneFormatData *format_data)
 Get a description of the scene format. More...
 
AI_API AI_PURE bool AiSceneFormatSupportsReading (const AtSceneFormatData *format_data)
 True if the scene format supports reading from file. More...
 
AI_API AI_PURE bool AiSceneFormatSupportsWriting (const AtSceneFormatData *format_data)
 True if the scene format supports writing to a file. More...
 
AI_API const AtMetadataStoreAiSceneFormatGetMetadataStore (const AtSceneFormatData *format_data)
 Get metadata for the scene format and its optional parameters. More...
 

Detailed Description

Scene file loading and writing using multiple formats.

The implementation of each specific scene format will determine how to load nodes into an Arnold universe or how to store the contents of an Arnold universe into a scene file.

Function Documentation

AI_API bool AiSceneLoad ( AtUniverse universe,
const char *  filename,
const AtParamValueMap *  params 
)

Load all nodes from a scene file into a specific Arnold universe.

If the filename is "-", it reads data from stdin (assuming ASS format)

This example code loads all node types from a scene file:

1 AtParamValueMap* params = AiParamValueMap();
2 AiParamValueMapSetInt(params, AtString("mask"), AI_NODE_ALL);
3 AiSceneLoad(universe, "scene.ass", params);
4 AiParamValueMapDestroy(params);

Supported format specific params:

Scene formatSupported load parameters
ASSmaskINTEGEROnly node types matching this mask will be loaded
USDNone
Parameters
universeuniverse where the nodes will be created (NULL for default universe)
filenameinput filename (extension will be used to determine scene format)
paramslist of arbitrary params which will be interpreted by the specific scene format
Returns
true if the file was loaded succesfully, false otherwise
AI_API bool AiSceneWrite ( AtUniverse universe,
const char *  filename,
const AtParamValueMap *  params,
const AtMetadataStore mds = NULL 
)

Write all nodes in the given universe to a scene file.

This function can selectively write all nodes in a given universe to a scene file, which format will be determined from the filename extension.

An arbitrary list of attributes can be passed, and these attributes can be used by specific file formats. For example, the .ass file format supports "mask", "binary" and "open_procs" attributes, which are equivalent to the parameters on AiASSWrite. Note these attributes might not work on other file formats.

For example, to write light nodes and camera nodes only, use:

1 AtParamValueMap* params = AiParamValueMap();
2 AiParamValueMapSetInt(params, AtString("mask"), AI_NODE_LIGHT + AI_NODE_CAMERA);
3 AiSceneWrite(universe, "lightsncams.ass", params);
4 AiParamValueMapDestroy(params);

To write all nodes of all types, use:

1 AtParamValueMap* params = AiParamValueMap();
2 AiParamValueMapSetInt(params, AtString("mask"), AI_NODE_ALL);
3 AiSceneWrite(universe, "everything.ass", params);
4 AiParamValueMapDestroy(params);

Supported format specific params:

Scene formatSupported write parameters
ASSmaskINTEGEROnly node types matching this mask will be loaded
binaryBOOLEANAllow binary encoding in .ass files
open_procsBOOLEANProcedurals will be expanded before writing
USDNone
Parameters
universeuniverse whose contents will be written to the scene file (NULL for default universe)
filenameoutput filename (extension will be used to select scene format)
paramslist of arbitrary params which will be interpreted by the specific scene format
mdsoptional metadata store for writing metadata into the file
Returns
true if the file was written succesfully, false otherwise
AI_API bool AiSceneFormatSupported ( const char *  extension)

Check if the scene format corresponding to a given filename extension is supported.

Parameters
extensionscene file extension to check for support (should start with ".")
Returns
true if the format is supported, false otherwise
AI_API AtSceneFormatIterator* AiSceneFormatIterator ( )

Get new scene format iterator.

Returns
New scene format iterator
AI_API void AiSceneFormatIteratorDestroy ( AtSceneFormatIterator iter)

Destroys scene format iterator and releases any allocated memory.

Parameters
iterScene format iterator to destroy
AI_API const AtSceneFormatData* AiSceneFormatIteratorGetNext ( AtSceneFormatIterator iter)

Gets the next supported scene format.

Parameters
iterScene format iterator
Returns
Information about the next supported scene format
AI_API AI_PURE bool AiSceneFormatIteratorFinished ( const AtSceneFormatIterator iter)

Check if there are more scene formats to iterate over.

Parameters
iterScene format iterator
Returns
true if the iterator reached the last supported scene format
AI_API AtSceneFormatExtensionIterator* AiSceneFormatGetExtensionIterator ( const AtSceneFormatData format_data)

Get an iterator over all supported extensions for this scene format.

Parameters
format_dataScene format data returned by AiSceneFormatIteratorGetNext
Returns
Iterator
AI_API void AiSceneFormatExtensionIteratorDestroy ( AtSceneFormatExtensionIterator iter)

Destroys scene format extension iterator and releases any allocated memory.

Parameters
iterScene format extension iterator to destroy
AI_API const char* AiSceneFormatExtensionIteratorGetNext ( AtSceneFormatExtensionIterator iter)

Gets the next supported scene format extension.

Parameters
iterScene format extension iterator
Returns
Next supported extension
AI_API AI_PURE bool AiSceneFormatExtensionIteratorFinished ( const AtSceneFormatExtensionIterator iter)

Check if there are more scene formats extensions to iterate over.

Parameters
iterScene format extension iterator
Returns
true if the iterator reached the last supported scene format extension
AI_API AI_PURE const char* AiSceneFormatGetName ( const AtSceneFormatData format_data)

Get the name of the scene format.

Parameters
format_dataScene format data returned by AiSceneFormatIteratorGetNext
Returns
Name of the scene format
AI_API AI_PURE const char* AiSceneFormatGetDescription ( const AtSceneFormatData format_data)

Get a description of the scene format.

Parameters
format_dataScene format data returned by AiSceneFormatIteratorGetNext
Returns
Description of the scene format
AI_API AI_PURE bool AiSceneFormatSupportsReading ( const AtSceneFormatData format_data)

True if the scene format supports reading from file.

Parameters
format_dataScene format data returned by AiSceneFormatIteratorGetNext
Returns
true if it can be read from file, false otherwise
AI_API AI_PURE bool AiSceneFormatSupportsWriting ( const AtSceneFormatData format_data)

True if the scene format supports writing to a file.

Parameters
format_dataScene format data returned by AiSceneFormatIteratorGetNext
Returns
true if it can be written to a file, false otherwise
AI_API const AtMetadataStore* AiSceneFormatGetMetadataStore ( const AtSceneFormatData format_data)

Get metadata for the scene format and its optional parameters.

Parameters
format_dataScene format data returned by AiSceneFormatIteratorGetNext
Returns
Metadata store with all metadata for the scene format and its optional parameters

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