/****************************************************************************
**
** Copyright (C) 1993-2009 NVIDIA Corporation.
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qt 3D Studio.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!

\title Using Sub-Presentations
\page best-practices-using-sub-presentations.html
\ingroup qt3dstudio-best-practices

\section1 Introduction

Sub-Presentations is a feature which allows a Studio presentation (\c{.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.

\section1 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.

\section2 Importing Sub-Presentations
To import a sub-presentation, do one of the following:
\list
  \li
    From the menu bar, select \uicontrol{File > Import Assets}. Then locate the \c{.uia} or
    \c{.qml} file you wish to import and press \uicontrol{Save}.
  \li Right-click anywhere in the project palette and select \uicontrol{Import Assets}
    from the context menu. Then locate the \c{.uia} or \c{.qml} file you wish to import and press
    \uicontrol{Save}.
  \li
    Click \inlineimage{import-assets-icon.png}
    in the bottom part of the project palette.
    Then locate the \c{.uia} or \c{.qml} file you wish to import and press \uicontrol{Save}.
\endlist

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 \e{presentations} or
\e{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.

\image {subpresentation-project-structure.png}

\section2 Creating Sub-Presentations

From the editor, you can create a new Studio presentation to use as a sub-presentation.
\list 1
  \li From the menu bar, select \uicontrol{File > New > Presentation}.
  \li Enter a name for the presentation and press \uicontrol{Save}.
  \li The presentation settings dialogue for the new presentation will open. If desired, make
  changes, then press \uicontrol{OK}.
\endlist

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
\uicontrol{Open Presentation}.

\image{open-presentation.png}

\section1 Using Sub-Presentations

\section2 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 \c{.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:
\list
  \li
    Drag the sub-presentation from the project palette to the scene view and select
    \uicontrol{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.
  \li
    Drag the sub-presentation from the project palette to a specific layer in the scene graph.
  \li
    Right-click a layer in the scene graph and select \uicontrol{Set sub-presentation}
    from the context menu. Then select desired sub-presentation.
    \image subpresentation-scene-graph.png
  \li
    Select the layer in the scene graph. Then, in the inspector palette, set the desired
    sub-presentation in the \uicontrol{Sub-presentation} property.
    \image subpresentation-layer-inspector.png
  \li
    Additionally, it is possible to add a sub-presentation as an
    \l {Using Image-based Lighting} {IBL light probe} for a layer. To do this, select the layer
    in the scene graph and set the desired sub-presentation in the \uicontrol{Light Probe} or
    \uicontrol{Secondary Light Probe} property.
\endlist

\section2 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
\c Nearest or \c Linear.

To add a sub-presentation as a texture of a 3D object, do one of the following:
\list
  \li
    Drag the sub-presentation from the project palette to the scene view and select
    \uicontrol{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.
  \li In the scene graph, right-click the material of an object and select
    \uicontrol{Set sub-presentation}. Then select desired sub-presentation and desired property.
    \image subpresentation-material-scene-graph.png
    \image subpresentation-set-as-property.png
  \li
    With the object selected, select the sub-presentation for the desired property in the
    inspector palette.
    \image subpresentation-diffuse-map.png
\endlist

\section1 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.

\list 1
\li
  Layer property \uicontrol{Layer Background} needs to be set to \c{Transparent}.
\li
  Scene property \uicontrol{Set Background} needs to be unchecked.
\endlist

*/