- Qt 3D Studio
- Best Practices
- Using Sub-Presentations
- Qt 3D Studio 2.8 Manual

# Using Sub-Presentations

## Introduction

Sub-Presentations is a feature which allows a Studio presentation (`.uia` file) or a QML file to be embedded in a Studio presentation.

Sub-presentations execute independently, albeit inside the same Runtime process as the initial presentation. The rendered frame from each sub-presentation is essentially used as a texture on a rectangle in the main presentation. This allows control over where and how each sub-presentation is composited into the final frame.

There are two different ways to display a sub-presentation; on a separate layer or as a texture on a 3D object.

## Importing and Creating Sub-Presentations

To use a sub-presentation, you will first need to add it to your project. This can be done either by creating a new one or importing an existing one. Sub-presentations of QML stream type cannot be created from the editor, only imported.

### Importing Sub-Presentations

To import a sub-presentation, do one of the following:

- From the menu bar, select File > Import Assets. Then locate the `.uia` or `.qml` file you wish to import and press Save.
- Right-click anywhere in the project palette and select Import Assets from the context menu. Then locate the `.uia` or `.qml` file you wish to import and press Save.
- Click in the bottom part of the project palette. Then locate the `.uia` or `.qml` file you wish to import and press Save.

Sub-presentations will be imported to the folder that is selected in the project palette. If no folder is selected, sub-presentations will be imported to the presentations or qml folder depending on the type of the sub-presentation. All assets (such as images, 3D models and effects) and folders of the imported sub-presentation will be imported.

### Creating Sub-Presentations

From the editor, you can create a new Studio presentation to use as a sub-presentation.

1. From the menu bar, select File > New > Presentation.
2. Enter a name for the presentation and press Save.
3. The presentation settings dialogue for the new presentation will open. If desired, make changes, then press OK.

Once created, your new presentation will open in the editor. To return to edit your main presentation (or any other sub-presentation), right-click it in the project palette and select Open Presentation.

## Using Sub-Presentations

### Adding a Sub-Presentation to a Layer

One of the main benefits of adding a sub-presentation on a layer is that you can author different parts of a large presentation as separate smaller presentations. This can help control complexity in single `.uip` files, as well as allow different parts of a presentation to be authored separately and simultaneously.

When you add a sub-presentation to a layer in either way described below, the layer will scale to match the size of the sub-presentation.

To add a sub-presentation to a layer, do one of the following:

- Drag the sub-presentation from the project palette to the scene view and select Layer from the dialogue. The sub-presentation will be added to the active layer, if no layer is active it will be added to the topmost layer.
- Drag the sub-presentation from the project palette to a specific layer in the scene graph.
- Right-click a layer in the scene graph and select Set sub-presentation from the context menu. Then select desired sub-presentation.

- Select the layer in the scene graph. Then, in the inspector palette, set the desired sub-presentation in the Sub-presentation property.

- Additionally, it is possible to add a sub-presentation as an IBL light probe for a layer. To do this, select the layer in the scene graph and set the desired sub-presentation in the Light Probe or Secondary Light Probe property.

### Adding a Sub-Presentation as a texture

One benefit of displaying a sub-presentation as a texture is that you can use Studio presentations and QML files to map the materials of objects in your presentation. You can apply sub-presentations to any map or image property of a material, i.e. diffuse maps, specular maps and displacement maps. This way you can for example create animated textures. For performance reasons it is best to disable mipmapping for subpresentation images by setting the minification filter to `Nearest` or `Linear`.

To add a sub-presentation as a texture of a 3D object, do one of the following:

- Drag the sub-presentation from the project palette to the scene view and select Texture from the dialogue. This will create a rectangle object in the scene and add the sub-presentation as a diffuse map to its material.
- In the scene graph, right-click the material of an object and select Set sub-presentation. Then select desired sub-presentation and desired property.

- With the object selected, select the sub-presentation for the desired property in the inspector palette.

## Transparency

To display the sub-presentation background as transparent in the main presentation there are two settings in the sub-presentation that needs to be set.

1. Layer property Layer Background needs to be set to `Transparent`.
2. Scene property Set Background needs to be unchecked.