变更内容Qt Quick 3D

Qt 6 的变更源于我们有意识地致力于提升框架的效率并使其更易于使用。

我们力求在每个版本中保持所有公共 API 的二进制和源代码兼容性。但为了使 Qt 成为更好的框架，某些变更在所难免。Qt Quick 3D API 的部分内容已进行了重大修改。

在本主题中，我们将总结Qt Quick 3D 中的这些变更，并提供相应的处理指南。

RHI

从 Qt 6.0 开始，Qt Quick 的默认实现始终通过图形抽象层——即由QtGui 模块提供的 Qt 渲染硬件接口（RHI）——进行渲染。这意味着，与 Qt 5 不同，场景图不再直接调用 OpenGL。 相反，它通过使用 RHI API 记录资源和绘制命令，随后由 RHI 将命令流转换为 OpenGL、Vulkan、Metal 或 Direct 3D 调用。着色器的处理也得到了统一：只需编写一次着色器代码，编译为SPIR-V，然后转换为适用于各种图形 API 的语言。

对于Qt Quick 3D 而言，Qt 6.0的最大变化是迁移至通用渲染硬件接口（RHI），这使得Qt Quick 3D 除了支持OpenGL和OpenGL ES外，还能在Direct3D、Metal和Vulkan上运行。

Qt Quick Qt Quick 3D 现已在这一方面实现完全统一。例如，任何与 RHI 相关的配置设置（如选择哪种图形 API 进行渲染）均适用于这两者。

更多详细信息请参阅《Qt Quick 3D 图形要求》。

其他 API 变更

QML 导入版本

从 Qt 6.0 开始，Qml 导入语句的版本号与 Qt 版本号相同。现在还可以不指定版本直接导入模块：这将导入该模块的最新版本。

照明

Light brightness 现在表示一个能量乘数，默认值为 1.0；而在 Qt 5 中，该参数使用百分比值，默认值为 100。实际上，这意味着所有brightness 值都应除以 100。

SceneEnvironment.probeBrightness 已重命名为probeExposure ，并被重新定义为默认值为 1.0 的倍数。也就是说，所有probeBrightness 值都应重命名为probeExposure 并除以 100。

AreaLight 出于性能考虑，该函数已被移除。在许多情况下，可以用SpotLight 代替，该函数是在Qt Quick 3D 5.15 中添加的。

自定义材质

自定义材质 API 在 6.0 版本中已彻底重构。这意味着任何现有的自定义材质都将需要进行大幅重写。有关新 API 的详细信息，请参阅CustomMaterial 文档。

后处理效果

Effect 已得到增强，现支持与CustomMaterial 极为接近的着色器代码，在结构和内置关键字方面遵循相同的模式。这意味着，涉及自定义着色器代码的现有效果在 Qt 6.0 中运行前需要进行迁移。详情请参阅Effect 文档。

Principled 材质

在Qt Quick 6.0 中，PrincipledMaterial QML 类型已得到大幅改进，现在更紧密地遵循基于物理的渲染（PBR）原则。导入的模型现在应能正确渲染，而无需更改材质的属性。现有材质需要进行调整，以消除此前因不准确性而进行的任何补偿。

部分属性的默认值已发生变化：

• metalness 默认值改为 0，而非 1。
• specularAmount 默认值为 0.5 而非 0.

默认材质

某些属性的默认值发生了变化：

• specularRoughness 默认值为 0，而非 50。

预定义材质

QtQuick3D 6.0 中未包含任何预定义材质。未来版本中添加的材质很可能与旧版本不兼容。“Materials”导入已不存在。（CustomMaterial 类型已移至基础的QtQuick3D 导入中。）

以下是在 Qt 6.0 中已移除的材质 Qt Qml 类型：

• AluminumAnodizedEmissiveMaterial
• AluminumAnodizedMaterial
• AluminumBrushedMaterial
• AluminumEmissiveMaterial
• AluminumMaterial
• 铜材质
• 磨砂玻璃材质
• 磨砂玻璃单次渲染材质
• 玻璃材料
• 玻璃折射材料
• 艺术纸材质
• 纸张办公材料
• 带纹理的红色发光塑料材料
• 塑料结构化红色材料
• 钢 铣削同心材质

镶嵌与位移贴图

由于更加侧重于支持嵌入式硬件，模型镶嵌模式已被移除。此外，作为相应调整，材质中的位移贴图支持也已移除。可以通过使用custom material 来实现类似的效果。

Qt Quick Item作为3D 的子项Node

虽然语法上完全相同，但内部处理 2D 子项的方式却大不相同。在 Qt 6.0 中，不再存在隐式的“渲染到纹理”步骤。 相反，2DQt Quick 的内容会在同一渲染通道中，采用适当的透视投影进行内联渲染，这不仅能提升性能、降低资源消耗，在某些情况下（例如使用Text 时）甚至可能提高视觉保真度。概述请参阅Qt Quick 3D 中的“包含 2D 内容的场景”。

如果出于某种原因（如裁剪、不透明度）需要穿透纹理，请通过设置layer.enabled: true ，将 2DItem 子树显式设为图层。这样，其行为将更接近 Qt 5.15 提供的效果。

2D 内容不再以父节点的原点为中心。相反，是顶级 2D Item 的左上角被放置在 3D 节点的原点上。 因此，顶级 2D Item 通常需要指定一个锚点（例如anchors.centerIn: parent ），以获得与 Qt 5.15 一致的效果。