/****************************************************************************
**
** Copyright (C) 2019 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 Lights
\page lights.html

Lights are the primary source to provide lighting in a Studio scene. Another way to light a
scene is \l{Using Image-based Lighting}{Image Based Lighting}.

By default, all new presentations will be created with one directional light in them. Additionally,
all layers created will be created with one directional light on them. The default scope of a light
is the layer they are located on, meaning that all objects on that layer will be effected by the
light.

\note Each additional light will reduce rendering performance of your presentation. Keep it
as simple as possible and use lights sparingly.

\section1 Light Types

\section2 Directional

The directional light emits light in one direction from a unidentifiable source located infinitely
far away. This is similar to the way sun light works in real life. If
\l {light properties}{Cast Shadows} is enabled, shadows will be parallel to the light direction.
A directional light has infinite range and does not diminish.

\image directional-light.png

Moving a directional light does not have any effect. The light will always
be emitted in the direction of the lights Z axis, rotating the light along its X or Y axis will
change the direction the light is emitted.

Scaling a directional light will only have an effect in the following cases:

\list
  \li
    If Z scale is set to a negative number, the light will be emitted in opposite direction.
  \li
    If the scale of any axis is set to 0, the light will be emitted along the world's Z axis.
    Rotating the light will then have no effect.
\endlist

\image directional-light-scene.png

By default, all new light objects created in Studio will be directional lights.

\section2 Point

The point light can be described as a sphere, emitting light with equal strength in all directions
from the center of the light. This is similar to the way a light bulb emits light.

\image point-light.png

Rotating or scaling a point light does not have any effect. Moving a point light will change the
position from where the light is emitted.

\image point-light-scene.png

By default, a point light has infinite range and does not diminish. However, the fade-off
(and range) can be controlled with the \l {light properties}{Linear Fade}
and \l {light properties}{Exponential Fade} properties.

The table below shows the difference between linear and exponential fade. In this example the Z
position of the light is 0, while the Z position of the cubes are 200, 400 and 700
respectively. The brightness of the light is 200.

\table
  \header
    \li
    \li {4,1} Fade value
  \row
    \li
    \li 20
    \li 50
    \li 100
    \li 200
  \row
    \li Linear fade
    \li \image linear-fade-20.png
    \li \image linear-fade-50.png
    \li \image linear-fade-100.png
    \li \image linear-fade-200.png
  \row
    \li Exponential fade
    \li \image exponential-fade-20.png
    \li \image exponential-fade-50.png
    \li \image exponential-fade-100.png
    \li \image exponential-fade-200.png
\endtable

\section2 Area

The area light is similar to the directional light, but instead of emitting equally bright light
across the whole scene, the area light emits directional light from a rectangle shaped object. Aside
from the size, an area light has the same characteristics and properties as the directional light.

The image below shows an example on how to light an object with different colors using two
different area lights.

\image area-light.png

Rotating, scaling and moving actions will all effect an area light.

\section1 Working with Lights

\section2 Add Lights

To add a light to a layer, drag it from the basic objects palette to either the scene graph or the
scene view.

\section2 Delete Lights
To delete a light, do one of the following:

\list 1
  \li Select the light in the scene graph or scene view, next press the \c Del key.
  \li Right-click the light in the scene graph, next select \uicontrol {Delete Object} from the
  context menu.
\endlist

\section1 Animating Lights

It is possible to animate most of the properties for lights. To read more about animations, see
the \l {Animations} section.

\section1 Light Properties

For full details on all light properties, see the
\l{studio-inspector-palette.html#light-properties}{inspector palette documentation}.

*/