Scene3D QML Type
Scene3D 类型用于将 Qt3D 场景集成到QtQuick 2 场景中。更多内容...
| Import Statement: | import QtQuick.Scene3D 2.12 |
| Inherits: | |
| Status: | Technology preview |
此类型处于技术预览阶段，可能会有变动。
属性
- aspects : list<string>
- cameraAspectRatioMode : enumeration
- compositingMode : enumeration
- entity : Entity
- hoverEnabled : bool
- multisample : bool
方法
- void setItemAreaAndDevicePixelRatio(size area, real devicePixelRatio)
详细说明
Scene3D 类型将由Entity 提供的 Qt3D 场景渲染到一个多采样帧缓冲区对象中。该对象随后会被复制到一个非多采样帧缓冲区对象中，然后以预乘透明度的方式进行渲染。 如果不需要多采样，可以通过将multisample 属性设置为false 来避免多采样。在这种情况下，Scene3D将直接渲染到非多采样的帧缓冲区对象中。
如果待渲染的场景包含非不透明材质，您可能需要通过自定义混合参数修改这些材质，以确保其正确渲染。例如，当使用PhongAlphaMaterial 且场景中存在不透明的清除颜色时，您可能需要为该材质添加：
sourceAlphaArg: BlendEquationArguments.Zero
destinationAlphaArg: BlendEquationArguments.One到该材质中。
不建议每个应用程序实例化多个 Scene3D 实例。原因是每个 Scene3D 实例都会在场景下实例化整个Qt 3D 引擎（例如，内存管理器、线程池、渲染器）。
注意：将 Scene3D 元素的可见性设置为 false 将停止Qt 3D 模拟循环。这意味着，若将 visible 属性绑定到依赖于Qt 3D 模拟循环（FrameAction）驱动的属性更新的表达式，该表达式将永远不会被重新评估。
属性文档
aspects : list<string>
应为该3D场景注册的方面列表。
例如，如果场景使用了 FrameAction，则应将"logic" 方面包含在列表中。
"render" 方面是硬编码的，无需显式列出。
cameraAspectRatioMode : enumeration
定义了如何计算场景中摄像机的宽高比。
| 常量 | 描述 |
|---|---|
Scene3D.AutomaticAspectRatio | 自动宽高比。 |
Scene3D.UserAspectRatio | 用户自定义宽高比。 |
compositingMode : enumeration
| 常数 | 描述 |
|---|---|
FBO | 场景将渲染到帧缓冲区对象中，这在某些平台和硬件上可能消耗较高资源，但能提供更大的灵活性。 自动宽高比。如果您的Scene3D 元素不应占据整个屏幕，并且您计划可选地对其进行缩放或动画处理，则应选择此合成模式。在此模式下，QML文件中Scene3D 的位置决定了其相对于其他Qt Quick 元素的堆叠顺序。 |
Underlay | 适用于全屏 3D 场景，在这些场景中使用 FBO 可能会消耗过多资源。Scene3D 的行为类似于QtQuick 的底层。请注意，使用此模式时，Scene3D 的大小及其变换将被忽略，渲染将占据整个屏幕。QML 文件中Scene3D 的位置也不会产生任何影响。Qt 3D 的内容将在任何Qt Quick 内容之前绘制。需注意避免因Qt Quick 内容重叠而覆盖并隐藏Qt 3D 的内容。此外，使用此模式时，窗口的`clearBeforeRendering`属性将自动设置为`false`。 |
默认值为FBO 。
entity : Entity [default]
要显示的 3D 场景的根实体。
hoverEnabled : bool
true 如果支持悬停事件的话。
multisample : bool
true 如果请求了多采样渲染缓冲区。
默认情况下，多采样功能处于启用状态。如果 OpenGL 实现不支持多采样渲染缓冲区或帧缓冲区复制，则使用多采样的请求将被忽略。
注意：请避免 频繁更改该值，因为这会涉及帧缓冲区及其他 OpenGL 资源的初始化操作，该过程开销较大且可能导致性能下降。
方法文档
void setItemAreaAndDevicePixelRatio(size area, real devicePixelRatio)
将项目区域设置为area ，并将像素比例设置为devicePixelRatio 。
© 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.
