Getting and Setting Scene Data with the Scene TOC

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, XSI looks for a corresponding scene TOC file. If it is found, XSI automatically applies the information it contains.

This lets you 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.

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

Enabling Scene TOC Files

When you enable scene TOC files, XSI 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 generate the scene TOC files when a scene is saved

1. Choose File > Preferences from the main menu.

2. In the Preferences window, select Data Management.

3. On the Files tab, activate the Create scene TOC (Table of Contents) file option.

Disabling Scene TOC Files

You can turn off the generation of scene TOC files at any time. The next time you save any 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 generation of scene TOC files

1. Choose File > Preferences from the main menu.

2. In the Preferences window, select Data Management.

3. On the Files tab, deactivate the Create scene TOC (Table of Contents) file option.

Modifying the Scene TOC

You can edit the scene TOC file outside of XSI 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.

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, XSI 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>

As 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.

SOFTIMAGE|XSI v.7.0