/****************************************************************************
**
** Copyright (C) 2018 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 Layers
\page layers.html

A single Studio presentation combines one or more \e layers. The visual result of each \e layer
comes from rendering a 3D scene, 2D scene (via an orthographic camera), or sub-presentation. Layers
are then composited with items on upper layers drawing on top of the content on lower layers.

A new presentation will be created with one layer by default. It is possible to add and remove
layers as desired, but there must always be at least one layer in a presentation.

When working with layers, keep it as simple as possible. For best performance:
\list
  \li Use as few layers as possible
  \li Use as small layers as possible
\endlist

\section1 Add a layer

To add a layer to a presentation, do one of the following:
\list
  \li In the bottom of the scene graph, press the
    \inlineimage Studio-Timeline-NewLayer.png
    icon.
  \li
    Right-click on the scene element in the scene graph, then select \uicontrol{Add Layer}
    \image add-layer-context.png
  \li
    Press \c{Ctrl + L}.
\endlist

\section1 Delete a layer

Deleting a layer will delete the layer itself, as well as all the elements on the layer.

To delete a layer, do one of the following:

\list
  \li
    Select the layer in the scene graph, then press \c{Del}.
  \li
    Select the layer in the scene graph, then press the
    \inlineimage Studio-Timeline-DeleteLayer.png
    icon in the bottom of the scene graph.
  \li
    Select the layer in the scene graph, then select \uicontrol{Edit > Delete Object} from the
    menu bar.
  \li
    Right-click on the layer in the scene graph, then select \uicontrol{Delete Object} from the
    context menu.
    \image delete-layer-context.png
\endlist

\section1 Rearranging layers

You can rearrange layers by dragging them in the scene graph as described in the
\l {Rearranging Elements}{timeline palette documentation}.

\note Layers must exist directly under the scene element, you can not move layers under other
elements.

The order of layers in the scene graph determines the order they are rendered. The top-most layer
will render last, hence it will render on top of below layers.

\section1 More About Layers

\section2 Layer Properties

For full list of layer properties, see the \l{layer-properties}{layer properties documentation}

\section2 Layer Effects

Each layer in a presentation may have one or more post-processing effects applied to the visual
result. A library of predefined effects is included in Qt 3D Studio.
Read more about \l{Applying Layer Effects}.

\section2 Blend Mode

The \l{Blend Mode} property controls how the colors of the active layer or object are blended with
the colors of the background layer or object.

\section2 Disable Depth Test

The \l{Disable Depth Test} property can be used to simultaneously override depth testing and
the order objects are rendered.

\section2 Variant Tags
\l{Using Variant Tags}{Variant tags} makes it possible to exclude layers during loading to
optimize performance.

\section2 Dynamic Resize
The Dynamic Resize property causes the layer to be dynamically resized based on the content.
This makes the layer texture as small as it can be while still showing all the content.
Thus effects like SSAA can be done more efficiently on the layer, since the empty space around
the content doesn't take up computing power. This can also, depending on the hardware, cause
performance problems due to constant resizing. This can be mitigated with the Padding property.
While resizing may cause problems on the GPU side, the content bounds calculation also takes time
on the CPU. If more inaccurate bounds are enough, Combine Bounds can be used to have less
calculations per object in the layer. The user has to balance the performance cost of the resize
to the performance gain of the lower texture size when evaluating the use of this feature.

*/