Transient histogram ReSTIR (TransientHistogramReSTIRInline)¶
This render pass renders the same transient histogram as the
transient histogram path tracer, the radiance per unit path
length in each of timeBin bins of [timeMin, timeMax), but with ReSTIR. Every pixel keeps one
reservoir per bin: a single path whose length falls in that bin, chosen from the pixel’s
candidate paths. The reservoirs are then resampled from neighboring pixels (spatial reuse), from
the previous frame (temporal reuse) and, optionally, from the adjacent bins of the same pixel. A
reused path is moved to the new pixel and bin with the path-length-aware shift mapping of
time-gated ReSTIR, which keeps its length inside the bin.
The scene and the laser must be static; only the camera may move.
Parameters¶
Histogram:
Parameter |
Type |
Description |
|---|---|---|
|
float |
Path-length range of the histogram. Paths outside |
|
integer |
Number of bins. Every bin has its own reservoir, so the pass’s memory and most of its work grow
with this; see Memory. (Default: |
|
string |
The bin filter: |
Initial sampling, the candidate paths each pixel starts from in every frame:
Parameter |
Type |
Description |
|---|---|---|
|
integer |
Camera paths traced per pixel in each frame. (Default: |
|
integer |
Maximum number of surface vertices on a camera path, counting the primary hit. Each vertex
after the primary hit is connected to the laser spot, and the connection is a candidate for the
bin its total length falls in. |
|
boolean |
Importance-sample the BSDF when extending a camera path. (Default: |
Reuse:
Parameter |
Type |
Description |
|---|---|---|
|
integer |
Rounds of spatial reuse per frame. 0 turns spatial reuse off. (Default: |
|
integer |
Neighbor pixels resampled in each round, each at the same bin. (Default: |
|
float |
Radius, in pixels, within which the neighbors are chosen. (Default: |
|
boolean |
In each spatial round, also resample bins |
|
boolean |
Resample the previous frame’s reservoirs, reprojected with motion vectors when the |
|
float |
Cap on the history’s sample count, in frames of |
|
integer |
Seed of the random numbers in spatial reuse; it advances with every round. (Default: |
Shift mapping, as for time-gated ReSTIR:
Parameter |
Type |
Description |
|---|---|---|
|
string |
The chart on which the reconnection vertex is moved: |
|
float |
A path can reconnect at a segment only if both of its vertices are rougher than this.
(Default: |
|
float |
A path can reconnect at a segment only if it is longer than this, in scene units. Very short
segments make the shift nearly singular. (Default: |
|
string |
Fixes the direction the path-length constraint leaves free. |
|
float pair |
Chart-space axis for |
|
integer |
Maximum Newton iterations per shift. Fewer are faster but leave more shifts one-way, which
biases reuse (the Cornell box with temporal reuse, |
|
float |
Tolerance of the shift solve on the path length, relative to the path-length change of the
shift, and at least the float32 resolution of the path lengths involved. Looser solves bias
reuse. (Default: |
|
float |
|
|
boolean |
Keep a shift only if the reverse shift maps it back to its start, at the cost of a second
shift. Newton’s method is local, so a rare shift reaches another solution than its reverse,
mostly with a ray chart; see the TG ReSTIR shift mapping.
(Default: |
|
boolean |
|
Performance. These options change how the work is split on the GPU, not the result:
Parameter |
Type |
Description |
|---|---|---|
|
boolean |
Run each spatial round as two passes: every candidate’s shifts at every bin in their own
thread, then the resampling. Much faster with a length-aware shift. The shift |
|
boolean |
Run temporal reuse as two passes after initial sampling (every bin’s shifts in their own
thread, then the merges) instead of inside it. Faster with a length-aware shift. The shift |
|
boolean |
Store only the reservoirs of bins that hold a path, plus every bin’s weight and sample count in
a small buffer. Faster while most bins are empty (initial sampling and the first spatial
round); it gains little once temporal or repeated spatial reuse has filled the bins.
(Default: |
Other:
Parameter |
Type |
Description |
|---|---|---|
|
boolean |
Include the shortest path, camera -> primary hit -> laser spot. Unlike in time-gated ReSTIR,
it is a candidate in the reservoirs like any other path. (Default: |
|
boolean |
Keep one channel, chosen by |
|
string |
The channel kept by |
|
boolean |
Honor alpha-tested materials when tracing rays. (Default: |
Without useSingleChannel, the reservoirs resample by the luminance of the path contribution.
Every frame¶
Initial sampling. Every pixel traces
samplesPerPixelcamera paths from its primary hit and connects their vertices to the laser spot. Each connection is a candidate for the bin that contains its total length, and each bin’s reservoir keeps one of its candidates, chosen in proportion to its contribution. Most bins of a pixel receive no candidate and stay empty.Temporal reuse (with
useTemporalReuse). Every bin resamples the same bin of the previous frame’s reservoirs at the reprojected pixel, shifted to the current camera.Spatial reuse,
spatialReuseIterationrounds. Every bin resamples the same bin ofspatialReuseNeighborCountrandom pixels withinspatialReuseGatherRadius, and withuseBinReusealso the adjacent bins of its own pixel. Neighbors without a primary hit, or whose primary hit differs too much in normal or depth, are skipped.Output. Each bin’s reservoir gives its estimate of that bin of the histogram.
Spatial reuse fills empty bins quickly: in a test on the Cornell box with 16 paths per pixel, about 10 % of the bins held a path after initial sampling, 34 % after one spatial round and 88 % after three.
As with time-gated ReSTIR, reuse lowers the noise of each frame but makes neighboring pixels and consecutive frames share paths.
When the history is discarded¶
The temporal history is discarded, and the next frame starts from its own samples only, when:
an option changes in the UI,
the scene or the laser changes in any way other than camera motion, including a camera animated by the scene,
the frame size changes, or
the camera uses depth of field.
Per pixel, the history is reused only if it saw the same surface: the same material, an orientation within about 45 degrees and a distance within 10 % (otherwise, e.g. where the camera’s motion uncovers a surface, the pixel starts from its own samples).
Memory¶
The pass keeps two sets of reservoirs, this frame’s and the previous one’s, each with timeBin
reservoirs of about 100 bytes per pixel: at 480 x 270 with 64 bins that is about 1.8 GB. The
two-pass reuse adds up to 512 MB of intermediate results, processing the bins in chunks when they
do not fit at once. These sizes are not checked against the GPU’s limits: keep each set of reservoirs,
a single buffer, below 4 GB, the largest buffer Vulkan binds (with 64 bins, up to about 0.6 megapixels,
e.g. 960 x 540). The limit of Direct3D 12, the default on Windows, was not tested.
Limitations¶
Static scene geometry: the camera may move, but objects may not move or deform (the history is discarded when geometry changes, as above), and the laser is assumed static.
Layered materials (for example pbrt’s
coateddiffuseandcoatedconductor) are not supported.
Laser¶
The laser is set on the LaserLight pass, as for the
time-gated path tracer. Moving or changing it discards the temporal history.
Inputs and outputs¶
Channel |
Description |
|---|---|
|
Primary hits, from |
|
Primary ray directions, from |
|
Motion vectors, from |
|
Transient histogram, |
|
Radiance of the frame, summed over all bins, RGBA32Float. |
The pass publishes the histogram’s range to the render graph, so a TransientHistogramViewer
downstream labels the path lengths. From a script, reset() clears the histogram before
the next frame.
Example¶
testbed.load_scene("cornell-box/scene-v4-nolight.pbrt", falcor.SceneBuilderFlags.DontMergeMaterials)
graph = testbed.create_render_graph("TransientReSTIR")
graph.create_pass("VBuffer", "VBufferRT", {"samplePattern": "Center", "sampleCount": 1})
graph.create_pass("Laser", "LaserLight", {
"laserPosition": [0.0, 1.7, 6.8], "laserDirection": [0.0, 0.0, -1.0], "laserPower": [170.0, 120.0, 40.0],
})
graph.create_pass("Tracer", "TransientHistogramReSTIRInline", {
"samplesPerPixel": 16, "maxBounces": 4,
"timeMin": 16.75, "timeMax": 18.03, "timeBin": 64,
"spatialReuseIteration": 1, "spatialReuseNeighborCount": 5,
"useTemporalReuse": True,
"shiftMappingMethod": "local_tangent", "gaugeMode": "avg_grad",
})
graph.add_edge("VBuffer.vbuffer", "Tracer.vbuffer")
graph.add_edge("VBuffer.viewW", "Tracer.viewW")
graph.add_edge("VBuffer.mvec", "Tracer.mvec")
graph.add_edge("Laser", "Tracer") # run the laser pass first
graph.mark_output("Tracer.histogram")
testbed.render_graph = graph
See the offline and online transient ReSTIR tutorials for complete scripts.