SceneEnvironment QML Type | Qt Quick 3D 5.15.0

- Qt 5.15
- Qt Quick 3D
- QML Types
- SceneEnvironment QML Type
- Qt Quick 3D | Commercial or GPLv3

# SceneEnvironment QML Type

Lets you configure how a scene is rendered. More...

Import Statement: | import QtQuick3D 1.15
Inherits: | Object3D

- List of all members, including inherited members

## Properties

- antialiasingMode : enumeration
- antialiasingQuality : enumeration
- aoBias : float
- aoDistance : float
- aoDither : bool
- aoSampleRate : int
- aoSoftness : float
- aoStrength : float
- backgroundMode : enumeration
- clearColor : color
- depthPrePassEnabled : bool
- depthTestEnabled : bool
- effects : List<QtQuick3D::Effect>
- fastImageBasedLightingEnabled : bool
- lightProbe : QtQuick3D::Texture
- probeBrightness : float
- probeFieldOfView : float
- probeHorizon : float
- temporalAAEnabled : bool
- temporalAAStrength : float

## Detailed Description

SceneEnvironment defines the environment in which the scene is rendered, which defines how the scene gets rendered globaly.

## Property Documentation

antialiasingMode : enumeration

This property controls the antialiasing mode that is applied when rendering the scene.

Possible values are:

Constant | Description
--- | ---
`SceneEnvironment.NoAA` | No antialiasing is applied.
`SceneEnvironment.SSAA` | Supersample antialiasing is applied.
`SceneEnvironment.MSAA` | Multisample antialiasing is applied.
`SceneEnvironment.ProgressiveAA` | Progressive antialiasing is applied.

The default value is `SceneEnvironment.NoAA`.

Supersampling

The scene is rendered in a higher resolution, and then scaled down to actual resolution.

Pros: High quality. Antialiases all scene content and not just geometry silhouettes.

Cons: Usually more expensive than MSAA. Increases video memory usage. Only supported with View3D items with renderMode set to Offscreen as the technique implies rendering to a texture first.

Multisampling

The edges of geometry are super-sampled, resulting in smoother silhouettes. This technique has no effect on the materials inside geometry, however.

Pros: Works with any View3D item regardless of the renderMode. Good results on geometry silhouettes, where aliasing is often most noticeable; works with fast animation without issues. Performance depends purely on the system's (GPU) capabilities.

Cons: Does not help with texture or reflection issues. Increases video memory usage. Can be expensive to use on less powerful graphics hardware. When using View3D items with a renderMode other than Offscreen, MSAA can only be controlled on a per-window basis, it cannot be enabled or disabled separately for the individual View3D items.

Note: For View3D items with a renderMode other than Offscreen, multisampling can only be enabled via the QSurfaceFormat of the QQuickWindow or QQuickView. This will then affect all content, both 2D and 3D, in that window.

Progressive antialiasing

This property enables and sets the level of progressive antialiasing applied to the scene.

When all content of the scene has stopped moving, the camera is jiggled very slightly between frames, and the result of each new frame is blended with the previous frames. The more frames you accumulate, the better looking the result.

Pros: Provides great results when all content in the scene is standing still.

Cons: Does not take effect if any visual changes are occurring. Expensive due to having to accumulate and blend. Increases video memory usage.

This property was introduced in Qt 5.15.

antialiasingQuality : enumeration

This property sets the level of antialiasing applied to the scene. Behavior depends on used antialiasingMode. With antialiasingMode property set to `NoAA` this property doesn't have an effect.

Possible values are:

Constant | Description
--- | ---
`SceneEnvironment.Medium` | SSAA: Antialiasing uses 1.2x supersampling resolution. MSAA: Antialiasing uses 2 samples per pixel. ProgressiveAA: Antialiasing uses 2 frames for final image.
`SceneEnvironment.High` | SSAA: Antialiasing uses 1.5x supersampling resolution. MSAA: Antialiasing uses 4 samples per pixel. ProgressiveAA: Antialiasing uses 4 frames for final image.
`SceneEnvironment.VeryHigh` | SSAA: Antialiasing uses 2.0x supersampling resolution. MSAA: Antialiasing uses 8 samples per pixel. ProgressiveAA: Antialiasing uses 8 frames for final image.

The default value is `SceneEnvironment.High`

This property was introduced in Qt 5.15.

aoBias : float

This property defines a cutoff distance preventing objects from exhibiting ambient occlusion at close distances. Higher values increase the distance required between objects before ambient occlusion is seen.

Note: If you see ambient occlusion shadowing on objects where there should be no shadowing, increase the value slightly to clip away close results.

aoDistance : float

This property defines roughly how far ambient occlusion shadows spread away from objects. Greater distances cause increasing impact to performance.

aoDither : bool

When this property is enabled it scatters the edges of the ambient occlusion shadow bands to improve smoothness (at the risk of sometimes producing obvious patterned artifacts).

Note: Very large distances between the clipping planes of your camera may cause problems with ambient occlusion. If you are seeing odd banding in your ambient occlusion, try adjusting the clipFar property of your camera to be closer to your content.

See also PerspectiveCamera.clipFar and OrthographicCamera.clipFar.

aoSampleRate : int

This property defines ambient occlusion quality (more shades of gray) at the expense of performance.

aoSoftness : float

This property how smooth the edges of the ambient occlusion shading are.

aoStrength : float

This property defines the amount of ambient occulusion applied. Ambient occulusion is a form of approximated global illumination which causes non-directional self-shadowing where objects are close together. A value of 100 causes full darkness shadows; lower values cause the shadowing to appear lighter. A value of 0 disables ambient occlusion entirely, improving performance at a cost to the visual realism of 3D objects rendered in the scene.

All values other than 0 have the same impact to the performance.

The default value is `0`

backgroundMode : enumeration

This property controls if and how the background of the scene should be cleared.

Constant | Description
--- | ---
`SceneEnvironment.Transparent` | The scene is cleared to be transparent. This is useful to render 3D content on top of another item.
`SceneEnvironment.Color` | The scene is cleared with the color specified by the clearColor property.
`SceneEnvironment.Skybox` | The scene will not be cleared, but instead a Skybox or Skydome will be rendered. The Skybox is defined using the HDRI map defined in the lightProbe property.

The default value is `SceneEnvironment.Color`

clearColor : color

This property defines which color will be used to clear the viewport when using `SceneEnvironment.Color` for the backgroundMode property.

The default value is `Qt::black`

See also backgroundMode.

depthPrePassEnabled : bool

When enabled, the renderer performs a Z-prepass for opaque objects, meaning it renders them with a simple shader and color write disabled in order to get the depth buffer pre-filled before issuing draw calls for the main rendering passes.

This can improve performance depending on the scene contents. It is typically scenes with lots of overlapping objects and expensive fragment shading that benefit from this. At the same time, it is worth noting that the renderer performs front to back sorting for opaque objects, which in itself helps reducing unnecessary fragment shading, and therefore the Z-prepass does not always bring significant improvements.

On GPUs that use a tiled rendering architecture, which is common in mobile and embedded systems, it is recommended to set this to `false`.

The default value is `false`.

Note: This property has no effect when depth testing is disabled.

depthTestEnabled : bool

When this property is set to `false`, the Z-buffer is not used, the depth test is skipped, and all objects, including fully opaque ones, are rendered in one go sorted back to front.

This is an optimization that can cause rendering errors if disabled.

The default value is `true`.

effects : List<QtQuick3D::Effect>

This property contains a list of post-processing effects that will be applied to the entire viewport. The result of each effect is fed to the next so the order is significant.

This property was introduced in Qt 5.15.

fastImageBasedLightingEnabled : bool

When this property is enabled more shortcuts are taken to approximate the light contributes of the light probe at the expense of quality.

lightProbe : QtQuick3D::Texture

This property defines an image (preferably a high-dynamic range image) to use to light the scene, either instead of or in addition to standard lights. If selected, note that this image will be used as the environment for any custom materials, instead of the environment map often associated with them.

probeBrightness : float

This property modifies the amount of light emitted by the light probe.

probeFieldOfView : float

This property defines the image source field of view for the case of using a camera source as the IBL probe.

probeHorizon : float

This property when defined with increasing values adds darkness (black) to the bottom half of the environment, forcing the lighting to come predominantly from the top of the image (and removing specific reflections from the lower half).

temporalAAEnabled : bool

When this property is enabled temporal antialiasing will be used.

The camera is jiggled very slightly between frames, and the result of each new frame is blended with the previous frame.

Note: Temporal antialiasing doesn't have an effect when antialiasingMode is MSAA.

Note: When combined with ProgressiveAA antialiasingMode, temporalAA is used when scene animates while ProgressiveAA is used once animations stop.

Pros: Due to the jiggling camera it finds real details that were otherwise lost; low impact on performance.

Cons: Fast-moving objects cause one-frame ghosting.

temporalAAStrength : float

This property modifies the amount of temporal movement (antialiasing). This has an effect only when temporalAAEnabled property is true.

This property was introduced in Qt 5.15.

See also temporalAAEnabled.