The farthest depth, at every scale

Why a pyramid

Phase two of the culling pass asks one question of each Instance in view: does its box lie wholly behind what phase one drew? Phase one has already drawn the Instances in view that were visible the frame before into the depth pre-pass. For each Instance, phase two projects the eight corners of its Mesh bounds, which gives a screen rectangle and the box's nearest depth. The box is hidden if even its nearest point lies behind the farthest depth drawn anywhere under that rectangle.

Answering from the depth target itself means reading every sample under the rectangle. The pre-pass draws at 4x MSAA, so a rectangle 200 pixels on a side covers 160,000 samples, by this guide's arithmetic, and town, the dense Reference scene of M3, the project's main-pass milestone, was planned with about 250k Instances; PRs #273 and #275 have since built it with 254,256.

A depth pyramid answers with four reads, whatever the rectangle's size. Each level halves the one below, and each texel holds the farthest depth over its share of the screen. Phase two picks the level whose texels are at least as large as the rectangle, so the rectangle touches one or two texels along each axis there, and reads those. Their minimum is never nearer than the farthest depth under the rectangle, because the texels cover all of it and more. The answer can be farther than the truth, which only ever keeps an Instance that could have been culled: the test is conservative.

Greene, Kass and Miller described the structure in 1993 as a Z pyramid, built by combining "four Z values at each level into one Z value at the next coarser level by choosing the farthest Z from the observer". Their basic test compared a polygon with the one entry whose region covered its whole bounding box, and they named its weakness: "a small polygon covering the center of the image will be compared to the Z value at the coarsest level of the pyramid." Reading up to four texels avoids it. A rectangle that straddles the centre still gets texels about its own size.

Why the minimum

Praxis's depth is reverse-Z (ADR 0015). A point d metres in front of the camera lands at depth 0.1 / d: 1 at the near plane, 0.1 at 1 m, 0.001 at 100 m, and towards 0 at infinity (src/camera/mod.rs). The depth target clears to 0, the far plane, and the depth pre-pass keeps a fragment where its depth is greater, so each sample ends up holding the nearest surface drawn there.

A texel of the depth pyramid must bound the farthest surface under it, so that no box that shows through a gap is mistaken for hidden. With nearer greater, the farthest is the smallest depth. ADR 0015 puts it in one clause: "a Hi-Z pyramid keeps the minimum depth, which is the farthest". Where phase one drew nothing, depth stays 0, and no box in front of the camera lies behind 0, so open sky hides nothing.

The test then reads: a box is occluded if its nearest depth is less than that minimum, that is, if even its nearest point is farther than the farthest surface under it. Spec #188 states the property for M3: "The pyramid holds minimum reverse-Z depth, the farthest, so it is conservative."

PR #242 shows the maximum failing. Its renderer test hides one quad behind a nearer one and expects 5, 5, 4 and 4 Instances drawn over four frames. With a pyramid that keeps the maximum, in its levels and over the four texels read, it draws 5, 5, 3 and 3. #196's check renders every Reference scene with the culling Render switch on and off and requires the two images to match within the Goldens' tolerance, one 8-bit step per channel. (Since PR #298 it checks town at eight frames, and allows one differing pixel per frame on software Vulkan and none on Metal.) With a maximum-depth pyramid it fails on four scenes, on Metal: pbr-sweep by 25,247 pixels, orrery by 2,742, texture-wall by 29,519 and helmet by 28,774. With the minimum, every scene matches, culling on and off, and at 100 km.

Rákos's 2010 article on Hi-Z occlusion culling keeps the maximum, a "store maximum depth" policy for "a usual depth buffer setup", and notes the other case: "For a reverse directed depth buffer the 'store minimum depth' policy has to be used."

Sizes and shares

RenderTargets creates the depth pyramid with the other targets whose size is the frame's. Level 0 is half the target's width and height, rounded down and at least 1, and the texture holds every level down to 1 × 1. Each level is the one below halved and rounded down, max(1, size >> level), as wgpu sizes any mip chain. At 2560 × 1440 that makes eleven levels: 1280 × 720, 640 × 360, 320 × 180, 160 × 90, 80 × 45, 40 × 22, 20 × 11, 10 × 5, 5 × 2, 2 × 1 and 1 × 1.

With sides halved and rounded down, some levels have an odd side, which raises the question of which texels of the level below a texel must cover. The pyramid answers with even shares. Each level's columns and rows divide the screen evenly, so texel x of a level n texels wide stands for x/n to (x+1)/n of the screen's width, its share of the screen. It holds the minimum of every texel of the level below whose share overlaps its own: for a level below m texels wide, from ⌊x·m/n⌋ to ⌈(x+1)·m/n⌉ − 1.

Where the level below halves exactly, m = 2n, the range is columns 2x and 2x + 1. Where it is odd, m = 2n + 1, each texel's share is 2 + 1/n columns of the level below wide, so every texel overlaps three of them, by this guide's arithmetic. A plain 2 × 2 reduction reads columns 2x and 2x + 1 everywhere. At 37 pixels across and 18 texels, it never reads column 36, and texel 8, whose share runs from 8/18 to 9/18 of the width, reads pixels 16 and 17 although its share also covers pixel 18.

That matters because phase two finds texels by the same even shares: a screen position u, from 0 to 1, picks texel ⌊u·n⌋. Under a plain reduction, pixels under a rectangle could go unread. If one of them showed the far plane through a gap, the test would see only the nearer depth around it and could cull a visible Instance. With texels covering two below and never three, PR #240's test finds 13 of level 0's 198 texels wrong.

The test resizes to 37 × 23, whose chain, 18 × 11, 9 × 5, 4 × 2, 2 × 1 and 1 × 1, reduces an odd side at levels 0, 1 and 2. The demo uses the same size and the same triangles.

Every sample of level 0

The depth pre-pass draws at 4x MSAA (ADR 0019), so the depth target holds four samples per pixel, each tested at its own point. Along a silhouette, some of a pixel's samples hold the near surface and others whatever lies behind it. Level 0 takes the minimum of all four samples of every pixel it covers, so one sample that sees past an edge pulls the texel to the farther depth. Reading sample 0 alone misses that: in the PR's test, 9 of level 0's 198 texels then differ.

Phase two relies on it. It grows each rectangle by a pixel past where rasterization rounds vertices, "so every sample a covered pixel holds is in the texels read" (PR #242). The same PR adds that "reading fewer samples, or a 1x depth, would stop the test being conservative under MSAA."

The pass binds the depth target as a texture_depth_multisampled_2d, which WGSL's textureLoad reads one sample at a time, by index, and the target gained TEXTURE_BINDING for it. A copy between a texture and a buffer needs a single-sampled texture, so the test reads the samples back with a compute kernel instead.

The loads are written out because a loop cost more. In PR #240's words, "in a loop, Metal's compiler serialised the loads". It measured level 0 at 1440p on the M4 Pro written three ways.

Even written out, level 0 is most of the pass: about 150 to 220 µs of it at 1440p, depending on the depth. It reads every sample of the 4x depth, 58,982,400 bytes uncompressed at 1440p (ADR 0019), about 59 MB. Scenes with grazing ground planes, minification and far-coplanar, cost the most, which PR #240 reads as "consistent with the depth compressing worse there".

At 2560 × 1440, level 0 is exactly half the target, so each of its texels reads 2 × 2 pixels, 16 samples. Where both sides of the target are odd, a level-0 texel reads 3 × 3 pixels, 36 samples, by this guide's arithmetic.

One pass, a level per dispatch

DepthPyramidPass holds two compute pipelines over two entry points of depth_pyramid.wgsl: reduce_depth for level 0, which reads the depth target, and reduce_level for every later level, which reads the level below. The PR's review kept them apart, since "WGSL has no generics, and a shared function would make each entry point use both bindings" (PR #240).

Their bind group is DEPTH_PYRAMID_LEVEL, defined once in bind_groups.rs with three bindings: level, the level written, a write-only r32float storage texture; depth, the multisampled depth target; and level_below. Each pipeline's layout holds only the two bindings its entry point uses, which BindGroupDefinition::layout_of builds from a list of binding names, checked as bind_group checks them. The pass keeps one bind group per level, with that level's size.

record opens one compute pass, labelled depth_pyramid_pass, and dispatches once per level, in order, over workgroups of 8 × 8 texels. At 1440p that is eleven dispatches.

The Renderer records the pass between the depth pre-pass and phase two; PR #240 split MainPass::record into record_depth_prepass and record_lit_pass to make room for it. TIMED_PASSES lists the frame's five passes in order, each timed from its start to its end, and Frame stats report each one's GPU time. Later PRs added seven passes around these: on main (270c5e4), TIMED_PASSES lists twelve, with the pyramid pass still between the depth pre-pass and phase two.

The order sets two attachment choices. The pre-pass clears the depth to 0 and stores it, since the pyramid and the lit pass read it. The lit pass is the frame's last pass that draws depth, so it loads the depth and ends with StoreOp::Discard. Once a render pass holds a pipeline that writes depth, a store writes the whole target back, "even when phase two draws nothing": about 50 µs at 1440p on the M4 Pro. PR #241 measured pbr-sweep at 730 µs with Store against 679 µs. Since PR #277, with shadow rays on, as they ship, phase two's Instances draw into depth in a render pass of their own, phase_two_depth_pass, which loads the depth and stores it for the shadow mask pass; the lit pass then writes no depth, and still loads the depth and discards it. With shadow rays off, the lit pass draws phase two's depth as above.

The pass asked nothing new of the Capability floor. It runs on compute shaders, which the floor already required for the culling pass (ADR 0021), and PR #240 changed neither ADR 0021 nor src/gpu/. The device is requested with exactly the floor, so the pass runs on what the floor guarantees. The raise #198 did need came in its second part: max_storage_buffers_per_shader_stage from 8 to 9, for the culling pass's visibility bits.

Recreated on resize

The pyramid's size follows the target's, so it lives with the targets. RenderTargets creates every target whose size is the frame's: the 4x depth, the 4x colour and the pyramid, and since PRs #251 and #277 the HDR target and the shadow mask too. Renderer::resize creates them all again. RenderTargets keeps two kinds of view of the pyramid: one of every level, which phase two reads and which PR #242 added, and one of each level alone, which the pyramid pass writes and reads a level at a time.

Bind groups are snapshots, not pointers, as the module's comment says. After a resize, a bind group built for the old pyramid still holds the old textures. If the pyramid pass kept its own, it would go on reducing the old depth into the old pyramid, and phase two would read texels the frame never wrote. So each pass builds the bind groups that read targets in one function, called at creation and after every resize: DepthPyramidPass::bind_render_targets, and CullingPass::bind_render_targets for the culling pass, whose group 3 holds the pyramid.

Tests check both. The pass-level test creates the pass for 16 × 16 targets, then rebinds it to targets created again at 37 × 23; without the rebinding, 62 of level 0's 198 texels differ. PR #242's renderer test creates its Renderer at 24 × 24 and resizes it to 16 × 16 first. If resize skips rebinding the culling pass, or the pyramid pass, it draws 5, 5, 5 and 4 Instances where it should draw 5, 5, 4 and 4.

The pyramid counts in gpu_memory_bytes through RenderTargets::gpu_memory_bytes, which counts every level of the texture behind level 0's view.

How phase two reads it

The pyramid's one reader is occluded, in culling.wgsl, which phase two calls for each Instance in view. This chapter follows only its use of the pyramid; the next guide covers the rest of the culling pass.

1. Project the box. For each of the eight corners of the Instance's Mesh bounds in clip space, keep the greatest depth, z over w: the box's nearest point. Each corner is first moved towards the camera, in clip-space z and in w, by 1/16384 of the summed magnitudes of that coordinate over the box's centre and its three half-axes, plus 0.1 mm, past what f32 rounding could do to the vertices. A box with a corner at or behind the camera's plane is never occluded.
2. Take the screen rectangle. The corners' x and y over w bound the screen rectangle. Phase two turns it into texture coordinates, rows top first, and grows it by half a level-0 texel on each side, about a pixel.
3. Pick the level. With e the rectangle's larger side, measured in level-0 texels, the level is min(⌈log₂ max(e, 1)⌉, levels − 1). Its texels are at least 2^level level-0 texels wide, so the rectangle spans at most two of them per axis, by this guide's reading.
4. Find the texels. Phase two computes the level's size, max(1, level 0's size >> level), and turns the rectangle's corners into a first and last texel per axis. If rounding leaves more than two per axis, the box is not occluded.
5. Read four texels, the corners of that block of one or two by one or two, and take their minimum.
6. Compare. The box is occluded if its nearest depth is less than that minimum, and phase two culls it.

The level rule has the form of the one on slide 67 of Wihlidal's GDC 2016 talk, min(ceil(log2(max(longestEdge, 1.0f))), levels - 1), and Rákos's 2010 article also reads four texels per test.

Sizes computed, not queried

Step 4 computes each level's size because lavapipe answered the query wrongly. On CI's lavapipe, Mesa 25.2.8, textureDimensions(.., level) gives every invocation that lavapipe runs together in one SIMD vector the size at the first one's level, which Mesa's source marks "FIXME: this needs to honor per-element lod"; the code comment above names the whole workgroup. Every Instance then read the 1 × 1 level's size, its rectangle collapsed to texel (0, 0), and the test culled two visible quads: the first CI run drew 5, 5, 2 and 4. Temporary probes on CI, since dropped, narrowed it down: loads through the all-levels view were right texel by texel, a copy of occluded run one invocation per workgroup got every step right, and inside the culling pass the queried size was 1 at every level. The fix "replaces one texture query with a shift", so the PR's timings, taken before it, stand. Level 0's size is still queried, with the same level in every invocation.

Phase one, the visibility bits, why phase two also tests the Instances phase one drew, and how the frame's draw grows across the two phases are the subject of the next guide, Instance Culling Explained.

How it is tested

Ticket #198's architecture review asked for a pass-level test beside the capture tests: "the pyramid built from a read-back depth texture against a CPU minimum-reduction". It is each_depth_pyramid_texel_holds_the_minimum_depth_of_its_share_of_the_screen, in depth_pyramid_pass.rs:

1. It creates the pass for 16 × 16 targets, then rebinds it to targets created again at 37 × 23, so that levels 0, 1 and 2 reduce an odd side.
2. It draws five triangles into the depth target as the pre-pass draws, cleared to 0 and passing Greater: one at depth 0.2, three times the others' size, and four at 0.7, 0.45, 0.9 and 0.3.
3. It records the pass, then reads back every sample of the 4x depth and every level with small compute kernels.
4. It builds the expected pyramid on the CPU, from each pixel's minimum, a level at a time, and requires every texel of every level to be equal, with no tolerance.
5. It checks that the expected pyramid is not all background.

The CPU side is written another way. The shader computes each texel's first and last texel below; the CPU loops over every texel below and keeps those whose share overlaps, by an integer test, below_texel * size < (texel + 1) * below_size && (below_texel + 1) * size > texel * below_size. Two formulations that agree are better evidence than one copied into the test.

Around it, capture_reports_the_pbr_sweep_frame_stats expects the five passes in order, each with a non-zero time (on main, twelve, some of which read no time, as chapter 5 notes), and a closed-form gpu_memory_bytes that adds the 80 × 45 pyramid's seven levels, 19,052 B. PR #242's renderer test drives the pyramid through phase two and a resize (chapters 2 and 6), and #196's check compares every Reference scene with culling on and off. Goldens were unchanged on Metal through all three PRs, and CI checked software Vulkan.

What it costs

PR #240 benched main at 93355f1 against its branch on the M4 Pro at 2560 × 1440, in three interleaved rounds per binary with the machine's load average at 4 to 8, and reports the median of the three runs' medians.

• GPU: the frame rises by the pass's own time plus up to 29 µs, which PR #240 puts down to the extra pass boundary between the pre-pass and the lit pass. Level 0 is about 150 to 220 µs of the pass; the ten later levels cost about 40 µs together, mostly per-dispatch cost.
• CPU: +15 to +34 µs a frame on every scene but texture-wall, for the compute pass, its eleven dispatches and its timestamps; by this guide's arithmetic from the table, texture-wall's CPU frame rose by 120.7 µs.
• Heap allocations: from 138 to 194 a frame on every scene, 56 more. Recording an empty pass with its timestamps costs 4, level 0's dispatch 16, and each later dispatch about 3.6, from wgpu's per-dispatch tracking.
• GPU memory: +4,915,164 B at 1440p: the pyramid's 1,228,763 R32Float texels, and 112 B for a fourth timed pass in the readback of GPU times (PR #241's split of the culling pass later made five). On CI's lavapipe, only gpu_memory_bytes, +307,164 B at 640 × 360, and heap allocations, from 146 to 196, moved. The Baselines were re-recorded on both.

After all three parts, PR #242 measured the pass at 180.0 to 265.5 µs on every scene but texture-wall, and #198 as a whole at +232 to +307 µs of GPU over 93355f1 on those scenes, of which the pyramid is 180 to 266 µs. That went past the ticket's line, "must not regress: GPU frame total on today's scenes beyond the pyramid's measured cost", and the project's owner accepted it. The PR's recommendation put the whole at about 2.5% of the 12 ms Budget, paid back once town hides Instances. When #198 closed, the Reference scenes paid the cost and gained nothing; PRs #273 and #275 have since built town.

What comes next

• Instance Culling Explained, next in this series: phase one and its visibility bits, phase two's test in full, the frame's draw across the two phases, and the Capability floor's ninth storage buffer.
• #206 builds town, the first Reference scene that hides Instances, about 1 × 1 km with building blocks as occluders. PRs #273 and #275 have since built it, and #206 closed on 2026-10-24 (Town Explained). Spec #188 asks for its camera path to run "at street level, then over the rooftops, with no cuts, so that occlusion changes exercise both Hi-Z phases".
• Fewer dispatches, deferred on #17, the issue that holds the project's architecture decisions and milestone order: "one dispatch could write two levels, the second from the level two below (still conservative, though not equal to the chained minimum)", revived "when a profile names the pyramid's tail or the frame's heap allocations".
• ADR 0019's gate times the opaque main pass from the first culling dispatch to the end of the lit pass with shadow rays off, the pyramid included. If a Reference scene's median at 1440p passes 6 ms of GPU, half of ADR 0013's 12 ms, options B and D of ADR 0019 are prototyped on that scene before anything changes.

Reading list

Grouped by source, each with what it is good for here. Every link below resolved when the guide was written. Repo links are pinned to main at fe08baa.

Glossary