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)
• ssrMaxSteps : int (since 6.12)
• ssrThickness : real (since 6.12)
• tonemapMode : enumeration
• vignetteColor : color
• vignetteEnabled : bool
• vignetteRadius : real
• vignetteStrength : real
• whitePoint : real

详细说明

ExtendedSceneEnvironment 是QtQuick3D 中SceneEnvironment 类型的扩展，内置了一组常用效果。这些效果通过一组属性对外提供，这些属性的前缀即为它们所控制的效果名称。

启用其中一个或多个效果时，其效果类似于手动将后处理效果添加到SceneEnvironment 的effects 列表中。 然而，ExtendedSceneEnvironment 提供了无法以独立形式获得的效果，更重要的是，它能高效地组合已启用的效果，从而减少所需的额外渲染通道数量，这比将单个后处理效果应用于场景能带来显著更好的性能。ExtendedSceneEnvironment 还与色调映射配合良好，即使对于更复杂的多通道效果，以及在启用并组合多个效果时也是如此。而独立效果则未必总是如此。

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

ExtendedSceneEnvironment 入门指南

要使用 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.Screen
• 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 光照贴图示例。

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 中引入。

ssrMaxSteps : int [default: 256, since 6.12]

限制反射光线在屏幕上可以传播的步数。数值越大，反射的传播距离和质量越好，但会降低性能。

该属性在 Qt 6.12 中引入。

ssrThickness : real [default: 20, since 6.12]

屏幕空间反射所使用的场景几何体的假定厚度。较大的数值可减少反射碎裂现象（类似于阴影痘），但可能会导致反射效果在物理上不正确。

该属性于 Qt 6.12 中引入。

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。