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

/*!
    \previouspage qtquick-form-editor.html
    \page studio-3d-editor.html
    \nextpage studio-material-editor.html

    \ingroup studio-views

    \title 3D

    \brief Edit a 3D scene.

    When editing a 3D scene, you view the scene in the \uicontrol{3D}
    view.

    When you import 3D scenes from files that you exported from 3D graphics
    tools, you also import a \l{Cameras}{scene camera},
    \l{Lights}{light}, \l{3D models}{model}, and \l {Materials and shaders}{materials}.
    If your scene does not contain them, add the corresponding \l {3D components}{Qt Quick 3D}
    components from \uicontrol Components > \imageplus
    > \uicontrol {Qt Quick 3D} > \uicontrol {Qt Quick 3D}.

    Use the \uicontrol 3D toolbar buttons to modify the \uicontrol 3D view,
    manipulate the 3D scene, and to access functionalities to \e transform 3D
    components. Transformation refers to moving, rotating, or scaling a
    component. The \e pivot of the component is used as the origin for
    transformations. Set a \l{Managing 3D Transformations}{local pivot offset}
    for a component in \uicontrol Properties to transform the component around
    a point other than its local origin. A line is drawn in the \uicontrol{3D}
    view from the pivot point to the center of the component to provide a visual
    connection between them.

    \note To avoid transforming components by mistake while editing your scene,
    use the \l {Showing and hiding other components}{showing and hiding} or the
    \l {Locking Components}{locking} features in \l Navigator.

    To refresh the contents of the \uicontrol{3D} view, select \key P or
    select the \imagereset
    (\uicontrol {Reset View}) button.

    \image studio-3d-editor.webp "The 3D view"

    The following video illustrates navigating in the \uicontrol{3D} view and
    using the toolbar:

    \youtube SsFWyUeAA_4

    \include qtdesignstudio-qt-academy.qdocinc qt-academy-3D-with-qt-design-studio

    \section1 Using the context menu in the 3D view

    There is a context menu in the \uicontrol 3D view. To open it, right-click
    in the \uicontrol 3D view. From the context menu you can, for example:
    \list
      \li Create cameras, lights, and models.
      \li Delete components.
      \li Align camera views.
    \endlist

    \image 3d-view-context-menu.webp "The context menu in the 3D view"

    \section1 Controlling the 3D view camera

    \section2 Toggling the camera mode

    Change the projection of the view by switching between \e {perspective camera}
    and \e {orthographic camera} modes. When using the perspective camera mode,
    components that are far from the camera appear smaller than those nearby. In
    the orthographic camera mode, all components appear at the same scale
    irrespective of their distance from the camera. Both of them are free-form
    camera modes that you can use to orbit around the scene.

    To toggle the camera mode, do one of the following:
    \list
        \li Select \imageperspectivecamera
         (\uicontrol {Toggle Perspective/Orthographic Camera}) to use the
         perspective camera mode.
        \li Select \imageorthographiccamera to use the orthographic
        camera mode.
    \endlist
    You can also toggle the camera mode by using the keyboard shortcut \key T.

    \section2 Navigating in the 3D scene

    Navigate the scene by panning, rotating, and zooming the 3D view
    camera:

    \list
        \li To pan, do one of the following and drag anywhere in the view to pan:
            \list
              \li Select and hold \key Alt (or \key Option on \macos) and
              \key {middle mouse button}.
              \li Select and hold \key {right mouse button}, and then select and hold
              \key {left mouse button}.
              \li Select and hold \key Shift and \key {left mouse button}.
            \endlist
        \li To orbit, select \key Alt and and drag anywhere in the
            \uicontrol 3D view to rotate the view.
        \li To zoom, use the mouse wheel or select \key Alt and right-click
            anywhere in the \uicontrol 3D view to zoom the view in or out as you drag
            up or down.
    \endlist

    To zoom and focus the 3D view camera on a selected component, select
    \imagefitselected (\uicontrol {Fit Selected}) or select \key F.

    The world axis helper (1) shows the direction of the world axes in the view.
    To point the 3D view camera at the currently selected component in the direction of
    an axis, select the axis. To point the camera at the opposite direction of the axis,
    select the dot at the end of the axis. If no component is
    selected, the camera is pointed at the world origin.

    \image studio-3d-editor-axis-helper.webp "Axis helper in the 3D view"

    Use scene cameras (2) to view the \uicontrol View3D component from a
    specific angle in the \l {2D} view while editing scenes. Drag a camera
    component to your scene from \uicontrol Components > \uicontrol {Qt Quick 3D} >
    \uicontrol {Qt Quick 3D}. For more information about using cameras in the
    scene and the available camera types, see \l{Cameras}.

    \section2 Using the split view

    Use the split view to view the scene from different points of view using the different
    viewport modes.

    Use the split view to split the \uicontrol 3D view into multiple viewports. You can
    manipulate each of the viewports separately.

    To view the scene in a split view, select \imagesplitview (\uicontrol {Show Viewport Modes})
    and then select one of the viewport modes:
    \list
        \li The \uicontrol Single mode shows the scene in a single viewport.
        \li The \uicontrol Quad mode shows the scene from four different viewports.
        \li The \uicontrol {3 Left 1 Right} mode shows the scene from four points of
            view using three smaller and one larger viewport.
        \li The \uicontrol {2 Horizontal} mode shows the scene from two horizontal
            viewports.
        \li The \uicontrol {2 Vertical} mode shows the scene from two vertical viewports.
    \endlist

    Select one of the viewports to make it the active viewport. The active viewport is marked with
    a blue frame. Use the world axis helper to change the point of view for each viewport
    independently. You can \l {Toggling the camera mode}{toggle the camera mode} between the
    perspective and orthographic modes independently for each viewport.
    \l {Navigating in the 3D scene}{Navigate} each split by panning, rotating, and zooming.
    To resize the viewports, drag the border between them.

    \image {studio-3d-split-view.webp} {Split view in the 3D view.}

    \section2 Using the fly mode

    Use the fly mode to move around freely in the 3D scene. To navigate the scene with
    fly mode, right-click and hold in the \uicontrol 3D view, and use the keyboard shortcuts
    to move around the scene:

    \table
    \header
        \li Key
        \li Action
    \row
        \li \key W or \key {Up arrow}
        \li Move forward.
    \row
        \li \key S or \key {Down arrow}
        \li Move backward.
    \row
        \li \key A or \key {Left arrow}
        \li Move left.
    \row
        \li \key D or \key {Right arrow}
        \li Move right.
    \row
        \li \key E or \key {Page up}
        \li Move up.
    \row
        \li \key Q or \key {Page down}
        \li Move down.
    \row
        \li \key Shift
        \li Move faster.
    \row
        \li \key Alt
        \li Move slower.
    \row
        \li \key Spacebar
        \li Move to an object in the crosshairs.
    \endtable

    To adjust the movement speed, right-click and hold in the \uicontrol 3D view, and rotate the
    mouse wheel. Alternatively, select \imagecameraspeed in the \uicontrol 3D
    view toolbar to open the configuration dialog.

    In the configuration dialog, you can:
    \list
        \li Adjust the movement speed of the camera with a slider.
        \li Set a value multiplier for the speed slider.
    \endlist

    \section1 Toggling the camera view

    In the 3D view, you can show a small window displaying the camera view.

    \image {3d-view-camera-view.webp} {The Camera view in the 3D view.}

    To toggle this view,
    select \imagevisibilityon
    and then one of the options:

    \table
      \row
        \li \uicontrol {Hide Camera View}
        \li Never shows the camera view.
      \row
        \li \uicontrol {Show Selected Camera View}
        \li Shows the camera view of the selected camera. If no camera is selected, the camera
        view is hidden.
      \row
        \li \uicontrol {Always Show Camera View}
        \li Always shows the camera view of the camera that was selected last, even if no camera
        is currently selected.
    \endtable

    \section1 Using the global and the local orientation

    In \uicontrol 3D view, you view the scene in global or local orientation
    mode.

    In global orientation mode, transformation of a selected component is
    presented with respect to the global space. For example, while the move tool
    is selected, selecting a cube will show its move gizmo aligned with the axes
    of global space. Dragging on the red arrow of the gizmo moves the component
    in the global x direction.

    In local orientation mode, the position of a selected component is shown
    according to local axes specific to the selected component. For example,
    selecting a rotated cube will show its axes rotated, and not aligned with
    the axes of global space. Dragging on the red arrow of the gizmo moves the
    component in the local x direction in relation to the component.

    To switch between local and global orientation, select \imageglobal
    (\uicontrol {Toggle Local/Global Orientation}) or select \key Y.

    \section1 Using the edit light

    The edit light is an extra point light that can be used to illuminate the
    scene. To toggle the edit light on and off, select \imageeditlighton
    or \imageeditlightoff (\uicontrol {Toggle Edit Light}) or
    select \key U.

    For information about the available scene light types and their properties,
    see \l{Lights}.

    \section1 Baking lights

    Bake lights to light static elements in your scene. To bake lights, select
    \imagebakelights to open the \uicontrol {Lights Baking Setup}
    dialog. For more information, see \l {Baking Lightmaps}.

    \section1 Selecting components

    To move, rotate, or scale components in the scene, you need to select them
    first. Toggle the selection mode to determine how components are selected
    when you select them in the \uicontrol{3D} view:

    \list
        \li Use the \imageselectitem (\uicontrol {Single Selection})
            mode to select a single component.
        \li Use the \imageselectgroup (\uicontrol {Group Selection})
            mode to select the top level parent of the component, so you can move
            a group of components simultaneously.
    \endlist

    Alternatively, select \key Q to toggle the selection mode.

    To multiselect, hold \key Ctrl and select the components you wish to select.

    After selecting a component, you can apply the usual \l {Keyboard Shortcuts}
    {keyboard shortcuts} applicable to your operating system, for example,
    \key Ctrl+C and \key Ctrl+V on Windows to copy-paste components.

    \target moving components 3d view
    \section1 Moving components

    \image studio-3d-editor-move.webp "The 3D view in move mode"

    You can move components in relation to their coordinate system, along the x,
    y, or z axis or on the top, bottom, left, and right clip planes of the
    the \uicontrol{3D} view.

    To move components, select \imagemoveoff or select \key W:

    \list
        \li To move components along the axes of the move gizmo, select the axis,
            and drag the component along the axis.
        \li To move components on a plane, drag the plane handle of the move
            component on the plane.
        \li To move components freely in the 3D view, drag the gray handle at the
            center of the move gizmo.
     \endlist

    \section1 Rotating components

    \image studio-3d-editor-rotate.webp "The 3D view in rotate mode"

    To rotate components, select \imagerotateoff
    or select the \key E key:

    \list
        \li To rotate a component around its rotation gizmo, drag the axis ring
            in the direction you want to rotate the component in.
        \li To freely rotate the component, drag the inner center circle of the
            gizmo.
    \endlist

    \section1 Scaling components

    \image studio-3d-editor-scale.webp "The 3D view in scale mode"

    Úse the scale handles to adjust the local x, y, or z scale of a
    component. You can adjust the scale across one, two, or three axes,
    depending on the handle.

    To scale components, select \imagescaleoff or select the \key R key:

    \list
        \li To adjust the scale across one axis, drag the scale handle
            attached to the axis.
        \li To adjust the scale across a plane, drag the plane handle of
            the component.
        \li To uniformly scale a component across all axes, drag the
            gray handle at the center of the component.
    \endlist

    \section1 Snapping

    With snapping turned on, the objects in the \uicontrol 3D view snap to certain
    intervals during transformation (move, rotate, scale).

    Toggle snapping in the following ways:

    \list
      \li Select \imagesnapping3d
      in the \uicontrol 3D view toolbar.
      \li Hold down the \key Ctrl key.
    \endlist

    With snapping turned on, select and hold \key Shift to snap objects to one tenth of
    the specified snap interval.

    \section2 Configuring snapping

    To edit the snapping settings, select \imagesnapping3dconf
    in the \uicontrol 3D view toolbar to open the configure dialog.

    In the configure dialog, you can do the following:
    \list
      \li Turn snapping on and off separately for the different transformations
      (move, rotate, scale).
      \li Set snap intervals for the transformations.
      \note Changing the snap interval for the position also changes the grid line intervals.
      \note All the grid lines might not be visible depending on the zoom level in the 3D view.
      \li Select \uicontrol {Absolute Position} to snap to absolute values. Clear the checkbox
       to use relative values.The absolute snapping aligns the object with the grid, while the
       relative snapping moves the object in fixed intervals without changing its alignment.
       For example, if you have an object that is slightly off the grid and you want to snap it
       to the grid, use the absolute snapping. If you want to move the object by a certain
       distance without affecting its orientation, use the relative snapping.
    \endlist

    \section1 Aligning views and cameras

    To align a camera to the \uicontrol{3D} view:
    \list 1
      \li Select a scene camera in the \uicontrol{3D} or \uicontrol {Navigator} view.
      \note If you don't have a camera selected, the most recently selected camera
      is aligned to the view.
      \li In the \uicontrol{3D} view, select \imagealigncameraon.
    \endlist

    This moves and rotates the scene camera to show the same view as the current view
    in the \uicontrol{3D} view.

    To align the \uicontrol{3D} view to a camera:
    \list 1
      \li Select a scene camera in the \uicontrol{3D} view or \uicontrol {Navigator}.
      \note If you don't have a camera selected, the view is aligned to the most recently
            selected camera.
      \li In the \uicontrol{3D} view, select \imagealignviewon.
    \endlist

    This moves and rotates the 3D view to show the same view as the selected scene camera.

    \section1 Toggling visibility

    To toggle the visibility of objects in the \uicontrol{3D} view, select
    \imagevisibilityon in the toolbar. This opens a menu with the
    following options:

    \table
        \header
            \li Action
            \li Description
            \li Keyboard shortcut
        \row
            \li Show Grid
            \li Toggles the visibility of the helper grid.
            \li \key G
        \row
            \li Show Look-at
            \li Toggles the visibility of the edit camera look-at indicator.
            \li \key L
        \row
            \li Show Selection Boxes
            \li Toggles the visibility of selection boxes for selected 3D objects.
            \li \key B
        \row
            \li Show Icon Gizmos
            \li Toggles the visibility of icon gizmos for object such as cameras,
                lights, and particle systems.
            \li \key I
        \row
            \li Always Show Camera Frustums
            \li Toggles between always showing the camera frustum and showing it
                only for cameras selected in the \uicontrol{3D} view.
            \li \key C
        \row
            \li Always Show Particle Emitters and Attractors
            \li Toggles between always showing the particle emitter and attractor
                visualizations and only showing them when the emitter or attractor
                is selected in the \uicontrol{3D} view.
            \li \key M
    \endtable

    \section1 Changing colors

    To change the \uicontrol 3D view background or grid color, select
    \image3dbackgroundcolor in the toolbar. This opens a menu
    with the following options:

    \table
        \header
            \li Action
            \li Decription
        \row
            \li Select Background Color
            \li Select a color for the background.
      \row
            \li Select Grid Color
            \li Select a color for the grid.
      \row
            \li Use Scene Environment
            \li Sets the 3D view to use the scene environment or skybox as background
            color.
            \note When \uicontrol {Use Scene Environment} is selected, a 3D scene that doesn't
            have a \uicontrol View3D component, uses the scene environment of the previous
            \uicontrol View3D for rendering the scene.
      \row
            \li Reset Colors
            \li Resets the background and grid colors to the default colors.
    \endtable

    \section1 Particle editor

    The particle editor tools help you preview your particle systems in
    the \uicontrol{3D} view. You can select one particle system to preview at a
    time.

    To preview a particle system in the \uicontrol{3D} view:

    \list 1
      \li Select a particle system in the \uicontrol Navigator or
      \uicontrol{3D} view.
      \li In the \uicontrol{3D} view, select
      \imageparticleanimationon to activate particle animation.
      Now you can see the particle animation in the \uicontrol{3D} view.
    \endlist

    You can pause the particle animation by selecting
    \imageparticlepause. When the animation is paused, use
    \imageparticlesseek to manually seek forward or backward in
    the particle animation.

    \section1 Using viewport shading

    Use \uicontrol {Viewport Shading} to change the rendering of the materials to only
    reflect a particular aspect of the overall rendering process. Use shading also as a
    debugging tool to understand why a material looks the way it does. In split view,
    view the scene using different shading properties in each split.

    To use the \uicontrol {Viewport Shading}, right-click the \uicontrol 3D view to open the
    context menu, select \uicontrol {Viewport Shading} and then select \uicontrol Wireframe,
    one of the material properties, or \uicontrol{Reset All Viewports}.

    Select \uicontrol Wireframe to only show the edges of the objects in the scene.

    Select one of the material properties available for shading:
    \table
        \header
            \li Property
            \li Description
        \row
            \li Base Color
            \li Shows only the base color of a material passed through without any lighting.
        \row
            \li Roughness
            \li Shows only the roughness of a material passed through as an unlit greyscale
                value.
        \row
            \li Metalness
            \li Shows only the metalness of a material passed through as an unlit greyscale
                value.
        \row
            \li Normals
            \li Shows only the interpolated world space normal value of the material mapped
                to an RGB color.
        \row
            \li Ambient Occlusion
            \li Shows only the ambient occlusion of the material.
        \row
            \li Diffuse
            \li Shows only the diffuse contribution of the material after all lighting.
        \row
            \li Specular
            \li Shows only the specular contribution of the material after all
                lighting.
    \endtable

    Select \uicontrol{Reset All Viewports} to reset the shading of the scene in all of the
    splits.

*/
