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.
An 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.
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
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
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].
