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)

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: 2, since 6.12]

The number of frames over which the IBL prefilter integrates iblSampleCount samples before reaching full convergence. Higher values spread the prefilter cost across more frames, so no single frame pays the full cost; lower values converge faster but make each frame more expensive.

When this value is 1 (or less), the prefilter is evaluated in a single frame (no time-slicing).

Values greater than iblSampleCount have no further effect: the prefilter cannot spread N samples across more than N frames, so the effective convergence period is capped at iblSampleCount frames.

Spreading the work across frames is useful when the procedural sky changes infrequently relative to the frame rate: a high iblSampleCount can be amortized over many frames. Whenever the sky content changes (a tracked property updates, the fragment shader changes, or radianceMapSize changes), accumulation restarts from scratch.

This property was introduced in Qt 6.12.

See also iblSampleCount.

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.

radianceMapSize : int [default: 512, since 6.12]

Specifies the resolution of the generated environment cubemap.

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.