就业培训     下载中心     Wiki     联络 登录   注册
  1. 首页
  2. Qt 6.5.1
  3. Qt Quick 3D
  4. QML 类型
  5. QtQuick3D.Helpers
  6. ExtendedSceneEnvironment

ExtendedSceneEnvironment QML Type

A SceneEnvironment providing commonly used rendering effects. 更多...

import 语句： import QtQuick3D.Helpers
Since: Qt 6.5
继承： SceneEnvironment

特性

详细描述

The ExtendedSceneEnvironment is an extension of QtQuick3D 's SceneEnvironment type that comes with a collection of commonly used effects built-in. The effects are exposed through a set of properties that are prefixed with the name of the effect they control.

When enabling one or more of these effects, the result is similar to manually adding post-processing effects to the SceneEnvironment 's effects list. ExtendedSceneEnvironment provides however effects that are not available in standalone form, and more importantly, it efficiently combines the effects that are enabled, reducing the number of additional render passes needed, which can lead to significantly better performance than applying individual post-processing effects to the scene. ExtendedSceneEnvironment also plays well with tonemapping, even for the more complicated multiple pass effects, and also when multiple effects are enabled and combined together. This was not always the case with standalone effects.

注意： If additional post-processing effects are added to the effects list of SceneEnvironment , then those effects will be applied before the effects provided by the ExtendedSceneEnvironment 类型。

Certain features of SceneEnvironment , such as the tonemapping, are inherited and extended with additional properties in ExtendedSceneEnvironment. For example, SceneEnvironment offers the tonemapMode property, whereas ExtendedSceneEnvironment adds control over the exposure, white point, sharpening, and dithering settings of the tonemapper as well. The tonemapMode property is not duplicated however since ExtendedSceneEnvironment inherits everything from SceneEnvironment , so the base setting of the tonemapping mode is usable regardless of which type of environment is associated with a View3D , but the additional properties are available only when using ExtendedSceneEnvironment. Other effects, such as screen space ambient occlusion (SSAO) or fog are fully part of SceneEnvironment and are usable with both types of environments.

Getting Started with ExtendedSceneEnvironment

To use the additional features offered by ExtendedSceneEnvironment, associate the View3D with an instance of it. Do not forget to import the QtQuick3D.Helpers 模块。 

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

注意： Experimenting with the effect parameters and tuning the values to achieve the desired visual results can often be more productive when done visually, with controls such as sliders that give instant feedback in the rendered scene when a value is changed. Using a designer tool such as Qt Design Studio, or a test bed similar to the Qt Quick 3D - Scene Effects Example is therefore often recommendable when aiming to set up a high quality scene that looks visually appealing.

注意： Switching SceneEnvironment to ExtendedSceneEnvironment automatically implies at least one additional render pass, just as if an Effect with a single pass was added to the SceneEnvironment's effect list . This is true regardless of how many of the individual post-processing steps are enabled. (the more complex effects may involve more than one additional render pass)

Available Effects

Below is an overview of the effects and related features provided by ExtendedSceneEnvironment, including features inherited from SceneEnvironment .

另请参阅 SceneEnvironment and Qt Quick 3D - Scene Effects Example .

特性文档编制

[default: 1] adjustmentBrightness : real

Adjusts the brightness of the scene.

Brightness of 1 Brightness of 4

[default: 1] adjustmentContrast : real

Adjusts the contrast of the scene.

Contrast of 1 Contrast of 4

[default: 1] adjustmentSaturation : real

Adjusts the saturation of the scene.

Saturation of 1 Saturation of 4

[default: false] colorAdjustmentsEnabled : bool

Enables color adjustments.

另请参阅 colorAdjustmentsEnabled.


[default: 4.0] depthOfFieldBlurAmount : real

amount of blur applied to objects outside the focus range. Sensible values are in the range 0 to 10 . A value of 0 applies no additional blur.

Blur amount of 0 Blur amount of 15

[default: false] depthOfFieldEnabled : bool

Enables the depth of field blur effect.


[default: 600] depthOfFieldFocusDistance : real

Sets the distance from the camera at which objects are in focus.

Here the Sponza scene has a scale of 100 applied in order to have a suitably big range to get blur applied to the back and the front of the view. The picture below is taken with a focus distance of 753 and a focus range of 482.


[default: 100] depthOfFieldFocusRange : real

The distance around the depthOfFieldFocusDistance where items are fully in focus. The focus then fades away to fully blurred by the same distance on both the near and far sides.


[default: false] ditheringEnabled : bool

Enables dithering to reduce banding artifacts.


[default: 1.0] exposure : real

Exposure level used by the tonemapper.

Filmic tonmapping with exposure 8 Filmic tonmapping with exposure set to 0.5

[default: false] fxaaEnabled : bool

Enables fast approximate anti-aliasing (FXAA).

FXAA disabled FXAA enabled

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

Blending mode for the glow effect.

Available modes are:

Additive is often recommendable for outdoor scenes, where a sky or sun is visible, whereas the default SoftLight may work better for in-door environments.

替换 does not perform any blending, but rather results in displaying only the contribution the glow/bloom effect would blend with the actual content. In practice this can be useful for experimenting and troubleshooting when setting up the parameters of a glow/bloom effect.

Blend mode 范例
Glow disabled
Additive
Screen
SoftLight
替换

[default: 0] glowBloom : real

Sets the amount of bloom applied to the glow effect. Values from 0 to 1 are expected.

The glowHDRMinimumValue , glowHDRMaximumValue , glowHDRScale , and glowBloom values together control the amount of luminance feedback generated by the glow/bloom effect.

In practice the values for glowStrength , glowIntensity , and glowBloom will often be tuned together to achieve the desired results.

For example, with four glow levels enabled, a strength of 1.5, and an intensity of 1:

glowBloom set to 0 glowBloom set to 0.5

[default: false] glowEnabled : bool

Enables the glow effect. It can also provide bloom, when the value of glowBloom is larger than 0.


[default: 12.0] glowHDRMaximumValue : real

Sets the maximum brightness of the glow, in high dynamic range. Value range is from 0 to 256 .

The glowHDRMinimumValue , glowHDRMaximumValue, glowHDRScale ，和 glowBloom values together control the amount of luminance feedback generated by the glow/bloom effect.


[default: 1.0] glowHDRMinimumValue : real

Sets the minimum brightness of the glow, in high dynamic range. Expected values are in the range 0 to 4 .

The glowHDRMinimumValue, glowHDRMaximumValue , glowHDRScale ，和 glowBloom values together control the amount of luminance feedback generated by the glow/bloom effect.


[default: 2.0] glowHDRScale : real

The bleed scale of the HDR glow. Expected values are in the range 0 to 8 .

The glowHDRMinimumValue , glowHDRMaximumValue , glowHDRScale, and glowBloom values together control the amount of luminance feedback generated by the glow/bloom effect.


[default: 1] glowIntensity : real

Glow intensity. Expected values are in the range 0 to 8 .

The intensity is effectively a scale factor (multiplier) for the accumulated glow color (including all levels).

In practice the values for glowStrength , glowIntensity, and glowBloom will often be tuned together to achieve the desired results.

For example, with a glowStrength of 1.0 and glowBloom of 0.25:

glowIntensity of 0.25 glowIntensity of 1.25

[default: 1] glowLevel : int

Sets which of the blur passes get applied to the glow effect. There are a total of 7 levels available.

Not having any levels set means that the glow will have no visual effect.

For example, to enable Glow Level One and Six we just OR the two enums together: 

glowLevel = (ExtendedSceneEnvironment.GlowLevel.One | ExtendedSceneEnvironment.GlowLevel.Six)
glowLevel value 范例
One
One | Two
One | Two | Three
One | Two | Three | Four

[default: false] glowQualityHigh : bool

Increases the samples used for the glow when downsampling to improve the quality of the glow effect.

注意： Enabling this is a trade off between rendering quality and performance. Consider if dithering can be used instead.

[default: 1] glowStrength : real

Glow strength. Acceptable values are from 0 to 2 .

The strength is effectively a scale factor (multiplier) that is applied per-level. This means the the more levels are enabled in glowLevel , the more pronounced effect a larger glowStrength has.

In practice the values for glowStrength, glowIntensity ，和 glowBloom will often be tuned together to achieve the desired results.

For example, with a glowIntensity of 1.0, glowBloom of 0.25, and the first four levels enabled:

glowStrength of 0.5 glowStrength of 1.5

[default: false] glowUseBicubicUpscale : bool

Reduces the aliasing artifacts and boxing in the glow effect.

注意： Using bi-cubic up-scaling will come at the cost of performance. Consider if dithering can be used instead.

[default: false] lensFlareApplyDirtTexture : bool

Set whether to apply a dirt texture to the lens flare.

Dirt texture disabled Default dirty texture enabled

另请参阅 lensFlareLensDirtTexture .


[default: false] lensFlareApplyStarburstTexture : bool

Set whether to apply a starburst texture to the lens flare.

Starburst texture disabled Default starburst texture enabled

另请参阅 lensFlareLensStarburstTexture .


[default: 0.95] lensFlareBloomBias : real

Sets the level at which the lens flare bloom starts.

The bias value is subtracted from the high dynamic range color value, with the result clamped to 0. This means that, depending on the scene, it may sometimes need be set to a quite low value, e.g. below 1, in order to make the lens flare obvious. Hence the default of 0.95. Whereas when having a higher range of colors, a bigger value may make more sense.

Bias of 0.81 Bias of 0.31

[default: 10] lensFlareBloomScale : real

Sets the scale of the lens flare bloom effect. Expected scale value ranges from 0 to 20 .

In practice this acts as a multiplier for the zero-clamped color value with the lensFlareBloomBias subtracted.

Scale 2, bias 0.81 Scale 20, bias 0.81

[default: 3] lensFlareBlurAmount : real

Set amount of blur to apply to the lens flare. Ranges from 0 to 50 .

Blur amount set to 0 Blur amount set to 30

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

Sets the direction of the camera in the scene.


[default: 5] lensFlareDistortion : real

Set amount of chromatic aberration in the lens flare. Expected values ranges from 0 to 20 .

Distortion set to 0 Distortion set to 15

[default: false] lensFlareEnabled : bool

Enables the lens flare effect.

Once enabled, the first property to tune is typically lensFlareBloomBias .


[default: 4] lensFlareGhostCount : int

Sets the amount of lens flare ghosts. Expected values are from 0 to 20 .

Ghost count of 2 Ghost count of 16

[default: 0.5] lensFlareGhostDispersal : real

Sets the distance between the lens flare ghosts. Expected values are between 0 and 5 . The value should be larger than 0.

Ghost dispersal of 0.25 Ghost dispersal of 0.90

[default: 0.25] lensFlareHaloWidth : real

Sets the size of the lens flare halo. Ranges from 0 to 1 .


lensFlareLensColorTexture : Texture

A gradient image used for the lens flare lens color.

By default a built-in 256x256 texture is used:


lensFlareLensDirtTexture : Texture

An image that is used to simulate inperfections on the lens.

Has an effect only when lensFlareApplyDirtTexture is enabled.

By default a built-in dirty texture is used:


lensFlareLensStarburstTexture : Texture

A noise image to augment the starburst effect of the lens flare. Has an effect only when lensFlareApplyStarburstTexture is enabled.

By default a built-in noise texture is used:


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

Set correction factor for roundness of the lens flare halo.


[default: false] lutEnabled : bool

Enables color grading with look-up tables (LUTs). The look-up table is given as a texture.


[default: 1] lutFilterAlpha : real

Sets the amount of color grading to mix with the scene. The value is expected to be between 0 and 1 .


[default: 16] lutSize : real

Sets the size of the LUT texture. The texture should have the dimensions:

width = lutSize * lutSize and height = lutSize


lutTexture : Texture

Source of look-up texture. If no texture is set a built-in identity table is used.

Pictured below is an example texture with a size of 256x16, matching the default lutSize of 16.

The result of this effect:


[default: 0.0] sharpnessAmount : real

Set the sharpening amount. Valid values are from 0.0 (off) to 1.0 (完整)。

Filmic tonmapping with sharpness set to 0 Filmic tonmapping with sharpness set to 1

tonemapMode : enumeration

This property defines how colors are tonemapped before rendering. All rendering in Qt Quick 3D is performed in linear color space and can in many cases lead to generating color values that are not displayable. The tonemapMode determines the technique that is used to remap colors into a displayable range.

默认值为 SceneEnvironment.TonemapModeLinear

常量 描述
SceneEnvironment.TonemapModeNone All Tonemapping is bypassed. This mode is useful when performing post processing effects.
SceneEnvironment.TonemapModeLinear Linear tonemapping is applied. Colors are gamma corrected and returned in sRGB color space.
SceneEnvironment.TonemapModeAces Academy Color Encoding System tonemapping is applied.
SceneEnvironment.TonemapModeHejlDawson Hejl-Dawson tonemapping is applied.
SceneEnvironment.TonemapModeFilmic Filmic tonemapping is applied.

注意： When using post-processing effects, many effects expect untonemapped linear color data. It is important to bypass the built-in tonemapping in this case by using the SceneEnvironment.TonemapModeNone value. This does not apply to the built-in effects of ExtendedSceneEnvironment because those automatically take care of proper tonemapping.

Tonemap mode 范例
None
Linear
Aces
HejlDawson
Filmic

[default: "gray"] vignetteColor : color

Sets the color of the vignette effect.

For example, changing the color to red, pictured here with radius 4 and strength 15:


[default: false] vignetteEnabled : bool

Enables the vignette effect.


[default: 0.35] vignetteRadius : real

Sets the radius of the vignette effect. Ranges from 0 to 5 .

Radius of 0.35 Radius of 5.0

[default: 15] vignetteStrength : real

Sets the strength of the vignette effect. Ranges from 0 to 15 .

Strength of 15 Strength of 10

[default: 1] whitePoint : real

Reference value for white when tonemapping is enabled. The value must be larger than 0.

注意： This value is ignored when using SceneEnvironment.TonemapModeLinear .

Filmic tonmapping with white point set to 0.1 Filmic tonmapping with white point set to 1

内容