SkyMaterial QML Type

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

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

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:

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.

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

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

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.

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.