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

/*!
    \page studio-3d-view.html
    \previouspage quick-animations.html
    \nextpage studio-3d-node.html

    \title 3D Views

    To create a Qt Quick 3D UI project, use the \uicontrol {3D} preset that adds the
    \l {3D Components}{Qt Quick 3D} components to \uicontrol Components
    and contains a 3D view component. The \uicontrol {View3D} component
    includes a \l {Scene Environments}{scene environment} as well as a scene \l {Lights}{light},
    \l {Cameras}{camera}, and \l {3D Models}{model}. A default \l {Materials and Shaders}{material}
    is attached to the model. You can attach \l {Textures}{textures} to materials.

    To create a project with many complex effects, use the \uicontrol {Extended 3D} preset
    that creates a project with an \uicontrol {Extended View3D} component.
    The extended 3D view includes an \uicontrol{Extended Scene Environment}
    component that enables using various effects by defining them as properties.

    \note The extended 3D view is available in projects created with Qt 6.5
    or higher set as the target version.

    For more information about creating projects, see \l{Creating Projects}.

    To manually add a 3D view to your project, you first need to add the
    \uicontrol {Qt Quick 3D} module to \uicontrol {Components}, as described in
    \l {Adding and Removing Modules}.

    \note \uicontrol {The Qt Quick 3D} module is not available in projects created
    with Qt 5 set as the target version.

    \image studio-qtquick-3d-components.webp "QtQuick3D components"

    You can now drag a \uicontrol View3D or an \uicontrol {Extended View3D} component from
    \l Components > \uicontrol QtQuick3D > \uicontrol Items to \l Navigator or to the
    \l {2D} view.

    To switch to the \uicontrol 3D view while maintaining the camera orientation of the
    \uicontrol View3D, right-click a \uicontrol View3D or an \uicontrol {Extended View3D}
    component in the \uicontrol Navigator or \uicontrol 2D view and select
    \uicontrol {Edit in 3D View}. Alternatively, you can double-click a \uicontrol View3D
    or an \uicontrol {Extended View3D} component in the \uicontrol 2D view to open the
    \uicontrol 3D view. Double-clicking a 3D model in the \uicontrol 2D view opens the
    \uicontrol 3D view with the 3D model selected.

    \image studio-navigator-view3d.png "A View 3D component in Navigator"

    By default, a directional light and a perspective camera are used in 3D
    scenes created by using the \uicontrol 3D and \uicontrol {Extended 3D}
    presets. To use other light and camera types, select the component in
    the \uicontrol {3D} or \uicontrol Navigator view and change the type of
    the component in the \uicontrol Type field in \l Properties. For example,
    to use a point light, enter \c {PointLight}.

    \image studio-3d-properties-type.webp "Type field in the Properties view"

    Select a 3D view in \uicontrol Navigator or in \uicontrol{3D} to modify
    its property values in the \uicontrol Properties view. Use the properties
    in the \uicontrol View3D tab to set properties specific to a 3D view
    component.

    \image studio-qtquick-3d-view.webp "View 3D component properties"

    The \uicontrol Camera property defines which camera is used to render the
    scene to the \uicontrol {2D} view. If this property is not defined, the
    first enabled camera in the scene will be used.

    The \uicontrol Environment property specifies the \uicontrol
    {Scene Environment} used to render the scene. By default, the first
    \uicontrol {Scene Environment} in the scene is set as the property value.

    The \uicontrol {Import Scene} property defines the ID of the component to
    render to the \uicontrol {2D} view. The component does not have to be a
    child of a 3D view component. This referenced component becomes a sibling to
    child items of a 3D view, if there are any. You can use this property, for
    example, to create a split screen view showing your scene from multiple
    cameras. For more information on how to to use a 3D view to show a scene
    from multiple cameras, see \l {Qt Quick 3D - View3D Example}.

    \note The \uicontrol {Import Scene} property can only be set once.
    Subsequent changes will have no effect.

    The \uicontrol {Render Format} property defines the format of the backing
    texture.
*/
