ExtendedSceneEnvironment QML Type

SceneEnvironment 提供常用的渲染效果。更多

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

属性

• adjustmentBrightness : real
• adjustmentContrast : real
• adjustmentSaturation : real
• colorAdjustmentsEnabled : bool
• depthOfFieldBlurAmount : real
• depthOfFieldEnabled : bool
• depthOfFieldFocusDistance : real
• depthOfFieldFocusRange : real
• ditheringEnabled : bool
• exposure : real
• fxaaEnabled : bool
• glowBlendMode : int
• glowBloom : real
• glowEnabled : bool
• glowHDRMaximumValue : real
• glowHDRMinimumValue : real
• glowHDRScale : real
• glowIntensity : real
• glowLevel : int
• glowQualityHigh : bool
• glowStrength : real
• glowUseBicubicUpscale : bool
• lensFlareApplyDirtTexture : bool
• lensFlareApplyStarburstTexture : bool
• lensFlareBloomBias : real
• lensFlareBloomScale : real
• lensFlareBlurAmount : real
• lensFlareCameraDirection : vector3d
• lensFlareDistortion : real
• lensFlareEnabled : bool
• lensFlareGhostCount : int
• lensFlareGhostDispersal : real
• lensFlareHaloWidth : real
• lensFlareLensColorTexture : Texture
• lensFlareLensDirtTexture : Texture
• lensFlareLensStarburstTexture : Texture
• lensFlareStretchToAspect : real
• lutEnabled : bool
• lutFilterAlpha : real
• lutSize : real
• lutTexture : Texture
• sharpnessAmount : real
• ssgiBufferSizeFactor : real (since 6.11)
• ssgiEnabled : bool (since 6.11)
• ssgiHitThickness : real (since 6.11)
• ssgiIndirectLightBoost : real (since 6.11)
• ssgiIndirectLightEnabled : bool (since 6.11)
• ssgiSampleCount : int (since 6.11)
• ssgiSampleRadius : real (since 6.11)
• ssgiSimulatedBounceEnabled : bool (since 6.11)
• ssgiSimulatedBounceFactor : real (since 6.11)
• ssgiSliceCount : int (since 6.11)
• ssrEnabled : bool (since 6.11)
• tonemapMode : enumeration
• vignetteColor : color
• vignetteEnabled : bool
• vignetteRadius : real
• vignetteStrength : real
• whitePoint : real

详细说明

ExtendedSceneEnvironment 是QtQuick3D 的SceneEnvironment 类型的扩展，内置一系列常用特效。这些特效通过一组以特效名称为前缀的属性显示出来。

启用一个或多个特效时，效果类似于在SceneEnvironment 的effects 列表中手动添加后期处理特效。然而，ExtendedSceneEnvironment 提供的特效是独立形式所不具备的，更重要的是，它能有效地组合已启用的特效，从而减少所需的额外渲染通道数量，这与在场景中应用单独的后期处理特效相比，能大大提高性能。ExtendedSceneEnvironment 还能很好地使用色调映射，即使是更复杂的多通道特效，以及启用多个特效并将其组合在一起时也是如此。而独立特效并非总是如此。

SceneEnvironment 的某些功能（如色调映射）可通过 ExtendedSceneEnvironment 中的附加属性继承和扩展。例如，SceneEnvironment 提供了tonemapMode 属性，而 ExtendedSceneEnvironment 则增加了对色调映射的曝光、白点、锐化和抖动设置的控制。不过，由于 ExtendedSceneEnvironment 继承了SceneEnvironment 中的所有内容，所以tonemapMode 属性不会重复，因此无论哪种环境类型与View3D 关联，色调映射模式的基本设置都是可用的，但附加属性只有在使用 ExtendedSceneEnvironment 时才可用。其他效果，如屏幕空间环境遮蔽（SSAO）或雾完全属于SceneEnvironment 的一部分，两种类型的环境均可使用。

开始使用扩展场景环境

要使用 ExtendedSceneEnvironment 提供的附加功能，请将View3D 与它的实例关联起来。不要忘记导入QtQuick3D.Helpers 模块。

import QtQuick3D
import QtQuick3D.Helpers

View3D {
    environment: ExtendedSceneEnvironment {
        tonemapMode: SceneEnvironment.Filmic
        vignetteEnabled: true
        // ...
    }
}

可用特效

以下是 ExtendedSceneEnvironment 提供的效果和相关功能概览，包括从SceneEnvironment 继承的功能。

• Tonemapping - 控制色彩在显示前如何从高清范围调制到 0-1 范围。ExtendedSceneEnvironment 增加了对曝光、白点、锐化和抖动的控制。

  由属性tonemapMode,exposure,whitePoint,ditheringEnabled 控制。

  

• Color adjustments - 亮度、对比度和饱和度调整。

  由属性colorAdjustmentsEnabled,adjustmentBrightness,adjustmentContrast,adjustmentSaturation 控制。

  

• Color grading 通过查找表 (LUT) 纹理。

  由属性lutEnabled,lutSize,lutFilterAlpha 控制。

  

• Depth of field

  由属性depthOfFieldEnabled,depthOfFieldFocusDistance,depthOfFieldFocusRange,depthOfFieldBlurAmount 控制。

  

• Glow and bloom

  受属性控制glowEnabled,glowQualityHigh,glowUseBicubicUpscale,glowStrength,glowIntensity,glowBloom,glowBlendMode,glowHDRMaximumValue,glowHDRMinimumValue,glowHDRScale 。

  

• Vignette

  受属性控制vignetteEnabled,vignetteStrength,vignetteColor,vignetteRadius 。

  

• Lens flare

  受属性控制lensFlareEnabled,lensFlareBloomBias,lensFlareGhostDispersal,lensFlareGhostCount,lensFlareHaloWidth,lensFlareStretchToAspect,lensFlareDistortion,lensFlareBlurAmount,lensFlareApplyDirtTexture,lensFlareApplyStarburstTexture,lensFlareCameraDirection,lensFlareLensColorTexture,lensFlareLensDirtTexture,lensFlareLensStarburstTexture 。

  

• Screen space ambient occlusion - 由SceneEnvironment 提供。请注意，SSGI 也提供环境闭塞功能，而且在实践中通常会提供质量更好的结果。请避免同时启用SceneEnvironment 的环境遮蔽和 ExtendedSceneEnvironment 的屏幕空间全局光照，因为同时执行这两种功能既不必要又浪费。由SceneEnvironment::aoEnabled,SceneEnvironment::aoStrength,SceneEnvironment::aoDistance,SceneEnvironment::aoSoftness,SceneEnvironment::aoDither,SceneEnvironment::aoSampleRate,SceneEnvironment::aoBias 控制。

  

• Fog - 由SceneEnvironment 提供。这不是后处理类型的效果，而是应用于场景中可渲染对象的材质。

  由与SceneEnvironment::fog 属性关联的Fog 对象控制。

  

• Antialiasing - 多采样、超采样、逐行抗锯齿、镜面抗锯齿和时间抗锯齿由SceneEnvironment 提供。ExtendedSceneEnvironment 增加了使用a form of FXAA 的选项。

  FXAA 由fxaaEnabled 控制。其他抗锯齿模式由SceneEnvironment::antialiasingMode,SceneEnvironment::temporalAAEnabled,SceneEnvironment::temporalAAStrength 和SceneEnvironment::specularAAEnabled 控制。

  

• Screen-space global illumination 提供环境遮蔽和间接照明。请注意，启用该效果可能会对 GPU 负载和性能产生较大影响。由属性ssgiEnabled,ssgiIndirectLightEnabled,ssgiIndirectLightBoost,ssgiBufferSizeFactor,ssgiSimulatedBounceEnabled,ssgiSimulatedBounceFactor,ssgiSampleCount,ssgiSampleRadius,ssgiSliceCount 控制、ssgiHitThickness

  

另请参阅 SceneEnvironment 和Qt Quick 3D - 场景效果示例。

属性文档

adjustmentBrightness : real [default: 1]

调整场景亮度。

adjustmentContrast : real [default: 1]

调整场景的对比度。

adjustmentSaturation : real [default: 1]

调整场景的饱和度。

colorAdjustmentsEnabled : bool [default: false]

启用颜色调整。

另请参阅 colorAdjustmentsEnabled。

depthOfFieldBlurAmount : real [default: 4.0]

设置对焦范围外物体的模糊程度。合理值范围为0至10。值为 0 时，不应用额外的模糊。

depthOfFieldEnabled : bool [default: false]

启用景深模糊效果。

depthOfFieldFocusDistance : real [default: 600]

设置对焦物体与摄像机的距离。

在这里，Sponza场景应用了100 的缩放比例，以便有一个合适的大范围来对视图的背面和正面进行模糊处理。下图的对焦距离为 753，对焦范围为 482。

depthOfFieldFocusRange : real [default: 100]

depthOfFieldFocusDistance 项目完全对焦的周围距离。然后，在远近两侧相同的距离内，焦点逐渐消失到完全模糊。

ditheringEnabled : bool [default: false]

启用抖动以减少带状伪影。

exposure : real [default: 1.0]

色调映射使用的曝光级别。

fxaaEnabled : bool [default: false]

启用快速近似抗锯齿 (FXAA)。

glowBlendMode : int [default: ExtendedSceneEnvironment.GlowBlendMode.SoftLight]

辉光效果的混合模式。

可用的模式有

• ExtendedSceneEnvironment.GlowBlendMode.Additive 混合模式
• ExtendedSceneEnvironment.GlowBlendMode.屏幕
• ExtendedSceneEnvironment.GlowBlendMode.柔光
• ExtendedSceneEnvironment.GlowBlendMode.Replace

Additive 通常推荐用于可见天空或太阳的室外场景，而默认的SoftLight 可能更适合室内环境。

Replace 而默认的 则更适合室内环境。实际上，在设置辉光/彩虹效果参数时，这对实验和故障排除很有用。

glowBloom : real [default: 0]

设置应用于发光效果的绽放量。预期值为0至1。

glowHDRMinimumValue,glowHDRMaximumValue,glowHDRScale, 和 glowBloom 的值共同控制着由辉光/绽放效果产生的luminance feedback 量。

在实际操作中，glowStrength 、glowIntensity 和 glowBloom 的值通常会一起调整，以达到所需的效果。

例如，在启用了四个发光级别、强度为 1.5 和强度为 1 的情况下，将

glowEnabled : bool [default: false]

启用发光效果。当glowBloom 的值大于 0 时，它还可以提供发光效果。

glowHDRMaximumValue : real [default: 12.0]

在高动态范围内设置辉光的最大亮度。数值范围为0至256。

glowHDRMinimumValue 、glowHDRMaximumValue、glowHDRScale 和glowBloom 的值共同控制着发光/绽放效果产生的luminance feedback 量。

glowHDRMinimumValue : real [default: 1.0]

在高动态范围内设置辉光的最小亮度。预期值范围为0至4。

glowHDRMinimumValue、glowHDRMaximumValue 、glowHDRScale 和glowBloom 值可共同控制由辉光/绽放效果产生的luminance feedback 量。

glowHDRScale : real [default: 2.0]

HDR 辉光的出血比例。预期值范围为0至8。

glowHDRMinimumValue 、glowHDRMaximumValue 、glowHDRScale 和glowBloom 的值共同控制着由辉光/发光效果产生的luminance feedback 量。

glowIntensity : real [default: 1]

辉光强度。预期值范围为0至8。

强度实际上是累积辉光颜色（包括所有级别）的比例因子（乘数）。

在实际操作中，glowStrength 、glowIntensity 和glowBloom 的值通常会一起调整，以达到预期效果。

例如，glowStrength 为 1.0，glowBloom 为 0.25：

glowLevel : int [default: 1]

设置哪种模糊效果会应用于发光效果。共有 7 个级别可供选择。

不设置任何级别意味着辉光效果没有视觉效果。

例如，要启用第一级和第六级辉光效果，我们只需将这两个枚举的值相加即可：

glowLevel = (ExtendedSceneEnvironment.GlowLevel.One | ExtendedSceneEnvironment.GlowLevel.Six)

glowQualityHigh : bool [default: false]

在降采样时增加辉光使用的样本，以提高辉光效果的质量。

glowStrength : real [default: 1]

发光强度。可接受的值为0至2。

强度实际上是一个按级别应用的比例系数（乘数）。这意味着glowLevel 中启用的级别越多，glowStrength 越大，效果就越明显。

在实践中，glowStrength、glowIntensity 和glowBloom 的值通常会一起调整，以达到所需的效果。

例如，glowIntensity 为 1.0，glowBloom 为 0.25，并启用前四级：

glowUseBicubicUpscale : bool [default: false]

减少光晕效果中的混叠伪影和盒状效果。

lensFlareApplyDirtTexture : bool [default: false]

设置是否为镜头耀斑应用污垢纹理。

另请参阅 lensFlareLensDirtTexture 。

lensFlareApplyStarburstTexture : bool [default: false]

设置是否为镜头耀斑应用星爆纹理。

另请参阅 lensFlareLensStarburstTexture 。

lensFlareBloomBias : real [default: 0.95]

设置镜头耀斑开始的水平。

偏置值从高动态范围色彩值中减去，结果箝位为 0。这意味着，根据场景的不同，有时可能需要将偏置值设置得很低，例如低于 1，才能使镜头耀斑明显。因此默认值为 0.95。而当色彩范围较大时，设置较大的值可能更合理。

lensFlareBloomScale : real [default: 10]

设置镜头耀斑绽放效果的比例。预期比例值范围为0至20。

在实际应用中，这将作为减去lensFlareBloomBias 的零钳位色彩值的乘数。

lensFlareBlurAmount : real [default: 3]

设置应用于镜头耀斑的模糊量。范围为0至50。

lensFlareCameraDirection : vector3d [default: Qt.vector3d(0, 0, -1)]

设置场景中摄像机的方向。

lensFlareDistortion : real [default: 5]

设置镜头耀斑中的色差量。预期值范围为0至20。

lensFlareEnabled : bool [default: false]

启用镜头炫光效果。

启用后，第一个要调整的属性通常是lensFlareBloomBias 。

lensFlareGhostCount : int [default: 4]

设置镜头炫光重影的数量。预期值为0至20。

lensFlareGhostDispersal : real [default: 0.5]

设置镜头耀斑重影之间的距离。预期值介于0和5 之间。该值应大于 0。

lensFlareHaloWidth : real [default: 0.25]

设置镜头耀斑光晕的大小。范围为0至1。

lensFlareLensColorTexture : Texture

用于炫光透镜颜色的渐变图像。

默认情况下使用内置的 256x256 纹理：

lensFlareLensDirtTexture : Texture

用于模拟镜头缺陷的图像。

只有启用lensFlareApplyDirtTexture 时才会产生效果。

默认情况下使用内置的脏污纹理：

lensFlareLensStarburstTexture : Texture

噪点图像，用于增强镜头耀斑的星芒效果。只有启用lensFlareApplyStarburstTexture 时才会产生效果。

默认情况下使用内置的噪点纹理：

lensFlareStretchToAspect : real [default: 0.5 [0, 1]]

设置镜头耀斑光晕圆度修正系数。

lutEnabled : bool [default: false]

使用查找表（LUT）进行调色。查找表以纹理的形式给出。

lutFilterAlpha : real [default: 1]

设置与场景混合的调色量。该值应介于0和1 之间。

lutSize : real [default: 16]

设置 LUT 纹理的大小。纹理的尺寸应为

width = lutSize * lutSize 和height = lutSize

lutTexture : Texture

查找纹理的来源。如果没有设置纹理，则会使用内置的标识表。

下图是一个尺寸为 256x16 的纹理示例，与默认的lutSize 16 相匹配。

效果图

sharpnessAmount : real [default: 0.0]

设置锐化量。有效值从0.0 （关闭）到1.0 （完全）。

ssgiBufferSizeFactor : real [default: 0.5, since 6.11]

控制 SSGI 特效所使用的色彩缓冲区大小。如果使用与输入和输出尺寸（即View3D 的像素尺寸）相匹配的渲染目标来执行所有操作，可能会导致成本过高，许多 GPU 和设备实际上都无法承受。因此，SSGI 效果会缩小中间纹理的尺寸。默认值为 0.5，即输入和输出纹理大小的一半。将值增大到 1 会提高结果的质量，但代价是 GPU 负载会大幅增加。

此属性在 Qt 6.11 中引入。

ssgiEnabled : bool [default: false, since 6.11]

启用屏幕空间全局照明。该效果可为场景添加环境遮蔽和间接光源，从而增强真实感。

此属性在 Qt 6.11 中引入。

另请参阅 Qt Quick 3D - SSGI Lightmap 示例。

ssgiHitThickness : real [default: 0.5, since 6.11]

配置全局光照算法。

建议范围为 0.001 至 4.0。

此属性在 Qt 6.11 中引入。

ssgiIndirectLightBoost : real [default: 4.0, since 6.11]

间接光结果的乘数。增加该值会使间接光的作用更加突出。建议范围为 1 至 100。适当的值始终取决于场景及其照明方式。

此属性在 Qt 6.11 中引入。

ssgiIndirectLightEnabled : bool [default: true, since 6.11]

控制结果中是否包含间接光，或仅包含环境光遮挡。默认情况下两者都启用。

将值设为 false 可以直接替代SceneEnvironment 的ambient occlusion 。SSGI 提供的 AO 结果预计质量较高，几乎不需要调整。但这样做的代价是可能会增加 GPU 负载。

此属性在 Qt 6.11 中引入。

ssgiSampleCount : int [default: 4, since 6.11]

配置全局光照算法。样本数越多，效果越好，但会增加 GPU 负载。

建议范围为 1 至 16。

此属性在 Qt 6.11 中引入。

ssgiSampleRadius : real [default: 0.1, since 6.11]

配置全局光照算法。

建议范围为 0.001 至 4.0。

此属性在 Qt 6.11 中引入。

ssgiSimulatedBounceEnabled : bool [default: false, since 6.11]

控制是否通过对上一帧的纹理进行采样来模拟额外的光线反弹。

此属性在 Qt 6.11 中引入。

ssgiSimulatedBounceFactor : real [default: 0.5, since 6.11]

模拟反弹计算结果的乘数。只有当ssgiSimulatedBounceEnabled 为true 时才会产生影响。该值可能需要与ssgiIndirectLightBoost 一起调整。根据场景和照明方式的不同，这些属性的较高值可能会导致间接光贡献过于夸张，甚至导致反馈循环，即间接光在帧间过度增长。

此属性在 Qt 6.11 中引入。

ssgiSliceCount : int [default: 4, since 6.11]

配置全局光照算法。

建议范围为 1 至 8。

此属性在 Qt 6.11 中引入。

ssrEnabled : bool [default: false, since 6.11]

启用屏幕空间反射，这是一种通过使用屏幕上渲染的数据来创建反射的后处理技术。

此属性在 Qt 6.11 中引入。

tonemapMode : enumeration [default: SceneEnvironment.TonemapModeLinear]

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

默认值为SceneEnvironment.TonemapModeLinear

vignetteColor : color [default: "gray"]

设置渐变效果的颜色。

例如，将颜色更改为红色，如图所示，半径为 4，强度为 15：

vignetteEnabled : bool [default: false]

启用渐晕效果。

vignetteRadius : real [default: 0.35]

设置渐晕效果的半径。范围为0至5。

vignetteStrength : real [default: 15]

设置渐晕效果的强度。范围为0至15。

whitePoint : real [default: 1]

启用色调映射时白色的参考值。该值必须大于 0。