/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Design Studio documentation.
**
** 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.
**
****************************************************************************/

/*!
    \previouspage studio-3d-design-mode.html
    \page studio-3d-editor.html
    \nextpage studio-3d-view.html

    \title Working in 3D Editor

    When editing a 3D scene, you view the scene in the \uicontrol {3D Editor}
    view. You can change the projection of the view by switching between
    \e {perspective camera} and \e {orthographic camera} modes. When using the
    perspective camera mode, objects that are far from the camera appear smaller
    than those nearby. In the orthographic camera mode, all objects 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.

    When you import 3D scenes from files that you exported from 3D graphics
    tools, you also import a \l{Using Scene Camera}{scene camera},
    \l{Using Lights}{light}, \l{Adding Models}{model}, and
    \l {Using Materials and Shaders}{materials}. If your scene did not contain
    them, you can add the corresponding Qt Quick 3D types from \uicontrol
    Library.

    You can use the toolbar buttons to \e transform 3D objects and manipulate
    the 3D scene. Transformation refers to moving, rotating, or scaling of an
    object. The \e pivot of the component is used as the origin for
    transformations. You can set a \l{Setting Transform Properties}{local pivot
    offset} for an item in \uicontrol Properties to transform the component
    around a point other than its local origin. A line is drawn in \uicontrol
    {3D Editor} from the pivot point to the center of the component to provide
    a visual connection between them.

    Toggle between local and global orientation to determine whether the gizmos
    affect only the local transformations of the item or whether they transform
    with respect to the global space.

    Additional helpful features when editing 3D scenes are the \e {edit light},
    which is a quick way to light the scene, and the grid that helps you to
    navigate in 3D space. Select the \inlineimage grid_on.png
    (\uicontrol {Toggle Grid Visibility}) or press \key G to show or hide the
    grid.

    \image studio-3d-editor.png "3D Editor"

    \section1 Controlling the 3D Editor Camera

    To switch to perspective camera mode, select
    \inlineimage perspective_camera.png
    (\uicontrol {Toggle Perspective/Orthographic Edit Camera}).
    To switch to orthographic camera mode, select
    \inlineimage orthographic_camera.png
    .

    You can navigate the scene by panning, rotating, and zooming the 3D Editor
    camera:

    \list
        \li To pan, press \key Alt and use the middle mouse button to click and
            drag anywhere in the rendered view to slide the view around.
        \li To orbit, press \key Alt and click and drag anywhere in the rendered
            view to rotate the view.
        \li To zoom, use the mouse wheel or press \key Alt and right-click
            anywhere in the rendered view to zoom the view in or out as you drag
            up or down.
    \endlist

    To zoom and focus the 3D Editor camera on a selected item,
    select \inlineimage fit_selected.png
    (\uicontrol {Fit Selected}) or press \key F.

    The world axis helper (1) shows the direction of the world axes in view.
    To point the camera at the currently selected component in the direction of
    an axis, click the axis. Clicking the dot at the end of the axis will point
    the camera at the opposite direction of the axis. If no component is
    selected, the camera is pointed at the world origin. This does not affect
    the camera zoom level.

    \image studio-3d-editor-axis-helper.png "Axis helper in 3D Editor"

    You can use scene cameras (2) to view the the View3D type from a specific
    angle in \uicontrol {Form Editor} while editing scenes. Different types of
    cameras are available in \uicontrol Library under \uicontrol
    {Qt Quick 3D}. For more information about using cameras in the scene,
    the available camera types, and their properties, see
    \l{Using Scene Camera}.

    \section1 Using Global and Local Orientation

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

    In global orientation mode, transformation of a selected object 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 object in
    the global x direction.

    In local orientation mode, the position of a selected object is shown
    according to local axes specific to the selected object. 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 object in the local x direction in relation to the object.

    \section1 Using 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 \inlineimage edit_light_on.png
    or \inlineimage edit_light_off.png
    (\uicontrol {Toggle Edit Light})
    or press \key U.

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

    \section1 Selecting Items

    To move, rotate, or scale items in the scene, you need to select them first.
    The selection mode buttons determine how items are selected when you click
    them in \uicontrol {3D Editor}:

    \list
        \li In the \inlineimage select_item.png
            (\uicontrol {Select Item}) mode, a single item is selected.
        \li In the \inlineimage select_group.png
            (\uicontrol {Select Group}) mode, the top level parent of the item
            is selected. This enables you to move, rotate, or scale a group of
            items.
    \endlist

    To toggle the selection mode, press \key Q.

    \section1 Moving Items

    \image studio-3d-editor-move.png "3D Editor in move mode"

    You can move items 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
    \uicontrol {3D Editor} view.

    To move items, select \inlineimage move_on.png
    or press \key W:

    \list
        \li To move items along the axes of the move gizmo, click the axis and
            drag the item along the axis.
        \li To move items on a plane, click the plane handle and drag the item
            on the plane.
        \li To move an item freely in 3D editor, click and drag the gray handle
            at the center of the move gizmo.
     \endlist

    \section1 Rotating Items

    \image studio-3d-editor-rotate.png "3D Editor in rotate mode"

    To rotate items, select \inlineimage rotate_on.png
    or press \key E:

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

    \section1 Scaling Items

    \image studio-3d-editor-scale.png "3D Editor in scale mode"

    You can use the scale handles to adjust the local x, y, or z scale of an
    item. You can adjust the scale across one, two, or three axes, depending on
    the handle.

    To scale items, select \inlineimage scale_on.png
    or press \key R:

    \list
        \li To adjust the scale across one axis, click and drag the scale handle
            attached to the axis.
        \li To adjust the scale across a plane, click the plane handle and drag
            the item on the plane.
        \li To uniformly scale an item across all axes, click and drag the gray
            handle at the center of the item.
    \endlist
*/