Back to Qt.io
Contact Us Blog Download Qt

ExtendedSceneEnvironment QML Type

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

Import Statement: import QtQuick3D.Helpers
Since: Qt 6.5
Inherits:

SceneEnvironment

属性

详细说明

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

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

注： 如果在SceneEnvironment 的effects 列表中添加了额外的后期处理效果，那么这些效果将在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
        // ...
    }
}

注： 使用滑块等控件来试验效果参数并调整数值以达到所需的视觉效果，往往更有成效。因此，在设置一个视觉效果吸引人的高质量场景时，建议使用Qt Design Studio 等设计工具或类似于Qt Quick 3D - 场景效果示例的测试平台。

注意： 将SceneEnvironment 切换为 ExtendedSceneEnvironment（扩展场景环境）自动意味着至少要增加一次渲染通 程，就像在SceneEnvironment's effect list 中添加了一个只有一次渲染过程的特效一样。无论启用了多少个单独的后处理步骤，情况都是如此。(更复杂的特效可能需要一个以上的额外渲染过程）。

可用特效

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

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

属性文档

adjustmentBrightness : real [default: 1]

调整场景亮度。

亮度为 1亮度为 4


adjustmentContrast : real [default: 1]

调整场景的对比度。

对比度为 1对比度为 4


adjustmentSaturation : real [default: 1]

调整场景的饱和度。

饱和度为 1饱和度为 4


colorAdjustmentsEnabled : bool [default: false]

启用色彩调整。

另请参阅 ColorAdjustmentsEnabled。


depthOfFieldBlurAmount : real [default: 4.0]

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

模糊量为 0模糊量为 15


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]

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

曝光为 8 的胶片色调映射曝光设置为 0.5 的胶片色调映射


fxaaEnabled : bool [default: false]

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

禁用 FXAA启用 FXAA


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

辉光效果的混合模式。

可用的模式有

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

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

混合模式示例
禁用辉光

添加

屏幕

柔光

替换


glowBloom : real [default: 0]

设置应用于辉光效果的绽放量。数值范围从0到1。

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

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

例如，在启用四个辉光级别、强度为 1.5 和强度为 1 的情况下，辉光/绽放的值为 0：

glowBloom 设置为 0glowBloom 设置为 0.5


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：

glowIntensity 为 0.25glowIntensity 为 1.25


glowLevel : int [default: 1]

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

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

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

glowLevel = (ExtendedSceneEnvironment.GlowLevel.One | ExtendedSceneEnvironment.GlowLevel.Six)
glowLevel 值示例
一

一 | 二

一 | 二 | 三

一 | 二 | 三 | 四


glowQualityHigh : bool [default: false]

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

注意： 启用此功能需要在渲染质量和性能之间进行权衡。请考虑是否可以使用dithering 代替。


glowStrength : real [default: 1]

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

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

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

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

glowStrength 为 0.5glowStrength 为 1.5


glowUseBicubicUpscale : bool [default: false]

减少辉光效果中的混叠伪影和拳击效果。

注意： 使用双立方向上缩放会影响性能。请考虑是否可以使用dithering 代替。


lensFlareApplyDirtTexture : bool [default: false]

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

禁用脏污纹理启用默认脏污纹理

另请参阅 lensFlareLensDirtTexture 。


lensFlareApplyStarburstTexture : bool [default: false]

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

禁用星爆纹理默认已启用星芒纹理

另请参阅 lensFlareLensStarburstTexture 。


lensFlareBloomBias : real [default: 0.95]

设置镜头耀斑开始绽放的级别。

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

偏差为 0.81偏置 0.31


lensFlareBloomScale : real [default: 10]

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

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

刻度 2，偏置 0.81刻度 20，偏置 0.81


lensFlareBlurAmount : real [default: 3]

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

模糊量设置为 0模糊量设置为 30


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

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


lensFlareDistortion : real [default: 5]

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

失真设置为 0失真设置为 15


lensFlareEnabled : bool [default: false]

启用镜头耀斑效果。

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


lensFlareGhostCount : int [default: 4]

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

鬼影数为 2鬼影数为 16


lensFlareGhostDispersal : real [default: 0.5]

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

鬼影分散度为 0.25鬼影分散度为 0.90


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 （完全）。

锐度设置为 0 的胶片色调映射胶片色调映射，锐度设为 1


tonemapMode : enumeration [default: SceneEnvironment.TonemapModeLinear]

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

默认值为SceneEnvironment.TonemapModeLinear

常量说明
SceneEnvironment.TonemapModeNone绕过所有色调映射。该模式在执行后期处理效果时非常有用。
SceneEnvironment.TonemapModeLinear应用线性色调映射。颜色经过伽玛校正，并以 sRGB 色彩空间返回。
SceneEnvironment.TonemapModeAces应用学院色彩编码系统色调映射。
SceneEnvironment.TonemapModeHejlDawson应用 Hejl-Dawson 色调映射。
SceneEnvironment.TonemapModeFilmic应用胶片色调映射。

注： 使用后期处理特效时，许多特效需要未调色的线性色彩数据。在这种情况下，使用SceneEnvironment.TonemapModeNone 值绕过内置色调映射非常重要。这不适用于ExtendedSceneEnvironment 的内置特效，因为这些特效会自动进行适当的色调映射。

色调映射模式示例
无

线性

王牌

海尔-道森

胶片效果


vignetteColor : color [default: "gray"]

设置渐晕效果的颜色。

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


vignetteEnabled : bool [default: false]

启用渐晕效果。


vignetteRadius : real [default: 0.35]

设置渐晕效果的半径。范围从0到5。

半径 0.35半径为 5.0


vignetteStrength : real [default: 15]

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

强度为 15强度为 10


whitePoint : real [default: 1]

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

注： 使用SceneEnvironment.TonemapModeLinear 时，此值将被忽略。

胶片色调映射，白点设置为 0.1胶片色调映射，白点设置为 1


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