Metal: occlusion culling of solid sections, the depth test in the shader

GPU occlusion culling ran on Vulkan only: its test needs early fragment
tests, which naga's Metal backend does not emit. On Metal the boxes are
tested in a pass of their own: phase 1's depth is bound read-only as the
attachment and as a texture, and the fragment shader compares its own
depth with it (reversed Z, greater or equal), as the fixed-function test
would. HORIZON_GPU_CULL=shader takes this path on Vulkan too, for checks.

Frames drawn flat (the default on Apple GPUs at high render distances)
still skip culling here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-23 11:09:56 +02:00
parent 62a6b3a620
commit 9fcf91e4bc
3 changed files with 246 additions and 59 deletions
+46 -18
View File
@@ -316,7 +316,8 @@ pub struct Renderer {
flat: Option<flat::Flat>,
/// `flat` draws this frame's sections (off: the per-section draws).
flat_on: bool,
/// Occlusion culling of solid section draws, where multi-draw is native.
/// Occlusion culling of solid section draws, where the GPU's instance
/// counts reach a multi-draw's entries (Vulkan, Metal).
cull: Option<cull::Cull>,
cull_on: bool,
sky: wgpu::RenderPipeline,
@@ -1408,7 +1409,6 @@ impl Renderer {
usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
let depth = Self::depth(&device, &config);
let (atlas_pixels, atlas_width, atlas_height) = hud_atlas;
let atlas = device.create_texture_with_data(
&queue,
@@ -2112,14 +2112,22 @@ impl Renderer {
.features()
.contains(wgpu::Features::INDIRECT_FIRST_INSTANCE);
// HORIZON_GPU_CULL=0 turns occlusion culling off, `all` culls every
// frame however little it hides (A/B checks).
// frame however little it hides, `shader` tests in the shader as on
// Metal (A/B checks).
let cull_env = std::env::var("HORIZON_GPU_CULL");
let cull = (cull_env.as_deref() != Ok("0") && cull::Cull::supported(&adapter, &device))
.then(|| {
let mut cull = cull::Cull::new(&device, config.format.remove_srgb_suffix());
let cull = cull::Cull::supported(&adapter, &device)
.filter(|_| cull_env.as_deref() != Ok("0"))
.map(|depth_test| match cull_env.as_deref() {
Ok("shader") => cull::DepthTest::InShader,
_ => depth_test,
})
.map(|depth_test| {
let mut cull =
cull::Cull::new(&device, config.format.remove_srgb_suffix(), depth_test);
cull.always = cull_env.as_deref() == Ok("all");
cull
});
let depth = Self::depth(&device, &config, cull.as_ref());
let world_post = world_post::Post::new(&device, config.format.remove_srgb_suffix());
let uploads = upload::Uploads::new(&device);
let section_uploads = upload::Uploads::with_chunk(&device, SECTION_UPLOAD_CHUNK);
@@ -2327,7 +2335,13 @@ impl Renderer {
self.surface = Some(surface);
Ok(())
}
fn depth(device: &wgpu::Device, config: &wgpu::SurfaceConfiguration) -> wgpu::TextureView {
/// The world's depth, which occlusion culling's test may read.
fn depth(
device: &wgpu::Device,
config: &wgpu::SurfaceConfiguration,
cull: Option<&cull::Cull>,
) -> wgpu::TextureView {
let read = cull.is_some_and(|c| c.depth_test() == cull::DepthTest::InShader);
device
.create_texture(&wgpu::TextureDescriptor {
label: Some("Horizon depth"),
@@ -2340,7 +2354,11 @@ impl Renderer {
sample_count: 1,
dimension: wgpu::TextureDimension::D2,
format: wgpu::TextureFormat::Depth32Float,
usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
usage: if read {
wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TEXTURE_BINDING
} else {
wgpu::TextureUsages::RENDER_ATTACHMENT
},
view_formats: &[],
})
.create_view(&Default::default())
@@ -2391,7 +2409,7 @@ impl Renderer {
} else {
self.offscreen = Some(Self::offscreen_target(&self.device, &self.config));
}
self.depth = Self::depth(&self.device, &self.config);
self.depth = Self::depth(&self.device, &self.config, self.cull.as_ref());
}
/// Whether sections are drawn as one index list per frame (`flat`).
pub fn flat_draws(&self) -> bool {
@@ -3096,16 +3114,18 @@ impl Renderer {
.inverse()
.transform_point3(Vec3::ZERO);
// Occlusion culling leaves the sections its last result did not see
// to phase 2, after the others, with instance counts of 0.
// to phase 2, after the others, with instance counts of 0. Frames
// drawn flat are not culled (phase 2's counts reach only per-section
// draws): those with as many draws as the last frame drew flat.
let flat_likely = self.flat_on
&& self
.flat
.as_ref()
.is_some_and(|f| self.section_draws >= f.min_draws);
let mut cull = self
.cull
.as_mut()
.filter(|_| {
self.cull_on
&& !frame.title
&& self.multi_draw
&& !(self.flat_on && self.flat.is_some())
})
.filter(|_| self.cull_on && !frame.title && self.multi_draw && !flat_likely)
.and_then(|cull| cull.begin(&self.device).then_some(cull));
self.phase2_draws.clear();
self.phase2_pages.clear();
@@ -3493,7 +3513,10 @@ impl Renderer {
);
let flat_frame = match &mut self.flat {
Some(flat)
if self.flat_on && !self.draws.is_empty() && self.draws.len() >= flat.min_draws =>
if self.flat_on
&& !culling
&& !self.draws.is_empty()
&& self.draws.len() >= flat.min_draws =>
{
let sections = &self.sections;
let lods = &self.lods;
@@ -3567,6 +3590,9 @@ impl Renderer {
Some((color, depth)) => (color, depth),
None => (&view_target, &self.depth),
};
if culling && let Some(cull) = &mut self.cull {
cull.bind_depth(&self.device, world_depth);
}
let cull = self.cull.as_ref().filter(|_| culling && solid_draws > 0);
{
let attachments = [Some(wgpu::RenderPassColorAttachment {
@@ -3659,12 +3685,14 @@ impl Renderer {
pass.set_vertex_buffer(1, self.instances.slice(..));
match cull {
Some(cull) => {
// Phase 1 and the boxes against its depth, then
// Phase 1 and the boxes against its depth (in
// its pass, or one of their own on Metal), then
// what they found in sight, in a pass that loads
// both targets (it reads the test's results).
self.draw_sections(&mut pass, &self.indirect, 0, 0, phase1_draws);
cull.test(&mut pass);
drop(pass);
cull.test_pass(&mut encoder);
let attachments = [Some(wgpu::RenderPassColorAttachment {
view: world_view,
resolve_target: None,
+180 -33
View File
@@ -22,8 +22,16 @@
//! Every solid draw is an entry of one of the two lists, so the CPU records
//! as many draws as without culling: drivers that unroll an indirect
//! multi-draw on the CPU (Mesa's on Intel Gen9) pay per entry. Phase 2's
//! counts come from the GPU, which needs a native multi-draw and forced
//! early depth tests: Vulkan. Translucent draws are not culled.
//! counts come from the GPU, which reads them from the draws themselves:
//! Vulkan's native multi-draw, and Metal's, which wgpu replays as one
//! indirect draw per entry. Translucent draws are not culled.
//!
//! Metal cannot force the depth test before a fragment shader that writes
//! storage (naga writes no `[[early_fragment_tests]]`), so there the boxes
//! are drawn in a pass of their own between the phases, which reads phase
//! 1's depth as a texture and makes the same comparison in the shader: the
//! fragment's depth against the stored one, greater or equal passing. The
//! same fragments pass, so the same sections are seen.
use std::num::NonZeroU64;
use std::sync::{
Arc,
@@ -74,10 +82,40 @@ struct Group {
group: wgpu::BindGroup,
}
/// Where the boxes' depth test runs.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DepthTest {
/// Forced before the fragment shader, in phase 1's pass (Vulkan).
Early,
/// In the fragment shader, against phase 1's depth read as a texture,
/// in a pass of its own (Metal).
InShader,
}
/// The Vulkan entry point: the depth test forced early, which naga cannot
/// write for Metal (so it is not in `cull.wgsl`, which every backend takes).
const EARLY_TEST: &str = "
@fragment
@early_depth_test(force)
fn fs_box_early(in: Box) -> @location(0) vec4<f32> {
see(in.test);
return vec4(0.0);
}
";
/// The test's depth texture binding (`InShader`), for the view it was made with.
struct DepthGroup {
view: wgpu::TextureView,
group: wgpu::BindGroup,
}
pub struct Cull {
pipeline: wgpu::RenderPipeline,
layout: wgpu::BindGroupLayout,
group: Option<Group>,
depth_test: DepthTest,
depth_layout: Option<wgpu::BindGroupLayout>,
depth_group: Option<DepthGroup>,
params: wgpu::Buffer,
/// Phase 2's draws: the solid draws after phase 1's in the frame's list.
pub phase2: wgpu::Buffer,
@@ -134,20 +172,33 @@ impl Cull {
pub fn features(adapter: &wgpu::Adapter) -> wgpu::Features {
adapter.features() & wgpu::Features::SHADER_EARLY_DEPTH_TEST
}
/// Whether the device draws an indirect multi-draw natively and runs
/// fragment shaders that write storage only past an early depth test.
pub fn supported(adapter: &wgpu::Adapter, device: &wgpu::Device) -> bool {
adapter.get_info().backend == wgpu::Backend::Vulkan
&& device.features().contains(
wgpu::Features::SHADER_EARLY_DEPTH_TEST | wgpu::Features::INDIRECT_FIRST_INSTANCE,
)
/// Where the device can run the test, if it can: Vulkan with early
/// depth tests, or Metal, both drawing an indirect multi-draw's entries
/// with the instance counts the GPU wrote, with fragment shaders that
/// write storage.
pub fn supported(adapter: &wgpu::Adapter, device: &wgpu::Device) -> Option<DepthTest> {
let depth_test = match adapter.get_info().backend {
wgpu::Backend::Vulkan
if device
.features()
.contains(wgpu::Features::SHADER_EARLY_DEPTH_TEST) =>
{
DepthTest::Early
}
wgpu::Backend::Metal => DepthTest::InShader,
_ => return None,
};
(device
.features()
.contains(wgpu::Features::INDIRECT_FIRST_INSTANCE)
&& adapter.get_downlevel_capabilities().flags.contains(
wgpu::DownlevelFlags::VERTEX_STORAGE
| wgpu::DownlevelFlags::FRAGMENT_WRITABLE_STORAGE,
)
))
.then_some(depth_test)
}
/// `color` is the world pass's colour format.
pub fn new(device: &wgpu::Device, color: wgpu::TextureFormat) -> Self {
pub fn new(device: &wgpu::Device, color: wgpu::TextureFormat, depth_test: DepthTest) -> Self {
let entry = |binding, visibility, ty| wgpu::BindGroupLayoutEntry {
binding,
visibility,
@@ -180,13 +231,41 @@ impl Cull {
});
let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
label: Some("Section culling"),
source: wgpu::ShaderSource::Wgsl(include_str!("cull.wgsl").into()),
source: wgpu::ShaderSource::Wgsl(source(depth_test).into()),
});
let depth_layout = (depth_test == DepthTest::InShader).then(|| {
device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("Section culling depth"),
entries: &[entry(
0,
fragment,
wgpu::BindingType::Texture {
sample_type: wgpu::TextureSampleType::Depth,
view_dimension: wgpu::TextureViewDimension::D2,
multisampled: false,
},
)],
})
});
let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
label: Some("Section culling"),
bind_group_layouts: &[Some(&layout)],
bind_group_layouts: &[Some(&layout), depth_layout.as_ref()],
..Default::default()
});
// In the shader: no colour target, and phase 1's depth attached read
// only (a pass needs an attachment), its test left to the shader.
let (fragment_entry, targets, depth_compare) = match depth_test {
DepthTest::Early => (
"fs_box_early",
&[Some(wgpu::ColorTargetState {
format: color,
blend: None,
write_mask: wgpu::ColorWrites::empty(),
})][..],
wgpu::CompareFunction::GreaterEqual,
),
DepthTest::InShader => ("fs_box", &[][..], wgpu::CompareFunction::Always),
};
let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
label: Some("Section culling"),
layout: Some(&pipeline_layout),
@@ -204,20 +283,16 @@ impl Cull {
depth_stencil: Some(wgpu::DepthStencilState {
format: wgpu::TextureFormat::Depth32Float,
depth_write_enabled: Some(false),
depth_compare: Some(wgpu::CompareFunction::GreaterEqual),
depth_compare: Some(depth_compare),
stencil: Default::default(),
bias: Default::default(),
}),
multisample: Default::default(),
fragment: Some(wgpu::FragmentState {
module: &module,
entry_point: Some("fs_box"),
entry_point: Some(fragment_entry),
compilation_options: Default::default(),
targets: &[Some(wgpu::ColorTargetState {
format: color,
blend: None,
write_mask: wgpu::ColorWrites::empty(),
})],
targets,
}),
multiview_mask: None,
cache: None,
@@ -226,6 +301,9 @@ impl Cull {
pipeline,
layout,
group: None,
depth_test,
depth_layout,
depth_group: None,
params: buffer(
device,
"Section culling parameters",
@@ -399,17 +477,69 @@ impl Cull {
}
}
/// In the world pass after phase 1: draw the tested boxes against its
/// depth. Leaves the pass's pipeline and group 0 changed.
pub fn depth_test(&self) -> DepthTest {
self.depth_test
}
/// In the world pass after phase 1 (`Early`): draw the tested boxes
/// against its depth. Leaves the pass's pipeline and group 0 changed.
pub fn test(&self, pass: &mut wgpu::RenderPass<'_>) {
let Some(Group { group, .. }) = &self.group else {
return;
};
if self.depth_test != DepthTest::Early || self.test_data.is_empty() {
return;
}
pass.set_pipeline(&self.pipeline);
pass.set_bind_group(0, group, &[]);
pass.draw(0..36, 0..self.test_data.len() as u32);
}
/// Before the world pass (`InShader`): the binding of the depth the
/// world is drawn with this frame.
pub fn bind_depth(&mut self, device: &wgpu::Device, depth: &wgpu::TextureView) {
let Some(layout) = &self.depth_layout else {
return;
};
if self.depth_group.as_ref().is_none_or(|g| g.view != *depth) {
self.depth_group = Some(DepthGroup {
view: depth.clone(),
group: device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some("Section culling depth"),
layout,
entries: &[wgpu::BindGroupEntry {
binding: 0,
resource: wgpu::BindingResource::TextureView(depth),
}],
}),
});
}
}
/// Between the phases (`InShader`): draw the tested boxes in a pass of
/// their own that reads phase 1's depth, bound by `bind_depth`.
pub fn test_pass(&self, encoder: &mut wgpu::CommandEncoder) {
let (Some(Group { group, .. }), Some(DepthGroup { view, group: depth })) =
(&self.group, &self.depth_group)
else {
return;
};
if self.test_data.is_empty() {
return;
}
let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
label: Some("Section culling"),
color_attachments: &[],
depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
view,
depth_ops: None,
stencil_ops: None,
}),
..Default::default()
});
pass.set_pipeline(&self.pipeline);
pass.set_bind_group(0, group, &[]);
pass.set_bind_group(1, depth, &[]);
pass.draw(0..36, 0..self.test_data.len() as u32);
}
@@ -498,16 +628,33 @@ impl Cull {
}
}
#[cfg(test)]
mod tests {
#[test]
fn shader_validates() {
let module = naga::front::wgsl::parse_str(include_str!("cull.wgsl")).unwrap();
naga::valid::Validator::new(
naga::valid::ValidationFlags::all(),
naga::valid::Capabilities::all(),
)
.validate(&module)
.unwrap();
/// The test's shader for `depth_test`.
fn source(depth_test: DepthTest) -> String {
let common = include_str!("cull.wgsl");
match depth_test {
DepthTest::Early => format!("{common}{EARLY_TEST}"),
DepthTest::InShader => common.to_owned(),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn shaders_validate() {
for (depth_test, capabilities) in [
(DepthTest::Early, naga::valid::Capabilities::all()),
// What wgpu's Metal backend allows: no early depth test.
(
DepthTest::InShader,
naga::valid::Capabilities::all() - naga::valid::Capabilities::EARLY_DEPTH_TEST,
),
] {
let module = naga::front::wgsl::parse_str(&source(depth_test)).unwrap();
naga::valid::Validator::new(naga::valid::ValidationFlags::all(), capabilities)
.validate(&module)
.unwrap_or_else(|e| panic!("{depth_test:?}: {e:?}"));
}
}
}
+20 -8
View File
@@ -86,16 +86,28 @@ fn vs_box(@builtin(vertex_index) v: u32, @builtin(instance_index) t: u32) -> Box
return out;
}
// Runs only for fragments that pass the depth test (forced early).
@fragment
@early_depth_test(force)
fn fs_box(in: Box) -> @location(0) vec4<f32> {
if results[in.test] != params.stamp {
results[in.test] = params.stamp;
let test = tests[in.test];
// The box is seen at this fragment: store the stamp, and give its phase 2
// draws their instance.
fn see(t: u32) {
if results[t] != params.stamp {
results[t] = params.stamp;
let test = tests[t];
for (var k = 0u; k < test.z; k++) {
phase2[(test.y + k) * 5u + 1u] = 1u;
}
}
return vec4(0.0);
}
// Phase 1's depth, where the test runs in the shader (gfx/cull.rs).
@group(1) @binding(0) var depth: texture_depth_2d;
// The world pass's reversed depth test, greater or equal passing, made here:
// where it cannot be forced before a shader that writes storage, a fragment
// that fails it would still write. Where it can, `fs_box_early` (cull.rs)
// runs only for the fragments that pass it.
@fragment
fn fs_box(in: Box) {
if in.position.z >= textureLoad(depth, vec2<u32>(in.position.xy), 0) {
see(in.test);
}
}