From 1e1c3b79e5267a532dc6a68444027edc83a3a299 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Fri, 16 Oct 2026 15:16:47 +0200 Subject: [PATCH] Stop animated textures from slowing every tick's frame Every frame that crossed a tick re-uploaded the animated block sprites, and that took about 1.8 ms on an M4 Pro (more than the world tick itself): - The mip-chain cache held 8 MiB, which fits 256 of the 594 vanilla animation frames (64-pixel layers, chains stored with spare capacity), so the other 338 frames had their resize and mip chain rebuilt on the render thread whenever their animation reached them. The budget is now 32 MiB and chains are allocated at their exact size: all 594 frames fit in 13 MB. - Each changed sprite mip level went through its own Queue::write_texture, which allocates and frees a GPU staging buffer per call (a few hundred a tick). They are now packed into one reused buffer, written once, and copied with one submission per tick. The texels are unchanged: a GPU test compares the batched copies with write_texture over several flushes, and the existing cache tests compare cached and generated chains. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/gfx.rs | 48 ++-- crates/horizon-client/src/gfx/uploads.rs | 285 +++++++++++++++++++++++ 2 files changed, 304 insertions(+), 29 deletions(-) create mode 100644 crates/horizon-client/src/gfx/uploads.rs diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs index 3863512f2..0eda4afe4 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 uploads; mod world_post; #[repr(C)] @@ -297,6 +298,8 @@ pub struct Renderer { lightmap_view: wgpu::TextureView, lightmap_sampler: wgpu::Sampler, animations: AnimatedSprites, + /// The animated sprites' changed mip levels, written once per tick. + sprite_uploads: uploads::TextureUploads, sprite_minimum_size: u32, indices: wgpu::Buffer, index_quads: u32, @@ -358,7 +361,9 @@ fn mip_chain( ) -> (Vec, u32) { let levels = size.trailing_zeros() + 1; let layer_bytes = (size * size * 4) as usize; - let mut out = Vec::new(); + // Exactly the chain's size: cached animation frames count their capacity. + let chain_bytes: usize = (0..levels).map(|l| layer_bytes >> (2 * l)).sum(); + let mut out = Vec::with_capacity(chain_bytes * layers as usize); for layer in 0..layers as usize { let base = crate::mipmap::Image { width: size, @@ -384,6 +389,7 @@ fn mip_chain( out.extend(image.pixels.iter().flatten()); } } + debug_assert_eq!(out.len(), chain_bytes * layers as usize); (out, levels) } /// What to tell a player whose system offers no usable graphics adapter. @@ -1557,6 +1563,7 @@ impl Renderer { lightmap_view, lightmap_sampler, animations: AnimatedSprites::new(animations, sprite_size, sprite_mips), + sprite_uploads: uploads::TextureUploads::default(), sprite_minimum_size, indices, index_quads, @@ -1964,36 +1971,14 @@ impl Renderer { self.lightmap_pixels = pixels; } fn animate(&mut self, tick: u64) { + let uploads = &mut self.sprite_uploads; animate_sprites( &mut self.animations, tick, self.mip_levels, - |layer, level, size, pixels| { - self.queue.write_texture( - wgpu::TexelCopyTextureInfo { - texture: &self.sprite_texture, - mip_level: level, - origin: wgpu::Origin3d { - x: 0, - y: 0, - z: layer, - }, - aspect: wgpu::TextureAspect::All, - }, - 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, - }, - ); - }, + |layer, level, size, pixels| uploads.push(layer, level, size, pixels), ); + uploads.flush(&self.device, &self.queue, &self.sprite_texture); } pub fn render(&mut self, frame: &Frame) -> Result { if self.suspended { @@ -2031,8 +2016,10 @@ impl Renderer { None => self.offscreen.clone().ok_or("no offscreen target")?, }; if self.animated_textures { - self.animate(frame.ticks); - self.hud.animate_fire(&self.queue, frame.ticks); + crate::spans::time("animate", || { + self.animate(frame.ticks); + self.hud.animate_fire(&self.queue, frame.ticks); + }); } self.update_lightmap( &frame.sky, @@ -3101,7 +3088,10 @@ pub(crate) fn sprite_mipmap_limit(requested: u32, size: u32, minimum: u32, avail let upscale = (size / minimum.max(1)).max(1).ilog2(); requested.saturating_add(upscale).min(available - 1) } -const ANIMATION_MIP_BUDGET: usize = 8 << 20; +/// Room for every frame of the vanilla animations (594 frames, 13 MB of mip +/// chains in 64-pixel layers), so no frame's chain is rebuilt on the render +/// thread when its animation comes back to it; larger packs stay bounded. +const ANIMATION_MIP_BUDGET: usize = 32 << 20; const ANIMATION_MIP_ENTRIES: usize = 4096; /// One immutable resource snapshot and its lazily generated frame mips. A new diff --git a/crates/horizon-client/src/gfx/uploads.rs b/crates/horizon-client/src/gfx/uploads.rs new file mode 100644 index 000000000..04bc11eb8 --- /dev/null +++ b/crates/horizon-client/src/gfx/uploads.rs @@ -0,0 +1,285 @@ +//! Square RGBA8 texture regions packed into one upload buffer. A tick's +//! animated sprites then cost one staging allocation and one submission +//! instead of a `Queue::write_texture` (and its own staging buffer) per sprite +//! and mip level, which made every tick's frame slower than the frames between +//! ticks. + +/// One queued region: `edge` x `edge` texels of array `layer`, mip `level`. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +struct Region { + offset: u64, + bytes_per_row: u32, + layer: u32, + level: u32, + edge: u32, +} + +#[derive(Default)] +pub(super) struct TextureUploads { + /// The queued texels, each row padded to `COPY_BYTES_PER_ROW_ALIGNMENT`. + data: Vec, + regions: Vec, + /// Kept between flushes and grown when a flush needs more room. + buffer: Option, +} + +impl TextureUploads { + /// Queue `pixels` (tightly packed RGBA8 rows) for `layer` at mip `level`. + pub(super) fn push(&mut self, layer: u32, level: u32, edge: u32, pixels: &[u8]) { + let row = edge as usize * 4; + debug_assert_eq!(pixels.len(), row * edge as usize); + let padded = row.next_multiple_of(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT as usize); + let offset = self.data.len(); + self.data.reserve(padded * edge as usize); + for source in pixels.chunks_exact(row) { + self.data.extend_from_slice(source); + self.data.resize(self.data.len() + padded - row, 0); + } + self.regions.push(Region { + offset: offset as u64, + bytes_per_row: padded as u32, + layer, + level, + edge, + }); + } + + /// Copy every queued region into `texture`, in the order they were queued, + /// and empty the queue. + pub(super) fn flush( + &mut self, + device: &wgpu::Device, + queue: &wgpu::Queue, + texture: &wgpu::Texture, + ) { + if self.regions.is_empty() { + return; + } + let size = self.data.len() as u64; + if self.buffer.as_ref().is_none_or(|b| b.size() < size) { + self.buffer = Some(device.create_buffer(&wgpu::BufferDescriptor { + label: Some("Texture uploads"), + size: size.next_power_of_two(), + usage: wgpu::BufferUsages::COPY_SRC | wgpu::BufferUsages::COPY_DST, + mapped_at_creation: false, + })); + } + let buffer = self.buffer.as_ref().expect("created above"); + // Queue writes land before the next submission's commands, and + // submissions run in order, so the previous flush's copies have read + // the buffer before this write replaces it. + queue.write_buffer(buffer, 0, &self.data); + let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor { + label: Some("Texture uploads"), + }); + for r in self.regions.drain(..) { + encoder.copy_buffer_to_texture( + wgpu::TexelCopyBufferInfo { + buffer, + layout: wgpu::TexelCopyBufferLayout { + offset: r.offset, + bytes_per_row: Some(r.bytes_per_row), + rows_per_image: Some(r.edge), + }, + }, + wgpu::TexelCopyTextureInfo { + texture, + mip_level: r.level, + origin: wgpu::Origin3d { + x: 0, + y: 0, + z: r.layer, + }, + aspect: wgpu::TextureAspect::All, + }, + wgpu::Extent3d { + width: r.edge, + height: r.edge, + depth_or_array_layers: 1, + }, + ); + } + queue.submit([encoder.finish()]); + self.data.clear(); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn rows_are_padded_and_regions_follow_each_other() { + let mut uploads = TextureUploads::default(); + let big: Vec = (0..16 * 16 * 4).map(|i| i as u8).collect(); + let small: Vec = (0..2 * 2 * 4).map(|i| 200 + i as u8).collect(); + uploads.push(3, 0, 16, &big); + uploads.push(3, 3, 2, &small); + let align = wgpu::COPY_BYTES_PER_ROW_ALIGNMENT as usize; + assert_eq!( + uploads.regions, + [ + Region { + offset: 0, + bytes_per_row: align as u32, + layer: 3, + level: 0, + edge: 16, + }, + Region { + offset: (16 * align) as u64, + bytes_per_row: align as u32, + layer: 3, + level: 3, + edge: 2, + }, + ] + ); + assert_eq!(uploads.data.len(), 18 * align); + // Every row starts on the alignment and holds the source row. + for y in 0..16 { + assert_eq!( + &uploads.data[y * align..y * align + 64], + &big[y * 64..(y + 1) * 64] + ); + } + for y in 0..2 { + let start = (16 + y) * align; + assert_eq!(&uploads.data[start..start + 8], &small[y * 8..(y + 1) * 8]); + } + } + + /// Every texel of a 64-pixel array texture with a full mip chain. + fn read_back(device: &wgpu::Device, queue: &wgpu::Queue, texture: &wgpu::Texture) -> Vec { + let mut encoder = device.create_command_encoder(&Default::default()); + let mut buffers = Vec::new(); + for level in 0..texture.mip_level_count() { + let edge = texture.width() >> level; + let row = (edge * 4).next_multiple_of(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT); + let layers = texture.depth_or_array_layers(); + let buffer = device.create_buffer(&wgpu::BufferDescriptor { + label: None, + size: u64::from(row * edge * layers), + usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ, + mapped_at_creation: false, + }); + encoder.copy_texture_to_buffer( + wgpu::TexelCopyTextureInfo { + texture, + mip_level: level, + origin: wgpu::Origin3d::ZERO, + aspect: wgpu::TextureAspect::All, + }, + wgpu::TexelCopyBufferInfo { + buffer: &buffer, + layout: wgpu::TexelCopyBufferLayout { + offset: 0, + bytes_per_row: Some(row), + rows_per_image: Some(edge), + }, + }, + wgpu::Extent3d { + width: edge, + height: edge, + depth_or_array_layers: layers, + }, + ); + buffers.push(buffer); + } + queue.submit([encoder.finish()]); + let mut out = Vec::new(); + for buffer in &buffers { + buffer.map_async(wgpu::MapMode::Read, .., |r| r.expect("map")); + device + .poll(wgpu::PollType::wait_indefinitely()) + .expect("poll"); + out.extend_from_slice(&buffer.get_mapped_range(..).expect("mapped")); + } + out + } + + /// The batched copies leave a texture exactly as one `write_texture` per + /// region does, over several flushes reusing (and growing) the buffer. + #[test] + fn batched_uploads_match_write_texture_on_a_gpu() { + let instance = + wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle_from_env()); + let Ok(adapter) = + pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default())) + else { + eprintln!("no GPU adapter: skipped"); + return; + }; + let (device, queue) = + pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor::default())) + .expect("device"); + let texture = || { + device.create_texture(&wgpu::TextureDescriptor { + label: None, + size: wgpu::Extent3d { + width: 64, + height: 64, + depth_or_array_layers: 4, + }, + mip_level_count: 7, + sample_count: 1, + dimension: wgpu::TextureDimension::D2, + format: wgpu::TextureFormat::Rgba8Unorm, + usage: wgpu::TextureUsages::COPY_DST | wgpu::TextureUsages::COPY_SRC, + view_formats: &[], + }) + }; + let (expected, batched) = (texture(), texture()); + let mut uploads = TextureUploads::default(); + let mut seed = 1u32; + // Small flushes first, then whole chains: the buffer has to grow. + for (round, layers) in [[1u32, 2].as_slice(), &[0, 1, 2, 3], &[3]] + .into_iter() + .enumerate() + { + for &layer in layers { + let levels = if round == 0 { 0..3 } else { 0..7 }; + for level in levels { + let edge = 64 >> level; + let pixels: Vec = (0..edge * edge * 4) + .map(|_| { + seed = seed.wrapping_mul(1_664_525).wrapping_add(1_013_904_223); + (seed >> 24) as u8 + }) + .collect(); + queue.write_texture( + wgpu::TexelCopyTextureInfo { + texture: &expected, + mip_level: level, + origin: wgpu::Origin3d { + x: 0, + y: 0, + z: layer, + }, + aspect: wgpu::TextureAspect::All, + }, + &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.push(layer, level, edge, &pixels); + } + } + uploads.flush(&device, &queue, &batched); + assert!(uploads.regions.is_empty() && uploads.data.is_empty()); + assert_eq!( + read_back(&device, &queue, &expected), + read_back(&device, &queue, &batched), + "round {round}" + ); + } + } +}