Contents

ExtendedSceneEnvironment QML Type

A SceneEnvironment providing commonly used rendering effects. More...

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

SceneEnvironment

Properties

Detailed Description

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.

Note: 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 type.

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

 import QtQuick3D
 import QtQuick3D.Helpers

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

Note: 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.

Note: 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.

See also SceneEnvironment and Qt Quick 3D - Scene Effects Example.

Property Documentation

adjustmentBrightness : real [default: 1]

Adjusts the brightness of the scene.

Brightness of 1Brightness of 4


adjustmentContrast : real [default: 1]

Adjusts the contrast of the scene.

Contrast of 1Contrast of 4


adjustmentSaturation : real [default: 1]

Adjusts the saturation of the scene.

Saturation of 1Saturation of 4


colorAdjustmentsEnabled : bool [default: false]

Enables color adjustments.

See also colorAdjustmentsEnabled.


depthOfFieldBlurAmount : real [default: 4.0]

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 0Blur amount of 15


depthOfFieldEnabled : bool [default: false]

Enables the depth of field blur effect.


depthOfFieldFocusDistance : real [default: 600]

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.


depthOfFieldFocusRange : real [default: 100]

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.


ditheringEnabled : bool [default: false]

Enables dithering to reduce banding artifacts.


exposure : real [default: 1.0]

Exposure level used by the tonemapper.

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


fxaaEnabled : bool [default: false]

Enables fast approximate anti-aliasing (FXAA).

FXAA disabledFXAA enabled


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

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.

Replace 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 modeExample
Glow disabled

Additive

Screen

SoftLight

Replace


glowBloom : real [default: 0]

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 0glowBloom set to 0.5


glowEnabled : bool [default: false]

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


glowHDRMaximumValue : real [default: 12.0]

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

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


glowHDRMinimumValue : real [default: 1.0]

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

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


glowHDRScale : real [default: 2.0]

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.


glowIntensity : real [default: 1]

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.25glowIntensity of 1.25


glowLevel : int [default: 1]

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 valueExample
One

One | Two

One | Two | Three

One | Two | Three | Four


glowQualityHigh : bool [default: false]

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

Note: Enabling this is a trade off between rendering quality and performance. Consider if dithering can be used instead.


glowStrength : real [default: 1]

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, and 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.5glowStrength of 1.5


glowUseBicubicUpscale : bool [default: false]

Reduces the aliasing artifacts and boxing in the glow effect.

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


lensFlareApplyDirtTexture : bool [default: false]

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

Dirt texture disabledDefault dirty texture enabled

See also lensFlareLensDirtTexture.


lensFlareApplyStarburstTexture : bool [default: false]

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

Starburst texture disabledDefault starburst texture enabled

See also lensFlareLensStarburstTexture.


lensFlareBloomBias : real [default: 0.95]

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.81Bias of 0.31


lensFlareBloomScale : real [default: 10]

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.81Scale 20, bias 0.81


lensFlareBlurAmount : real [default: 3]

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

Blur amount set to 0Blur amount set to 30


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

Sets the direction of the camera in the scene.


lensFlareDistortion : real [default: 5]

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

Distortion set to 0Distortion set to 15


lensFlareEnabled : bool [default: false]

Enables the lens flare effect.

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


lensFlareGhostCount : int [default: 4]

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

Ghost count of 2Ghost count of 16


lensFlareGhostDispersal : real [default: 0.5]

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.25Ghost dispersal of 0.90


lensFlareHaloWidth : real [default: 0.25]

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:


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

Set correction factor for roundness of the lens flare halo.


lutEnabled : bool [default: false]

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


lutFilterAlpha : real [default: 1]

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


lutSize : real [default: 16]

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:


sharpnessAmount : real [default: 0.0]

Set the sharpening amount. Valid values are from 0.0 (off) to 1.0 (full).

Filmic tonmapping with sharpness set to 0Filmic 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.

The default value is SceneEnvironment.TonemapModeLinear

ConstantDescription
SceneEnvironment.TonemapModeNoneAll Tonemapping is bypassed. This mode is useful when performing post processing effects.
SceneEnvironment.TonemapModeLinearLinear tonemapping is applied. Colors are gamma corrected and returned in sRGB color space.
SceneEnvironment.TonemapModeAcesAcademy Color Encoding System tonemapping is applied.
SceneEnvironment.TonemapModeHejlDawsonHejl-Dawson tonemapping is applied.
SceneEnvironment.TonemapModeFilmicFilmic tonemapping is applied.

Note: 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 modeExample
None

Linear

Aces

HejlDawson

Filmic


vignetteColor : color [default: "gray"]

Sets the color of the vignette effect.

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


vignetteEnabled : bool [default: false]

Enables the vignette effect.


vignetteRadius : real [default: 0.35]

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

Radius of 0.35Radius of 5.0


vignetteStrength : real [default: 15]

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

Strength of 15Strength of 10


whitePoint : real [default: 1]

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

Note: This value is ignored when using SceneEnvironment.TonemapModeLinear.

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


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