Revision control

// 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.
+ and use the resulting 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
+ The \c AdvancedSky helper is a \l SkyMaterial subclass implementing a
+ physically-based atmospheric scattering model following Hillaire's
+ "A Scalable and Production Ready Sky and Atmosphere Rendering Technique"
+ (2020), with configurable aerosols, ozone, eye altitude, and ray-marched
+ volumetric clouds.
\section1 Setting Up the Scene
- The application is a standard \l Window with a \l View3D. The relevant
- QtQuick3D imports are:
+ The application uses \l ApplicationWindow with a \l View3D filling the
+ window. A settings panel overlays the left edge and slides in and out
+ when the toggle button is clicked. The relevant QtQuick3D imports are:
\snippet skymaterial/main.qml import
- \section1 Defining the Sky Materials
+ \section1 Defining the Sky Material
- 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:
+ \c AdvancedSky is declared inside the View3D so it shares the same
+ \c skyLight \l Node (the sun):
- \snippet skymaterial/main.qml sky-materials
+ \snippet skymaterial/main.qml advanced-sky
- 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.
+ \c AdvancedSky is a \l SkyMaterial subclass defined in \c AdvancedSky.qml.
+ Its QML properties are automatically forwarded as uniforms to the fragment
+ shader.
\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:
+ Assigning the sky material 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
+ \section1 Managing Frame Budget
- 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.
+ \l{SkyMaterial::}{iblRenderFrames} spreads the IBL prefilter across several
+ frames: the same total \l{SkyMaterial::}{iblSampleCount} is integrated
+ incrementally, one slice per frame, until convergence. The default value of
+ \c 0 runs sample accumulation, normalization, and irradiance all in a single
+ frame. Setting it higher amortizes the prefilter cost, keeping the scene
+ responsive when IBL sample counts are high.
\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.
+ the "Animate sun" toggle is on. Each change in sun position invalidates the
+ IBL accumulator, but with \l{SkyMaterial::}{iblRenderFrames} set
+ appropriately the prefilter cost is spread across frames and no single frame
+ pays the full cost.
\snippet skymaterial/main.qml sun-animation
- \section1 Controls
+ \section1 Settings Panel
+
+ The settings panel slides in and out over the \l View3D, toggled by the
+ button in the top-left corner of the viewport. It is divided into two
+ groups.
+
+ \section2 Sky
+
+ Controls for the sky appearance and clouds.
+
+ \list
+ \li \b{Animate sun} — runs a ping-pong sun sweep across the horizon.
+ \li \b{Cycle speed} — sweep speed for the sun animation.
+ \li \b{Sun elevation} — manual sun position in degrees (0° = dawn,
+ 90° = noon, 180° = dusk).
+ \li \b{Enable clouds} — toggles ray-marched volumetric clouds.
+ \li \b{Cloud coverage} — fraction of the sky covered by clouds
+ (0 = clear, 1 = overcast).
+ \li \b{Animate wind} — drifts the cloud noise texture each frame,
+ continuously invalidating the IBL accumulator — a useful stress test
+ for the frame budget controls.
+ \endlist
+
+ \section2 Rendering
+
+ Controls that map directly to \l SkyMaterial base-class properties.
\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.
+ \li \b{IBL render frames} — see \l{SkyMaterial::}{iblRenderFrames}.
+ \li \b{Enable IBL} — see \l{SkyMaterial::}{enableIBL}.
+ \li \b{IBL sample count} — see \l{SkyMaterial::}{iblSampleCount}.
+ \li \b{Radiance map size} — see \l{SkyMaterial::}{radianceMapSize}.
\endlist
- The camera responds to standard \l WasdController navigation — W/A/S/D
- plus mouse drag to look around.
+ The camera responds to standard \l WasdController navigation — W/A/S/D plus
+ mouse drag to look around. Tap the viewport to give it keyboard focus.
\sa {SkyMaterial}
\sa {SceneEnvironment}
*/