sgl-post-fx 0.9.2

SGL wgpu post-processing effects: screen-space reflections and temporal anti-aliasing derived from DiligentFX
Documentation

sgl-post-fx

SGL's wgpu post-processing effects, including screen-space reflections (SSR), temporal anti-aliasing (TAA) and their shared post-effect context. Implemented in Rust and WGSL, they were derived from DiligentFX and include subsequent fixes and enhancements. This is not a Diligent Graphics product.

The library evolves for SGL3D under its rendering development rules. DiligentFX is its origin, not a promise of 1:1 equivalence or a limit on its features. Improvements may draw on other compatible implementations while preserving their attribution and licences. This crate stays in the SGL workspace and owns GPU effects; SGL3D owns scene conventions and frame integration. It has no dependency on SGL3D.

PROVENANCE.md records the source revisions and useful algorithm and implementation notes. vendor/ in the repository retains the original reference files unedited; the published crate keeps only their licences, source revisions and the blue-noise table source it reads.

  • SSR is AMD's FidelityFX SSSR tracing with a confidence output and its own energy-preserving denoiser (spatial reconstruction, temporal accumulation, bilateral cleanup); vendor/DiligentFX/PostProcess/ScreenSpaceReflection/README.md describes the algorithm. Its view-space reconstruction removes a jittered projection's offset (DFX-15), and its spatial reconstruction averages tone-mapped samples as Wicked Engine's resolve does (DFX-16). Its radiance is premultiplied by confidence, to be composited as radiance + (1 - confidence) * environment (DFX-17). A ray more than the depth-buffer thickness behind a surface passes behind it, as Godot's hierarchical SSR traces (DFX-18). A ray stops at the viewport edge (DFX-22) and at the far plane (DFX-26), as AMD's hybrid traversal stops it. Only depths at or beyond the far plane are background, whatever the near plane (DFX-61). At half resolution each displaced pixel centre reads the ray of its containing 2×2 block, so a mirror in a complete block reads its own ray (DFX-55). An unpaired final row or column clamps to the existing ray grid. The half- resolution mask keeps a block if any sampled pixel is a non-background surface within RoughnessThreshold, as the full-resolution mask decided it (DFX-62), which bilateral cleanup also reads; the intersection keeps its preferred quadrant pixel if eligible, otherwise chooses another eligible pixel in that quad (DFX-58). Rough or background neighbors no longer suppress a mirror strip. A quad with no eligible surface reports a miss. At full importance-sample bias a ray follows the mirror direction, as Godot's SSR traces (DFX-20), and at roughness 0 at any bias; the resolve clamps N·V above 0 as Filament does (DFX-40). The stored sample PDF is capped at binary16's largest finite value so glossy grazing rays retain finite reconstruction weights on every backend (DFX-60). Its temporal pass reprojects by the reflection's virtual point as AMD's reflection denoiser places it. Only confirmed hits with non-negligible BRDF weight set that distance; an all-miss sample kernel reprojects the surface (DFX-56). It compares the current pixel with the previous surface and hit candidates and reduces the radiance history's influence where the receiver or reflected source moves independently. Its existing Wicked Engine 2-deviation box limits the resulting history. Only candidates inside the previous viewport enter this comparison (DFX-57): an off-screen virtual point, including one behind the previous camera (DFX-31), leaves a valid surface candidate available. A surface that was behind the previous camera finds no history, in SSR and TAA alike (DFX-32). Both linearise a surface's reprojected depth with the previous camera's projection, so a changed near plane keeps history (DFX-43). Its denoiser passes run only on the 8×8 tiles with a confident hit within their reach, as AMD's denoiser runs only over its tile list; a skipped tile's histories hold zero radiance and DiligentFX's no-history variance (DFX-29).
  • TAA accumulates a Halton-jittered frame into a history, rejecting by depth disocclusion and motion and clipping to the neighbourhood's variance box, intersected with its min/max box as Filament's is; vendor/DiligentFX/PostProcess/TemporalAntiAliasing/README.md describes it. As Godot's TAA, it rejects history gradually where motion changes between frames, not by speed, and clips it towards the neighbourhood mean within a box that narrows with speed (DFX-14). A pixel that has not moved keeps a longer history within the same box and is not rejected by depth, as Bevy's TAA treats still pixels (DFX-19). Its closest-motion search clamps neighbours to the screen, as Godot's and Bevy's do (DFX-42).
  • Both effects read colour at most 65504, binary16's largest finite value, as FSR2 clamps its input, so a texel of +infinity leaves their outputs finite (DFX-46).
  • PostFXContext::prepare_resources records the latest FrameDesc, including output-only resizes. Its depth resources rebuild only when the render size or depth format changes. get_frame_desc reports that latest description.
  • Host: derived from ScreenSpaceReflection.cpp, TemporalAntiAliasing.cpp, PostFXContext.cpp and PostFXRenderTechnique.cpp, recording into a caller's wgpu::CommandEncoder where Diligent records into a device context (module table in src/lib.rs).
  • GPU: shaders/wgsl/ mirrors the upstream shader files one WGSL module per HLSL file, beside SGL's own SSR_DenoiserTiles and SSR_ComputeDenoiserTiles (DFX-29); src/shaders.rs assembles a shader as Diligent's shader factory compiles one (HLSLDefinitions.fxh, the macros, the file, its includes).
  • Structures: src/structures.rs holds the host halves of CameraAttribs, ScreenSpaceReflectionAttribs and TemporalAntiAliasingAttribs with the headers' defaults.

Use

Most games use these effects through SGL3D, which owns scene conventions, settings, and frame integration. Use this crate directly only when supplying your own GPU pipeline and effect inputs. See Building games with SGL for dependency setup.

As DiligentFX's README describes, per frame:

context.prepare_resources(&device, &FrameDesc { index, width, height, .. }, post_fx_context::FeatureFlags::REVERSED_DEPTH);
ssr.prepare_resources(&device, &mut encoder, &mut context, FeatureFlags::NONE);
context.execute(&mut post_fx_context::RenderAttributes { /* depths, cameras */ });
ssr.execute(&mut screen_space_reflection::RenderAttributes { /* G-buffer, attribs */ });
// ssr.get_ssr_radiance_srv(): rgb reflected radiance, a confidence

TAA runs the same way, after the context:

taa.prepare_resources(&device, &mut encoder, &context, temporal_anti_aliasing::FeatureFlags::NONE, 0);
// Render the frame with TemporalAntiAliasing::get_jittered_proj_matrix(proj, taa.get_jitter_offset(0)).
taa.execute(&mut temporal_anti_aliasing::RenderAttributes { /* color, depth, motion, responsive inputs, attribs */ });
// taa.get_accumulated_frame_srv(false, 0): the anti-aliased frame

post_fx_context::RenderAttributes::camera_attribs_cb supplies a read-only current/previous camera pair instead of inline curr_camera and prev_camera. A context may alternate between these sources each frame; it uploads inline cameras only into its own buffer and never changes the caller’s buffer.

The caller supplies Diligent's conventions: a left-handed camera (view space +z forward) with a finite far plane, the depth buffer as a depth texture, unit world normals (SSR traces a normal that is not unit length as a miss, DFX-52), NDC motion vectors (current − previous) and the previous frame's depth. SSR's temporal pass needs four-channel motion vectors (such as Rgba16Float; it panics on fewer), as motion-adaptive TAA does: XY the NDC motion, Z the surface's previous minus current camera-space Z, its own and the camera's motion included, and W that depth motion's validity (above 0 valid, 0 none). It compares history with the depth that motion gives, so a surface the camera follows keeps its reflection history, and with the camera's reprojection where W is 0 (DFX-63). Both conventional and reversed depth are supported. SSR stores its resolved reprojection depth in R32Float for conventional depth, and R16Float for reversed depth (DFX-59); neither needs optional float filtering features. Changing depth convention recreates SSR's resources and resets its history. Set each CameraAttribs' clip planes with set_clip_planes(near, far), passing far before near for reversed-Z: SSR's and TAA's temporal passes read the near and far planes' depths (DFX-32), and left at Default's 0 they keep no history; SSR's intersection clips rays towards the camera at the near plane (DFX-39), just in front of the camera when it is left at 0. The SSR output composites as (F0 · LUT.x + LUT.y) · lerp(environment, rgb, a). RenderAttributes::pass_timestamps optionally supplies per-pass timestamp writes by the name of each pass's upstream debug group. screen_space_reflection::RenderAttributes::frame_time is the seconds since the previous execution, which time the transition fade instead of a clock (DFX-24): pass the measured frame time, or create the context with CreateInfo::transition_duration 0, as SGL3D does. With the default duration of 1.0 and frame_time left at 0, SSR's output stays zero. SSR and TAA discard their history:

  • on their first execution,
  • after skipped frame indices,
  • after a resize (or SSR's half-resolution change) recreates it (DFX-49, DFX-53),
  • when SSR's RenderAttributes::reset_accumulation or TemporalAntiAliasingAttribs::reset_accumulation asks.

Executing the same frame index again repeats that frame, its reset included: it reads the same history and writes the same halves, so a caller can render a frame again after one it did not submit or finish (DFX-12, DFX-50).

TAA's first frame for a new feature set writes the current RGB with reset history confidence, independent of input alpha (DFX-47). Its following resolve ramps up history weight as after an explicit reset.

TAA finds the closest motion vectors in its resolve, from the depth buffer and motion vectors it is given (DFX-13). Both are listed in PROVENANCE.md.

Motion-adaptive TAA

temporal_anti_aliasing::FeatureFlags::MOTION_ADAPTIVE_HISTORY opts into Filament-derived partial history rectification and adaptive feedback at rest, with camera/local-surface recovery holds and jitter-aware current/previous depth-neighborhood rejection. Default flags retain the existing resolve. Use TemporalStabilityFactor = 0.88 for the reference's 0.12 current feedback, 0.036 relaxed feedback and twelve-frame recovery hold; SGL3D uses that pair. Changing feedback changes convergence and recovery time. Both forward and reversed depth are normalized to near=1/far=0 for the adaptive comparisons. The flag requires a four-channel motion input (such as Rgba16Float; execute panics on fewer): XY the NDC motion, Z the surface's previous minus current camera-space Z, its own and the camera's motion included, and W that depth motion's validity (above 0 valid, 0 none). The depth test accepts history matching either the camera reprojection or the surface's own previous depth, so surfaces moving in depth keep their history. Depth's magnitude does not select the rejection strength, unlike Filament's sky override: the sky and far surfaces settle at rest like near ones. The sky is the far plane's exact depth, and a 3x3 neighbourhood that changes wholly to or from it is a disocclusion however close the depths (PROVENANCE.md, Motion-adaptive TAA). The closest-motion history uses RGBA16F rather than RG16F under this flag, adding eight bytes per pixel across its two buffers; B transports recovery hold, W the responsive masks' recovery hold (zero without them), and input motion's extra channels are never copied into it.

Set TemporalAntiAliasingAttribs::camera_motion from TemporalAntiAliasing::camera_moved(&current, &previous), the cameras given to the context: it compares the unjittered matrices to within a few f32 rounding steps of each element, the view's translation at the eye's distance from the origin, so a camera at rest anywhere from the origin is at rest. Set rigid_object_motion when content changes without a motion vector that describes it: an object appears, leaves, is shown or hidden, changes geometry, or moves without writing its motion. Each rearms recovery throughout the view. Newly exposed background can have zero current and previous motion and still require this global hold. Motion the motion vectors carry, an object's or deformation's, arms recovery locally (the pixel's own motion, its 3x3 closest-motion search and the neighbourhood motion below), so things moving elsewhere do not prevent stabilization everywhere. This is partial rectification, not disabled history rejection. It cannot reconstruct geometry never sampled across the jitter sequence. See provenance.

Two optional inputs mark what changes at a pixel without a motion vector of its own, read only under this flag; &[] and None leave the resolve as it was:

  • RenderAttributes::responsive_masks: up to two single-channel views at the input size in 0..1, such as FSR's reactive and transparency-and-composition masks. The resolve takes the largest value of either over the pixel's 3x3 neighbourhood, as FSR dilates them, so a pixel at the jittered edge of still marked content is marked on every frame: while a pixel is marked it rectifies and feeds back toward full strength (0.12 of the current frame at 0.88) in proportion to it, and it arms a twelve-frame hold of its own at full strength for once the content has left its neighbourhood, so blended surfaces, effects and animated shading respond at rest as in motion and leave no trail however dim they were.
  • RenderAttributes::neighborhood_motion (NeighborhoodMotion): a view whose texel pixel / tile_size holds a motion, in input pixels a frame, at least as long as any that reaches that pixel, such as a tile maximum and its 3x3 neighbourhood maximum. Where its length is at least the motion threshold (a pixel a frame, the reach of the resolve's own closest-motion search) it arms the recovery hold, so a pixel a surface has just left is rejected however it moved; slower motion changes nothing, and reprojection, the closest-motion search and the depth test keep the pixel's own motion.

execute panics on more than two masks, a tile of 0, or a neighbourhood motion that does not cover the input. Each combination of inputs is its own resolve, which execute creates when it first meets it; prepare_responsive_variant creates one ahead of the frame that needs it.

Translation conventions

The original port established these conventions, which the current shaders use:

  • An HLSL matrix row is a WGSL matrix column, so constructors and m[row][col] read the same and HLSL mul(a, b) is WGSL b * a. Host matrices are glam to_cols_array of the column-vector matrix.
  • WGSL has no overloading; an overload carries a type suffix (IsInsideScreen_f2, MatrixFromRows_f3). Function-like macros are functions; #define NAME VALUE is a const.
  • HLSL Load outside a texture returns zero; every ported load goes through HlslLoad* (DiligentCore/HLSLDefinitions.wgsl), which does the same.
  • Where WGSL forces anything else, a // WGSL: comment says what and why.
  • Modules keep only the declarations the ported passes use, in upstream order.

PROVENANCE.md explains the existing adaptations and algorithm changes; it is not an exhaustive conformance ledger.

Tests

cargo test -p sgl-post-fx -p sgl-post-fx-tests builds, binds and executes every feature permutation of each effect (reversed depth; SSR's previous frame and half resolution; TAA's Gaussian weighting, bicubic filter, YCoCg colour space and motion-adaptive history, with and without its responsive inputs) on the device and checks the output stays finite. SGL3D's integration (crates/sgl-3d/src/view/post_fx.rs) is tested in tests/sgl-3d/tests/screen_space_reflections.rs.

Licence

DiligentFX and DiligentCore are Copyright Diligent Graphics LLC and licensed under the Apache License, Version 2.0 (LICENSE.txt, vendor/*/License.txt); neither ships a NOTICE file. DFX-14 and DFX-18 port Godot Engine code under the MIT licence (LICENSE-godot.txt); DFX-14's comes from Godot's TAA resolve, based on Spartan Engine's TAA, also MIT (LICENSE-spartan.txt). DFX-19 ports Bevy code under the MIT licence (LICENSE-bevy.txt), and DFX-25 AMD FidelityFX Denoiser code under the MIT licence (LICENSE-amd-fidelityfx-denoiser.txt). Every ported file states its origin and that it was modified.