Qt Quick 3D - Volumetric Fog Extension Example

Overview

This example implements volumetric fog as a Qt Quick 3D render extension, and shows how to reuse the extension in your own project.

The extension divides the camera frustum into a 3D grid of froxels, frustum-aligned voxels, and uses a compute shader to accumulate the light that scatters toward the camera in each cell. A post-processing effect then composites the result onto the rendered frame.

Controls

Drag with the mouse to orbit the camera around the scene. Use the settings panel to change the lighting, the fog, the post-processing, and the shadow settings.

Implementation

The VolumetricFogExtension type implements the volumetric fog extension. It lives in the separate VFExtension subproject, so you can add it to your own project unchanged.

Set the following properties on VolumetricFogExtension:

VolumetricFogExtension {
    id: froxelExtension
    froxelWidth: 160
    froxelHeight: 96
    froxelDepth: 96
    nearPlane: 1.0
    farPlane: 4000.0
    fogVolumes: [ fogSphere ]

    iesTexture: settings.iesLights ? iesAtlasTexture : null
    iesCount: iesTextureData.sources.length
    iesLightProfiles: [
        IESLightProfileIndex { light: pinkSpot; index: settings.iesLightIndex; intensity: 0.5}
    ]
}

The froxelWidth, froxelHeight, and froxelDepth properties define the resolution of the froxel grid that the compute shader fills. A higher resolution produces more detailed light scattering, but uses more GPU memory and compute time.

The nearPlane and farPlane properties define the depth range that the volumetric effect covers. Match them to the clip distances of the PerspectiveCamera.

The fogVolumes property holds the list of Fog3DVolume nodes that define where fog is present in the scene.

IES Light Profiles

A photometric profile from the Illuminating Engineering Society (IES) shapes the angular light distribution of a spot light. The iesTexture property takes a Texture whose data comes from an IESTextureData object. That object parses .ies files and packs them into a 2D atlas texture. The iesCount property specifies how many profiles the atlas holds, and iesLightProfiles maps individual lights to profile indices through IESLightProfileIndex objects.

Texture {
    id: iesAtlasTexture
    textureData: IESTextureData {
        id: iesTextureData
        sources: [
            "qrc:/assets/l0.ies",
            "qrc:/assets/l1.ies",
            "qrc:/assets/l2.ies",
            "qrc:/assets/l3.ies",
            "qrc:/assets/l4.ies",
            "qrc:/assets/l5.ies",
        ]
    }

    tilingModeHorizontal: Texture.ClampToEdge
    tilingModeVertical: Texture.ClampToEdge
    minFilter: Texture.Linear
    magFilter: Texture.Linear
    generateMipmaps: false
}

Attaching the Extension to a View3D

Add the extension to the extensions list of the View3D. The render pipeline then invokes the extension's compute shader once per frame:

View3D {
    extensions: [ froxelExtension ]
}

Fog Volumes

A Fog3DVolume node defines a fog region in the scene. The type property selects one of two shapes, Fog3DVolume.Sphere or Fog3DVolume.Box, and the extents property sets the bounding dimensions. The color and density properties control the appearance.

Advancing noiseOffset each frame animates the noise. To make the density fall off with height, set heightEnabled to true and adjust leastIntenseY, mostIntenseY, and heightCurve:

Fog3DVolume {
    id: fogSphere
    type: Fog3DVolume.Sphere
    extents: Qt.vector3d(5000, 5000, 5000)
    color: settings.fogVolumeColor
    density: settings.fogVolumeDensity
    noiseOffset: Qt.vector3d(baseNode.time * 0.1 * settings.fogSpeed,
                             baseNode.time * 0.02 * settings.fogSpeed,
                             baseNode.time * 0.01 * settings.fogSpeed)
    noiseScale: settings.fogVolumeNoiseScale
    heightEnabled: settings.fogVolumeHeightEnabled
    leastIntenseY: settings.fogVolumeHeightLeastY
    mostIntenseY: settings.fogVolumeHeightMostY
    heightCurve: settings.fogVolumeHeightCurve
}

VolumetricFogEffect

The extension exposes its result through the read-only froxelTexture property, a 3D RGBA texture that holds the accumulated light scattering data for each froxel. Add the VolumetricFogEffect post-processing effect to the ExtendedSceneEnvironment to consume that texture. The effect ray-marches through the froxel texture and composites the volumetric light onto the rendered frame:

effects: [
    VolumetricFogEffect {
        froxelTexture: froxelExtension.froxelTexture
        cameraPosition: camera.scenePosition
        cameraForward: camera.forward
        invViewMatrix: camera.sceneTransform
        marchSteps: froxelExtension.froxelDepth
        nearPlane: froxelExtension.nearPlane
        farPlane: froxelExtension.farPlane
        frameBaseJitter: se.temporalAAEnabled &&
                         se.temporalAAMode === SceneEnvironment.TAAMotionVector &&
                         se.antialiasingMode !== SceneEnvironment.MSAA ? 1.0 : 0.0
        jitterIntensity: settings.jitterIntensity
    }
]

The marchSteps property controls the number of ray marching steps. Match it to froxelDepth. The frameBaseJitter and jitterIntensity properties enable temporal dithering, which reduces banding artifacts when the scene also uses temporal antialiasing.

Reusing the Extension in Your Own Project

The VFExtension subproject builds as a QML module of its own. To use it in another project, copy the directory, add it with add_subdirectory(), and link the library into your target:

add_subdirectory(VFExtension)

target_link_libraries(myapp PRIVATE VFExtension)

Then import the module in QML:

import VFExtension

Example project @ code.qt.io