From 9e73a8417f7d30e914c4330c03cfed70700ec67d Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Fri, 16 Oct 2026 15:07:02 +0200 Subject: [PATCH] Upload animated sprites through a reused staging belt Queue::write_texture creates a new staging buffer for every call, a kernel call each on Metal. Animated sprites write every changed frame's mip levels once per tick, so tick frames spent about 1.3 ms in buffer creation. The copies now go through one wgpu StagingBelt recorded into the frame's encoder; a GPU readback test checks they write the same texels as write_texture on every mip level. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/gfx.rs | 34 ++-- crates/horizon-client/src/gfx/upload.rs | 196 ++++++++++++++++++++++++ 2 files changed, 212 insertions(+), 18 deletions(-) create mode 100644 crates/horizon-client/src/gfx/upload.rs diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs index 3863512f2..c99b39c2a 100644 --- a/crates/horizon-client/src/gfx.rs +++ b/crates/horizon-client/src/gfx.rs @@ -63,6 +63,7 @@ mod occlusion; mod pack_stages; pub mod panorama; mod timing; +mod upload; mod world_post; #[repr(C)] @@ -297,6 +298,7 @@ pub struct Renderer { lightmap_view: wgpu::TextureView, lightmap_sampler: wgpu::Sampler, animations: AnimatedSprites, + uploads: upload::Uploads, sprite_minimum_size: u32, indices: wgpu::Buffer, index_quads: u32, @@ -1489,6 +1491,7 @@ impl Renderer { .features() .contains(wgpu::Features::INDIRECT_FIRST_INSTANCE); let world_post = world_post::Post::new(&device, config.format.remove_srgb_suffix()); + let uploads = upload::Uploads::new(&device); let panorama = panorama::Panorama::new( &device, &queue, @@ -1557,6 +1560,7 @@ impl Renderer { lightmap_view, lightmap_sampler, animations: AnimatedSprites::new(animations, sprite_size, sprite_mips), + uploads, sprite_minimum_size, indices, index_quads, @@ -1963,13 +1967,14 @@ impl Renderer { ); self.lightmap_pixels = pixels; } - fn animate(&mut self, tick: u64) { + fn animate(&mut self, encoder: &mut wgpu::CommandEncoder, tick: u64) { animate_sprites( &mut self.animations, tick, self.mip_levels, |layer, level, size, pixels| { - self.queue.write_texture( + self.uploads.texture( + encoder, wgpu::TexelCopyTextureInfo { texture: &self.sprite_texture, mip_level: level, @@ -1980,17 +1985,9 @@ impl Renderer { }, aspect: wgpu::TextureAspect::All, }, + size, + size, pixels, - wgpu::TexelCopyBufferLayout { - offset: 0, - bytes_per_row: Some(size * 4), - rows_per_image: Some(size), - }, - wgpu::Extent3d { - width: size, - height: size, - depth_or_array_layers: 1, - }, ); }, ); @@ -2030,8 +2027,13 @@ impl Renderer { Some(f) => f.texture.clone(), None => self.offscreen.clone().ok_or("no offscreen target")?, }; + let mut encoder = self + .device + .create_command_encoder(&wgpu::CommandEncoderDescriptor { + label: Some("Horizon frame"), + }); if self.animated_textures { - self.animate(frame.ticks); + self.animate(&mut encoder, frame.ticks); self.hud.animate_fire(&self.queue, frame.ticks); } self.update_lightmap( @@ -2390,11 +2392,6 @@ impl Renderer { format: Some(self.config.format.remove_srgb_suffix()), ..Default::default() }); - let mut encoder = self - .device - .create_command_encoder(&wgpu::CommandEncoderDescriptor { - label: Some("Horizon frame"), - }); if let Some(timer) = &mut self.gpu_timer { timer.begin(&mut encoder); } @@ -2742,6 +2739,7 @@ impl Renderer { .screenshot .take() .map(|path| (path, self.copy_frame(&mut encoder, &target_texture))); + self.uploads.finish(&encoder); let submission = self.queue.submit([encoder.finish()]); if let Some(timer) = &mut self.gpu_timer { timer.submitted(); diff --git a/crates/horizon-client/src/gfx/upload.rs b/crates/horizon-client/src/gfx/upload.rs new file mode 100644 index 000000000..25b9b155a --- /dev/null +++ b/crates/horizon-client/src/gfx/upload.rs @@ -0,0 +1,196 @@ +//! Per-frame uploads through one reused staging belt. `Queue::write_buffer` +//! and `Queue::write_texture` create a fresh staging buffer for every call (on +//! Metal a kernel call each), which made the animated sprites' few hundred +//! texture writes a spike on every tick that changes a frame. The belt keeps a +//! few mapped buffers and records the copies into the frame's encoder instead. +use std::num::NonZeroU64; + +/// Large enough for a tick of animated sprites at 16x16 with every mip level. +const CHUNK: u64 = 1 << 20; + +pub struct Uploads { + belt: wgpu::util::StagingBelt, +} + +impl Uploads { + pub fn new(device: &wgpu::Device) -> Self { + Self { + belt: wgpu::util::StagingBelt::new(device.clone(), CHUNK), + } + } + /// Copy tightly packed RGBA8 `pixels` (`width` by `height`) into one mip + /// level of one array layer, padding rows to the copy alignment. + pub fn texture( + &mut self, + encoder: &mut wgpu::CommandEncoder, + destination: wgpu::TexelCopyTextureInfo<'_>, + width: u32, + height: u32, + pixels: &[u8], + ) { + let row = width as usize * 4; + debug_assert_eq!(pixels.len(), row * height as usize); + let padded = row.next_multiple_of(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT as usize); + let size = NonZeroU64::new((padded * height as usize) as u64).expect("non-empty texture"); + let alignment = NonZeroU64::new(u64::from(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT)) + .expect("non-zero alignment"); + let slice = self.belt.allocate(size, alignment); + { + let mut view = slice + .get_mapped_range_mut() + .expect("staging belt slices are mapped"); + for (i, src) in pixels.chunks(row).enumerate() { + view.slice(i * padded..i * padded + row) + .copy_from_slice(src); + } + } + encoder.copy_buffer_to_texture( + wgpu::TexelCopyBufferInfo { + buffer: slice.buffer(), + layout: wgpu::TexelCopyBufferLayout { + offset: slice.offset(), + bytes_per_row: Some(padded as u32), + rows_per_image: Some(height), + }, + }, + destination, + wgpu::Extent3d { + width, + height, + depth_or_array_layers: 1, + }, + ); + } + /// Close this frame's staging buffers: they come back for reuse once the + /// encoder's submission finishes on the GPU. + pub fn finish(&mut self, encoder: &wgpu::CommandEncoder) { + self.belt.finish_and_recall_on_submit(encoder); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn device() -> Option<(wgpu::Device, wgpu::Queue)> { + let instance = wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle()); + let adapter = pollster::block_on(instance.request_adapter(&Default::default())).ok()?; + pollster::block_on(adapter.request_device(&Default::default())).ok() + } + + /// Every mip level of one layer, read back as tightly packed RGBA8. + fn read_back(device: &wgpu::Device, queue: &wgpu::Queue, texture: &wgpu::Texture) -> Vec { + let mut out = Vec::new(); + for level in 0..texture.mip_level_count() { + let edge = texture.width() >> level; + let padded = (edge * 4).next_multiple_of(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT); + let buffer = device.create_buffer(&wgpu::BufferDescriptor { + label: None, + size: u64::from(padded * edge), + usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST, + mapped_at_creation: false, + }); + let mut encoder = device.create_command_encoder(&Default::default()); + encoder.copy_texture_to_buffer( + wgpu::TexelCopyTextureInfo { + texture, + mip_level: level, + origin: wgpu::Origin3d { x: 0, y: 0, z: 1 }, + aspect: wgpu::TextureAspect::All, + }, + wgpu::TexelCopyBufferInfo { + buffer: &buffer, + layout: wgpu::TexelCopyBufferLayout { + offset: 0, + bytes_per_row: Some(padded), + rows_per_image: Some(edge), + }, + }, + wgpu::Extent3d { + width: edge, + height: edge, + depth_or_array_layers: 1, + }, + ); + queue.submit([encoder.finish()]); + buffer + .slice(..) + .map_async(wgpu::MapMode::Read, |r| r.unwrap()); + device.poll(wgpu::PollType::wait_indefinitely()).unwrap(); + let data = buffer.slice(..).get_mapped_range().unwrap(); + for row in data.chunks(padded as usize) { + out.extend_from_slice(&row[..edge as usize * 4]); + } + } + out + } + + #[test] + fn belt_uploads_match_queue_writes_on_every_mip_level() { + let Some((device, queue)) = device() else { + eprintln!("no GPU adapter: skipped"); + return; + }; + let texture = || { + device.create_texture(&wgpu::TextureDescriptor { + label: None, + size: wgpu::Extent3d { + width: 16, + height: 16, + depth_or_array_layers: 3, + }, + mip_level_count: 5, + sample_count: 1, + dimension: wgpu::TextureDimension::D2, + format: wgpu::TextureFormat::Rgba8Unorm, + usage: wgpu::TextureUsages::COPY_DST | wgpu::TextureUsages::COPY_SRC, + view_formats: &[], + }) + }; + let (expected, actual) = (texture(), texture()); + let mut uploads = Uploads::new(&device); + // Two frames, so the second reuses the belt's recalled buffers. + for frame in 0..2u8 { + let mut encoder = device.create_command_encoder(&Default::default()); + for level in 0..5 { + let edge = 16 >> level; + let pixels: Vec = (0..edge * edge * 4) + .map(|i| { + (i as u8) + .wrapping_mul(31) + .wrapping_add(level as u8 * 7 + frame) + }) + .collect(); + let at = |texture| wgpu::TexelCopyTextureInfo { + texture, + mip_level: level, + origin: wgpu::Origin3d { x: 0, y: 0, z: 1 }, + aspect: wgpu::TextureAspect::All, + }; + queue.write_texture( + at(&expected), + &pixels, + wgpu::TexelCopyBufferLayout { + offset: 0, + bytes_per_row: Some(edge * 4), + rows_per_image: Some(edge), + }, + wgpu::Extent3d { + width: edge, + height: edge, + depth_or_array_layers: 1, + }, + ); + uploads.texture(&mut encoder, at(&actual), edge, edge, &pixels); + } + uploads.finish(&encoder); + queue.submit([encoder.finish()]); + device.poll(wgpu::PollType::wait_indefinitely()).unwrap(); + assert_eq!( + read_back(&device, &queue, &actual), + read_back(&device, &queue, &expected), + "frame {frame}" + ); + } + } +}