// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page studio-3d-scene-environment.html
    \previouspage studio-3d-camera.html
    \nextpage studio-3d-morph-target.html

    \title Scene Environments

    The \uicontrol {Scene Environment} and the \uicontrol {Extended Scene Environment}
    components define how a scene is rendered globally.

    \note The available properties for the scene environments and their location in the
    \uicontrol Properties view vary according to \uicontrol {Target Qt Version} that
    you select when \l {Creating projects}{creating your project}.

    \note \uicontrol {Extended Scene Environment} is available in projects created with
    Qt 6.5 or higher as \uicontrol {Target Qt Version}.

    \section1 Creating a new project with a scene environment

    To include a scene environment component in your project, select a suitable preset when
    \l{Creating projects}{creating your project}:
    \list
        \li Choose the \uicontrol {3D} preset to create a project with a \uicontrol View3D
            component that includes a \uicontrol {Scene Environment}.
        \li Choose the \uicontrol {3D Extended} preset to create a project with an
            \uicontrol {Extended View3D} component that includes an
            \uicontrol {Extended Scene Environment}.
    \endlist

    \section1 Adding a scene environment to an existing project

    To add a 3D view component, which includes a scene environment, drag it from
    \uicontrol Components > \uicontrol {Qt Quick 3D} > \uicontrol Items to
    \uicontrol Navigator or the \uicontrol {2D} view.

    To add a scene environment component separately to your project, drag it
    from \uicontrol Components to a 3D view component in \uicontrol Navigator.
    The \uicontrol {Scene Environment} component is available in \uicontrol {Qt Quick 3D} >
    \uicontrol Components and the \uicontrol {Extended Scene Environment} in
    \uicontrol {Qt Quick 3D Helpers}.

    \section1 Setting a scene environment

    To define properties for the scene environment, select \uicontrol {Scene Environment}
    in \uicontrol Navigator and specify its properties in the \uicontrol Properties view.

    Set the properties in the \uicontrol {Scene Environment} section of the
    \uicontrol Properties view to specify whether and how the background
    of the scene should be cleared, to apply post-processing effects to the scene,
    to define how colors are tonemapped before the scene is rendered, and to
    specify fog settings.

    \image studio-3d-scene-environment-properties.webp "The Scene Environment properties"

    The \uicontrol {Clear color} property specifies which color will be used to
    clear the background of the scene if \uicontrol {Background mode} is defined
    as \uicontrol Color. Use the \l{Picking Colors}{color picker} to select the
    color of your choice.

    The \uicontrol {Background mode} property defines whether the background
    of the scene should be cleared as well as the manner of clearing it.
    Use the dropdown menu to select one of the available modes:
        \table
            \header
                \li Background mode
                \li Description
            \row
                \li Transparent
                \li The scene is cleared to be transparent, which is useful
                    for rendering 3D content on top of another item. This mode
                    has no effect when the \uicontrol View3D component is using
                    \uicontrol Underlay or \uicontrol Overlay as the render mode.
            \row
                \li Color
                \li The scene is cleared with the color specified by the
                    \uicontrol {Clear color} property. This mode has no effect
                    when the \uicontrol View3D component is using the
                    \uicontrol Underlay or \uicontrol Overlay as the render
                    mode.
            \row
                \li SkyBox
                \li The scene will not be cleared, but instead a
                    \uicontrol SkyBox or Skydome will be rendered. Define an
                    image as a \uicontrol SkyBox using the
                    \uicontrol Image property in the \uicontrol {Light probe}
                    section (In Qt 5, the \uicontrol {Light Probe} property in
                    the \uicontrol {Image-Based Lighting} group).
            \row
                \li SkyBoxCubeMap
                \li The scene will not be cleared, but instead a
                    \uicontrol SkyBox or Skydome that uses a \uicontrol CubeMapTexture
                    will be rendered. A cube map texture has six faces
                    (X+, X-, Y+, Y-, Z+, and Z-), where each face is an individual
                    2D image. Selecting this mode allows custom materials and post-processing
                    effects to work with cube map textures in their shaders.
        \endtable

    To leave the scene uncleared, select \uicontrol {Unspecified} as the
    \uicontrol {Background mode}.

    The \uicontrol Effects property defines post-processing effects applied
    to the scene. Use the dropdown menu to select one of the effects that will be
    applied to the entire scene. The order of the effects is significant since
    the result of each effect is fed to the next.

    The \uicontrol {Tonemap mode} property defines how colors are tonemapped
    before rendering. Select \uicontrol ToneMapModeLinear to apply linear
    tonemapping, which gamma corrects colors and returns them in sRGB color
    space. You can also select \uicontrol ToneMapModeAces to apply Academy Color
    Encoding System, \uicontrol ToneMapModeHejlDawson to apply the Hejl-Dawson
    tonemapping, or \uicontrol ToneMapModeFilmic to apply filmic tonemapping.
    \note The \uicontrol {Tonemap mode} property is not available in Qt 5.

    The \uicontrol Fog property defines settings for fog applied to the
    scene. When the \uicontrol Fog property of a scene environment is set to a
    valid \uicontrol Fog object, the properties are used to configure the
    rendering of fog. The simple fog provided by this type is implemented by
    the materials. Use the dropdown menu to select a \uicontrol Fog object for
    your scene.

    \section1 Applying Antialiasing

    Use antialiasing to make curved lines smoother on the screen. In the
    \uicontrol Antialiasing section of the \uicontrol Properties view, you can
    specify the mode and quality of antialiasing and also enable temporal
    antialiasing and define its strength.

    \image studio-3d-scene-environment-antialiasing.webp "The antialiasing properties"

    The \uicontrol {Antialiasing mode} property specifies the mode of
    antialiasing applied when the scene is rendered. Select one of the following
    modes using the dropdown menu:
        \table
            \header
                \li Mode of antialiasing
                \li Description
            \row
                \li MSAA
                \li Applies multisample antialiasing. The scene is rendered in a
                    higher resolution and then scaled down to actual resolution.
            \row
                \li NoAA
                \li No antialiasing is applied.
            \row
                \li SSAA
                \li Supersample antialiasing is applied. The edges of geometry
                    are supersampled, resulting in smoother silhouettes. This
                    technique has no effect on the materials inside geometry.
            \row
                \li ProgressiveAA
                \li Progressive antialiasing is applied. When the content of the
                    scene has stopped moving, the camera is jiggled very slightly
                    between frames, and the result of each new frame is blended
                    with the previous frames. The more frames you accumulate,
                    the better looking the result.
        \endtable

    The \uicontrol {Antialiasing quality} property sets the level of antialiasing
    applied to the scene. Define the quality of antialiasing as \uicontrol Medium,
    \uicontrol High, or \uicontrol {Very High}. The effect of the selected
    \uicontrol {Antialiasing quality} depends on the selected
    \uicontrol {Antialiasing mode}, as you can see from the table below.
    In the \uicontrol SSAA mode the selected quality affects the supersampling
    resolution, in \uicontrol MSAA it determines the number or samples per
    pixel, and in \uicontrol ProgressiveAA it defines the number of frames for
    final image.
        \table
            \header
                \li Level of antialiasing
                \li Supersampling resolution used in SSAA
                \li Number of samples per pixel in MSAA
                \li Number of frames for final image in ProgressiveAA
            \row
                \li Medium
                \li 1.2x
                \li 2
                \li 2
            \row
                \li High
                \li 1.5x
                \li 4
                \li 4
            \row
                \li Very High
                \li 2.0x
                \li 8
                \li 8
        \endtable

    \note With \uicontrol {Antialiasing mode} set to \uicontrol NoAA,
    \uicontrol {Antialiasing quality} does not affect antialiasing.

    The \uicontrol {Temporal AA} property enables temporal antialiasing.
    This means that the camera is jiggled very slightly between frames, and the
    result of each new frame is blended with the previous frame.
    \note Temporal antialiasing does not have an effect when the \uicontrol MSAA
    mode is used.
    \note When combined with \uicontrol ProgressiveAA mode, temporal antialising
    is used for animations, and \uicontrol ProgressiveAA is used once
    animations stop.

    The \uicontrol {Temporal AA strength} property modifies the amount of
    temporal movement in antialiasing. This property is only available when
    the \uicontrol {Temporal AA} property is set to true.

    The \uicontrol {Specular AA} property enables specular antialiasing. Specular
    aliasing is often visible in form of bright dots and flickering when moving the
    camera around.

    \section1 Applying Ambient Occlusion

    Ambient occlusion is a form of approximated global illumination that causes
    non-directional self-shadowing where objects are close together. You can
    define the \uicontrol Strength, \uicontrol Distance, \uicontrol Softness,
    \uicontrol {Sample rate}, and \uicontrol Bias properties in the
    \uicontrol {Ambient Occlusion} section of the \uicontrol Properties view.

    \image studio-3d-scene-environment-ambient-occlusion.webp "The ambient occlusion properties"

    In \uicontrol Properties > \uicontrol {Ambient Occlusion}, select the
    \uicontrol Enabled checkbox to define settings for ambient occlusion.

    Set the strength of the shadows using the \uicontrol Strength property,
    which defines the amount of ambient occlusion applied. A value of 100 causes
    full darkness shadows, while lower values cause the shadowing to appear lighter.
    A value of 0 disables ambient occlusion entirely, thus improving performance at
    a cost to the visual realism of 3D objects rendered in the scene. All values other
    than 0 have the same impact on performance.

    The \uicontrol Distance property defines roughly how far the ambient occlusion
    shadows spread away from objects. Greater distances cause increasing impact
    to performance.

    The \uicontrol Softness property specifies how smooth the edges of the
    ambient occlusion shading are. The value set for the property must be
    between 0.0 and 50.0. To improve smoothness at the risk of sometimes
    producing obvious patterned artifacts, you can scatter the edges of the
    ambient occlusion shadow bands by selecting the \uicontrol {Dither} check
    box.

    \note Large distances between the clipping planes of your camera may cause
    problems with ambient occlusion. If you are seeing odd banding in ambient
    occlusion, try adjusting the value in the \uicontrol {Clip far} field in
    the \l{Cameras}{scene camera} properties.

    The \uicontrol {Sample Rate} property specifies the number of shades of gray,
    thus defining the quality of ambient occlusion at the expense of performance.

    The \uicontrol Bias property defines a cutoff distance preventing objects
    from exhibiting ambient occlusion at close distances. The higher the
    value, the greater the distance required between objects before ambient
    occlusion occurs.
    \note If you see ambient occlusion shadowing on objects where there should
    be no shadowing, increase the value slightly to clip away close results.

    \note In Qt 5, some the ambient occlusion properties are named slightly
    differently: \uicontrol {AO strength}, \uicontrol {AO distance},
    \uicontrol {AO softness}, \uicontrol {AO dither}, and \uicontrol {AO bias}.

    \section1 Setting image-based lighting

    In the \uicontrol {Image Based Lighting} section of the \uicontrol Properties view,
    you can set the \uicontrol {HDR Image}, \uicontrol Exposure, \uicontrol Horizon,
    and \uicontrol Orientation properties for image-based lighting.

    \image studio-3d-scene-environment-image-based-lighting.webp "Image-based lighting properties"

    The \uicontrol {HDR Image} property defines an image used to light the scene
    instead of or in addition to standard lights. The image is preferably a
    high-dynamic range image or a pre-generated cubemap. Pre-baking provides
    significant performance improvements at run time because no time is spent on
    filtering and mipmap generation. If the source is a .hdr or other image,
    the GPU-based pre-processing happens at run time after loading the image
    file, which can be potentially time consuming, in particular on embedded and
    mobile hardware. Therefore, it is strongly recommended that applications
    pre-process .hdr images at latest at build time, as described here.

    \note In Qt 6, using a \uicontrol Texture component with \uicontrol Image >
    \uicontrol Source is not supported in combination with this property.
    Pre-filtering of all mip levels for dynamic Qt Quick content is typically not
    reasonable in practice due to performance implications. In Qt 5, the
    \uicontrol Image property is referred to as \uicontrol {Light probe}, which
    defines a texture for overriding or setting an image-based lighting texture
    for use with the skybox of the scene.

    The \uicontrol Exposure property modifies the amount of light emitted by the
    light probe.

    When defined with increasing values, the \uicontrol Horizon property adds
    darkness (black) to the bottom half of the environment, thus forcing the
    lighting to come predominantly from the top of the image (and removing
    specific reflections from the lower half). This property is useful for
    accounting for a ground plane that would have the effect of obscuring the
    reflection of the light probe from the ground. This is necessary because
    light probe contributions come directily from the image without consideration
    for the content of the scene. You can set the value of the
    \uicontrol Horizon property between 0.0 and 1.0. Using the default value of
    the property applies the entire light probe without adjustment.
    \note The \uicontrol Horizon property only affects materials lighting and
    has no effect on the rendering of the sky box.
    \note In Qt 5, the \uicontrol Horizon property is referred to as
    \uicontrol {Probe horizon}.

    The \uicontrol Orientation property defines the orientation of the light
    probe. Orientation is defined in terms of euler angles in degrees over the
    x, y, and z axes.

    \section2 Additional light probe properties in Qt 5

    The \uicontrol {Probe Brightness} property modifies the amount of light
    emitted by the light probe.

    When the \uicontrol {Fast IBL} (Fast image-based lighting) property is
    enabled, more shortcuts are taken to approximate the light contribution of
    the light probe at the expense of quality.

    The value of the \uicontrol {Probe FOV} property sets the angle of the
    image source field of view when using a camera source as the IBL probe.

    \section2 Advanced scene environment settings

    You can perform depth tests to optimize the scene environment. To skip the
    depth tests, clear the \uicontrol {Enable depth test} checkbox. Note that
    skipping the tests can cause rendering errors.

    To have the renderer write to the depth buffer as part of the color pass,
    clear the \uicontrol {Enable depth prepass} checkbox. Clearing the
    checkbox disables the depth prepass on any GPU that uses tiled rendering
    architecture.

    To specify additional render settings for debugging scenes, define
    \uicontrol {Debug Settings}.

    To define lightmap baking settings for direct and indirect lighting, use
    the \uicontrol {Light Mapper} property to specify a lightmapper object.
    These settings are not relevant at other times, such as when using already
    generated lightmaps to render a scene.

    \section1 Applying post-processing effects in the Extended Scene Environment

    In addition to properties described above, in the extended scene environment
    you can apply effects to your scene by defining them as properties. When enabling
    one or more of these effects, the result is similar to manually adding
    \l {Creating Post-Processing Effects}{custom effects} to \uicontrol {Scene Environment}.

    Use \uicontrol {Extended Scene Environment} instead of \uicontrol {Scene Environment}
    to add multiple and complex effects to your scene. Because the \uicontrol
    {Extended Scene Environment} combines the effects that are enabled, the number of
    render passes is reduced, which results in significantly better performance
    than applying individual post-processing effects to the scene.

    For the extended scene environment, you can also define \uicontrol {Local Custom Properties}.

    \image studio-ext-scene-environment.webp "Properties of Extended Scene Environment"

    \note If additional post-processing effects are manually added to
    \uicontrol {Scene Environment}, those effects will be applied before the effects
    defined in the properties of \uicontrol {Extended Scene Environment}.

*/
