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 AtSceneFormatIterator *	AiSceneFormatIterator ()
	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 AtSceneFormatData *	AiSceneFormatIteratorGetNext (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 AtSceneFormatExtensionIterator *	AiSceneFormatGetExtensionIterator (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 AtMetadataStore *	AiSceneFormatGetMetadataStore (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

AiSceneLoad()

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:

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

Supported format specific params:

Scene format	Supported load parameters
ASS	mask	INTEGER	Only node types matching this mask will be loaded
USD	mask	INTEGER	Only node types matching this mask will be loaded
	frame	FLOAT	Load a given frame from the USD file

Parameters

universe	universe where the nodes will be created (NULL for default universe)
filename	input filename (extension will be used to determine scene format)
params	list of arbitrary params which will be interpreted by the specific scene format

Returns

true if the file was loaded succesfully, false otherwise

AiSceneWrite()

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:

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

To write all nodes of all types, use:

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

Supported format specific params:

Scene format	Supported write parameters
ASS	mask	INTEGER	Only node types matching this mask will be written
	binary	BOOLEAN	Allow binary encoding in .ass files
	open_procs	BOOLEAN	Procedurals will be expanded before writing
USD	mask	INTEGER	Only node types matching this mask will be written

Parameters

universe	universe whose contents will be written to the scene file (NULL for default universe)
filename	output filename (extension will be used to select scene format)
params	list of arbitrary params which will be interpreted by the specific scene format
mds	optional metadata store for writing metadata into the file

Returns

true if the file was written succesfully, false otherwise

AiSceneFormatSupported()

AI_API bool AiSceneFormatSupported

(

const char *

extension

)

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

Parameters

extension

scene file extension to check for support (should start with ".")

Returns

true if the format is supported, false otherwise

AiSceneFormatIterator()

AI_API AtSceneFormatIterator * AiSceneFormatIterator

(

)

Get new scene format iterator.

Returns

New scene format iterator

AiSceneFormatIteratorDestroy()

AI_API void AiSceneFormatIteratorDestroy

(

AtSceneFormatIterator *

iter

)

Destroys scene format iterator and releases any allocated memory.

Parameters

iter	Scene format iterator to destroy

AiSceneFormatIteratorGetNext()

AI_API const AtSceneFormatData * AiSceneFormatIteratorGetNext

(

AtSceneFormatIterator *

iter

)

Gets the next supported scene format.

Parameters

iter	Scene format iterator

Returns

Information about the next supported scene format

AiSceneFormatIteratorFinished()

AI_API AI_PURE bool AiSceneFormatIteratorFinished

(

const AtSceneFormatIterator *

iter

)

Check if there are more scene formats to iterate over.

Parameters

iter	Scene format iterator

Returns

true if the iterator reached the last supported scene format

AiSceneFormatGetExtensionIterator()

AI_API AtSceneFormatExtensionIterator * AiSceneFormatGetExtensionIterator

(

const AtSceneFormatData *

format_data

)

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

Parameters

format_data

Scene format data returned by AiSceneFormatIteratorGetNext

Returns

Iterator

AiSceneFormatExtensionIteratorDestroy()

AI_API void AiSceneFormatExtensionIteratorDestroy

(

AtSceneFormatExtensionIterator *

iter

)

Destroys scene format extension iterator and releases any allocated memory.

Parameters

iter	Scene format extension iterator to destroy

AiSceneFormatExtensionIteratorGetNext()

AI_API const char * AiSceneFormatExtensionIteratorGetNext

(

AtSceneFormatExtensionIterator *

iter

)

Gets the next supported scene format extension.

Parameters

iter	Scene format extension iterator

Returns

Next supported extension

AiSceneFormatExtensionIteratorFinished()

AI_API AI_PURE bool AiSceneFormatExtensionIteratorFinished

(

const AtSceneFormatExtensionIterator *

iter

)

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

Parameters

iter	Scene format extension iterator

Returns

true if the iterator reached the last supported scene format extension

AiSceneFormatGetName()

AI_API AI_PURE const char * AiSceneFormatGetName

(

const AtSceneFormatData *

format_data

)

Get the name of the scene format.

Parameters

format_data

Scene format data returned by AiSceneFormatIteratorGetNext

Returns

Name of the scene format

AiSceneFormatGetDescription()

AI_API AI_PURE const char * AiSceneFormatGetDescription

(

const AtSceneFormatData *

format_data

)

Get a description of the scene format.

Parameters

format_data

Scene format data returned by AiSceneFormatIteratorGetNext

Returns

Description of the scene format

AiSceneFormatSupportsReading()

AI_API AI_PURE bool AiSceneFormatSupportsReading

(

const AtSceneFormatData *

format_data

)

True if the scene format supports reading from file.

Parameters

format_data

Scene format data returned by AiSceneFormatIteratorGetNext

Returns

true if it can be read from file, false otherwise

AiSceneFormatSupportsWriting()

AI_API AI_PURE bool AiSceneFormatSupportsWriting

(

const AtSceneFormatData *

format_data

)

True if the scene format supports writing to a file.

Parameters

format_data

Scene format data returned by AiSceneFormatIteratorGetNext

Returns

true if it can be written to a file, false otherwise

AiSceneFormatGetMetadataStore()

AI_API const AtMetadataStore * AiSceneFormatGetMetadataStore

(

const AtSceneFormatData *

format_data

)

Get metadata for the scene format and its optional parameters.

Parameters

format_data

Scene format data returned by AiSceneFormatIteratorGetNext

Returns

Metadata store with all metadata for the scene format and its optional parameters