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
and use the resulting cubemap as the light probe for image-based lighting
(IBL) on the scene's PBR materials.
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 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 Material
\c AdvancedSky is declared inside the View3D so it shares the same
\c skyLight \l Node (the sun):
\snippet skymaterial/main.qml advanced-sky
\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 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 Choosing How the Sky Is Drawn
\l{SkyMaterial::}{skyboxMode} selects what SkyMaterial produces for the
visible background, independently of the IBL cube used for reflections:
\list
\li \c SkyMaterial.Cubemap samples the radiance cubemap (the same cube
used for image-based lighting), so for a static sky the cube is
rendered once and then sampled cheaply every frame. Background
sharpness is capped at \l{SkyMaterial::}{radianceMapSize}. This is
the lowest per-frame cost when only the camera moves.
\li The \c ScreenSpace modes evaluate the sky shader directly on screen
every frame — at full, half, or quarter resolution per axis. They
decouple the visible background from the IBL cube, giving a crisp
sky for dynamic conditions (a moving sun, animated volumetric
clouds) at the cost of a per-frame render. Lower scales trade
sharpness for speed.
\endlist
Switch the "Skybox mode" combo box in the settings panel to compare the
options live: the cubemap modes stay cheap but soften as the sun and clouds
move, while the screen-space modes track every change sharply.
\section1 Managing Frame Budget
\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. 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 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{Skybox mode} — see \l{SkyMaterial::}{skyboxMode}.
\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. Tap the viewport to give it keyboard focus.
\sa {SkyMaterial}
\sa {SceneEnvironment}
*/