SkyMaterial QML Type | Qt Quick 3D | Qt 6.12.0
Description: Renders a procedural sky and generates image-based lighting data.
Keywords: qmltype

- Qt 6.12
- Qt Quick 3D
- QML Types
- SkyMaterial
- Qt Quick 3D | Commercial or GPLv3

# SkyMaterial QML Type

Renders a procedural sky and generates image-based lighting data. More...

Import Statement: | `import QtQuick3D`
Since: | Qt 6.12

- List of all members, including inherited members

## Properties

- enableIBL : bool `(since 6.12)`
- fragmentShader : url `(since 6.12)`
- fragmentShaderCode : string `(since 6.12)`
- iblRenderFrames : int `(since 6.12)`
- iblSampleCount : int `(since 6.12)`
- radianceMapSize : int `(since 6.12)`
- skyboxMode : enumeration `(since 6.12)`

## Detailed Description

SkyMaterial renders a sky environment into a cubemap using custom fragment shader code. The resulting cubemap can optionally be filtered and used as image-based lighting (IBL) for physically based rendering.

The shader is evaluated for all six faces of the cubemap and may implement arbitrary procedural skies, gradients, or analytical models.

The generated cubemap is used both as the visible scene background and as the source for image-based lighting when enabled.

Note: Changes to shader code or properties may take a frame or more before being reflected in the generated IBL.

## Shader

The shader has access to the built-in variable `qt_eyeDir` (`vec3`), which provides the non-normalized direction vector from the center of the cubemap to the current sample direction.

The fragment shader must define a `MAIN()` entry point, which is executed for each fragment generated while rendering the cubemap.

The final pixel color must be written to `FRAGCOLOR` (`vec4`), which is the output variable of the fragment shader.

A minimal shader example:

     void MAIN()
     {
         vec3 dir = normalize(qt_eyeDir);

         // Output color (encoded direction as RGB)
         FRAGCOLOR = vec4(dir * 0.5 + 0.5, 1.0);
     }

Custom QML properties declared on SkyMaterial are automatically exposed as uniforms in the fragment shader. The property name must match the GLSL variable name. No explicit uniform declaration is required.

The following type mappings are supported:

QML Type | Shader Type | Notes
--- | --- | ---
real, int, bool | float, int, bool |
color | vec4 | sRGB is converted to linear space
vector2d | vec2 |
vector3d | vec3 |
vector4d | vec4 |
matrix4x4 | mat4 |
quaternion | vec4 | w stores scalar component
rect | vec4 |
point, size | vec2 |
TextureInput | sampler2D |

## Property Documentation

### enableIBL : bool `[default: true, since 6.12]`

Determines whether the generated sky cubemap is used for image-based lighting.

When enabled, the engine generates filtered radiance and irradiance maps used for ambient lighting and reflections in physically based rendering.

When disabled, the sky is only rendered as a visual background and no IBL preprocessing is performed.

This property was introduced in Qt 6.12.

See also SceneEnvironment::lightProbe.

### fragmentShader : url `[since 6.12]`

Specifies a fragment shader loaded from a file or resource URL.

If both fragmentShader and fragmentShaderCode are set, fragmentShaderCode takes precedence.

If no shader is specified, a built-in debug shader is used.

This property was introduced in Qt 6.12.

See also fragmentShaderCode.

### fragmentShaderCode : string `[since 6.12]`

Specifies inline fragment shader source code.

This behaves identically to fragmentShader and uses the same execution model, built-ins, and automatic property-to-uniform mapping.

If both fragmentShader and fragmentShaderCode are set, this property takes precedence.

This property was introduced in Qt 6.12.

See also fragmentShader.

### iblRenderFrames : int `[default: 0, since 6.12]`

Controls how the IBL prefilter work is spread across frames.

- 0 — Everything in one frame: sample accumulation, normalization, and irradiance are all evaluated in the same frame.
- N ≥ 1 — The iblSampleCount samples are divided across N slice frames (`ceil(iblSampleCount / N)` samples per frame), followed by a dedicated normalization and irradiance frame.

Higher values amortize the GGX prefilter cost across more frames, which is useful when the sky changes infrequently and a high iblSampleCount is required for quality.

Note: This property has no effect when enableIBL is `false`.

This property was introduced in Qt 6.12.

See also iblSampleCount and enableIBL.

### iblSampleCount : int `[default: 32, since 6.12]`

The total number of GGX importance samples evaluated per output texel of the filtered radiance map. Higher values reduce shimmering on high-frequency features such as a sun disk, at the cost of generation time.

Values are clamped to the range [1, 1024].

Note: This property has no effect when enableIBL is `false`.

This property was introduced in Qt 6.12.

See also iblRenderFrames and enableIBL.

### radianceMapSize : int `[default: 512, since 6.12]`

Specifies the resolution of the generated environment cubemap used for image-based lighting and reflection probes.

Higher values improve reflection sharpness and lighting quality, especially for glossy materials, but increase memory usage and rendering cost.

Values are snapped to the nearest power of two and clamped to the range [8, 2048].

Note: With skyboxMode set to a `ScreenSpace` value, the visible sky is evaluated directly on screen and this property only affects the IBL/reflection cubemap. With `SkyMaterial.Cubemap` it also determines the sharpness of the visible background. When enableIBL is `false`, skyboxMode is a `ScreenSpace` value, and no reflection probes are present, no cubemap is generated at all.

This property was introduced in Qt 6.12.

See also skyboxMode and enableIBL.

### skyboxMode : enumeration `[default: SkyMaterial.Cubemap, since 6.12]`

Selects what the SkyMaterial produces for the visible background.

Constant | Description
--- | ---
`SkyMaterial.Cubemap` | The background samples the radiance cubemap (the same cube used for image-based lighting), whose resolution follows radianceMapSize. For a static sky the cube is rendered once and then sampled cheaply every frame, so this is the lowest per-frame cost when nothing but the camera is moving. Sharpness is capped at radianceMapSize.
`SkyMaterial.ScreenSpaceFull` | The sky shader is evaluated directly on screen at full viewport resolution every frame (sharpest, most costly).
`SkyMaterial.ScreenSpaceHalf` | Direct screen-space evaluation at half resolution per axis (quarter the pixels), upscaled to the viewport.
`SkyMaterial.ScreenSpaceQuarter` | Direct screen-space evaluation at quarter resolution per axis (one sixteenth the pixels), upscaled to the viewport.

The `ScreenSpace` modes decouple the visible background from the IBL cube and are best for dynamic skies (e.g. moving sun, animated volumetric clouds); `Cubemap` is best for static skies. `Cubemap` forces the cubemap to be generated even when enableIBL is `false`.

This property was introduced in Qt 6.12.

See also radianceMapSize and enableIBL.