feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: Improve the documentation for 3D

Browse Source 
Some editions to comply with the MS Style guide and to
improve the structure.

Task-number: QDS-12670
Change-Id: Iddb0778327880ec65bdb590d1e02e4ca15e72051
Reviewed-by: Mats Honkamaa <mats.honkamaa@qt.io>
This commit is contained in:
Johanna Vanhatapio
2024-05-06 12:35:45 +03:00
parent fc79bad535
commit 46350083de
1 changed files with 158 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

264
doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-editor.qdoc
View File

@@ -13,54 +13,28 @@
\brief Edit a 3D scene. \brief Edit a 3D scene.
When editing a 3D scene, you view the scene in the \uicontrol{3D} When editing a 3D scene, you view the scene in the \uicontrol{3D}
view. You can change the projection of the view by switching between view.
\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.
When you import 3D scenes from files that you exported from 3D graphics When you import 3D scenes from files that you exported from 3D graphics
tools, you also import a \l{Cameras}{scene camera}, tools, you also import a \l{Cameras}{scene camera},
\l{Lights}{light}, \l{3D Models}{model}, and \l{Lights}{light}, \l{3D Models}{model}, and \l {Materials and Shaders}{materials}.
\l {Materials and Shaders}{materials}. If your scene did not contain If your scene does not contain them, add the corresponding \l {3D Components}{Qt Quick 3D}
them, you can add the corresponding \l {3D Components}{Qt Quick 3D}
components from \uicontrol Components > \inlineimage icons/plus.png components from \uicontrol Components > \inlineimage icons/plus.png
> \uicontrol {Qt Quick 3D} > \uicontrol {Qt Quick 3D}. > \uicontrol {Qt Quick 3D} > \uicontrol {Qt Quick 3D}.
You can use the toolbar buttons Use the \uicontrol 3D toolbar buttons to modify the \uicontrol 3D view,
to \e transform 3D components and manipulate the 3D scene. Transformation manipulate the 3D scene, and to access functionalities to \e transform 3D
refers to moving, rotating, or scaling of a component. The \e pivot of the components. Transformation refers to moving, rotating, or scaling a
component is used as the origin for transformations. You can set a component. The \e pivot of the component is used as the origin for
\l{Managing 3D Transformations}{local pivot offset} for a component in transformations. Set a \l{Managing 3D Transformations}{local pivot offset}
\uicontrol Properties to transform the component around a point other than for a component in \uicontrol Properties to transform the component around
its local origin. A line is drawn in the \uicontrol{3D} view from the pivot a point other than its local origin. A line is drawn in the \uicontrol{3D}
point to the center of the component to provide a visual connection between view from the pivot point to the center of the component to provide a visual
them. Especially when working with complex scenes, it may be useful to use connection between them.
the \l {Showing and Hiding Components}{showing and hiding} or the
\l {Locking Components}{locking} features in \l Navigator to avoid
transforming components by mistake while editing your scene.
Toggle between local and global orientation to determine whether the gizmos \note To avoid transforming components by mistake while editing your scene,
affect only the local transformations of the component or whether they use the \l {Showing and Hiding Components}{showing and hiding} or the
transform with respect to the global space. \l {Locking Components}{locking} features in \l Navigator.
Another helpful feature when editing 3D scenes is the \e {edit light},
which is a quick way to light the scene.
Additionally, you can toggle the visibility of the grid, selection boxes,
icon gizmos, and camera frustums in the 3D scene.
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:
\list
\li Create cameras, lights, and models.
\li Open \uicontrol {Material Editor} and edit materials.
\li Delete components
\endlist
\image 3d-view-context-menu.webp "The context menu in the 3D view"
To refresh the contents of the \uicontrol{3D} view, press \key P or To refresh the contents of the \uicontrol{3D} view, press \key P or
select the \inlineimage icons/reset.png select the \inlineimage icons/reset.png
@@ -73,53 +47,74 @@
\youtube SsFWyUeAA_4 \youtube SsFWyUeAA_4
\section1 Usingn 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 Open \uicontrol {Material Editor} and edit materials.
\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 \section1 Controlling the 3D View Camera
\section2 Toggling Camera Mode \section2 Toggling Camera Mode
To switch to perspective camera mode, select Change the projection of the view by switching between \e {perspective camera}
\inlineimage perspective_camera.png and \e {orthographic camera} modes. When using the perspective camera mode,
(\uicontrol {Toggle Perspective/Orthographic Edit Camera}). components that are far from the camera appear smaller than those nearby. In
To switch to orthographic camera mode, select the orthographic camera mode, all components appear at the same scale
\inlineimage orthographic_camera.png irrespective of their distance from the camera. Both of them are free-form
. You can also Toggle the camera mode by using the keyboard shortcut \key T. camera modes that you can use to orbit around the scene.
To toggle the camera mode, do one of the following:
\list
\li Select \inlineimage perspective_camera.png
(\uicontrol {Toggle Perspective/Orthographic Camera}) to use the
perspective camera mode.
\li Select \inlineimage orthographic_camera.png 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 \section2 Navigating in the 3D Scene
You can navigate the scene by panning, rotating, and zooming the 3D view Navigate the scene by panning, rotating, and zooming the 3D view
camera: camera:
\list \list
\li To pan, press \key Alt (or \key Option on \macos) and use the \li To pan, press \key Alt (or \key Option on \macos) and use the
middle mouse button to click and drag anywhere in the rendered wheel button to drag anywhere in the \uicontrol 3D view to
view to slide the view around. Alternatively, press and hold \key {right mouse slide the view around. Alternatively, press and hold \key
button} and \key {left mouse button} and drag anywhere in the view to pan. {right mouse button} and \key {left mouse button} and drag
\li To orbit, press \key Alt and click and drag anywhere in the rendered anywhere in the view to pan.
view to rotate the view. \li To orbit, press \key Alt and and drag anywhere in the
\uicontrol 3D view to rotate the view.
\li To zoom, use the mouse wheel or press \key Alt and right-click \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 anywhere in the \uicontrol 3D view to zoom the view in or out as you drag
up or down. up or down.
\endlist \endlist
To zoom and focus the 3D view camera on a selected component, To zoom and focus the 3D view camera on a selected component, select
select \inlineimage fit_selected.png \inlineimage fit_selected.png (\uicontrol {Fit Selected}) or press \key F.
(\uicontrol {Fit Selected}) or press \key F.
The world axis helper (1) shows the direction of the world axes in the view. The world axis helper (1) shows the direction of the world axes in the view.
To point the camera at the currently selected component in the direction of To point the 3D view 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 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 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 selected, the camera is pointed at the world origin.
the camera zoom level.
\image studio-3d-editor-axis-helper.webp "Axis helper in the 3D view" \image studio-3d-editor-axis-helper.webp "Axis helper in the 3D view"
You can use scene cameras (2) to view the \uicontrol View3D component from a Use scene cameras (2) to view the \uicontrol View3D component from a
specific angle in the \l {2D} view while editing scenes. Different types of specific angle in the \l {2D} view while editing scenes. Drag a camera
cameras are available in \uicontrol Components component to your scene from \uicontrol Components > \uicontrol {Qt Quick 3D} >
> \uicontrol {Qt Quick 3D} > \uicontrol {Qt Quick 3D}. For more information \uicontrol {Qt Quick 3D}. For more information about using cameras in the
about using cameras in the scene, the available camera types, and their scene and the available camera types, see \l{Cameras}.
properties, see \l{Cameras}.
\section2 Using Split View \section2 Using Split View
@@ -128,14 +123,14 @@
\image studio-3d-split-view.webp "Split view in the 3D view" \image studio-3d-split-view.webp "Split view in the 3D view"
To select one of the four panes, click on it. The selected pane is marked with To select one of the four panes, click the pane. The selected pane is marked with
a blue frame. Use the world axis helper to change the point of view for each pane a blue frame. Use the world axis helper to change the point of view for each pane
independently. Navigate each split by panning, rotating, and zooming, as independently. Navigate each split by panning, rotating, and zooming, as
described above. described above.
\section2 Using Fly Mode \section2 Using Fly Mode
You can move around freely in the 3D scene with fly mode. To navigate the scene with 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 fly mode, right-click and hold in the \uicontrol 3D view, and use the keyboard shortcuts
to move around the scene: to move around the scene:
@@ -177,10 +172,8 @@
\section1 Using Global and Local Orientation \section1 Using Global and Local Orientation
To switch between local and global orientation, select In \uicontrol 3D view, you view the scene in global or local orientation
\inlineimage global.png mode.
(\uicontrol {Toggle Local/Global Orientation})
or press \key Y.
In global orientation mode, transformation of a selected component is In global orientation mode, transformation of a selected component is
presented with respect to the global space. For example, while the move tool presented with respect to the global space. For example, while the move tool
@@ -194,40 +187,40 @@
the axes of global space. Dragging on the red arrow of the gizmo moves the 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. component in the local x direction in relation to the component.
To switch between local and global orientation, select \inlineimage global.png
(\uicontrol {Toggle Local/Global Orientation}) or press \key Y.
\section1 Using Edit Light \section1 Using Edit Light
The edit light is an extra point light that can be used to illuminate the 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 scene. To toggle the edit light on and off, select \inlineimage edit_light_on.png
or \inlineimage edit_light_off.png or \inlineimage edit_light_off.png (\uicontrol {Toggle Edit Light}) or
(\uicontrol {Toggle Edit Light}) press \key U.
or press \key U.
For more information about the available scene light types and their For information about the available scene light types and their properties,
properties, see \l{Lights}. see \l{Lights}.
\section1 Baking Lights \section1 Baking Lights
Bake lights to light static elements in your scene. To bake lights, Bake lights to light static elements in your scene. To bake lights, select
select \inlineimage icons/bakelights.png to open the \inlineimage icons/bakelights.png to open the \uicontrol {Lights Baking Setup}
\uicontrol {Lights Baking Setup} dialog. For more information, see dialog. For more information, see \l {Baking Lightmaps}.
\l {Baking Lightmaps}.
\section1 Selecting Components \section1 Selecting Components
To move, rotate, or scale components in the scene, you need to select them To move, rotate, or scale components in the scene, you need to select them
first. The selection mode buttons determine how components are selected when first. Toggle the selection mode to determine how components are selected
you click them in the \uicontrol{3D} view: when you click them in the \uicontrol{3D} view:
\list \list
\li In the \inlineimage select_item.png \li Use the \inlineimage select_item.png (\uicontrol {Single Selection})
(\uicontrol {Single Selection}) mode, a single component is selected. mode to select a single component.
\li In the \inlineimage select_group.png \li Use the \inlineimage select_group.png (\uicontrol {Group Selection})
(\uicontrol {Group Selection}) mode, the top level parent of the mode to select the top level parent of the component, so you can move
component is selected. This enables you to move, rotate, or scale a a group of components simultaneously.
group of components.
\endlist \endlist
To toggle the selection mode, press \key Q. Alternatively, press \key Q to toggle the selection mode.
To multiselect, hold \key Ctrl and click the components you wish to select. To multiselect, hold \key Ctrl and click the components you wish to select.
@@ -244,16 +237,15 @@
y, or z axis or on the top, bottom, left, and right clip planes of the y, or z axis or on the top, bottom, left, and right clip planes of the
the \uicontrol{3D} view. the \uicontrol{3D} view.
To move components, select \inlineimage move_off.png To move components, select \inlineimage move_off.png or press \key W:
or press \key W:
\list \list
\li To move components along the axes of the move gizmo, click the axis, \li To move components along the axes of the move gizmo, click the axis,
and drag the component along the axis. and drag the component along the axis.
\li To move components on a plane, click the plane handle and drag the \li To move components on a plane, drag the plane handle of the move
component on the plane. component on the plane.
\li To move components freely in the 3D view, click and drag the gray \li To move components freely in the 3D view, drag the gray handle at the
handle at the center of the move gizmo. center of the move gizmo.
\endlist \endlist
\section1 Rotating Components \section1 Rotating Components
@@ -264,29 +256,28 @@
or press \key E: or press \key E:
\list \list
\li To rotate a component around its rotation gizmo, click the axis ring \li To rotate a component around its rotation gizmo, drag the axis ring
and drag in the direction you want to rotate the component in. in the direction you want to rotate the component in.
\li To freely rotate the component, click and drag the inner center \li To freely rotate the component, drag the inner center circle of the
circle of the gizmo. gizmo.
\endlist \endlist
\section1 Scaling Components \section1 Scaling Components
\image studio-3d-editor-scale.webp "The 3D view in scale mode" \image studio-3d-editor-scale.webp "The 3D view in scale mode"
You can use the scale handles to adjust the local x, y, or z scale of a Ú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, component. You can adjust the scale across one, two, or three axes,
depending on the handle. depending on the handle.
To scale components, select \inlineimage scale_off.png To scale components, select \inlineimage scale_off.png or press \key R:
or press \key R:
\list \list
\li To adjust the scale across one axis, click and drag the scale handle \li To adjust the scale across one axis, drag the scale handle
attached to the axis. attached to the axis.
\li To adjust the scale across a plane, click the plane handle and drag \li To adjust the scale across a plane, drag the plane handle of
the component on the plane. the component.
\li To uniformly scale a component across all axes, click and drag the \li To uniformly scale a component across all axes, drag the
gray handle at the center of the component. gray handle at the center of the component.
\endlist \endlist
@@ -295,7 +286,7 @@
With snapping turned on, the objects in the \uicontrol 3D view snap to certain With snapping turned on, the objects in the \uicontrol 3D view snap to certain
intervals during transformation (move, rotate, scale). intervals during transformation (move, rotate, scale).
You can toggle snapping in the following ways: Toggle snapping in the following ways:
\list \list
\li Select \inlineimage icons/snapping-3d.png \li Select \inlineimage icons/snapping-3d.png
@@ -303,7 +294,7 @@
\li Hold down the \key Ctrl key. \li Hold down the \key Ctrl key.
\endlist \endlist
With snapping turned on, you can press and hold \key Shift to snap objects to one tenth of With snapping turned on, press and hold \key Shift to snap objects to one tenth of
the specified snap interval. the specified snap interval.
\section2 Configuring Snapping \section2 Configuring Snapping
@@ -330,65 +321,72 @@
To align a camera to the \uicontrol{3D} view: To align a camera to the \uicontrol{3D} view:
\list 1 \list 1
\li Select a camera in the \uicontrol{3D} or \uicontrol {Navigator} view. \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 \note If you don't have a camera selected, the most recently selected camera
is aligned to the view. is aligned to the view.
\li In the \uicontrol{3D} view, \li In the \uicontrol{3D} view, select \inlineimage icons/align-camera-on.png.
select \inlineimage icons/align-camera-on.png
.
\endlist \endlist
This moves and rotates the camera so that the camera shows the same view This moves and rotates the scene camera to show the same view as the current view
as the current view in the \uicontrol{3D} view. in the \uicontrol{3D} view.
To align the \uicontrol{3D} view to a camera: To align the \uicontrol{3D} view to a camera:
\list 1 \list 1
\li Select a camera in the \uicontrol{3D} view or \uicontrol {Navigator}. \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 \note If you don't have a camera selected, the view is aligned to the most recently
selected camera. selected camera.
\li In the \uicontrol{3D} view, \li In the \uicontrol{3D} view, select \inlineimage icons/align-view-on.png.
select \inlineimage icons/align-view-on.png
.
\endlist \endlist
This copies the position as well as x and y rotation values from the This moves and rotates the 3D view to show the same view as the selected scene camera.
camera and applies them to the \uicontrol{3D} view.
\section1 Toggling Visibility \section1 Toggling Visibility
To toggle the visibility of objects in the \uicontrol{3D} view, select To toggle the visibility of objects in the \uicontrol{3D} view, select
\inlineimage icons/visibilityon.png \inlineimage icons/visibilityon.png in the toolbar. This opens a menu with the
in the toolbar. This opens a menu with the following options: following options:
\table \table
\header
\li Action
\li Description
\li Keyboard Shortcut
\row \row
\li Show Grid \li Show Grid
\li Toggles the visibility of the helper grid. \li Toggles the visibility of the helper grid.
\li \key G
\row \row
\li Show Selection Boxes \li Show Selection Boxes
\li Toggles the visibility of selection boxes for selected 3D objects. \li Toggles the visibility of selection boxes for selected 3D objects.
\li \key B
\row \row
\li Show Icon Gizmos \li Show Icon Gizmos
\li Toggles the visibility of icon gizmos for object such as cameras, \li Toggles the visibility of icon gizmos for object such as cameras,
lights, and particle systems. lights, and particle systems.
\li \key I
\row \row
\li Always Show Camera Frustums \li Always Show Camera Frustums
\li Toggles between always showing the camera frustum and showing it \li Toggles between always showing the camera frustum and showing it
only for cameras selected in the \uicontrol{3D} view. only for cameras selected in the \uicontrol{3D} view.
\li \key C
\row \row
\li Always Show Particle Emitters and Attractors \li Always Show Particle Emitters and Attractors
\li Toggle between always showing the particle emitter and attractor \li Toggles between always showing the particle emitter and attractor
visualizations and only showing them when the emitter or attractor is visualizations and only showing them when the emitter or attractor
selected in the \uicontrol{3D} view. is selected in the \uicontrol{3D} view.
\li \key M
\endtable \endtable
\section1 Changing Colors \section1 Changing Colors
To change the \uicontrol 3D view background or grid color, select To change the \uicontrol 3D view background or grid color, select
\inlineimage icons/3d-background-color.png \inlineimage icons/3d-background-color.png in the toolbar. This opens a menu
in the toolbar. This opens a menu with the following options: with the following options:
\table \table
\header
\li Action
\li Decription
\row \row
\li Select Background Color \li Select Background Color
\li Select a color for the background. \li Select a color for the background.
@@ -416,16 +414,14 @@
\li Select a particle system in the \uicontrol Navigator or \li Select a particle system in the \uicontrol Navigator or
\uicontrol{3D} view. \uicontrol{3D} view.
\li In the \uicontrol{3D} view, select \li In the \uicontrol{3D} view, select
\inlineimage icons/particle-animation-on.png \inlineimage icons/particle-animation-on.png to activate particle animation.
to activate particle animation. Now you can see the particle animation in Now you can see the particle animation in the \uicontrol{3D} view.
the \uicontrol{3D} view.
\endlist \endlist
You can pause the particle animation by selecting You can pause the particle animation by selecting
\inlineimage icons/particle-pause.png \inlineimage icons/particle-pause.png. When the animation is paused, use
. When the animation is paused, you can use \inlineimage icons/particles-seek.png to manually seek forward or backward in
\inlineimage icons/particles-seek.png the particle animation.
to manually seek forward or backward in the particle animation.
\section1 Using Viewport Shading \section1 Using Viewport Shading