Scene Format Plugin API

Implementation of custom scene formats. More...

Data Structures
struct	AtSceneFormatLib
	Used by dynamically-linked scene format plugins. More...
struct	AtSceneFormatMethods
	Scene format methods. More...

Macros
#define	AI_SCENE_FORMAT_EXPORT_METHODS(tag)
	Exporter for common methods. More...
#define	scene_format_loader   AI_EXPORT_LIB bool SceneFormatLoader(AtSceneFormatLib* format)
	Entry point for the scene format plugin.
#define	scene_load
	Scene format loading method. More...
#define	scene_write
	Scene format writing method. More...

Typedefs
typedef bool(*	AtSceneLoad) (AtUniverse *universe, const char *filename, const AtParamValueMap *params)
	Scene format load method. More...
typedef bool(*	AtSceneWrite) (AtUniverse *universe, const char *filename, const AtParamValueMap *params, const AtMetadataStore *mds)
	Scene format write method. More...

Variables
const char **	AtSceneFormatLib::extensions
	null-terminated list of extensions used by this format
const char *	AtSceneFormatLib::name
	name of this scene format ("ASS", "USD", etc)
const char *	AtSceneFormatLib::description
	description for this scene format
const void *	AtSceneFormatLib::methods
	pointer to load/write methods for this format
char	AtSceneFormatLib::version [AI_MAXSIZE_VERSION]
	Arnold version that this plugin was compiled against
const AtParamValueMap *	AtSceneFormatLib::params
	optional params that will be passed on to the methods
AtSceneLoad	AtSceneFormatMethods::SceneLoad
AtSceneWrite	AtSceneFormatMethods::SceneWrite

Detailed Description

Implementation of custom scene formats.

This API is used to implement support for loading and/or writing custom scene formats.

Implementing support for a new scene format requires exposing the plugin entry point symbol, which in this case is called SceneFormatLoader(). This can be done through the convenience macro scene_format_loader. For example, this is how a plugin could be implemented to support the fictional ".xxx" scene format:

AI_SCENE_FORMAT_EXPORT_METHODS(XXXSceneFormatMtd);
 
scene_load
{
   . . .
}
 
scene_write
{
   . . .
}
 
scene_format_loader
{
   static const char* extensions[] = { ".xxx", NULL };
 
   format->methods     = XXXSceneFormatMtd;
   format->extensions  = extensions;
   format->name        = "XXX";
   format->description = "Support for loading XXX files in Arnold";
   strcpy(format->version, AI_VERSION);
   return true;
}

Both load and write methods are optional, so any of them can be implemented, or both could be implemented.

Macro Definition Documentation

AI_SCENE_FORMAT_EXPORT_METHODS

#define AI_SCENE_FORMAT_EXPORT_METHODS

(

tag

)

Value:

static AtSceneFormatMethods ai_scene_mtds = {  \
   NULL,                                       \
   NULL                                        \
};                                             \
const AtSceneFormatMethods* tag = &ai_scene_mtds;

Exporter for common methods.

scene_load

#define scene_load

Value:

static bool SceneLoad(AtUniverse* universe, const char* filename, const AtParamValueMap* params); \
AI_OPTIONAL_METHOD_INSTALL(ai_scene_mtds, SceneLoad) \
static bool SceneLoad(AtUniverse* universe, const char* filename, const AtParamValueMap* params)

Scene format loading method.

scene_write

#define scene_write

Value:

static bool SceneWrite(AtUniverse* universe, const char* filename, const AtParamValueMap* params, const AtMetadataStore* mds); \
AI_OPTIONAL_METHOD_INSTALL(ai_scene_mtds, SceneWrite) \
static bool SceneWrite(AtUniverse* universe, const char* filename, const AtParamValueMap* params, const AtMetadataStore* mds)

Scene format writing method.

Typedef Documentation

AtSceneLoad

typedef bool(* AtSceneLoad) (AtUniverse *universe, const char *filename, const AtParamValueMap *params)

Scene format load method.

Parameters

universe	universe where the loaded scene nodes will be created (NULL for default universe)
filename	name of the scene file to load
params	list of arbitrary params which will be interpreted by the specific scene format

Returns

true upon success

AtSceneWrite

typedef bool(* AtSceneWrite) (AtUniverse *universe, const char *filename, const AtParamValueMap *params, const AtMetadataStore *mds)

Scene format write method.

Parameters

universe	universe with the nodes to be written to the scene file (NULL for default universe)
filename	name of the scene file to write to
params	list of arbitrary params which will be interpreted by the specific scene format
mds	metadata store that might be stored in the output scene file (if supported)

Returns

true upon success