Merge pull request #501 from ludovic111/perf/animated-sprite-uploads

Upload animated sprites through a reused staging belt
This commit is contained in:
Ludovic Marie
2026-10-16 16:31:11 +02:00
committed by GitHub
2 changed files with 212 additions and 18 deletions
+16 -18
View File
@@ -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();
+196
View File
@@ -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<u8> {
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<u8> = (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}"
);
}
}
}