Revision control

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
// Qt-Security score:significant reason:default
#include <QtQuick3D/private/qquick3dskymaterial_p.h>
#include <QtQuick3D/private/qquick3dobject_p.h>
#include <QtQuick3DRuntimeRender/private/qssgrenderskymaterial_p.h>
#include <QtCore/qmath.h>
#include <QtGui/qquaternion.h>
QT_BEGIN_NAMESPACE
/*!
\qmltype SkyMaterial
\inqmlmodule QtQuick3D
\since 6.12
\brief Renders a procedural sky and generates image-based lighting data.
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.
\note Changes to shader code or properties may take a frame or more
before being reflected in the generated IBL.
\section1 Shader
The shader has access to the built-in variable \c qt_eyeDir (\c 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 \c MAIN() entry point, which is
executed for each fragment generated while rendering the cubemap.
The final pixel color must be written to \c FRAGCOLOR (\c vec4), which
is the output variable of the fragment shader.
A minimal shader example:
\badcode
void MAIN()
{
vec3 dir = normalize(qt_eyeDir);
// Output color (encoded direction as RGB)
FRAGCOLOR = vec4(dir * 0.5 + 0.5, 1.0);
}
\endcode
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:
\table
\header
\li QML Type
\li Shader Type
\li Notes
\row \li real, int, bool \li float, int, bool \li
\row \li color \li vec4 \li sRGB is converted to linear space
\row \li vector2d \li vec2 \li
\row \li vector3d \li vec3 \li
\row \li vector4d \li vec4 \li
\row \li matrix4x4 \li mat4 \li
\row \li quaternion \li vec4 \li w stores scalar component
\row \li rect \li vec4 \li
\row \li point, size \li vec2 \li
\row \li TextureInput \li sampler2D \li
\endtable
*/
/*!
\qmlproperty int SkyMaterial::radianceMapSize
\since 6.12
\default 512
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].
*/
/*!
\qmlproperty url SkyMaterial::fragmentShader
\since 6.12
Specifies a fragment shader loaded from a file or resource URL.
If both \l fragmentShader and \l fragmentShaderCode are set,
\l fragmentShaderCode takes precedence.
If no shader is specified, a built-in debug shader is used.
\sa fragmentShaderCode
*/
/*!
\qmlproperty string SkyMaterial::fragmentShaderCode
\since 6.12
Specifies inline fragment shader source code.
This behaves identically to \l fragmentShader and uses the same
execution model, built-ins, and automatic property-to-uniform mapping.
If both \l fragmentShader and \l fragmentShaderCode are set,
this property takes precedence.
\sa fragmentShader
*/
/*!
\qmlproperty bool SkyMaterial::enableIBL
\since 6.12
\default true
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.
\sa SceneEnvironment::lightProbe
*/
/*!
\qmlproperty int SkyMaterial::iblSampleCount
\since 6.12
\default 32
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].
- \sa iblRenderFrames
+ \note This property has no effect when \l enableIBL is \c false.
+
+ \sa iblRenderFrames, enableIBL
*/
/*!
\qmlproperty int SkyMaterial::iblRenderFrames
\since 6.12
- \default 2
+ \default 0
- The number of frames over which the IBL prefilter integrates \l 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.
+ Controls how the IBL prefilter work is spread across frames.
- When this value is \c 1 (or less), the prefilter is evaluated in a single
- frame (no time-slicing).
+ \list
+ \li \b 0 — Everything in one frame: sample accumulation, normalization, and
+ irradiance are all evaluated in the same frame.
+ \li \b {N ≥ 1} — The \l iblSampleCount samples are divided across N slice
+ frames (\c ceil(iblSampleCount / N) samples per frame), followed by a
+ dedicated normalization and irradiance frame.
+ \endlist
- Values greater than \l iblSampleCount have no further effect: the prefilter
- cannot spread N samples across more than N frames, so the effective
- convergence period is capped at \l iblSampleCount frames.
+ Higher values amortize the GGX prefilter cost across more frames, which is
+ useful when the sky changes infrequently and a high \l iblSampleCount is
+ required for quality.
- Spreading the work across frames is useful when the procedural sky changes
- infrequently relative to the frame rate: a high \l iblSampleCount can be
- amortized over many frames. Whenever the sky content changes (a tracked
- property updates, the fragment shader changes, or \l radianceMapSize
- changes), accumulation restarts from scratch.
+ \note This property has no effect when \l enableIBL is \c false.
- \sa iblSampleCount
+ \sa iblSampleCount, enableIBL
*/
QQuick3DSkyMaterial::QQuick3DSkyMaterial(QQuick3DObject *parent)
: QQuick3DObject(parent), QQuick3DPropertyChangedTracker(this, QQuick3DSuperClassInfo<QQuick3DSkyMaterial>())
{
}
int QQuick3DSkyMaterial::radianceMapSize() const
{
return m_radianceMapSize;
}
QSSGRenderGraphObject *QQuick3DSkyMaterial::updateSpatialNode(QSSGRenderGraphObject *node)
{
QSSGRenderSkyMaterial *material = static_cast<QSSGRenderSkyMaterial *>(node);
if (!material) {
material = new QSSGRenderSkyMaterial;
material->isDirty = true;
}
// isDirty tracks whether the procedural cubemap content needs to be regenerated.
// Toggling enableIBL alone reuses the same cubemap, so it isn't a content change.
if (material->radianceMapSize != m_radianceMapSize || (m_dirtyFlag & (Dirty::FragmentShader | Dirty::TrackedProperty))) {
material->isDirty = true;
}
material->radianceMapSize = m_radianceMapSize;
material->enableIBL = m_enableIBL;
material->iblSampleCount = m_iblSampleCount;
// Convert user-facing "frames to converge" to the render-side per-frame sample budget.
// 1 frame = no time-slicing (mapped to 0, the render struct's "single-frame" sentinel).
// Otherwise ceil(sampleCount/frameCount) so accumulation always finishes within the
// requested frame budget, even when the division isn't exact.
material->iblSamplesPerFrame = (m_iblRenderFrames <= 1) ? 0 : (m_iblSampleCount + m_iblRenderFrames - 1) / m_iblRenderFrames;
+ material->iblRenderFrames = m_iblRenderFrames;
if (m_dirtyFlag & Dirty::FragmentShader) {
const QQmlContext *context = qmlContext(this);
material->fragmentShaderSource = !m_fragmentShaderCode.isEmpty() ? m_fragmentShaderCode.toUtf8()
: !m_fragmentShader.isEmpty() ? QSSGShaderUtils::resolveShader(m_fragmentShader, context, material->shaderPathKey)
: QByteArray();
material->isFragmentShaderDirty = true;
}
if (m_dirtyFlag & Dirty::TrackedProperty) {
material->propertyUniforms = extractProperties();
}
m_dirtyFlag = 0;
return QQuick3DObject::updateSpatialNode(material);
}
void QQuick3DSkyMaterial::markTrackedPropertyDirty(QMetaProperty property, DirtyPropertyHint hint)
{
Q_UNUSED(property);
Q_UNUSED(hint);
markDirty(Dirty::TrackedProperty);
}
void QQuick3DSkyMaterial::markDirty(Dirty v)
{
m_dirtyFlag |= v;
update();
}
void QQuick3DSkyMaterial::setRadianceMapSize(int radianceMapSize)
{
// Snap to the nearest power of two, then clamp to [8, 2048]. We store the
// normalized value so reading the property back reflects the resolution the
// renderer will actually use.
const int upper = qNextPowerOfTwo(qMax(1, radianceMapSize));
const int lower = upper >> 1;
radianceMapSize = (radianceMapSize - lower < upper - radianceMapSize) ? lower : upper;
radianceMapSize = qBound(8, radianceMapSize, 2048);
if (m_radianceMapSize == radianceMapSize)
return;
m_radianceMapSize = radianceMapSize;
emit radianceMapSizeChanged();
update();
}
QUrl QQuick3DSkyMaterial::fragmentShader() const
{
return m_fragmentShader;
}
void QQuick3DSkyMaterial::setFragmentShader(const QUrl &newFragmentShader)
{
if (m_fragmentShader == newFragmentShader)
return;
m_fragmentShader = newFragmentShader;
emit fragmentShaderChanged();
markDirty(Dirty::FragmentShader);
}
QString QQuick3DSkyMaterial::fragmentShaderCode() const
{
return m_fragmentShaderCode;
}
void QQuick3DSkyMaterial::setFragmentShaderCode(const QString &newFragmentShaderCode)
{
if (m_fragmentShaderCode == newFragmentShaderCode)
return;
m_fragmentShaderCode = newFragmentShaderCode;
emit fragmentShaderCodeChanged();
markDirty(Dirty::FragmentShader);
}
bool QQuick3DSkyMaterial::enableIBL() const
{
return m_enableIBL;
}
void QQuick3DSkyMaterial::setEnableIBL(bool newEnableIBL)
{
if (m_enableIBL == newEnableIBL)
return;
m_enableIBL = newEnableIBL;
emit enableIBLChanged();
update();
}
int QQuick3DSkyMaterial::iblSampleCount() const
{
return m_iblSampleCount;
}
void QQuick3DSkyMaterial::setIblSampleCount(int newIblSampleCount)
{
const int clamped = qBound(1, newIblSampleCount, 1024);
if (m_iblSampleCount == clamped)
return;
m_iblSampleCount = clamped;
emit iblSampleCountChanged();
update();
}
int QQuick3DSkyMaterial::iblRenderFrames() const
{
return m_iblRenderFrames;
}
void QQuick3DSkyMaterial::setIblRenderFrames(int newIblRenderFrames)
{
- const int clamped = qMax(1, newIblRenderFrames);
+ const int clamped = qMax(0, newIblRenderFrames);
if (m_iblRenderFrames == clamped)
return;
m_iblRenderFrames = clamped;
emit iblRenderFramesChanged();
update();
}
QT_END_NAMESPACE