Provides a viewport on which to render a 3D scene. 更多...
| import 语句： | import QtQuick3D |
(从 6.7 起)
(从 6.7 起)
(从 6.7 起)
(从 6.4 起)
(从 6.2 起)
(从 6.2 起)
(从 6.2 起)
View3D provides a 2D surface on which a 3D scene can be rendered. This surface is a Qt Quick Item and can be placed in a Qt Quick scene.
There are two ways to define the 3D scene that is visualized on the View3D: If you define a hierarchy of Node-based items as children of the View3D directly, then this will become the implicit scene of the View3D.
It is also possible to reference an existing scene by using the importScene property and setting it to the root Node of the scene you want to visualize. This Node does not have to be an ancestor of the View3D, and you can have multiple View3Ds that import the same scene.
This is demonstrated in View3D example .
If the View3D both has child 节点 和 importScene property is set simultaneously, then both scenes will be rendered as if they were sibling subtrees in the same scene.
To control how a scene is rendered, you can set the
environment
property. The type
SceneEnvironment
has a number of visual properties that can be adjusted, such as background color, tone mapping, anti-aliasing and more.
ExtendedSceneEnvironment
在
QtQuick3D.Helpers
模块延伸
SceneEnvironment
with even more features, adding common post-processing effects.
In addition, in order for anything to be rendered in the View3D, the scene needs a Camera . If there is only a single Camera in the scene, then this will automatically be picked. Otherwise, the camera property can be used to select the camera. The Camera decides which parts of the scene are visible, and how they are projected onto the 2D surface.
By default, the 3D scene will first be rendered into an off-screen buffer and then composited with the rest of the Qt Quick scene when it is done. This provides the maximum level of compatibility, but may have performance implications on some graphics hardware. If this is the case, the renderMode property can be used to switch how the View3D is rendered into the window.
A View3D with the default Offscreen renderMode is implicitly a 纹理提供程序 as well. This means that ShaderEffect or Texture.sourceItem can reference the View3D directly as long as all items live within the same window . Like with any other Item , it is also possible to switch the View3D, or one of its ancestors, into a texture-based item layer .
另请参阅 Qt Quick 3D - View3D example .
|
camera : QtQuick3D::Camera |
This property specifies which Camera is used to render the scene. If this property is not set, then the first enabled camera in the scene will be used.
注意： If this property contains a camera that's not visible then no further attempts to find a camera will be done.
另请参阅 PerspectiveCamera , OrthographicCamera , FrustumCamera ，和 CustomCamera .
|
effectiveTextureSize
:
size
|
This property exposes the size, in pixels, of the underlying color (and depth/stencil) buffers. It is provided for use on the GUI (main) thread, in QML bindings or JavaScript.
This is a read-only property.
注意：
This property is relevant only when
renderMode
被设为
Offscreen
.
This property was introduced in Qt 6.7.
另请参阅 explicitTextureWidth , explicitTextureHeight ，和 DebugView .
|
environment : QtQuick3D::SceneEnvironment |
This property specifies the SceneEnvironment used to render the scene.
另请参阅 SceneEnvironment .
|
explicitTextureHeight
:
int
|
The height, in pixels, of the item's associated texture. Relevant when a fixed texture size is desired that does not depend on the item's size. This size has no effect on the geometry of the item (its size and placement within the scene), which means the texture's content will appear scaled up or down (and possibly stretched) onto the item's area.
默认情况下，值为
0
. A value of 0 means that texture's size follows the item's size. (
texture size in pixels
=
item's logical size
*
设备像素比率
).
注意：
This property is relevant only when
renderMode
被设为
Offscreen
. Its value is ignored otherwise.
This property was introduced in Qt 6.7.
另请参阅 explicitTextureWidth , effectiveTextureSize ，和 DebugView .
|
explicitTextureWidth
:
int
|
The width, in pixels, of the item's associated texture. Relevant when a fixed texture size is desired that does not depend on the item's size. This size has no effect on the geometry of the item (its size and placement within the scene), which means the texture's content will appear scaled up or down (and possibly stretched) onto the item's area.
默认情况下，值为
0
. A value of 0 means that texture's size follows the item's size. (
texture size in pixels
=
item's logical size
*
设备像素比率
).
注意：
This property is relevant only when
renderMode
被设为
Offscreen
. Its value is ignored otherwise.
This property was introduced in Qt 6.7.
另请参阅 explicitTextureHeight , effectiveTextureSize ，和 DebugView .
|
extensions : List < QtQuick3D::Object3D > |
This property contains a list of user extensions that should be used with this View3D .
另请参阅 RenderExtension .
|
importScene : QtQuick3D::Node |
This property defines the reference node of the scene to render to the viewport. The node does not have to be a child of the View3D . This referenced node becomes a sibling with child nodes of View3D , if there are any.
注意： This property can only be set once, and subsequent changes will have no effect.
另请参阅 Node .
|
renderFormat
:
enumeration
|
This property determines the backing texture's format. Applicable only when the
View3D
is rendering to a texture, for example because the
renderMode
is
View3D.Offscreen
.
默认为
ShaderEffectSource.RGBA8
.
If the format is not supported by the underlying graphics driver at run time, RGBA8 is used.
该特性在 Qt 6.4 引入。
另请参阅 QtQuick::ShaderEffectSource::format and QtQuick::Item::layer.format .
|
renderMode : enumeration |
This property determines how the View3D is combined with the other parts of the Qt Quick scene.
By default, the scene will be rendered into an off-screen buffer as an intermediate step. This off-screen buffer is then rendered into the window (or render target) like any other Qt Quick Item .
For most users, there will be no need to change the render mode, and this property can safely be ignored. But on some graphics hardware, the use of an off-screen buffer can be a performance bottleneck. If this is the case, it might be worth experimenting with other modes.
| 常量 | 描述 |
|---|---|
View3D.Offscreen
|
The scene is rendered into an off-screen buffer as an intermediate step. This off-screen buffer is then composited with the rest of the Qt Quick scene. |
View3D.Underlay
|
The scene is rendered directly to the window before the rest of the Qt Quick scene is rendered. With this mode, the View3D cannot be placed on top of other Qt Quick items. |
View3D.Overlay
|
The scene is rendered directly to the window after Qt Quick is rendered. With this mode, the View3D will always be on top of other Qt Quick items. |
View3D.Inline
|
The View3D 's scene graph is embedded into the main scene graph, and the same ordering semantics are applied as to any other Qt Quick Item . As this mode can lead to subtle issues, depending on the contents of the scene, due to injecting depth-based 3D content into a 2D scene graph, it is not recommended to be used, unless a specific need arises. |
默认为
View3D.Offscreen
.
注意：
When changing the render mode, it is important to note that
View3D.Offscreen
(the default) is the only mode which guarantees perfect graphics fidelity. The other modes all have limitations that can cause visual glitches, so it is important to check that the visual output still looks correct when changing this property.
注意： When using the Underlay, Overlay, or Inline modes, it can be useful, and in some cases, required, to disable the Qt Quick scene graph's depth buffer writes via QQuickGraphicsConfiguration::setDepthBufferFor2D () before showing the QQuickWindow or QQuickView hosting the View3D 项。
|
renderStats
:
QtQuick3D::RenderStats
|
This property provides statistics about the rendering of a frame, such as fps , frameTime , renderTime , syncTime ，和 maxFrameTime .
|
scene
:
QtQuick3D::Node
|
Holds the root Node 的 View3D 's scene.
另请参阅 importScene .
变换 scenePos from scene space (3D) into view space (2D).
The returned x- and y-values will be be in view coordinates, with the top-left corner at [0, 0] and the bottom-right corner at [width, height]. The returned z-value contains the distance from the near clip plane of the frustum (clipNear) to scenePos in scene coordinates. If the distance is negative, that means the scenePos is behind the active camera. If scenePos cannot be mapped to a position in the scene, a position of [0, 0, 0] is returned.
此函数要求 camera is assigned to the view.
另请参阅 mapTo3DScene () 和 Camera.mapToViewport ().
变换 viewPos from view space (2D) into scene space (3D).
The x- and y-values of viewPos should be in view coordinates, with the top-left corner at [0, 0] and the bottom-right corner at [width, height]. The z-value is interpreted as the distance from the near clip plane of the frustum (clipNear) in scene coordinates.
若 viewPos cannot successfully be mapped to a position in the scene, a position of [0, 0, 0] is returned.
This function requires that a camera is assigned to the view.
另请参阅 mapFrom3DScene () 和 Camera.mapFromViewport ().
|
PickResult pick ( float x , float y ) |
This method will "shoot" a ray into the scene from view coordinates x and y and return information about the nearest intersection with an object in the scene.
This can, for instance, be called with mouse coordinates to find the object under the mouse cursor.
|
|
This method will "shoot" a ray into the scene from view coordinates x and y and return a list of information about intersections with objects in the scene. The returned list is sorted by distance from the camera with the nearest intersections appearing first and the furthest appearing last.
This can, for instance, be called with mouse coordinates to find the object under the mouse cursor.
This method was introduced in Qt 6.2.
|
|
This method will "shoot" a ray into the scene starting at origin 和在 direction and return information about the nearest intersection with an object in the scene.
This can, for instance, be called with the position and forward vector of any object in a scene to see what object is in front of an item. This makes it possible to do picking from any point in the scene.
This method was introduced in Qt 6.2.
|
|
This method will "shoot" a ray into the scene starting at origin 和在 direction and return a list of information about the nearest intersections with objects in the scene. The list is presorted by distance from the origin along the direction vector with the nearest intersections appearing first and the furthest appearing last.
This can, for instance, be called with the position and forward vector of any object in a scene to see what objects are in front of an item. This makes it possible to do picking from any point in the scene.
This method was introduced in Qt 6.2.