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.mddescribes 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 asradiance + (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 withinRoughnessThreshold, 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.mddescribes 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_resourcesrecords the latestFrameDesc, including output-only resizes. Its depth resources rebuild only when the render size or depth format changes.get_frame_descreports that latest description.- Host: derived from
ScreenSpaceReflection.cpp,TemporalAntiAliasing.cpp,PostFXContext.cppandPostFXRenderTechnique.cpp, recording into a caller'swgpu::CommandEncoderwhere Diligent records into a device context (module table insrc/lib.rs). - GPU:
shaders/wgsl/mirrors the upstream shader files one WGSL module per HLSL file, beside SGL's ownSSR_DenoiserTilesandSSR_ComputeDenoiserTiles(DFX-29);src/shaders.rsassembles a shader as Diligent's shader factory compiles one (HLSLDefinitions.fxh, the macros, the file, its includes). - Structures:
src/structures.rsholds the host halves ofCameraAttribs,ScreenSpaceReflectionAttribsandTemporalAntiAliasingAttribswith 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;
ssr.prepare_resources;
context.execute;
ssr.execute;
// ssr.get_ssr_radiance_srv(): rgb reflected radiance, a confidence
TAA runs the same way, after the context:
taa.prepare_resources;
// Render the frame with TemporalAntiAliasing::get_jittered_proj_matrix(proj, taa.get_jitter_offset(0)).
taa.execute;
// 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_accumulationorTemporalAntiAliasingAttribs::reset_accumulationasks.
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(¤t, &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 texelpixel / tile_sizeholds 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 HLSLmul(a, b)is WGSLb * a. Host matrices are glamto_cols_arrayof 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 VALUEis aconst. - HLSL
Loadoutside a texture returns zero; every ported load goes throughHlslLoad*(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.