Revision control

Copy as Markdown

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example skymaterial
\ingroup quick3d-examples
\title Qt Quick 3D - Sky Material Example
\examplecategory {3D}
\brief Demonstrates procedural sky rendering and image-based lighting with SkyMaterial.
\image skymaterial-example.webp
{Procedural atmospheric sky with PBR spheres reflecting the environment}
This example shows how to use \l SkyMaterial to render a procedural sky
directly from a fragment shader and use the same procedural cubemap as the
light probe for image-based lighting (IBL) on the scene's PBR materials.
Two SkyMaterial subclasses are provided side by side:
\list
\li \c BasicSky — a small shader that produces a gradient sky with a
sun disk, suitable as a starting point for stylized or game-style
skies.
\li \c AdvancedSky — a physically-based atmospheric scattering model
following Hillaire's "A Scalable and Production Ready Sky and
Atmosphere Rendering Technique" (2020), with configurable aerosols,
ozone, and eye altitude.
\endlist
\section1 Setting Up the Scene
The application is a standard \l Window with a \l View3D. The relevant
QtQuick3D imports are:
\snippet skymaterial/main.qml import
\section1 Defining the Sky Materials
Both sky variants are declared inside the View3D so they share the same
skyLight \l Node (the sun). The active material is selected by a
property that the UI swaps between the two:
\snippet skymaterial/main.qml sky-materials
Each helper file is a \l SkyMaterial subclass with its own fragment shader
and an exported set of QML properties; the properties are automatically
forwarded as uniforms to the shader. See \c BasicSky.qml and
\c AdvancedSky.qml.
\section1 Image-Based Lighting
Assigning the active SkyMaterial to \l SceneEnvironment::skyMaterial uses
the procedurally rendered cubemap both as the visible background and as
the source for image-based lighting on the PBR materials in the scene:
\snippet skymaterial/main.qml environment
The smoothest sphere in the demo mirrors the procedural sky almost
perfectly; the rougher spheres show progressively blurred reflections,
produced by SkyMaterial's GGX prefilter chain over the procedural cubemap.
\section1 Time-Sliced IBL Convergence
Generating the prefiltered IBL cubemap is the most expensive part of a
procedural sky. SkyMaterial exposes \l {SkyMaterial::}{iblRenderFrames}
so that the cost can be spread across several frames: the same total
\l {SkyMaterial::}{iblSampleCount} is integrated incrementally, with the
accumulator advancing each frame until convergence.
With the default value of \c 1 the prefilter runs in a single frame.
Setting it higher amortizes the cost, which is useful when the
sky changes infrequently relative to the frame rate, e.g. an animated
sun-sweep that should not stall the main thread on every step.
\section1 Animating the Sun
A \l FrameAnimation drives the sun back and forth across the horizon when
the "Animate sun" toggle is on. Time-slicing pairs naturally with this
kind of slow drift: every sun position invalidates the accumulator, but
the convergence catches up over the next few frames without any single
frame paying the full prefilter cost.
\snippet skymaterial/main.qml sun-animation
\section1 Controls
\list
\li \b{Sky variant} — selects which SkyMaterial subclass is active.
\li \b{Animate sun} — runs the sun sweep across the horizon.
\li \b{Sun elevation} — manual sun position; enabled when the sweep
animation is off.
\li \b{IBL Render frames} — how many frames the prefilter takes to
converge. \c 1 means single-frame (no time-slicing); higher values
spread the cost.
\li \b{IBL sample count} — number of GGX importance samples integrated
per output texel of the prefiltered radiance map. Higher values
reduce shimmering on high-frequency features (e.g. the sun disk)
at the cost of more work per cycle.
\li \b{Radiance map size} — resolution of the procedural environment
cubemap. Higher values sharpen reflections on glossy materials but
increase memory and rendering cost. Internally clamped to the
nearest power-of-two.
\endlist
The camera responds to standard \l WasdController navigation — W/A/S/D
plus mouse drag to look around.
\sa {SkyMaterial}
\sa {SceneEnvironment}
*/