Opening Scenes with Auxiliary Data

An auxiliary data file contains a sequence of values that can be set once a scene has finished loading. All parameters are set sequentially prior to registered OnEndSceneOpen events.

Auxiliary data is especially useful for batch rendering because it provides a simple way to modify various parameters of a scene without having to modify the scene file.

NoteAn alternative to auxiliary data is the scene TOC file. One difference is that scene TOC data is specific to individual scenes, while auxiliary data applies to any scene. For more information about scene TOC files, see Getting and Setting Scene Data with the Scene TOC.

Defining an Auxiliary Data File

The auxiliary data file format is a plain ASCII file that must start with the following header:

	XSI_AuxiliaryDataFile ASCII 1 0

The header identifies the file as a v1.0 Auxiliary data file in plain ASCII. At the moment, there is no other format but other file formats may be introduced in the future.

Lines following the header can be:

Comments (lines starting with //).

Comments cannot be put anywhere else but on the start of a line, unlike C++ style comments.
White space (carriage returns, tabs, or spaces).
Parameters.

Parameters use the same syntax as the argument of the Softimage VBScript command SetValue. Every parameter in the auxiliary data file must fit on a single line.

For example, using the following line in your auxiliary file...

"Passes.Default_Pass.RenderOptions.EndFrame", 1

...has the same effect as calling this command in Softimage:

SetValue "Passes.Default_Pass.RenderOptions.EndFrame", 1

NoteEvery parameter in the auxiliary data file must fit on a single line.

Loading and Applying Auxiliary Data

To apply auxiliary data in Softimage, you have to specify which file contains the values you want to set with the -auxiliary_data switch.

If your auxiliary data file is named C:\myData.txt, type the following at the command line:
```
	xsi -auxiliary_data C:\myData.txt
```
This creates a new check box labeled Apply Auxiliary Data in the Open Scene dialog box.
Turn this option on to apply the auxiliary data when a scene is opened. This is a convenient way to test if your auxiliary data is applied correctly.

To apply auxiliary data with scripting

You can use scripting to apply previously loaded auxiliary data. For example, if you want to apply auxiliary data to your scene called C:\MyProject\Scenes\MyScene.scn, use the following command:

	OpenScene "C:\MyProject\Scenes\MyScene.scn",,TRUE

NoteAuxiliary data is not applied by default in both cases (through the interface and scripting).

To apply auxiliary data from the command line

You can apply auxiliary data automatically to a scene from the command line by typing either of these lines at the prompt:

xsi C:\MyProject\Scenes\MyScene.scn -auxiliary_data C:\myData.txt

xsibatch -render -scene C:\MyProject\Scenes\MyScene.scn -auxiliary_data C:/myData.txt

For a description of the difference between xsi and xsibatch, see Issues in Batch Scripting [SDK Guide].

Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License