View3D QML 类型

提供用于渲染 3D 场景的前视图。更多...

导入语句	import QtQuick3D

所有成员列表，包括继承的成员

属性

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

方法

vector3d mapFrom3DScene(vector3d scenePos)
vector3d mapTo3DScene(vector3d viewPos)
PickResult pick(float x, float y)
List pickAll(float x, float y) (since 6.2)
PickResult rayPick(vector3d origin, vector3d direction) (since 6.2)
List rayPickAll(vector3d origin, vector3d direction) (since 6.2)

详细描述

View3D 提供一个二维表面，可以在其上渲染 3D 场景。这个表面是一个 Qt Quick Item，可以放置在 Qt Quick 场景中。

定义在 View3D 上可视化的 3D 场景的方式有两种：如果您直接将基于 Node 的项目的层次结构定义为 View3D 的子项，那么这将成为 View3D 的隐含场景。

还可以通过使用importScene属性并设置它为要可视化的场景的根Node来引用现有的场景。这个Node不必是View3D的祖先，并且可以拥有多个导入相同场景的View3D。

这可以在View3D 示例中看到。

如果View3D同时具有子Node和设置了importScene属性，那么这两个场景将像同一场景中的兄弟子树一样渲染。

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

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

默认情况下，3D场景首先将被渲染到一个离屏缓冲区中，然后当渲染完成时与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。如果没有设置此属性，则将使用场景中启用的第一个相机。

注意：如果此属性包含一个不可见的相机，则将停止进一步搜索相机。

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

effectiveTextureSize : size [since 6.7]

此属性公开了底层颜色（和深度/模板）缓冲区的大小，以像素为单位。它在GUI（主）线程上的QML绑定或JavaScript中提供使用。

这是一个只读属性。

注意： 当 renderMode 设置为 Offscreen 时，此属性相关。

该属性从 Qt 6.7 开始引入。

另请参阅 explicitTextureWidth、explicitTextureHeight 和 DebugView。

环境 : QtQuick3D::SceneEnvironment

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

另请参阅 SceneEnvironment。

显式纹理高度 : int [since 6.7]

以像素为单位，表示与项目关联的纹理的高度。当需要不依赖于项目大小的固定纹理大小时相关。此大小对项目的几何形状（大小和场景中的位置）没有影响，这意味着纹理的内容将按比例放大或缩小（可能还会拉伸）到项目的区域。

默认值为 0。0 的值表示纹理的大小随项目大小变化。(像素纹理大小 = 项目的逻辑大小 * 设备像素比).

注意： 当 renderMode 设置为 Offscreen 时，此属性相关。在其他情况下，其值将被忽略。

该属性从 Qt 6.7 开始引入。

另请参阅 explicitTextureWidth、effectiveTextureSize 和 DebugView。

显式纹理宽度 : int [since 6.7]

与项目关联的纹理的宽度，以像素为单位。当需要不依赖于项目大小的固定纹理大小时相关。此大小对项目的几何形状（大小和场景中的位置）没有影响，这意味着纹理的内容将按比例放大或缩小（可能还会拉伸）到项目的区域。

默认值为 0。0 的值表示纹理的大小随项目大小变化。(像素纹理大小 = 项目的逻辑大小 * 设备像素比).

注意： 当 renderMode 设置为 Offscreen 时，此属性相关。在其他情况下，其值将被忽略。

该属性从 Qt 6.7 开始引入。

另请参阅 explicitTextureHeight、effectiveTextureSize 和 DebugView。

扩展 : List<QtQuick3D::Object3D>

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

另请参阅 RenderExtension。

导入场景 : QtQuick3D::Node

此属性定义了渲染到视口的场景的引用节点。此节点不必是 View3D 的子节点。如果有的话，该引用节点将作为 View3D 的子节点，成为其兄弟节点。

注意： 此属性只能设置一次，后续更改将无效果。

另请参阅 Node。

渲染格式 : 枚举 [since 6.4]

此属性确定后备纹理的格式。仅当 View3D 正在将渲染到纹理时适用，例如当 renderMode 设置为 View3D.Offscreen。

默认值为 ShaderEffectSource.RGBA8。

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

此属性是在 Qt 6.4 中引入的。

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

renderMode : 枚举

此属性决定了 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 的相同顺序语义应用于。由于将基于深度的 3D 内容注入到 2D 场景图中可能会引起细微的问题，因此不推荐使用该模式，除非有特殊需求。

默认值为 View3D.Offscreen。

注意： 当更改渲染模式时，请注意，View3D.Offscreen（默认模式）是唯一保证完全图形保真度的模式。其他模式都有局限性，可能导致视觉问题，因此当更改此属性时，重要的是要检查视觉输出是否仍然看起来正确。

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

renderStats : QtQuick3D::RenderStats [只读]

此属性提供了关于帧渲染的统计信息，例如 fps、frameTime、renderTime、syncTime 和 maxFrameTime。

scene : QtQuick3D::Node [只读]

包含 View3D 场景的根 Node。

也请参阅 importScene。

方法文档

vector3d mapFrom3DScene(vector3d scenePos)

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

返回的x和y值将在视图坐标中，其中左上角为[0, 0]，右下角为[width, height]。返回的z值包含场景坐标中

scenePos

到近裁剪平面（clipNear）的距离。如果距离为负值，则表示

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.2] List<PickResult> pickAll(float x, float y)

此方法将从视图坐标x和y向场景“发射”一条射线，并返回关于场景中与对象交点的信息列表。返回的列表按相机到交点的距离排序，最近的交点排在首位，最远的交点排在末尾。

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

此方法自Qt 6.2版本引入。

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

此方法将从origin开始向direction方向“发射”一条射线，并返回场景中与对象最近交点的信息。

例如，可以用场景中任何对象的位姿和前向向量调用此方法来查看物体前面的对象。这让从场景中的任何位置进行拾取成为可能。

此方法自Qt 6.2版本引入。

[自 6.2 开始] 列表<PickResult> rayPickAll(vector3d origin, vector3d direction)

此方法将“射入”一条光线到场景中，起点为origin，方向为direction，并返回关于场景中最近物体交点信息列表。列表按从起点沿方向向量距离排序，最近的交点排在最前面，最远的排在最后。

例如，可以调用场景中任何对象的当前位置和前进向量，以查看在项目前面的对象。这使得可以从场景中的任何点进行拾取。

此方法自Qt 6.2版本引入。