View3D QML Type

提供用于渲染 3D 场景的视口。更多

Import Statement:	`import QtQuick3D`
Inherits:	Item

所有成员（包括继承成员）的列表

属性

camera : QtQuick3D::Camera
effectiveTextureSize : size (since 6.7)
environment : QtQuick3D::SceneEnvironment
explicitTextureHeight : int (since 6.7)
explicitTextureWidth : int (since 6.7)
extensions : List<QtQuick3D::Object3D>
importScene : QtQuick3D::Node
renderFormat : enumeration (since 6.4)
renderMode : enumeration
renderStats : QtQuick3D::RenderStats
scene : QtQuick3D::Node

方法

vector3d mapFrom3DScene(vector3d scenePos)
vector3d mapTo3DScene(vector3d viewPos)
pickResult pick(float x, float y)
pickResult pick(float x, float y, Model model) (since 6.8)
List<pickResult> pickAll(float x, float y) (since 6.2)
List<pickResult> pickSubset(float x, float y, list<Model> models) (since 6.8)
pickResult rayPick(vector3d origin, vector3d direction) (since 6.2)
List<pickResult> rayPickAll(vector3d origin, vector3d direction) (since 6.2)
setTouchpoint(Item target, point position, int pointId, bool pressed) (since 6.8)

详细说明

View3D 提供了一个可渲染 3D 场景的 2D 表面。该表面是Qt Quick Item ，可放置在Qt Quick 场景中。

有两种方法可以定义在 View3D 上可视化的三维场景：如果将Node-based 项的层次结构直接定义为 View3D 的子项，则该层次结构将成为 View3D 的隐式场景。

也可以使用importScene 属性引用现有场景，并将其设置为要可视化场景的根Node 。该Node 不一定是 View3D 的祖先，而且可以有多个导入相同场景的 View3D。

View3D 示例对此进行了演示。

如果 View3D 都有子Nodes ，并且同时设置了importScene 属性，那么这两个场景将被渲染为同一场景中的同胞子树。

要控制场景的渲染方式，可以设置environment 属性。SceneEnvironment 类型有许多可调整的视觉属性，如背景颜色、色调映射、抗锯齿等。QtQuick3D.Helpers 模块中的ExtendedSceneEnvironment 扩展了SceneEnvironment 的更多功能，增加了常用的后期处理效果。

此外，要在 View3D 中渲染任何内容，场景都需要一个Camera 。如果场景中只有一个Camera ，则会自动选中。否则，可以使用camera 属性来选择摄像机。Camera 决定了场景中哪些部分是可见的，以及如何将它们投射到 2D 表面上。

默认情况下，三维场景将首先渲染到屏幕外的缓冲区，然后在渲染完成后与Qt Quick 场景的其余部分合成。这提供了最大程度的兼容性，但可能会对某些图形硬件的性能产生影响。如果是这种情况，可以使用renderMode 属性来切换 View3D 渲染到窗口的方式。

具有默认离屏renderMode 的 View3D 也隐含为texture provider 。这意味着，只要所有项目都在同一个window 中，ShaderEffect 或Texture.sourceItem 就可以直接引用 View3D。与任何其他Item 一样，也可以将 View3D 或其祖先之一切换为基于纹理的item layer 。

另请参阅 Qt Quick 3D - View3D 示例。

属性文档

camera : QtQuick3D::Camera

该属性指定使用哪个Camera 渲染场景。如果未设置此属性，则将使用场景中第一个启用的摄像机。

注：如果此属性包含的摄像机不是visible ，则不会再尝试查找摄像机。

另请参阅 PerspectiveCamera,OrthographicCamera,FrustumCamera, 和CustomCamera 。

effectiveTextureSize : size [since 6.7]

该属性显示底层颜色（和深度/模版）缓冲区的大小（像素）。该属性可在 GUI（主）线程、QML 绑定或 JavaScript 中使用。

这是一个只读属性。

注意： 只有当renderMode 设置为Offscreen 时，该属性才相关。

此属性在 Qt 6.7 中引入。

另请参阅 explicitTextureWidth,explicitTextureHeight, 和DebugView 。

environment : QtQuick3D::SceneEnvironment

此属性指定用于渲染场景的SceneEnvironment 。

注意： 将此属性设置为null 会将SceneEnvironment 重置为默认值。

另请参阅 SceneEnvironment 。

explicitTextureHeight : int [since 6.7]

项目关联纹理的高度（以像素为单位）。当需要一个不依赖于项目大小的固定纹理尺寸时使用。该尺寸对物品的几何形状（其尺寸和在场景中的位置）没有影响，这意味着纹理的内容将按比例放大或缩小（可能还会拉伸）到物品的区域上。

默认情况下，该值为0 。值为 0 表示纹理的大小与项目的大小一致。(texture size in pixels =item's logical size *device pixel ratio)。

注意： 只有当renderMode 设置为Offscreen 时，该属性才相关。否则，其值将被忽略。

此属性在 Qt 6.7 中引入。

另请参阅 explicitTextureWidth,effectiveTextureSize, 和DebugView 。

explicitTextureWidth : int [since 6.7]

项目关联纹理的宽度（像素）。当需要一个固定的纹理尺寸而不依赖于项目的大小时，该值就会起作用。该尺寸对物品的几何形状（其尺寸和在场景中的位置）没有影响，这意味着纹理的内容将按比例放大或缩小（可能还会拉伸）到物品的区域上。

默认情况下，该值为0 。值为 0 表示纹理的大小与项目的大小一致。(texture size in pixels =item's logical size *device pixel ratio)。

注意： 只有当renderMode 设置为Offscreen 时，该属性才相关。否则，其值将被忽略。

此属性在 Qt 6.7 中引入。

另请参阅 explicitTextureHeight,effectiveTextureSize, 和DebugView 。

extensions : List<QtQuick3D::Object3D>

此属性包含应与此View3D 一起使用的用户扩展名列表。

另请参见 RenderExtension 。

importScene : QtQuick3D::Node

该属性定义了要渲染到视口的场景的引用节点。该节点不一定是View3D 的子节点。如果有View3D 的子节点，则该引用节点会与的子节点成为同级节点。

注意： 此属性只能设置一次，后续更改将不起作用。

您也可以将Node-based 项的层次结构直接定义为View3D 的子节点，那么这将成为View3D 的隐式场景。

要返回View3D 的当前场景，请使用scene 属性。

另请参阅 Node 。

renderFormat : enumeration [since 6.4]

该属性决定背景纹理的格式。仅在View3D 渲染纹理时适用，例如因为renderMode 是View3D.Offscreen 。

默认为ShaderEffectSource.RGBA8 。

如果底层图形驱动程序在运行时不支持该格式，则使用 RGBA8。

此属性在 Qt 6.4 中引入。

另请参阅 QtQuick::ShaderEffectSource::format 和QtQuick::Item::layer.format 。

renderMode : enumeration

该属性决定View3D 如何与Qt Quick 场景的其他部分相结合。

默认情况下，场景将作为中间步骤渲染到屏幕外缓冲区。然后，这个非屏幕缓冲区会像其他Qt Quick Item 一样渲染到窗口（或渲染目标）中。

对于大多数用户来说，无需更改呈现模式，因此可以放心地忽略此属性。但在某些图形硬件上，使用屏幕外缓冲区可能会成为性能瓶颈。如果是这种情况，不妨尝试使用其他模式。

常数	说明
`View3D.Offscreen`	作为中间步骤，场景被渲染到屏幕外缓冲区。然后将该离屏缓冲区与Qt Quick 场景的其余部分进行合成。
`View3D.Underlay`	在渲染Qt Quick 场景的其余部分之前，该场景会直接渲染到窗口中。在此模式下，View3D 不能放置在其他Qt Quick 项目之上。
`View3D.Overlay`	场景在Qt Quick 渲染完成后直接渲染到窗口。在此模式下，View3D 将始终位于其他Qt Quick 项目之上。
`View3D.Inline`	View3D 的场景图被嵌入到主场景图中，其排序语义与任何其他Qt Quick Item 的排序语义相同。由于在 2D 场景图中注入了基于深度的 3D 内容，因此根据场景内容的不同，该模式可能会导致一些微妙的问题，除非有特殊需要，否则不建议使用。

默认值为View3D.Offscreen 。

注意： 在更改渲染模式时，必须注意View3D.Offscreen （默认）是唯一能保证完美图形保真度的模式。其他模式都有可能导致视觉故障的限制，因此在更改此属性时，必须检查视觉输出是否仍然正确。

注意： 使用 Underlay、Overlay 或 Inline 模式时，在显示QQuickWindow 或QQuickView 承载View3D 项目之前，通过QQuickGraphicsConfiguration::setDepthBufferFor2D() 禁用Qt Quick 场景图的深度缓冲区写入可能是有用的，在某些情况下甚至是必需的。

renderStats : QtQuick3D::RenderStats [read-only]

该属性提供有关帧渲染的统计数据，如fps,frameTime,renderTime,syncTime, 和maxFrameTime 。

scene : QtQuick3D::Node [read-only]

返回View3D 场景的根Node 。

定义在View3D 中可视化的 3D 场景：

直接定义Node-based 项的层次结构作为View3D 的子项，那么这将成为View3D 的隐式场景。
使用importScene 属性引用现有场景，并将其设置为要可视化场景的根Node 。该Node 不一定是View3D 的祖先，您可以有多个导入相同场景的 View3D。

另请参阅 importScene 。

方法文档

vector3d mapFrom3DScene(vector3d scenePos)

将scenePos 从场景空间（3D）转换为视图空间（2D）。

返回的 x 值和 y 值为视图坐标，左上角为 [0, 0]，右下角为 [width, height]。返回的 z 值包含以场景坐标为单位的近剪辑平面（clipNear）到scenePos 的距离。如果距离为负数，则表示scenePos 位于活动相机的后方。如果scenePos 无法映射到场景中的某个位置，则会返回一个 [0, 0, 0] 的位置。

此函数要求camera 已分配给视图。

另请参阅 mapTo3DScene() 和Camera.mapToViewport()。

vector3d mapTo3DScene(vector3d viewPos)

将viewPos 从视图空间（2D）转换到场景空间（3D）。

viewPos 的 x 值和 y 值应使用视图坐标，左上角为 [0, 0]，右下角为 [width, height]。z 值被解释为场景坐标中与近剪辑平面（clipNear）的距离。

如果viewPos 无法成功映射到场景中的某个位置，则会返回一个 [0, 0, 0] 的位置。

此函数要求为视图分配一个camera 。

另请参阅 mapFrom3DScene() 和Camera.mapFromViewport() 。

pickResult pick(float x, float y)

该方法将从视图坐标x 和y 向场景中 "发射 "一条射线，并返回与场景中物体最近的交点信息。

例如，可以使用鼠标坐标调用该方法来查找鼠标光标下的对象。

[since 6.8] pickResult pick(float x, float y, Model model)

该方法将从视图坐标x 和y 向场景 "发射 "一条射线，并返回射线与指定model 之间的交点信息。

例如，可以使用鼠标坐标调用该方法来查找鼠标光标下的对象。

该方法在 Qt 6.8 中引入。

[since 6.2] List<pickResult> pickAll(float x, float y)

该方法将从视图坐标x 和y 向场景中 "发射 "一条射线，并返回一个与场景中物体相交的信息列表。返回的列表按与摄像机的距离排序，最近的交点显示在最前面，最远的交点显示在最后面。

例如，可以使用鼠标坐标调用该方法来查找鼠标光标下的对象。

此方法在 Qt 6.2 中引入。

[since 6.8] List<pickResult> pickSubset(float x, float y, list<Model> models)

该方法将从视图坐标x 和y 向场景中 "发射 "一条射线，并返回与传入的models 列表的交点信息。该方法将只对传入的模型列表进行检查。返回的列表按与摄像机的距离排序，最近的交叉点出现在最前面，最远的出现在最后面。

例如，可以使用鼠标坐标调用此功能，以查找鼠标光标下的对象。

可与属性 list<Model> 和动态 JavaScript 模型数组一起使用。

此方法在 Qt 6.8 中引入。

[since 6.2] pickResult rayPick(vector3d origin, vector3d direction)

该方法将从origin 开始向场景中 "发射 "一条射线，direction ，并返回与场景中物体最近的交点信息。

例如，可以调用场景中任何对象的位置和前向矢量来查看物品前方的对象。这样就可以从场景中的任意点进行拾取。

此方法在 Qt 6.2 中引入。

[since 6.2] List<pickResult> rayPickAll(vector3d origin, vector3d direction)

该方法将从origin 开始，在direction 向场景中 "发射 "一条射线，并返回一个与场景中物体最近交点的信息列表。该列表按照从原点到方向矢量的距离进行排序，最近的交点出现在最前面，最远的交点出现在最后面。

例如，可以使用场景中任何物体的位置和前向矢量来调用该列表，以查看某个物体前面有哪些物体。这样就可以从场景中的任意点进行拾取。

此方法在 Qt 6.2 中引入。

[since 6.8] setTouchpoint(Item target, point position, int pointId, bool pressed)

向target 发送合成触摸事件，将 ID 为pointId 的触摸点移动到position ，由pressed 判断该点是否被按下。如果pointId 之前在其他项目上处于活动状态，则还会发送相应的触摸释放事件。

此方法在 Qt 6.8 中引入。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.