/****************************************************************************
**
** 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 the 3D Editor

    To project a 3D scene to a 2D viewport, it is necessary to view the scene
    from a \l{Using Scene Camera}{camera}. Select the \uicontrol {Toggle
    Perspective/Orthographic Projection} button (1) on the 3D editor toolbar to
    switch between a \e {perspective camera} and an \e {orthographic camera}.
    A perspective camera uses field of view and near and far clip planes to
    specify the projection, whereas an orthographic camera can be thought of
    as a 2D camera. Both of them are free-form cameras 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 the camera, light, model, and materials. If your
    scene did not contain them, you can add the corresponding Qt Quick 3D
    types from the \uicontrol Library.

    You can use the toolbar buttons (2) to show the \e transformation
    gizmo in the \uicontrol {3D Editor} when an item is selected
    and to determine what happens when you drag the selected item.
    Transformation refers to moving, rotating, or scaling of an object.
    Select the \uicontrol {Toggle Local/Global Orientation} button (3) to
    determine whether the gizmos affect only the local transformations of the
    item or whether they transform with respect to the global space.

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

    The \e pivot of the component is used as the origin for position, scale,
    and rotation operations. You can set a \l{Setting Transform Properties}
    {local pivot offset} for an item in the \uicontrol Properties view to
    manipulate the component around a point other than its local origin. A
    line is drawn in the 3D editor from the pivot point to the center of the
    component to provide a visual connection between them.

    \section1 Controlling the Edit View Camera

    You can add 3D camera types to the scene to project the view you see in
    the View3D type in the application. While editing scenes, you can use
    a separate \e {edit view camera} (4) to project the scene to the 3D edit
    view in the Design mode.

    You can navigate the scene by rotating, panning, and zooming the edit view
    camera.

    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.

    To pan, press \key Alt and use the middle mouse button to click anywhere in
    the rendered view to slide the view around.

    To orbit, press \key Alt and click anywhere in the rendered view to rotate
    the view.

    To scale the edit view camera and to focus it on the selected items, select
    \uicontrol {Fit Selected} button or press \key F.

    The world axis helper (5) shows the direction of the world axes in respect
    to the edit view camera. To point the camera at the currently selected
    component in the direction of an axis, click the axis. If no component
    is selected, the camera is pointed at the world origin. This does not
    affect the camera zoom level.

    For more information about using the cameras in the scene, the available
    3D camera types, and their properties, see \l{Using Scene Camera}.

    \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 the 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 view axis or on the top, bottom, left, and right clip planes of the
    render camera.

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

    To move items along an axis, click the axis and drag the item along the
    axis.

    To move items on a plane, select the plane handle and drag the item on
    the plane.

    To move an item freely in the editor, select the handle at the center of
    the item.

    \section1 Rotating Items

    You can rotate items around the view axes of the camera.

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

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

    To rotate an item around an axis, select the axis and drag in the direction
    you want to rotate the item in.

    To freely rotate the item, select the gray circle.

    \section1 Using Global and Local Orientation

    To switch between global and local orientation, select \uicontrol
    {Toggle Local/Global Orientation}.

    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 Scaling Items

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

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

    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 adjust the scale across one axis, select the scale handle attached to
    the axis. To uniformly scale an item across all axes, select the handle
    at the center of the item.

    To adjust the scale across a plane, select the plane handle and drag the
    item on the plane.

    \section1 Using Edit View Light

    You use 3D light types to light the models in the scene. While editing
    scenes, you can use a separate \e {edit view light} to illuminate the
    portions of the scene that the scene lights do not hit. To switch the edit
    view light on and off, select the \uicontrol {Toggle Edit Light} button (6).

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