Scene3D QML Type

Scene3D 类型用于将 Qt3D 场景集成到QtQuick 2 场景中。更多

Import Statement:	`import QtQuick.Scene3D 2.9`
Inherits:	Item
Status:	Preliminary

此类型正在开发中，可能会有更改。

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

属性

aspects : list<string>
cameraAspectRatioMode : enumeration
compositingMode : enumeration
entity : Entity
hoverEnabled : bool
multisample : bool

方法

void setItemAreaAndDevicePixelRatio(size area, real devicePixelRatio)

详细描述

Scene3D 类型可将Entity 提供的 Qt3D 场景渲染为多采样 Framebuffer 对象。随后，该对象会被混合到一个非多重采样的 Framebuffer 对象中，然后以预乘法 alpha 渲染该对象。如果不需要多重采样，可以通过将multisample 属性设置为false 来避免多重采样。在这种情况下，Scene3D 将直接渲染到非多重采样的 Framebuffer 对象中。

如果要渲染的场景包含非不透明材质，则可能需要使用自定义混合参数修改这些材质，以便正确渲染。例如，如果使用PhongAlphaMaterial 和具有不透明透明颜色的场景，您可能需要在该材质中添加

sourceAlphaArg: BlendEquationArguments.Zero
destinationAlphaArg: BlendEquationArguments.One

添加到该材质中。

不建议每个应用程序实例化一个以上的 Scene3D 实例。原因是一个 Scene3D 实例会实例化场景下的整个Qt 3D 引擎（例如内存管理器、线程池、渲染）。

注意： 将 Scene3D 元素的可见性设置为 false 将停止Qt 3D 模拟循环。这意味着，将可见属性绑定到依赖于由Qt 3D 模拟循环驱动的属性更新的表达式（FrameAction ）将永远不会重新评估。

属性文档

aspects : list<string>

三维场景应注册的方面列表。

例如，如果场景使用FrameAction ，则"logic" 方面应包含在列表中。

"render" 长宽比是硬连接的，无需明确列出。

cameraAspectRatioMode : enumeration

定义如何计算场景中摄像机的纵横比。

常量	说明
`Scene3D.AutomaticAspectRatio`	自动纵横比。
`Scene3D.UserAspectRatio`	用户定义的长宽比。

compositingMode : enumeration

常量说明

FBO 场景被渲染到帧缓冲对象中，这在某些平台和硬件上成本较高，但灵活性更大。自动纵横比。如果您的Scene3D 元素不应占据整个屏幕，而且您还计划调整其大小或使其动画化，则应选择这种合成模式。在这种模式下，Scene3D 在 QML 文件中的位置控制着它与其他Qt Quick 元素的堆叠顺序。

Underlay 适用于全屏三维场景，在这种场景中，使用 FBO 可能会占用过多资源。Scene3D 就像QtQuick 底层一样。请注意，使用该模式时，Scene3D 的大小及其变换将被忽略，渲染将占据整个屏幕。Scene3D 在 QML 文件中的位置也不会有任何影响。Qt 3D 内容将先于Qt Quick 内容绘制。必须注意不要过度绘制，以免重叠的Qt Quick 内容隐藏了Qt 3D 内容。此外，使用该模式时，窗口 clearBeforeRendering 将自动设置为 false。

常量	说明
`FBO`	场景被渲染到帧缓冲对象中，这在某些平台和硬件上成本较高，但灵活性更大。自动纵横比。如果您的Scene3D 元素不应占据整个屏幕，而且您还计划调整其大小或使其动画化，则应选择这种合成模式。在这种模式下，Scene3D 在 QML 文件中的位置控制着它与其他Qt Quick 元素的堆叠顺序。
`Underlay`	适用于全屏三维场景，在这种场景中，使用 FBO 可能会占用过多资源。Scene3D 就像QtQuick 底层一样。请注意，使用该模式时，Scene3D 的大小及其变换将被忽略，渲染将占据整个屏幕。Scene3D 在 QML 文件中的位置也不会有任何影响。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 。

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