ExtendedSceneEnvironment QML 类型

一个提供常用渲染效果的 SceneEnvironment。更多信息...

导入语句	import QtQuick3D.Helpers
自	Qt 6.5
继承	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 : 实数
lensFlareEnabled : 布尔
lensFlareGhostCount : 整数
lensFlareGhostDispersal : 实数
lensFlareHaloWidth : 实数
lensFlareLensColorTexture : 纹理
lensFlareLensDirtTexture : 纹理
lensFlareLensStarburstTexture : 纹理
lensFlareStretchToAspect : 实数
lutEnabled : 布尔
lutFilterAlpha : 实数
lutSize : 实数
lutTexture : 纹理
sharpnessAmount : 实数
tonemapMode : 枚举类型
vignetteColor : 颜色
vignetteEnabled : 布尔
vignetteRadius : 实数
vignetteStrength : 实数
whitePoint : 实数

详细介绍

ExtendedSceneEnvironment 是对 QtQuick3D 的 SceneEnvironment 类型的一个扩展，它内置了一组常用的效果。这些效果通过以效果的名称为前缀的属性集合公开。

当启用这些效果之一或多个时，结果类似于手动将后处理效果添加到 SceneEnvironment 的 effects 列表中。然而，ExtendedSceneEnvironment 提供的效果不是独立形式存在的，更重要的是，它有效地组合了启用的效果，减少了所需的额外渲染次数，从而可能比逐个应用后处理效果带来显著更好的性能。ExtendedSceneEnvironment 还与色调映射表现良好，即便对于更复杂的多次遍历效果，以及当同时启用并组合多个效果时也是如此。这不是独立效果始终能实现的。

注意：如果将额外的后处理效果添加到 SceneEnvironment 的 effects 列表，则这些效果将在 ExtendedSceneEnvironment 类型提供的效果之前应用。

《SceneEnvironment》的一些特性，如色调映射，在《ExtendedSceneEnvironment》中被继承和扩展，增加了额外的属性。例如，《SceneEnvironment》提供了tonemapMode属性，而《ExtendedSceneEnvironment》添加了对色调映射器曝光度、白色点、锐化和抖动设置的控件。然而，由于《ExtendedSceneEnvironment》继承自《SceneEnvironment》，因此tonemapMode属性不会被重复。但是，由于《ExtendedSceneEnvironment》继承了《SceneEnvironment》的所有内容，因此色调映射模式的基本设置在将《View3D》与任何类型的《SceneEnvironment》相关联时都是可用的，但附加的属性仅在使用《ExtendedSceneEnvironment》时才可用。其他效果，如屏幕空间环境光遮挡（SSAO）或雾，是《SceneEnvironment》的完整部分，并且在使用两种类型的《SceneEnvironment》时都可用。

《ExtendedSceneEnvironment》入门指南

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

import QtQuick3D
import QtQuick3D.Helpers

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

注意：调整效果参数并调整值以获得所需的外观效果，通常在视觉上进行操作时更为高效，尤其是在值更改时，滑块等控件会即时回馈渲染场景的结果。因此，在尝试设置外观吸引人的高质量场景时，推荐使用Qt Design Studio等设计工具或类似于Qt Quick 3D - Scene Effects Example的测试平台。

注意：将《SceneEnvironment》切换到《ExtendedSceneEnvironment》会自动意味着至少增加一个渲染通道，就像在《SceneEnvironment》的效果列表中添加了一个只有一个渲染通道的效果一样。无论启用或禁用多少个单独的后处理步骤，这都是正确的。（更复杂的效果可能包含多个额外的渲染通道）

可用效果

以下是对《ExtendedSceneEnvironment》提供的效果和相应功能的概述，包括从《SceneEnvironment》继承的功能。

色调映射 - 控制如何将高分辨率范围内的颜色色调映射到0-1范围，然后在显示之前进行映射。扩展的《ExtendedSceneEnvironment》增加了对曝光度、白色点、锐化和抖动的额外控制。
由属性tonemapMode、exposure、whitePoint、ditheringEnabled控制。
色彩调整 - 亮度、对比度、饱和度调整。
由属性colorAdjustmentsEnabled、adjustmentBrightness、adjustmentContrast、adjustmentSaturation控制。
通过查找表（LUT）纹理进行色彩分级。
由属性lutEnabled、lutSize、lutFilterAlpha控制。
景深（Depth of field）
由属性depthOfFieldEnabled、depthOfFieldFocusDistance、depthOfFieldFocusRange、depthOfFieldBlurAmount控制。
发光和漫反射
由属性glowEnabled、glowQualityHigh、glowUseBicubicUpscale、glowStrength、glowIntensity、glowBloom、glowBlendMode、glowHDRMaximumValue、glowHDRMinimumValue、glowHDRScale控制。
晕影
由属性vignetteEnabled、vignetteStrength、vignetteColor、vignetteRadius控制。
镜头耀斑
由属性lensFlareEnabled、lensFlareBloomBias、lensFlareGhostDispersal、lensFlareGhostCount、lensFlareHaloWidth、lensFlareStretchToAspect、lensFlareDistortion、lensFlareBlurAmount、lensFlareApplyDirtTexture、lensFlareApplyStarburstTexture、lensFlareCameraDirection、lensFlareLensColorTexture、lensFlareLensDirtTexture、lensFlareLensStarburstTexture控制。
屏幕空间环境遮挡 - 由SceneEnvironment提供。
由SceneEnvironment::aoEnabled、SceneEnvironment::aoStrength、SceneEnvironment::aoDistance、SceneEnvironment::aoSoftness、SceneEnvironment::aoDither、SceneEnvironment::aoSampleRate、SceneEnvironment::aoBias控制。
雾效 - 由SceneEnvironment提供。这不是一种后期处理效果，而是应用于场景中可渲染对象的材质。
由与SceneEnvironment::fog属性相关联的Fog对象控制。
抗锯齿 - SceneEnvironment提供多采样、超采样、渐进式抗锯齿、镜面抗锯齿、临时抗锯齿。ExtendedSceneEnvironment增加使用FXAA的一种形式的选项。
FXAA（快速近似抗锯齿）由 fxaaEnabled 控制。其他抗锯齿模式由 SceneEnvironment::antialiasingMode、SceneEnvironment::temporalAAEnabled、SceneEnvironment::temporalAAStrength 和 SceneEnvironment::specularAAEnabled 控制。

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

属性文档

adjustmentBrightness : real [默认值: 1]

调整场景的亮度。

亮度为 1	亮度为 4

adjustmentContrast : real [默认值: 1]

调整场景的对比度。

对比度为 1	对比度为 4

adjustmentSaturation : real [默认值: 1]

调整场景的饱和度。

饱和度为 1	饱和度为 4

colorAdjustmentsEnabled : bool [默认值: false]

启用颜色调整。

另请参阅 colorAdjustmentsEnabled。

depthOfFieldBlurAmount : real [默认值: 4.0]

应用于焦点范围外对象的模糊量。合理的值在 0 到 10 范围内。0 值不应用额外的模糊。

模糊量为 0	模糊量为 15

depthOfFieldEnabled : bool [默认值: false]

启用景深模糊效果。

depthOfFieldFocusDistance : real [默认值: 600]

设置物体在焦点的相机距离。

此处，Sponza 场景被应用了 100 的缩放，以便有足够大的范围来应用前后视图的模糊。下面的图像是通过焦点距离 753 和焦点范围 482 拍摄的。

depthOfFieldFocusRange : real [默认值: 100]

围绕 depthOfFieldFocusDistance 的距离，其中项目完全聚焦。焦点随后通过相同的距离在前后两侧逐渐变得模糊。

ditheringEnabled : bool [默认值: false]

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

exposure : real [默认值: 1.0]

用于调色器的曝光级别。

使用曝光 8 的电影调色器	将曝光设置为 0.5 的电影调色器

fxaaEnabled : bool [默认值: false]

启用快速近似抗锯齿（FXAA）。

FXAA 已禁用	FXAA 已启用

glowBlendMode : int [默认值: ExtendedSceneEnvironment.GlowBlendMode.SoftLight]

光晕效果的混合模式。

可用模式为

ExtendedSceneEnvironment.GlowBlendMode.Additive
扩展场景环境.GlowBlendMode.Screen
扩展场景环境.GlowBlendMode.SoftLight
扩展场景环境.GlowBlendMode.Replace

加成通常推荐用于户外场景，其中可见天空或太阳，而默认的柔和光线可能对室内环境效果更好。

替换不会进行任何混合，而是仅显示发光/闪烁效果会混合到实际内容中的贡献。在实际操作中，这可以在设置发光/闪烁效果的参数时进行实验和故障排除很有用。

混合模式	示例
关闭发光
加成
屏幕
柔和光线
替换

glowBloom : 实数 [默认值: 0]

设置应用于发光效果的光晕程度。预期值为从0到1。

glowHDRMinimumValue、glowHDRMaximumValue、glowHDRScale和glowBloom值共同控制发光/闪烁效果产生的亮度反馈量。

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

例如，启用四个发光级别，强度为1.5，强度为1

glowBloom设置为0	glowBloom设置为0.5

glowEnabled : 布尔值 [默认值: false]

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

glowHDRMaximumValue : 实数 [默认值: 12.0]

设置发光的最高亮度，使用高动态范围。值范围从0到256。

glowHDRMinimumValue、glowHDRMaximumValue、glowHDRScale和glowBloom值共同控制发光/闪烁效果产生的亮度反馈量。

glowHDRMinimumValue : 实数 [默认值: 1.0]

设置发光的最低亮度，使用高动态范围。预期值在0到4的范围内。

glowHDRMinimumValue、glowHDRMaximumValue、glowHDRScale和glowBloom值共同控制发光/闪烁效果产生的亮度反馈量。

glowHDRScale : 实数 [默认值: 2.0]

HDR发光的溢出缩放比例。预期值在0到8的范围内。

glowHDRMinimumValue（نبض HDR_MIN_VALUE）、glowHDRMaximumValue（نبض HDR_MAX_VALUE）、glowHDRScale以及glowBloom值共同控制闪亮/柔和效果生成的亮度反馈量。

glowIntensity : real [默认值: 1]

亮度强度。预期值范围是0到8。

其实际上是一个累积亮度颜色的比例因子（乘数），包括所有级别。

实际上，glowStrength（闪亮强度）、glowIntensity和glowBloom（柔和度）的值通常需要一起调整以达到 desired 想要的结果。

例如，当glowStrength（闪亮强度）为1.0且glowBloom（柔和度）为0.25时

glowIntensity（亮度强度）为0.25	glowIntensity（亮度强度）为1.25

glowLevel : int [默认值: 1]

设置哪些模糊通道路由应用于闪亮效果。总共有7个级别可用。

未设置任何级别意味着闪亮将没有可视效果。

例如，要启用Glow Level One（第一级）和 Six（第六级）

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

glowLevel值	示例
One（一）
One \| Two（一 \| 二）
One \| Two \| Three（一 \| 二 \| 三）
One \| Two \| Three \| Four（一 \| 二 \| 三 \| 四）

glowQualityHigh : bool [默认值: false]

提高降采样时使用的闪烁样本，以改善闪烁效果的质量。

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

glowStrength : real [默认值: 1]

闪烁强度。接受的值从0到2。

强度实际上是一个应用于每个级别的比例因子（乘数）。这意味着，在glowLevel中启用的级别越多，较大的glowStrength产生的影响就越明显。

实际上，glowStrength、glowIntensity和glowBloom的值经常一起调整以达到 desired 想要的结果。

例如，当glowIntensity（亮度强度）为1.0、glowBloom（柔和度）为0.25，前三级启用时

glowStrength（闪烁强度）为0.5	glowStrength（闪烁强度）为1.5

glowUseBicubicUpscale : bool [默认值: false]

减少发光效果中的混叠伪影和块状。

注意：使用双线性上采样将付出性能代价。考虑是否可以使用dithering代替。

lensFlareApplyDirtTexture : bool [默认值: false]

设置是否将泥土纹理应用于镜头闪光。

泥土纹理已禁用	默认启用泥土纹理

另请参阅：lensFlareLensDirtTexture.

lensFlareApplyStarburstTexture : bool [默认: false]

设置是否应用星爆纹理到镜头闪光效果。

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

另请参阅 lensFlareLensStarburstTexture.

lensFlareBloomBias : real [默认: 0.95]

设置镜头闪光亮度开始的级别。

从高动态范围颜色值减去阈值值，并将结果限制为0。这意味着，根据场景的不同，有时需要将其设置为相当低的值，例如低于1，以便使镜头闪光效果明显。因此默认值为0.95。而在颜色范围更广的情况下，可能需要更大的值。

阈值为0.81	阈值为0.31

lensFlareBloomScale : real [默认: 10]

设置镜头闪光亮度效果的比例。期望的比例值范围从 0 到 20。

在实际应用中，这个参数与lensFlareBloomBias的差值一起作为一个乘数来应用。

比例2，阈值为0.81	比例20，阈值为0.81

lensFlareBlurAmount : real [默认: 3]

设置应用于镜头闪光效果的模糊程度。范围从 0 到 50。

模糊程度设置为0	模糊程度设置为30

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

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

lensFlareDistortion : real [默认: 5]

设置镜头闪光中色差的程度。期望值范围从 0 到 20。

色差设置为0	色差设置为15

lensFlareEnabled : bool [默认: false]

启用镜头闪光效果。

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

lensFlareGhostCount : int [默认: 4]

设置镜头闪光幽灵的数量。期望值范围从 0 到 20。

幽灵数量为2	幽灵数量为16

lensFlareGhostDispersal : real [默认: 0.5]

设置镜头闪光幽灵之间的距离。期望值范围从 0 到 5。该值应大于0。

幽灵扩散为0.25	幽灵扩散为0.90

lensFlareHaloWidth : real [默认: 0.25]

设置镜头闪光光环的大小。范围从 0 到 1。

lensFlareLensColorTexture : Texture

用于镜头闪光镜头颜色的渐变图像。

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

lensFlareLensDirtTexture : Texture

用于模拟镜头不完美的图像。

仅在lensFlareApplyDirtTexture启用时才会产生效果。

默认使用内置的污点纹理。

lensFlareLensStarburstTexture : Texture

用于增强镜头闪光星芒效果的光晕噪声图像。仅在lensFlareApplyStarburstTexture启用时才会产生效果。

默认使用内置的噪声纹理。

lensFlareStretchToAspect : real [默认: 0.5 [0, 1]]

设置镜头闪光光环的圆形校正因子。

lutEnabled : bool [默认: false]

启用使用查找表（LUTs）的色彩分级。查找表作为一个纹理给出。

lutFilterAlpha : real [默认: 1]

设置与场景混合的色彩分级量。该值应在0到1之间。

lutSize : real [默认: 16]

设置LUT纹理的大小。纹理的维度应为

宽度 = lutSize * lutSize 和 高度 = lutSize

lutTexture : Texture

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

以下是一个大小为256x16的示例纹理，与默认的lutSize 16匹配。

此效果的输出结果

sharpnessAmount : real [默认: 0.0]

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

色彩范围为0的胶片式调色映射	色彩范围为1的胶片式调色映射

tonemapMode : enumeration

此属性定义在渲染之前如何对颜色进行色调映射。Qt Quick 3D中的所有渲染都是在线性颜色空间中执行的，并且可能导致生成不可显示的颜色值。tonemapMode确定用于将颜色重新映射为可显示范围的技巧。

默认值是SceneEnvironment.TonemapModeLinear

常数	描述
`SceneEnvironment.TonemapModeNone`	绕过所有色调映射。此模式适用于执行后期处理效果。
`SceneEnvironment.TonemapModeLinear`	应用线性色调映射。颜色在sRGB颜色空间中进行了伽马校正并返回。
`SceneEnvironment.TonemapModeAces`	应用学院色彩编码系统色调映射。
`SceneEnvironment.TonemapModeHejlDawson`	应用Hejl-Dawson色调映射。
`SceneEnvironment.TonemapModeFilmic`	应用胶片式色调映射。

注意: 当使用后期处理效果时，许多效果都期望未调整色调映射的线性颜色数据。在这种情况下通过使用SceneEnvironment.TonemapModeNone值来绕过内置色调映射很重要。这不影响ExtendedSceneEnvironment的内置效果，因为那些自动处理适当的色调映射。

色调映射模式	示例
无
线性
Aces
HejlDawson
胶片

vignetteColor : color [默认: "gray"]

设置阴影效果的颜色。

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

vignetteEnabled : bool [默认: false]

启用晕影效果。

vignetteRadius : real [默认: 0.35]

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

半径为 0.35	半径为 5.0

vignetteStrength : real [默认: 15]

设置晕影效果的强度。范围从 0 到 15。

强度为 15	强度为 10

whitePoint : real [默认: 1]

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

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

将白点设置为 0.1 的电影式色调映射	将白点设置为 1 的电影式色调映射