- Qt 3D Studio
- File Formats
- The .uia File Format
- Qt 3D Studio 2.8 Manual

# The .uia File Format

TODO: Rewrite is needed.

Every project has one `.uia` file (which we like to pronounce as "OO-yah!") representing the application. This XML file is created automatically when you create a new project with Qt 3D Studio. The file contains an `<assets>` section followed by zero or more `<statemachine>` sections:

     <?xml version="1.0" encoding="UTF-8"?>
     <application scalemode="center" watermark-location="1.0 1.0" xmlns="http://nvidia.com/uicomposer">
       <assets initial="#IVI">
         <behavior     id="MainApp" src="scripts/App.lua"                        />
         <presentation id="IVI"     src="IVI.uip"                                />
         <presentation id="music"   src="sub_music.uip"                          />
         <presentation id="radio"   src="sub_radio.uip"   active="false"         />
         <statemachine id="logic"   src="./charts/app.scxml" datamodel="getIt()" />
         <renderplugin id="plugin:mapviewer" src="scripts/mylib.so" args="whee"  />
       </assets>

       <statemachine ref="#logic">
         <visual-states>
           <state ref="Menu">
             <enter>
               <goto-slide element="IVI:Scene.Layer3D.Camera" slide="Animated"/>
             </enter>
             <exit>
               <goto-slide element="IVI:Scene" rel="next" wrap="true"/>
             </exit>
           </state>
           <state ref="Climate"><enter>
             <call element="IVI:Scene.Menu" handler="focusItem" arguments="'Climate'"/>
             <set-attribute element="IVI:Scene.Subs" attribute="sourcepath" value="'phone'"/>
           </enter></state>
           <transition ref="transition_93">
             <fire-event element="IVI:Scene" event="onSomethingHappened" />
           </transition>
         </visual-states>
       </statemachine>
     </application>

## Application

The `<application>` element encompasses the contents of the file and also specifies simple attributes for the application's display.

The `scalemode="..."` attribute specifies how large the "initial presentation" (see below) is rendered when the dimensions of the supplied viewport are different than the size entered for that presentation. There are three legal values for this attribute:

- `scalemode="center"` - the presentation is rendered at the size specified in Studio. Additional content is cropped, additional space is letterboxed. This setting is the default behavior if not specified.
- `scalemode="fit"` - the aspect ratio of the initial presentation is preserved, letterboxing as needed.
- `scalemode="fill"` - the presentation is always rendered to fill the viewport.

For more information on the behavior of the `scalemode` settin - nd its interaction with layer sizing and camera scalin - ee Using Scale Modes.

## Assets

The `<assets>` section may contain one or more `<behavior/>`, `<presentation/>`, `<statemachine/>`, and `<renderplugin/>` elements, in any order.

Each asset must have a unique `id="..."` attribute and a `src="..."` attribute referencing the location of the file (relative to the project folder).

A `<statemachine/>` asset may optionally have a `datamodel="..."` attribute. If present, this attribute must provide valid Lua code to run that returns a Lua table. The contents of this table will be used for the initial values in the data model of the state chart.

A `<renderplugin/>` asset may optionally have a `args="..."` attribute. This provides arguments needed to initialize the shared library for the plugin.

An application does not need any `<presentation/>` elements to run. This allows you to create state charts and test them before any visuals have been created. Such an application will not display anything on screen, however.

If more than one `<presentation/>` asset is supplied then the first one listed is chosen as the `initial' (outermost) presentation that renders for the application; all others are treated as `sub-presentations' which may be referenced by the main presentation. To select a different presentation as the initial the `<assets>` element may have an `initial="\#presentation-id"` attribute referencing the presentation to use as the main presentation.

A `<presentation/>` element may optionally have an `active="..."` attribute with either the value `true` (the default) or `false`. See the `<set-presentation> action` below for more information on the effects of making a presentation inactive.

All `<behavior/>` assets are initialized before any `<statemachine/>` assets, regardless of element ordering. This allows you to create a global function in your application behaviors and use that function to initialize the data model for a state chart.

## Visual States

Each `<statemachine/>` in the `<assets>` section (above) may have a paired `<statemachine>` element following the `<assets>` section. These provide the glue between the logical states of the state chart and the visual impact displayed by the presentation(s).

A `<statemachine>` section must have a `ref="\#statemachine-asset-id"` attribute referencing the state chart to listen to.

The only allowed child element of a `<statemachine>` section is `<visual-states>`. The `<visual-states>` element may have zero or more `<state>` and `<transition>` elements, in any order.

- Each `<state>` element must have a `ref="StateId"` attribute describing a valid state id in the associated state chart. It may have either or both of `<enter>` and `<exit>` elements, describing what occurs when the state is entered or exited. Each of these elements may have zero or more visual action elements (see below).
- Each `<transition>` element must have a `ref="TransitionId"` attribute describing a valid transition id in the associated state chart. It may have zero or more visual action elements that describe what occurs when the transition is taken.

## Visual Actions

The content elements in each `<enter>`, `<exit>`, and `<transition>` element may be any of the following (as many as you like, in any order):

### `<goto-slide element="..."/>`

Change scene or component slide, possibly changing how it plays.

- The `element` attribute must reference a full path to a Scene or component element in a presentation, prefixed with that presentation's id and a colon. For example, `element="IVI:Scene.Background.Theme"`.
- The action must have either a `slide="..."`** or `rel="..."` attribute (but not both):
- The `slide` attribute must reference the name of a slide to go to.
- The `rel` attribute must be either `rel="next"` or `rel="prev"`, describing a direction to change slides.
  - (optional) With `rel` you may also supply `wrap="true"` to indicate that slide changes past the end of the slide list should wrap to the slide on the other end.
- (optional) Specifying `direction="..."` will force playback on the new slide to go either `forward` or `reverse`.
- If the direction is `reverse` and no `time="..."` attribute is specified (see below) then playback will start at the end time of the slide.
- (optional) Specifying `mode="..."` will override the play mode for the slide to be one of: `stopatend`, `looping`, `ping`, `pingpong`, or `playthrough`.
- If `playthrough` is specified you must also add `playthroughto="..."` with either the name of a slide to play through to, or the values `next` or `previous`.
- (optional) Specifying `state="..."` with either `play` or `pause` will override the play state set for the slide.
- (optional) Specifying `rate="..."` with a floating point value will cause the playback speed to be multiplied by this value.
- For example, a value of `2` will cause animations on the slide to play back twice as fast as normal, while a value of `0.5` will cause animations to play at half speed.
- The behavior of the runtime for negative rate values is not guaranteed; use `direction="reverse"` to play backwards.
- (optional) Specifying `time="..."` with a floating point value will cause playback to start at the specified time.

### `<call element="..." handler="..."/>`

Invoke a function on a presentation behavior.

- The `element` attribute must reference a full id-prefixed path to a behavior element in a presentation.
- The `handler` attribute must match the name of a function value on the table for the referenced behavior.
- (optional) Specifying an `arguments="..."` attribute allows you to pass arguments to the function. The contents of this attribute are evaluated in the global Lua context. If the resulting value is a Lua table, it is treated as a list and each integer-keyed value passed to the function through `unpack()`. If the result is any other type of value it is passed as a single first parameter to the function.
- To pass just one argument, use `arguments="42"`
- To pass multiple arguments, use `arguments="\{1,2,3\}"`
- To pass a single Lua table to the function wrap it in a list table, e.g. `arguments="\{\{hello='World',valid=true\}\}"`

### `<set-attribute element="..." attribute="..." value="..."/>`

Set a value on a presentation element.

- The `element` attribute must reference a full id-prefixed path to any element in a presentation.
- The `attribute` attribute must match the scripting name of an attribute on that element.
- The `value` attribute must provide a Lua expression to evaluate, the result of which will be set as the value on the element.

For example, `<set-attribute element="IVI:Scene.Background" attribute="name" value="'new name'"/>`; note the extra quotes needed in the `value` attribute to set a string value.

### `<set-presentation ref="..." attribute="active" value="..."/>`

make a presentation active/inactive.

- The `ref` must be the id of a `<presentation/>` in the `<assets>` section.
- The `attribute` attribute must be equal to `active`. (Future releases may allow the control of more presentation attributes.)
- The `value` attribute must be either `true` or `false`. (Arbitrary Lua expressions are not supported at this time.)

For example, `<set-presentation ref="music" attribute="active" value="true"/>`.

Notes

- Making a presentation inactive prevents any elements, behaviors, and animations within it from updating. It also prevents any events within that presentation from being processed. It does not, however, prevent the presentation from rendering. An inactive presentation will continue to render using its last-updated information.
- Explicitly inactivating presentations can provide a significant performance increase, depending on the number and size of the presentations that are inactive.
- Inactive presentations are not `paused'. When the presentation is re-activated, animations will resume at the time they should be had they been running, not where they were when the presentation was made inactive.

### `<fire-event element="..." event="..."/>`

Fire a presentation event on an element in the presentation.

- The `element` attribute must reference a full id-prefixed path to any element in a presentation.
- The `event` attribute must be the name of the event to fire.