Getting and Setting Scene Data with the Scene TOC

The scene TOC (scene table of contents) is an XML-based file that contains scene information. It has an extension of .scntoc with the same name and in the same folder as the corresponding scene file.

When you open a scene file, Softimage looks for a corresponding scene TOC file. If it is found, Softimage automatically reads and applies the information it contains. You can modify this default behavior by individually setting the Create and Read scene TOC preferences. For more information, see Creating and Reading Scene TOC Files.

The benefit of a scene TOC file is that you can use a text editor or XML editor to do any of the following:

Set the resolution of referenced models, as well as change the external files used for the resolutions and deltas.
Change the path for external files such as texture images, audio, or actions.
Change render options.
Change the current render pass.
Run a script automatically after loading the scene.

These options are discussed in more detail in Modifying the Scene TOC.

NoteAn alternative to using scene TOC files to modify data is to use auxiliary data. One difference is that scene TOC data is specific to individual scenes while auxiliary data applies to any scene. For more information about auxiliary data, see Opening Scenes with Auxiliary Data.

Creating and Reading Scene TOC Files

When you enable the creation and reading of scene TOC files, Softimage saves the current scene information to the corresponding scene TOC file every time you save a scene. You can then modify the scene TOC file in a text editor or XML editor, and the modifications are automatically applied the next time that scene is opened.

To automatically create and read scene TOC files

Choose File Preferences from the main menu.
In the Preferences window, select Data Management.
On the Files tab, activate the Create scene TOC (Table of Contents) file and the Read scene TOC (Table of Contents) file on load if available options (both options are enabled by default).

To disable the creation of scene TOC files

You can turn off the creation of scene TOC files at any time, by deactivating the Create scene TOC (Table of Contents) file option. If the Read scene TOC (Table of Contents) file on load if available option is enabled, the next time you open the scene, the TOC file is read and applied. However, when you save the scene, the corresponding TOC file's extension is changed from .scntoc to .scntoc_Obsolete so that it will be ignored when you reopen the scene.

To disable the reading of scene TOC files

You can turn off the reading of scene TOC files at any time, by deactivating the Read scene TOC (Table of Contents) file on load if available option. The next time you open the scene, the TOC file is ignored and none of the information it contains will be applied to your scene. If the Create scene TOC (Table of Contents) file option is enabled, when you save the scene, the current scene information is also saved to the corresponding scene TOC file.

Getting Version Information from the Scene TOC

The root <xsi_file> element has a sub-element called xsi_version that indicates the version of Softimage used to create the associated scene file.

The version number is specified in the format of Major.Minor.BuildNumber.UpdateNumber.

For example:

<xsi_file type="SceneTOC" xsi_version="8.0.114.0" syntax_version="2.0">

It is important to note that Softimage's internal version number may not match the one used in its product display name. For example, 8.0 is the internal version number for Autodesk Softimage 2010. Version 2010 is used in the product name for the splash screen and install path, but the scene information and the Softimage SDK will return the version number as 8.0.

Modifying the Scene TOC

You can edit the scene TOC file outside of Softimage using a text editor or XML editor. Any changes you make are automatically applied the next time the scene is opened.

The root <xsi_file> element has five child elements whose content can be modified:

<Models> specifies the referenced models used in the scene, including the external files used for different resolutions, the active resolution, and the delta file (if using an external delta).
<Sources> specifies the paths and file names of images, external actions, audio, and referenced models.
<Passes> specifies the render options for every pass in the scene.
<Parametersvalues> specifies the current (that is, active) render pass.
<PostLoadScript> lets you write a script to be executed after the scene is loaded and after all other modifications in the scene TOC file have been applied.

In general, you can change the content of any element in the scene TOC — that is, anything between the start and end tags. You should not change any attributes within the tags themselves, with certain exceptions as noted elsewhere.

Modifying Referenced Models

The <Models> element of the Scene TOC file contains a <Model> element for every referenced model in the scene. In turn, each <Model> element has a <resolution> element for each resolution, as well as a <delta> element if the delta is external.

<Models>
  <Model name="RefModel" active_resolution="2">
   <resolution name="Offloaded" id="0" href=""></resolution>
   <resolution name="res1" id="1" href="file://Models\lo-res.emdl"></resolution>
   <resolution name="res2" id="2" href="file://Models\md-res.emdl"></resolution>
   <resolution name="res3" id="3" href="file://Models\hi-res.emdl"></resolution>
   <delta name="Delta" href="file://Deltas\RefModel_Delta.delta"></delta>
  </Model>
 </Models>

You can substitute a file or change the active resolution by modifying the appropriate attribute. You cannot change the name attribute of any element. You also cannot add additional models, resolutions, or deltas.

Modifying Sources

The <Source> element of the Scene TOC file contains elements for external files such as images used in the scene. You can change the contents of any source in the <Sources> section of the scene TOC file. For example, this lets you change the path of a texture file or even substitute textures. Do not change the source name attribute.

For example, you can change this:

<Image name="metal">\slowserver\myTexLib\dull.pic</Image>

To this:

<Image name="metal">\fastserver\myTexLib\shiny.pic</Image>

The order of elements within <Sources> is not important. If you do not want to modify a particular source, you can remove the corresponding element; however, that element reappears the next time the scene TOC is saved.

Modifying Render Options

The <Passes> element of the Scene TOC file contains the rendering options for all the passes. There are three <RenderOption> elements with the names RenderOptions, HardwareRenderer, and mentalray for the scene global and renderer-specific options.

In addition, there is a <Pass> element for every render pass in the scene. Each <Pass> element contains the render options for that pass.

You can modify a render option for a specific pass by changing the contents of the corresponding element. For example, you can change this:

<StartFrame>1</StartFrame>

To this:

<StartFrame>24</StartFrame>

Note that some options are interdependent; for example, <PictureRatio> is related to <CameraXRes> and <CameraYRes>. In these cases, Softimage applies the values in order and recalculates the others, so the last value to be set is the one that "wins." You can change the priority by reordering the elements in <RenderOptions>.

If you do not want to change a render option, you can remove the corresponding element; however, that element reappears the next time the scene TOC is saved.

You cannot add a pass or change the name of an existing pass.

Modifying Other Parameters

The <Parametersvalues> element of the Scene TOC file lets you set two other parameter values: which render pass is current, and the frame rate.

For example to change the current render pass, you can change this:

<Param name="Passes.current">Passes.Default_Pass</Param>

To this:

<Param name="Passes.current">Passes.Diffuse</Param>

You must specify the name of an existing pass in the scene.

To change the frame rate, you can change this:

<Param name="PlayControl.Rate">29.970030</Param>

To this:

<Param name="PlayControl.Rate">25.0</Param>

Running Post Load Scripts

The <PostLoadScript> element of the scene TOC file lets you run a script procedure after the scene is loaded and after all other modifications (both in the TOC file and in the auxiliary data, if any) have been applied. It consists of three children: <Language>, <Function>, and <Script_Content>.

The <Language> element specifies the scripting language used. Depending on the languages available on your computer, you can specify any of the following:

VBScript
JScript
PerlScript
Python

For example:

<Language>VBScript</Language>

The <Function> element specifies the procedure to run. For example:

<Function>myPostLoadProc</Function>

The specified procedure must be declared in the <Script_Content> element. The <Script_Content> element can contain multiple procedures, and you can switch between them easily by changing <Function>.

If there is any global code in the <Script_Content> element (that is, if there is code that is not contained in a subroutine or function), the global code is executed before the specified procedure. This is a side-effect of parsing the script.

Global code is also executed if you do not specify a procedure to run.

The <Script_Content> element contains the actual code to run. You should enclose the script in a CDATA section; this allows you to use characters that have special meaning in XML syntax, such as <, >, and &. For example, in VBScript:

<Script_Content>
  <![CDATA[
    sub myPostLoadProc
      LogMessage "Running scene TOC postload script"
    end sub
  ]]>
</Script_Content>

NoteAs an alternative to using a script in the scene TOC file to modify values, you can use auxiliary data. One difference is that scene TOC data is specific to individual scenes, while auxiliary data applies to any scene. For more information about auxiliary data, see Opening Scenes with Auxiliary Data.