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.
+
+ 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}
+ */