Back to Qt.io
Contact Us Blog Download Qt
本页内容

View3D QML Type

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

Import Statement: import QtQuick3D
Inherits:

Item

属性

方法

  • pickResult closestPointPick(vector3d origin, float radius, Model model) (since 6.11)
  • 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<Object3D> pickInRect(point start, point end) (since 6.11)
  • List<pickResult> pickSubset(float x, float y, list<Model> models) (since 6.8)
  • pickResult rayPick(vector3d origin, vector3d direction) (since 6.2)
  • pickResult rayPick(vector3d origin, vector3d direction, Model model) (since 6.11)
  • List<pickResult> rayPickAll(vector3d origin, vector3d direction) (since 6.2)
  • void setTouchpoint(Item target, point position, int pointId, bool pressed) (since 6.8)

详细说明

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

定义在 View3D 上可视化的 3D 场景有两种方式：若将一组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 表面上。

默认情况下，3D 场景会先渲染到一个离屏缓冲区中，渲染完成后再与Qt Quick 场景的其余部分进行合成。这提供了最高的兼容性，但在某些图形硬件上可能会影响性能。如果出现这种情况，可以使用renderMode 属性来切换View3D在窗口中的渲染方式。

默认使用“Offscreen”renderMode 的View3D，隐式地也是texture provider 。这意味着，只要所有项目都位于同一个window 内，ShaderEffect 或Texture.sourceItem 就可以直接引用该View3D。与其他Item 一样，也可以将View3D或其某个祖先切换为基于纹理的item layer 。

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

属性文档

camera : QtQuick3D::Camera

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

注意： 强烈建议 显式设置此属性，而非依赖自动摄像机选择。当场景中存在多个摄像机时，自动选择无法保证最终会选中哪个摄像机。在使用layers 时，显式指定摄像机还可以避免对场景节点进行不必要的重新评估。

注意：如果 该属性包含的摄像机不属于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 有子节点，则该引用节点将与这些子节点成为同级节点。

注意：场景 仅可在位于同一window 中的View3D 项目之间共享。

注意：在 多个View3D 项之间共享场景时， 应完整导入整个场景，即不支持仅导入场景的子树。如果多个View3D需要显示同一共享场景的不同部分，请考虑改用layers 。

注意：此 属性仅可设置一次，后续更改将无效。

您还可以直接将一组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.InlineView3D 的场景图被嵌入到主场景图中，并应用与其他任何Qt Quick Item 相同的排序规则。 由于将基于深度的 3D 内容注入到 2D 场景图中，此模式可能会根据场景的内容导致一些难以察觉的问题，因此除非有特殊需要，否则不建议使用。

默认设置为View3D.Offscreen 。

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

注意：在 使用“底层”（Underlay）、“叠加”（Overlay）或“内联”（Inline）模式时， 在显示承载View3D 项的QQuickWindow 或QQuickView 之前，通过QQuickGraphicsConfiguration::setDepthBufferFor2D()禁用Qt Quick 场景图的深度缓冲区写入操作，这不仅很有用，在某些情况下甚至是必需的。

renderOverrides : enumeration

控制Qt Quick 3D 的渲染方式。

常量描述
View3D.None渲染过程正常进行。内部渲染阶段将根据应用程序中使用的功能按需调度。
View3D.DisableInternalPasses禁用Qt Quick 3D 的内部渲染阶段。设置此模式时，应用程序负责生成并呈现最终帧。通常，这涉及实现自定义用户渲染阶段，并使用SimpleQuadRenderer 或自定义的render extension 将结果呈现到视口。

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 。

方法文档

[since 6.11] pickResult closestPointPick(vector3d origin, float radius, Model model)

该方法将查找model 表面上距离origin 最近的点，且距离不超过radius 。如果model 为null ，则将查找radius 范围内最近的对象。

如果不存在此类对象，则返回null 。

该方法在 Qt 6.11 中引入。

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 向场景中“发射”一条光线，并返回关于该光线与场景中物体最近交点的信息。

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

材质在渲染时由cull mode 舍弃的三角形也不会被选中，因此只报告沿光线实际可见的几何体。

另请参阅 pickAll()、pickSubset() 和pickInRect()。

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

该方法将从视图坐标x 和y 向场景中“射出”一条光线，并返回该光线与指定model 的相交信息。

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

该方法在 Qt 6.8 中引入。

另请参见 pickAll()、pickSubset() 和pickInRect()。

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

该方法将从视图坐标x 和y 向场景中“射出”一条光线，并返回一个包含与场景中对象交点信息的列表。返回的列表按与摄像机的距离排序，距离最近的交点排在最前面，距离最远的排在最后。

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

该方法在 Qt 6.2 中引入。

另请参阅 pick()、pickSubset() 和pickInRect()。

[since 6.11] list<Object3D> pickInRect(point start, point end)

该方法会选取所有位于由视图坐标系中start 和end 点所定义的矩形区域内的对象。

返回位于指定矩形区域内的对象列表。该方法可用于“选区框”选择，即用户通过拖动矩形来选择多个对象。

该方法在 Qt 6.11 中引入。

另请参阅 pick()、pickAll() 和pickSubset()。

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

该方法将从视图坐标x 和y 向场景中“射出”一条光线，并返回与传入的models 列表中对象的交点信息。该方法仅检查与传入的模型列表是否存在交点。返回的列表按与摄像机的距离排序，距离最近的交点排在最前面，距离最远的排在最后。

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

既支持 `list<Model>` 属性列表，也支持动态的 JavaScript 模型数组。

该方法在 Qt 6.8 中引入。

另请参阅 pick()、pickAll() 和pickInRect()。

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

该方法将从origin 出发，沿direction 方向向场景中“发射”一条光线，并返回该光线与场景中物体最近交点的相关信息。

例如，可以传入场景中任意对象的位置和前进向量来调用此方法，以查看哪个对象位于某个物品的前方。这使得可以从场景中的任意点进行拾取操作。

材质在渲染时由cull mode 剔除的三角形也不会被选中，因此仅报告沿光线实际可见的几何体。

该方法于 Qt 6.2 版本中引入。

[since 6.11] pickResult rayPick(vector3d origin, vector3d direction, Model model)

该方法将从origin 处、朝direction 方向向场景中“发射”一条光线，并返回该光线与指定model 的交点信息。

该方法于 Qt 6.11 中引入。

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

该方法将从坐标origin 、方向向量direction 处向场景内“发射”一条光线，并返回一个列表，其中包含与场景中物体最近交点的相关信息。该列表已按沿方向向量方向到原点的距离进行预排序，最近的交点排在最前，最远的排在最后。

例如，可以使用场景中任意对象的位置和前进向量调用此方法，以查看该对象前方有哪些物体。这使得可以从场景中的任意点进行拾取操作。

该方法于 Qt 6.2 版本中引入。

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

向target 发送一个合成触摸事件，将ID为pointId 的触摸点移动到position ，其中pressed 用于确定该点是否被按下。如果pointId 此前在另一个项目上处于活动状态，则还会发送相应的触摸释放事件。

该方法在 Qt 6.8 中引入。

© 2026 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.