qquick3dskymaterial.cpp

Go to the documentation of this file.

// 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.
 
    A ready-made SkyMaterial with a gradient sky, ground, and sun disk is
    available as \l ProceduralSkyMaterial in the \l{Qt Quick 3D Helpers QML
    Types}{QtQuick3D.Helpers} module. It can be used directly without writing
    any shader code.
 
    \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, vector3d, vector4d \li vec2, vec3, 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 Texture \li sampler2D, samplerCube, sampler3D
    \li The sampler type follows the referenced texture: a \l CubeMapTexture
    becomes a \c samplerCube, a \l Texture with 3D texture data becomes a
    \c sampler3D, and any other \l Texture becomes a \c sampler2D.
    \endtable
 
    A texture property that has no texture set is not exposed to the shader at
    all, so referencing it in the shader code results in a compilation error.
 
    \sa SceneEnvironment::skyMaterial, ProceduralSkyMaterial
*/
 
/*!
    \qmlproperty int SkyMaterial::radianceMapSize
    \since 6.12
    \default 512
 
    Specifies the resolution of the generated environment cubemap used for
    image-based lighting and reflection probes.
 
    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].
 
    \note With \l skyboxMode set to a \c ScreenSpace value, the visible sky is
    evaluated directly on screen and this property only affects the IBL/reflection
    cubemap. With \c SkyMaterial.Cubemap it also determines the sharpness of the
    visible background. When \l enableIBL is \c false, \l skyboxMode is a
    \c ScreenSpace value, and no reflection probes are present, no cubemap is
    generated at all.
 
    \sa skyboxMode, enableIBL
*/
 
/*!
    \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].
 
    \note This property has no effect when \l enableIBL is \c false.
 
    \sa iblRenderFrames, enableIBL
*/
 
/*!
    \qmlproperty int SkyMaterial::iblRenderFrames
    \since 6.12
    \default 0
 
    Controls how the IBL prefilter work is spread across frames.
 
    \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
 
    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.
 
    \note This property has no effect when \l enableIBL is \c false.
 
    \sa iblSampleCount, enableIBL
*/
 
/*!
    \qmlproperty enumeration SkyMaterial::skyboxMode
    \since 6.12
    \default SkyMaterial.Cubemap
 
    Selects what the SkyMaterial produces for the visible background.
 
    \value SkyMaterial.Cubemap          The background samples the radiance
        cubemap (the same cube used for image-based lighting), whose resolution
        follows \l radianceMapSize. For a static sky the cube is rendered once and
        then sampled cheaply every frame, so this is the lowest per-frame cost when
        nothing but the camera is moving. Sharpness is capped at \l radianceMapSize.
    \value SkyMaterial.ScreenSpaceFull    The sky shader is evaluated directly on
        screen at full viewport resolution every frame (sharpest, most costly).
    \value SkyMaterial.ScreenSpaceHalf    Direct screen-space evaluation at half
        resolution per axis (quarter the pixels), upscaled to the viewport.
    \value SkyMaterial.ScreenSpaceQuarter Direct screen-space evaluation at quarter
        resolution per axis (one sixteenth the pixels), upscaled to the viewport.
 
    The \c ScreenSpace modes decouple the visible background from the IBL cube and
    are best for dynamic skies (e.g. moving sun, animated volumetric clouds);
    \c Cubemap is best for static skies. \c Cubemap forces the cubemap to be
    generated even when \l enableIBL is \c false.
 
    \sa radianceMapSize, 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;
    material->skyboxMode = static_cast<QSSGRenderSkyMaterial::SkyboxMode>(m_skyboxMode);
 
    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;
        material->isBackgroundShaderDirty = 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(0, newIblRenderFrames);
    if (m_iblRenderFrames == clamped)
        return;
    m_iblRenderFrames = clamped;
    emit iblRenderFramesChanged();
    update();
}
 
QQuick3DSkyMaterial::SkyboxMode QQuick3DSkyMaterial::skyboxMode() const
{
    return m_skyboxMode;
}
 
void QQuick3DSkyMaterial::setSkyboxMode(SkyboxMode skyboxMode)
{
    if (m_skyboxMode == skyboxMode)
        return;
    m_skyboxMode = skyboxMode;
    emit skyboxModeChanged();
    update();
}
 
QT_END_NAMESPACE