SceneEnvironment QML Type

允许您配置场景的渲染方式。更多...

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

属性

• antialiasingMode : enumeration
• antialiasingQuality : enumeration
• aoBias : real
• aoDistance : real
• aoDither : bool
• aoEnabled : bool (since 6.5)
• aoSampleRate : int
• aoSoftness : real
• aoStrength : real
• backgroundMode : enumeration
• clearColor : color
• debugSettings : QtQuick3D::DebugSettings (since 6.5)
• depthPrePassEnabled : bool
• depthTestEnabled : bool
• effects : List<QtQuick3D::Effect>
• fog : QtQuick3D::Fog (since 6.5)
• lightProbe : QtQuick3D::Texture
• lightmapper : Lightmapper
• oitMethod : enumeration (since 6.11)
• probeExposure : real
• probeHorizon : real
• probeOrientation : vector3d
• scissorRect : rect (since 6.5)
• skyBoxCubeMap : QtQuick3D::CubeMapTexture (since 6.4)
• skyMaterial : QtQuick3D::SkyMaterial (since 6.12)
• skyboxBlurAmount : real (since 6.4)
• specularAAEnabled : bool (since 6.4)
• temporalAAEnabled : bool
• temporalAAMode : enumeration (since 6.11)
• temporalAAStrength : real
• tonemapMode : enumeration (since 6.0)

详细说明

SceneEnvironment 定义了一组全局属性，用于控制场景的渲染方式。

要使用 SceneEnvironment 或ExtendedSceneEnvironment ，请将View3D 的environment property 与这些类型的实例相关联。该对象可以内联声明，例如如下所示：

View3D {
    environment: SceneEnvironment {
        antialiasingMode: SceneEnvironment.MSAA
        tonemapMode: SceneEnvironment.TonemapModeFilmic
        backgroundMode: SceneEnvironment.SkyBox
        lightProbe: Texture {
            source: "panoramic_hdri_background.hdr"
        }
    }
}

此外，环境对象也可以单独定义。随后，一个或多个View3D 对象可以引用该环境对象。以下是一个示例代码片段，本次使用的是ExtendedSceneEnvironment ：

ExtendedSceneEnvironment {
    id: myEnv
    vignetteEnabled: true
}

View3D {
    width: parent.width / 2
    environment: myEnv
}

View3D {
    width: parent.width / 2
    x: parent.width / 2
    environment: myEnv
}

功能概述

• 抗锯齿设置。有关此主题的概述，请参阅《抗锯齿最佳实践》。相关属性包括antialiasingMode 、antialiasingQuality 、specularAAEnabled 、temporalAAEnabled 以及temporalAAStrength 。此外，若使用ExtendedSceneEnvironment ，还可通过fxaaEnabled 调用另一种方法。
• 屏幕空间环境光遮蔽。相关属性包括：aoEnabled 、aoStrength 、aoBias 、aoDistance 、aoDither 、aoSampleRate 、aoSoftness 。请注意，SSGI 也提供环境光遮蔽，尽管可能需要更高的性能开销，但通常能提供更高质量的结果。请避免同时启用 SceneEnvironment 的环境光遮蔽和ExtendedSceneEnvironment 的 SSGI。
• 背景色、天空盒、基于图像的照明（IBL）。有关 IBL 的更多信息，请参阅《使用基于图像的照明》。相关属性包括backgroundMode 、clearColor 、lightProbe 、probeExposure 、probeHorizon 、probeOrientation 、skyboxBlurAmount 以及skyBoxCubeMap 。
• 色调映射。tonemapMode 用于配置色调映射方法，该方法在图形处理管道末端将高动态范围的颜色值转换为 0-1 范围。ExtendedSceneEnvironment 提供了若干额外属性，例如whitePoint 和sharpnessAmount ，可用于调整色调映射的计算。
• 深度缓冲区设置。相关属性包括depthPrePassEnabled 和depthTestEnabled 。
• 后处理效果。除了ExtendedSceneEnvironment 提供的内置后处理效果外，应用程序还可以通过Effect 类型提供自定义效果。effects 属性是一个Effect 实例的列表。
• 调试可视化设置，例如线框模式或仅渲染材质的特定颜色分量。这些设置由通过debugSettings 属性引用的DebugSettings 对象控制。当将DebugView 项添加到场景中时，其中大部分设置也可通过交互方式进行控制。
• 雾效设置。要启用雾效，请在fog 属性中设置一个配置适当的Fog 对象。
• 光照贴图烘焙设置。当场景中的某些模型使用预烘焙光照贴图时，在lightmapper 属性中设置的Lightmapper 对象将定义烘焙过程中使用的设置。
• 剪刀设置。若要应用与视口不同的剪刀，请设置scissorRect 属性。

另请参阅 ExtendedSceneEnvironment 。

属性文档

antialiasingMode : enumeration

此属性控制渲染场景时应用的抗锯齿模式。

可能的取值包括：

默认值为SceneEnvironment.NoAA 。

超采样

场景以较高的分辨率进行渲染，然后缩放至实际分辨率。

优点：质量高。对所有场景内容（而不仅仅是几何轮廓）进行抗锯齿处理。

缺点：通常比 MSAA 更耗资源。会增加视频内存的使用量。 支持View3D 项目中的所有 renderMode（除 Inline 之外），但由于该技术需要先渲染到纹理上，因此在 renderMode 为 Underlay 或 Overlay 时启用 SSAA 会导致使用通常不需要的中间纹理和渲染通道，这意味着性能开销可能会更加明显。 建议仅在 renderMode 为默认的 Offscreen 时使用 SSAA。

多采样

对几何体的边缘进行超采样，从而获得更平滑的轮廓。不过，该技术对几何体内部的材质没有影响。

优点：适用于任何View3D 对象，无论其renderMode如何。在几何体轮廓上效果良好（该处锯齿现象通常最为明显）；可无缝支持高速动画。性能完全取决于系统（GPU）的性能。

缺点：无法解决纹理或反射问题。会增加视频内存占用。在性能较弱的图形硬件上使用可能消耗较高资源。可根据renderMode设置，按窗口或针对单个View3D 项进行控制。当使用“底层/叠加”（Underlay/Overlay）并应用效果，或使用“离屏”（Offscreen）模式时，可针对每个View3D 项单独控制MSAA。 另一方面，若在不应用任何特效的情况下使用“底层/叠加”（Underlay/Overlay）或“内联”（Inline）模式，则 MSAA 将按窗口进行控制。

渐进式抗锯齿

此属性用于启用并设置应用于场景的渐进式抗锯齿级别。

当场景中的所有内容停止移动时，相机的位置会在帧与帧之间发生微小抖动，并且每帧的新结果都会与前几帧进行混合。累积的帧数越多，最终效果就越佳。

优点：当场景中的所有内容静止时，能提供极佳的效果。

缺点：若存在任何视觉变化，则无法生效。由于需要累积和混合，计算成本较高。会增加视频内存占用。

有关抗锯齿方法的进一步讨论，请参阅《抗锯齿最佳实践》。

antialiasingQuality : enumeration

此属性用于设置应用于场景的抗锯齿级别。其行为取决于所使用的antialiasingMode 。当antialiasingMode 属性设置为NoAA 时，此属性将不起作用。

可能的取值为：

默认值为SceneEnvironment.High

aoBias : real

此属性定义了一个截止距离，用于防止物体在近距离时显示环境光遮蔽效果。数值越高，物体之间需要保持的距离就越大，环境光遮蔽效果才会显现。

默认值为 0.0。

aoDistance : real

此属性大致定义了环境光遮蔽阴影从物体向外扩散的距离。距离越远，对性能的影响就越大。

默认值为 5.0。

下图展示了默认的aoSoftness 和最大值aoStrength 的效果：

另请参阅 aoStrength 和aoSoftness 。

aoDither : bool

启用此属性后，它会将环境光遮蔽阴影带的边缘进行分散处理，以提高平滑度（但有时可能会产生明显的条纹状伪影）。

默认值为false 。

另请参阅“ PerspectiveCamera.clipFar ”和“OrthographicCamera.clipFar ”。

aoEnabled : bool [since 6.5]

启用或禁用环境光遮蔽。

默认值为false ，这意味着环境光遮蔽已被禁用。

该属性在 Qt 6.5 中引入。

另请参阅 aoStrength 和aoDistance 。

aoSampleRate : int

此属性定义了环境光遮蔽的质量（更多灰色调），但会牺牲性能。

该值必须为 2、3 或 4。默认值为 2。

aoSoftness : real

此属性用于定义环境光遮蔽着色的边缘有多平滑。

该值必须在 0.0 到 50.0 之间。默认值为 50.0。

下图展示了默认值aoDistance 和最大值aoStrength 的效果：

另请参阅 aoStrength 和aoDistance 。

aoStrength : real

此属性定义了环境光遮蔽的强度。环境光遮蔽是一种近似全局照明的技术，当物体彼此靠近时，会产生非定向的自阴影。 数值设为 100 时会产生完全黑暗的阴影；数值越低，阴影看起来越浅。数值设为 0 时将完全禁用环境光遮蔽，虽然这会提高性能，但会牺牲场景中渲染的 3D 物体的视觉真实感。

除 0 以外的所有值对性能的影响相同。

默认值为 0.0，最大值为 100.0。

值为 0 相当于将“环境光遮蔽”（aoEnabled ）设置为 false。

下图展示了默认的aoSoftness 和aoDistance 设置：

另请参阅 aoEnabled 、aoDistance 和aoSoftness 。

backgroundMode : enumeration

此属性控制是否以及如何清除场景的背景。

默认值为SceneEnvironment.Transparent

请看以下示例。Suzanne 模型应已通过balsam 工具预处理，并来自glTF 样本模型存储库。

import QtQuick
import QtQuick3D
import QtQuick3D.Helpers

Item {
    width: 1280
    height: 720

    View3D {
        id: v3d
        anchors.fill: parent

        environment: ExtendedSceneEnvironment {
            backgroundMode: SceneEnvironment.SkyBox
            lightProbe: Texture { source: "00455_OpenfootageNET_field_low.hdr" }

            glowEnabled: true
            glowStrength: 1.25
            glowBloom: 0.25
            glowBlendMode: ExtendedSceneEnvironment.GlowBlendMode.Additive
        }

        DirectionalLight {
        }

        Suzanne {
            scale: Qt.vector3d(50, 50, 50)
            z: -500
        }

        PerspectiveCamera {
            id: camera
        }

        WasdController {
            controlledObject: camera
        }
    }
}

在DirectionalLight 的基础上使用基于图像的照明，并将光探针纹理用作天空盒，结果如下：

如果没有光探针会怎样？

backgroundMode: SceneEnvironment.Transparent

在此情况下，背景并非由View3D 提供，而是由托管2D和3D场景的QQuickWindow 或QQuickView 提供。照明仅基于DirectionalLight 。

使用固定的清除颜色：

backgroundMode: SceneEnvironment.Color
clearColor: "green"

另请参阅 lightProbe 、QQuickWindow::setColor()、Window::color 以及View3D 。

clearColor : color

该属性用于定义在使用SceneEnvironment.Color 设置backgroundMode 属性时，清除视口所使用的颜色。

默认值为Qt::black

另请参阅 backgroundMode 。

debugSettings : QtQuick3D::DebugSettings [since 6.5]

该属性指定了一个DebugSettings 对象，用于配置渲染器的调试工具。在构造过程中，SceneEnvironment 会自动创建一个与其关联的DebugSettings 对象，因此通常无需设置自定义的DebugSettings 。

以下是一个启用线框模式渲染场景的示例：

可视化网格的法线向量：

可视化镜面反射光照贡献：

该属性在 Qt 6.5 中引入。

另请参阅 DebugSettings 。

depthPrePassEnabled : bool

启用此功能后，渲染器会对不透明对象执行 Z 预渲染，即使用简单的着色器并禁用颜色写入来渲染这些对象，以便在发出主渲染阶段的绘制调用之前预先填充深度缓冲区。

根据场景内容的不同，此操作可提升性能。通常，包含大量重叠对象且片段着色开销较大的场景能从中获益。同时值得注意的是，渲染器会对不透明对象执行由前至后的排序，这本身有助于减少不必要的片段着色，因此 Z 预处理并不总能带来显著的性能提升。

在采用瓦片式渲染架构的 GPU 上（这在移动和嵌入式系统中很常见），建议将此参数设置为 `false`。

默认值为false 。

depthTestEnabled : bool

默认值为true 。默认情况下，渲染器会将场景中的对象分类为opaque 或semi-transparent 。opaque 列表中的对象（带有相关材质的子网格）将首先被渲染，此时启用了深度测试和深度写入，从而为没有半透明区域的典型3D对象提供最佳的Z裁剪效果。semi-transparent 列表中的对象在渲染时会禁用深度写入，但仍启用深度测试（用于与不透明对象进行深度比较），并按从后到前的顺序渲染（根据其中心点到摄像机的距离进行排序）。 这使得对于表面包含半透明区域的 3D 对象（无论是由于“node opacity ”还是材质中的某些颜色或纹理贴图所致）能够实现正确的混合（“透视”）。

当此属性设置为“false ”时，不会写入 Z 缓冲区并进行深度测试，深度测试将被跳过，所有对象（包括完全不透明的对象）都将按从后到前的顺序一次性渲染。

通常很少需要将此属性设置为“false ”。在已知两轮渲染方法收益甚微的场景中，此设置可能很有用——例如，不透明物体非常少，或者这些物体经过变换后，单次从后到前排序的渲染效果更好。

effects : List<QtQuick3D::Effect>

此属性包含一组将应用于整个视口的后处理效果。每个效果的结果都会传递给下一个效果，因此顺序至关重要。

fog : QtQuick3D::Fog [since 6.5]

当此属性被设置为一个有效的Fog 对象时，它将用于配置渲染器的内置雾效支持。

默认值为 null，表示不启用雾效。这相当于设置一个enabled 属性值为 false 的 Fog 对象。

该属性在 Qt 6.5 中引入。

另请参阅 Fog 。

lightProbe : QtQuick3D::Texture

此属性定义了一张用于为场景提供照明的图像，该图像既可以替代标准光源，也可以作为标准光源的补充。

该图像最好是高动态范围图像（HDR）或预生成的立方贴图。预烘焙可在运行时显著提升性能，因为无需花费时间进行滤波和米普图生成。 如果源文件是 .hdr 或其他图像，则基于 GPU 的预处理将在加载图像文件后的运行时进行，这可能会非常耗时，特别是在嵌入式和移动硬件上。因此，强烈建议应用程序最迟在构建时预处理 .hdr 图像，具体方法如本文所述。

有关基于图像的照明的更多信息，请参阅《使用基于图像的照明》。

下面的示例是在以下场景的环境中，通过调整backgroundMode 生成的。该场景中没有方向光（DirectionLight）、PointLight 或SpotLight 。所有照明均基于全景HDRI图像。

import QtQuick
import QtQuick3D
import QtQuick3D.Helpers

Item {
    width: 1280
    height: 720

    View3D {
        id: v3d
        anchors.fill: parent

        environment: ExtendedSceneEnvironment {
            backgroundMode: SceneEnvironment.SkyBox
            lightProbe: Texture { source: "00455_OpenfootageNET_field_low.hdr" }

            tonemapMode: SceneEnvironment.TonemapModeFilmic
            sharpnessAmount: 0.4

            glowEnabled: true
            glowStrength: 1.25
            glowBloom: 0.25
            glowBlendMode: ExtendedSceneEnvironment.GlowBlendMode.Additive
        }

        Node {
            scale: Qt.vector3d(100, 100, 100)

            Sponza {
            }

            Suzanne {
                y: 1
                scale: Qt.vector3d(0.5, 0.5, 0.5)
                eulerRotation.y: -90
            }
        }

        PerspectiveCamera {
            id: camera
            y: 100
        }

        WasdController {
            controlledObject: camera
        }
    }
}

在上述环境下的渲染结果：

将backgroundMode 切换为SceneEnvironment.Transparent 后，结果如下：

此时，3D 场景的照明效果与之前相同，这意味着材质在照明计算中仍像之前一样使用光探针，但未渲染天空盒。背景呈白色，因为这是承载 2D 和 3D 场景的QQuickWindow 的默认清除颜色。

将 lightProbe 属性值重置为默认的 null 是有效的。这将解除之前关联的纹理。例如，让我们使用 Delete 键在带天空盒的基于图像的照明与不带基于图像的照明（背景采用固定清除颜色）之间动态切换：

environment: ExtendedSceneEnvironment {
    id: env

    backgroundMode: SceneEnvironment.SkyBox
    lightProbe: iblTex

    tonemapMode: SceneEnvironment.TonemapModeFilmic
    sharpnessAmount: 0.4

    glowEnabled: true
    glowStrength: 1.25
    glowBloom: 0.25
    glowBlendMode: ExtendedSceneEnvironment.GlowBlendMode.Additive
}

Texture {
    id: iblTex
    source: "00455_OpenfootageNET_field_low.hdr"
}

focus: true
Keys.onDeletePressed: {
    if (env.backgroundMode == SceneEnvironment.SkyBox) {
        env.backgroundMode = SceneEnvironment.Color;
        env.clearColor = "green";
        env.lightProbe = null;
    } else {
        env.backgroundMode = SceneEnvironment.SkyBox;
        env.lightProbe = iblTex;
    }
}

按下 Delete 键会得到以下结果。请注意，此处使用的场景中没有光源，因此所有 3D 模型都呈现为纯黑色。

虽然 lightProbe 通常与从图像文件（通常为 .hdr 或 .ktx）获取数据的 Texture 实例结合使用，但将其关联到使用内存中procedurally generated image data 的 Texture 也是合理的。 一个典型的例子是，图像数据由QtQuick3D.Helpers模块中的ProceduralSkyTextureData 生成的纹理：

backgroundMode: SceneEnvironment.SkyBox
lightProbe: Texture {
    textureData: ProceduralSkyTextureData {
    }
}

这为我们提供了一个程序生成的HDR天空盒纹理，该纹理现既用作天空盒，也用于基于图像的照明：

另请参阅 backgroundMode 、使用基于图像的照明、预生成 IBL 立方贴图、probeExposure 、probeHorizon 、probeOrientation 以及ProceduralSkyTextureData 。

lightmapper : Lightmapper

当此属性设置为一个有效的 Lightmapper 对象时，在烘焙光照贴图时会考虑该对象指定的设置。

默认值为 null，这意味着所有与烘焙相关的设置都将使用默认值。

有关如何烘焙光照贴图的更多信息，请参阅《Lightmapper 》文档。

当光照贴图与应用程序无关且从未生成烘焙光照时，该属性及其关联对象实际上没有任何作用。

另请参阅 Model::usedInBakedLighting 、Model::bakedLightmap 、Light::bakeMode 以及Lightmapper 。

oitMethod : enumeration [since 6.11]

此属性用于指定“顺序无关透明度（OIT）”方法。将此属性设置为有效的 OIT 方法后，渲染器将按照正确的深度顺序渲染透明像素。

可能的取值包括：

默认值为None ，且顺序无关透明度被关闭。

加权混合

这是对顺序无关透明度的近似实现。透明的片段会被渲染到一个离屏缓冲区中，同时根据每个片段到摄像机的距离对其应用权重。 随后，在对每个像素进行去权重处理后，该缓冲区与后缓冲区进行混合。该方法并非对所有片段都遵循“源上叠加”合成规则，且结果与正确结果有所不同，但该方法在较旧的硬件上也能运行，并且比其他更严格的方法速度更快。

链表

这是一种精确的顺序无关透明度实现。在渲染阶段，透明片段被渲染到一个链表中，并按其深度排序；在合成阶段进行混合。

此属性在 Qt 6.11 中引入。

probeExposure : real

此属性用于调整光探针发出的光量。色调映射的一部分是曝光映射，该属性可调节光探针中的光值如何进行色调映射。

默认情况下，曝光值设置为 1.0

另请参阅“ lightProbe ”、“probeHorizon ”和“probeOrientation ”。

probeHorizon : real

当该属性被定义为递增值时，会使环境的下半部分变暗（变黑），从而迫使光线主要来自图像的上半部分（并去除下半部分的特定反射）。该属性对于处理地面平面非常有用，因为地面平面会遮挡光探针在地面上的反射。 这是必要的，因为光探针的贡献直接来自图像，而不考虑场景中的内容。

probeHorizon 属性的预期值范围为 0.0 到 1.0。超出此范围的任何值都将被限制在预期范围内。

默认情况下，`probeHorizon` 设置为 0.0，这意味着将使用整个光探针，无需调整。

另请参阅 lightProbe 、probeExposure 和probeOrientation 。

probeOrientation : vector3d

该属性用于定义光探针的方向。方向通过欧拉角（以度为单位）沿 x、y 和 z 轴来定义。

另请参阅 lightProbe 、probeHorizon 和probeExposure 。

scissorRect : rect [since 6.5]

该属性在视图坐标系中定义了一个剪刀矩形，其左上角位于 [0, 0]

该属性于 Qt 6.5 中引入。

skyBoxCubeMap : QtQuick3D::CubeMapTexture [since 6.4]

当背景模式为SkyBoxCubeMap 时，此属性定义了一个用作天空盒的立方体贴图。

该属性自 Qt 6.4 起引入。

skyMaterial : QtQuick3D::SkyMaterial [since 6.12]

该属性定义了一个基于程序生成、由 GPU 驱动的天空模型，用于 IBL 以及作为场景的背景。

该属性于 Qt 6.12 版本中引入。

另请参阅 backgroundMode 和lightProbe 。

skyboxBlurAmount : real [since 6.4]

该属性用于确定在使用SceneEnvironment.SkyBox 作为backgroundMode 属性值时，天空盒应被模糊的程度。默认值为0.0 ，这意味着不会进行模糊处理。

有效值范围为 0.0 到 1.0，所有其他值都将被限制在此范围内。

该属性在 Qt 6.4 中引入。

specularAAEnabled : bool [since 6.4]

启用此属性后，将减轻镜面反射锯齿现象。镜面反射锯齿通常表现为明亮的点，当移动摄像机时，这些点可能会闪烁。

默认值为false。

该属性自 Qt 6.4 起引入。

temporalAAEnabled : bool [default: false]

启用此属性后，将使用时间抗锯齿。

相机在相邻帧之间会发生极轻微的抖动，每帧的新画面都会与上一帧进行混合。

优点：由于摄像机的抖动，它能捕捉到原本会丢失的真实细节；对性能影响较小。

缺点：快速移动的物体会导致单帧重影。

temporalAAMode : enumeration [since 6.11]

控制时间抗锯齿模式。时间抗锯齿通过融合多个帧的信息，从而减少闪烁和锯齿现象。

默认值为SceneEnvironment.TAADefault 。

该属性在 Qt 6.11 中引入。

temporalAAStrength : real [default: 0.3]

此属性用于调整时间移动的幅度（抗锯齿）。仅当temporalAAEnabled 属性为true时，此属性才会生效。

另请参阅 temporalAAEnabled 。

tonemapMode : enumeration [since 6.0]

该属性定义了在渲染前如何对颜色进行色调映射。Qt Quick 3D 中的所有渲染都在线性颜色空间中进行，这在许多情况下会导致生成无法显示的颜色值。tonemapMode 属性决定了用于将颜色重新映射到可显示范围的技术。

默认值为SceneEnvironment.TonemapModeLinear

有关这些不同模式的示例，请参见ExtendedSceneEnvironment 。

该属性在 Qt 6.0 中引入。