Merge pull request #647 from ludovic111/feat/sprite-arrays

Block textures: share identical sprites, and draw past 2048 layers
This commit is contained in:
Ludovic Marie
2026-10-17 04:58:13 +02:00
committed by GitHub
4 changed files with 328 additions and 148 deletions
+1 -1
View File
@@ -245,7 +245,7 @@ impl Assets {
material_states,
sprite_size: sprites.size,
sprite_minimum_size: sprites.minimum_size,
texture_layers: u32::try_from(sprites.layers.len())?,
texture_layers: u32::try_from(sprites.count())?,
pixels: sprites.pixels,
model_catalog: models.catalog,
model_library,
+199 -112
View File
@@ -290,7 +290,13 @@ pub struct Renderer {
group: wgpu::BindGroup,
globals: wgpu::Buffer,
lightmap: wgpu::Texture,
sprite_texture: wgpu::Texture,
/// The block sprites, [`SPRITE_SPLIT`] layers per array (the first is
/// `sprites` in terrain.wgsl, the others `sprites_1`...).
sprite_textures: Vec<wgpu::Texture>,
/// A 1-layer array bound where a pack needs fewer arrays.
sprite_unused: wgpu::TextureView,
/// Layers per sprite array ([`SPRITE_SPLIT`] but in tests).
sprite_split: u32,
mip_levels: u32,
/// The mipmap levels sampled (the Mipmap Levels option), at most `mip_levels - 1`.
mipmaps: u32,
@@ -356,6 +362,79 @@ pub struct Renderer {
}
/// Every layer's mip levels, layer major (`first` is the first layer's
/// index into `settings`), made by `MipmapGenerator`.
/// Block sprite layers per texture array: the smallest
/// `max_texture_array_layers` of the GPUs Horizon runs on. Mods add sprites
/// past it into more arrays (terrain.wgsl's `sprite`).
pub(crate) const SPRITE_SPLIT: u32 = 2048;
/// [`SPRITE_SPLIT`], or a smaller split from `HORIZON_SPRITE_SPLIT` (dev
/// only: vanilla's sprites drawn from several arrays must look the same).
fn sprite_split() -> u32 {
std::env::var("HORIZON_SPRITE_SPLIT")
.ok()
.and_then(|v| v.parse().ok())
.filter(|&n| (1..=SPRITE_SPLIT).contains(&n))
.unwrap_or(SPRITE_SPLIT)
}
/// Sprite arrays terrain.wgsl binds (`sprites`, `sprites_1`...).
const SPRITE_ARRAYS: u32 = 4;
/// The views of terrain.wgsl's sprite arrays, the unused ones a 1-layer
/// stand-in.
fn sprite_views(
textures: &[wgpu::Texture],
unused: &wgpu::TextureView,
mips: Option<u32>,
) -> Vec<wgpu::TextureView> {
(0..SPRITE_ARRAYS as usize)
.map(|i| match textures.get(i) {
Some(t) => t.create_view(&wgpu::TextureViewDescriptor {
dimension: Some(wgpu::TextureViewDimension::D2Array),
mip_level_count: mips,
..Default::default()
}),
None => unused.clone(),
})
.collect()
}
/// terrain.wgsl's group 0.
#[allow(clippy::too_many_arguments)]
fn terrain_group(
device: &wgpu::Device,
label: &str,
layout: &wgpu::BindGroupLayout,
globals: &wgpu::Buffer,
sprites: &[wgpu::TextureView],
sprite_sampler: &wgpu::Sampler,
lightmap: &wgpu::TextureView,
lightmap_sampler: &wgpu::Sampler,
) -> wgpu::BindGroup {
let view = |binding, view| wgpu::BindGroupEntry {
binding,
resource: wgpu::BindingResource::TextureView(view),
};
device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some(label),
layout,
entries: &[
wgpu::BindGroupEntry {
binding: 0,
resource: globals.as_entire_binding(),
},
view(1, &sprites[0]),
wgpu::BindGroupEntry {
binding: 2,
resource: wgpu::BindingResource::Sampler(sprite_sampler),
},
view(3, lightmap),
wgpu::BindGroupEntry {
binding: 4,
resource: wgpu::BindingResource::Sampler(lightmap_sampler),
},
view(5, &sprites[1]),
view(6, &sprites[2]),
view(7, &sprites[3]),
],
})
}
fn mip_chain(
pixels: &[u8],
size: u32,
@@ -496,10 +575,19 @@ impl Renderer {
),
);
let limits = adapter.limits();
if limits.max_texture_array_layers < layers {
let split = sprite_split();
if layers > split * SPRITE_ARRAYS {
return Err(format!(
"GPU supports {} texture layers; {layers} required",
limits.max_texture_array_layers
"{layers} block textures; Horizon draws at most {}",
split * SPRITE_ARRAYS
)
.into());
}
if limits.max_texture_array_layers < layers.min(split) {
return Err(format!(
"GPU supports {} texture layers; {} required",
limits.max_texture_array_layers,
layers.min(split)
)
.into());
}
@@ -567,6 +655,19 @@ impl Renderer {
count: None,
};
let vf = wgpu::ShaderStages::VERTEX_FRAGMENT;
let sprite_array = wgpu::BindingType::Texture {
sample_type: wgpu::TextureSampleType::Float { filterable: true },
view_dimension: wgpu::TextureViewDimension::D2Array,
multisampled: false,
};
let sprite_arrays = layers.div_ceil(split).max(1);
if sprite_arrays > 1 {
log::info!("Horizon: {layers} block textures in {sprite_arrays} arrays");
}
let sprite_constants = [
("SPRITE_ARRAYS", f64::from(sprite_arrays)),
("SPRITE_SPLIT", f64::from(split)),
];
let bindings = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("Horizon terrain bindings"),
entries: &[
@@ -607,6 +708,9 @@ impl Renderer {
vf,
wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
),
entry(5, vf, sprite_array),
entry(6, vf, sprite_array),
entry(7, vf, sprite_array),
],
});
let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
@@ -679,7 +783,10 @@ impl Renderer {
fragment: Some(wgpu::FragmentState {
module: &shader,
entry_point: Some(fragment),
compilation_options: Default::default(),
compilation_options: wgpu::PipelineCompilationOptions {
constants: &sprite_constants,
..Default::default()
},
targets: &[Some(wgpu::ColorTargetState {
format: config.format.remove_srgb_suffix(),
blend,
@@ -786,30 +893,62 @@ impl Renderer {
usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
let (mips, mip_levels) = mip_chain(sprite_pixels, sprite_size, sprite_mips, 0, layers);
let sprite_texture = device.create_texture_with_data(
&queue,
&wgpu::TextureDescriptor {
label: Some("Block sprites"),
let layer_bytes = (sprite_size * sprite_size * 4) as usize;
let mut mip_levels = 1;
let sprite_textures: Vec<wgpu::Texture> = (0..sprite_arrays)
.map(|array| {
let first = array * split;
let count = layers.saturating_sub(first).clamp(1, split);
let start = (first as usize * layer_bytes).min(sprite_pixels.len());
let (mips, levels) = mip_chain(
&sprite_pixels[start..],
sprite_size,
sprite_mips,
first,
count,
);
mip_levels = levels;
device.create_texture_with_data(
&queue,
&wgpu::TextureDescriptor {
label: Some("Block sprites"),
size: wgpu::Extent3d {
width: sprite_size,
height: sprite_size,
depth_or_array_layers: count,
},
mip_level_count: levels,
sample_count: 1,
dimension: wgpu::TextureDimension::D2,
format: wgpu::TextureFormat::Rgba8Unorm,
usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
view_formats: &[],
},
wgpu::util::TextureDataOrder::LayerMajor,
&mips,
)
})
.collect();
let sprite_unused = device
.create_texture(&wgpu::TextureDescriptor {
label: Some("Block sprites (unused)"),
size: wgpu::Extent3d {
width: sprite_size,
height: sprite_size,
depth_or_array_layers: layers,
width: 1,
height: 1,
depth_or_array_layers: 1,
},
mip_level_count: mip_levels,
mip_level_count: 1,
sample_count: 1,
dimension: wgpu::TextureDimension::D2,
format: wgpu::TextureFormat::Rgba8Unorm,
usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
usage: wgpu::TextureUsages::TEXTURE_BINDING,
view_formats: &[],
},
wgpu::util::TextureDataOrder::LayerMajor,
&mips,
);
let sprite_view = sprite_texture.create_view(&wgpu::TextureViewDescriptor {
dimension: Some(wgpu::TextureViewDimension::D2Array),
..Default::default()
});
})
.create_view(&wgpu::TextureViewDescriptor {
dimension: Some(wgpu::TextureViewDimension::D2Array),
..Default::default()
});
let sprite_views = sprite_views(&sprite_textures, &sprite_unused, None);
let sprite_sampler = device.create_sampler(&wgpu::SamplerDescriptor {
label: Some("Block sprites"),
address_mode_u: wgpu::AddressMode::Repeat,
@@ -840,58 +979,26 @@ impl Renderer {
min_filter: wgpu::FilterMode::Linear,
..Default::default()
});
let group = device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some("Horizon terrain resources"),
layout: &bindings,
entries: &[
wgpu::BindGroupEntry {
binding: 0,
resource: globals.as_entire_binding(),
},
wgpu::BindGroupEntry {
binding: 1,
resource: wgpu::BindingResource::TextureView(&sprite_view),
},
wgpu::BindGroupEntry {
binding: 2,
resource: wgpu::BindingResource::Sampler(&sprite_sampler),
},
wgpu::BindGroupEntry {
binding: 3,
resource: wgpu::BindingResource::TextureView(&lightmap_view),
},
wgpu::BindGroupEntry {
binding: 4,
resource: wgpu::BindingResource::Sampler(&lightmap_sampler),
},
],
});
let crosshair_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some("Debug crosshair resources"),
layout: &bindings,
entries: &[
wgpu::BindGroupEntry {
binding: 0,
resource: crosshair_globals.as_entire_binding(),
},
wgpu::BindGroupEntry {
binding: 1,
resource: wgpu::BindingResource::TextureView(&sprite_view),
},
wgpu::BindGroupEntry {
binding: 2,
resource: wgpu::BindingResource::Sampler(&sprite_sampler),
},
wgpu::BindGroupEntry {
binding: 3,
resource: wgpu::BindingResource::TextureView(&lightmap_view),
},
wgpu::BindGroupEntry {
binding: 4,
resource: wgpu::BindingResource::Sampler(&lightmap_sampler),
},
],
});
let group = terrain_group(
&device,
"Horizon terrain resources",
&bindings,
&globals,
&sprite_views,
&sprite_sampler,
&lightmap_view,
&lightmap_sampler,
);
let crosshair_group = terrain_group(
&device,
"Debug crosshair resources",
&bindings,
&crosshair_globals,
&sprite_views,
&sprite_sampler,
&lightmap_view,
&lightmap_sampler,
);
let index_quads = 1 << 16;
let indices = Self::quad_indices(&device, index_quads);
let instance_capacity = 4096;
@@ -1577,7 +1684,9 @@ impl Renderer {
group,
globals,
lightmap,
sprite_texture,
sprite_textures,
sprite_unused,
sprite_split: split,
mip_levels,
mipmaps: mip_levels - 1,
terrain_layout: bindings,
@@ -1867,7 +1976,7 @@ impl Renderer {
pub fn set_mipmap_levels(&mut self, levels: u32) {
let levels = sprite_mipmap_limit(
levels,
self.sprite_texture.width(),
self.sprite_textures[0].width(),
self.sprite_minimum_size,
self.mip_levels,
);
@@ -1875,39 +1984,17 @@ impl Renderer {
return;
}
self.mipmaps = levels;
let sprite_view = self
.sprite_texture
.create_view(&wgpu::TextureViewDescriptor {
dimension: Some(wgpu::TextureViewDimension::D2Array),
mip_level_count: Some(levels + 1),
..Default::default()
});
self.group = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some("Horizon terrain resources"),
layout: &self.terrain_layout,
entries: &[
wgpu::BindGroupEntry {
binding: 0,
resource: self.globals.as_entire_binding(),
},
wgpu::BindGroupEntry {
binding: 1,
resource: wgpu::BindingResource::TextureView(&sprite_view),
},
wgpu::BindGroupEntry {
binding: 2,
resource: wgpu::BindingResource::Sampler(&self.sprite_sampler),
},
wgpu::BindGroupEntry {
binding: 3,
resource: wgpu::BindingResource::TextureView(&self.lightmap_view),
},
wgpu::BindGroupEntry {
binding: 4,
resource: wgpu::BindingResource::Sampler(&self.lightmap_sampler),
},
],
});
let views = sprite_views(&self.sprite_textures, &self.sprite_unused, Some(levels + 1));
self.group = terrain_group(
&self.device,
"Horizon terrain resources",
&self.terrain_layout,
&self.globals,
&views,
&self.sprite_sampler,
&self.lightmap_view,
&self.lightmap_sampler,
);
}
pub fn view_projection(&self, frame: &Frame) -> Mat4 {
self.projection(
@@ -2007,12 +2094,12 @@ impl Renderer {
self.uploads.texture(
encoder,
wgpu::TexelCopyTextureInfo {
texture: &self.sprite_texture,
texture: &self.sprite_textures[(layer / self.sprite_split) as usize],
mip_level: level,
origin: wgpu::Origin3d {
x: 0,
y: 0,
z: layer,
z: layer % self.sprite_split,
},
aspect: wgpu::TextureAspect::All,
},
+103 -33
View File
@@ -82,6 +82,10 @@ pub struct Sprites {
/// Each layer's frames at the texture's own resolution (square), and the
/// frame shown first.
native: Vec<(u32, Arc<Vec<Vec<u8>>>, usize)>,
/// Still textures by their pixels and mip settings: mods copy vanilla's
/// textures under their own names, and one layer serves them all (the
/// GPU's array may hold as few as 2048).
still: std::collections::HashMap<(Vec<u8>, u32, [u32; 2], [bool; 4]), u32>,
}
/// Edge length of vanilla's block textures: the smallest array layer.
pub const SPRITE_SIZE: u32 = 16;
@@ -104,6 +108,10 @@ fn resample(frame: &[u8], from: u32, to: u32) -> Vec<u8> {
out
}
impl Sprites {
/// How many array layers the textures take.
pub fn count(&self) -> usize {
self.native.len()
}
/// Lay every layer out at one size: the largest texture's (resource packs
/// may ship 32x, 64x... textures, like vanilla's stitched atlas), rounded
/// up to a power of two and limited to [`MAX_ARRAY_BYTES`]. Smaller
@@ -152,7 +160,7 @@ impl Sprites {
}
})
.collect();
let layer = u32::try_from(self.layers.len())?;
let layer = u32::try_from(self.native.len())?;
self.opaque.push(true);
self.translucent.push(false);
self.mips.push(crate::mipmap::Settings::default());
@@ -209,7 +217,7 @@ impl Sprites {
};
pixels.extend(rgba);
}
let layer = u32::try_from(self.layers.len())?;
let layer = u32::try_from(self.native.len())?;
let columns = info.width / width;
let count = columns * (info.height / height);
// Layers are square; a frame of another shape is nearest-resampled to
@@ -230,6 +238,46 @@ impl Sprites {
}
frames.push(frame);
}
let settings = crate::mipmap::Settings {
native_size: side,
strategy: texture_section(metadata.as_ref())
.as_ref()
.and_then(|t| t["mipmap_strategy"].as_str())
.and_then(crate::mipmap::Strategy::parse)
.unwrap_or_default(),
alpha_cutoff_bias: texture_section(metadata.as_ref())
.as_ref()
.and_then(|t| t["alpha_cutoff_bias"].as_f64())
.unwrap_or(0.0) as f32,
has_transparent: pixels.as_chunks::<4>().0.iter().any(|p| p[3] == 0),
item: name
.split_once(':')
.is_some_and(|(_, p)| p.starts_with("item/")),
};
let opaque = pixels.as_chunks::<4>().0.iter().all(|p| p[3] == 255);
let translucent = pixels
.as_chunks::<4>()
.0
.iter()
.any(|p| p[3] != 0 && p[3] != 255);
let still = (animation.is_none() && frames.len() == 1).then(|| {
(
frames[0].clone(),
side,
[
settings.strategy as u32,
settings.alpha_cutoff_bias.to_bits(),
],
[settings.has_transparent, settings.item, opaque, translucent],
)
});
if let Some(&same) = still.as_ref().and_then(|k| self.still.get(k)) {
self.layers.insert(name.to_owned(), same);
return Ok(same);
}
if let Some(key) = still {
self.still.insert(key, layer);
}
let frames = Arc::new(frames);
let mut initial = 0;
if let Some(clip) = animation
@@ -245,43 +293,25 @@ impl Sprites {
clip: Arc::new(clip),
});
}
// SpriteContents: TextureMetadataSection's mipmap strategy and alpha
// cutoff bias, and the whole image's NativeImage.computeTransparency.
let texture = metadata
.as_ref()
.and_then(|v| v.get("texture"))
.and_then(|v| serde_json::from_str::<serde_json::Value>(v.get()).ok());
self.mips.push(crate::mipmap::Settings {
native_size: side,
strategy: texture
.as_ref()
.and_then(|t| t["mipmap_strategy"].as_str())
.and_then(crate::mipmap::Strategy::parse)
.unwrap_or_default(),
alpha_cutoff_bias: texture
.as_ref()
.and_then(|t| t["alpha_cutoff_bias"].as_f64())
.unwrap_or(0.0) as f32,
has_transparent: pixels.as_chunks::<4>().0.iter().any(|p| p[3] == 0),
item: name
.split_once(':')
.is_some_and(|(_, p)| p.starts_with("item/")),
});
self.opaque
.push(pixels.as_chunks::<4>().0.iter().all(|p| p[3] == 255));
self.translucent.push(
pixels
.as_chunks::<4>()
.0
.iter()
.any(|p| p[3] != 0 && p[3] != 255),
);
self.mips.push(settings);
self.opaque.push(opaque);
self.translucent.push(translucent);
self.layers.insert(name.to_owned(), layer);
self.native.push((side, frames, initial));
Ok(layer)
}
}
/// SpriteContents: the `.mcmeta` `texture` section (TextureMetadataSection's
/// mipmap strategy and alpha cutoff bias).
fn texture_section(
metadata: Option<&BTreeMap<String, Box<serde_json::value::RawValue>>>,
) -> Option<serde_json::Value> {
metadata
.and_then(|v| v.get("texture"))
.and_then(|v| serde_json::from_str(v.get()).ok())
}
#[cfg(test)]
pub(crate) fn test_animation(size: u32, layer: u32) -> SpriteAnimation {
test_clip(size, layer, r#"{"frametime":1,"frames":[0,1]}"#)
@@ -305,6 +335,46 @@ pub(crate) fn test_clip(size: u32, layer: u32, metadata: &str) -> SpriteAnimatio
mod tests {
use super::*;
#[test]
fn identical_still_textures_share_a_layer() {
let root =
std::env::temp_dir().join(format!("horizon-sprite-share-{}", std::process::id()));
let directory = root.join("assets/a/textures/block");
fs::create_dir_all(&directory).unwrap();
let write = |name: &str, red: u8| {
let mut encoder =
png::Encoder::new(File::create(directory.join(name)).unwrap(), 16, 16);
encoder.set_color(png::ColorType::Rgba);
encoder.set_depth(png::BitDepth::Eight);
let pixels: Vec<u8> = (0..256).flat_map(|i| [red, i as u8, 0, 255]).collect();
encoder
.write_header()
.unwrap()
.write_image_data(&pixels)
.unwrap();
};
write("one.png", 10);
write("copy.png", 10);
write("other.png", 20);
let mut sprites = Sprites::default();
let one = sprites.insert(&root, "a:block/one").unwrap();
let copy = sprites.insert(&root, "a:block/copy").unwrap();
let other = sprites.insert(&root, "a:block/other").unwrap();
// The same pixels as an item sprite mip differently: a layer of its own.
fs::create_dir_all(root.join("assets/a/textures/item")).unwrap();
fs::copy(
directory.join("one.png"),
root.join("assets/a/textures/item/one.png"),
)
.unwrap();
let item = sprites.insert(&root, "a:item/one").unwrap();
fs::remove_dir_all(&root).unwrap();
assert_eq!((one, copy, other, item), (0, 0, 1, 2));
assert_eq!((sprites.count(), sprites.layers.len()), (3, 4));
assert_eq!((sprites.opaque.len(), sprites.mips.len()), (3, 3));
sprites.finish();
assert_eq!(sprites.pixels.len(), 3 * 16 * 16 * 4);
}
#[test]
fn a_32px_only_atlas_does_not_add_an_extra_mipmap() {
let mut sprites = Sprites {
native: vec![
+25 -2
View File
@@ -27,6 +27,29 @@ struct Globals {
@group(0) @binding(2) var sprite_sampler: sampler;
@group(0) @binding(3) var lightmap: texture_2d<f32>;
@group(0) @binding(4) var lightmap_sampler: sampler;
// Layers past the first array's SPRITE_SPLIT (2048, gfx.rs): mods' sprites.
@group(0) @binding(5) var sprites_1: texture_2d_array<f32>;
@group(0) @binding(6) var sprites_2: texture_2d_array<f32>;
@group(0) @binding(7) var sprites_3: texture_2d_array<f32>;
// How many sprite arrays hold layers (a pipeline constant): 1 for vanilla,
// which then samples exactly as before.
override SPRITE_ARRAYS: u32 = 1u;
override SPRITE_SPLIT: u32 = 2048u;
fn sprite(uv: vec2<f32>, layer: u32) -> vec4<f32> {
if SPRITE_ARRAYS == 1u {
return textureSample(sprites, sprite_sampler, uv, i32(layer));
}
// The array is chosen per fragment: sample with the derivatives taken here.
let dx = dpdx(uv);
let dy = dpdy(uv);
let l = i32(layer % SPRITE_SPLIT);
switch layer / SPRITE_SPLIT {
case 0u: { return textureSampleGrad(sprites, sprite_sampler, uv, l, dx, dy); }
case 1u: { return textureSampleGrad(sprites_1, sprite_sampler, uv, l, dx, dy); }
case 2u: { return textureSampleGrad(sprites_2, sprite_sampler, uv, l, dx, dy); }
default: { return textureSampleGrad(sprites_3, sprite_sampler, uv, l, dx, dy); }
}
}
struct TerrainOut {
@builtin(position) clip: vec4<f32>,
@@ -67,12 +90,12 @@ fn apply_fog(color: vec4<f32>, spherical: f32, cylindrical: f32) -> vec4<f32> {
}
@fragment fn fs_solid(in: TerrainOut) -> @location(0) vec4<f32> {
// Bit 15 of the layer marks opaque leaves (forceOpaque): no alpha cutout.
let color = textureSample(sprites, sprite_sampler, in.uv, i32(in.layer & 0x7fffu)) * in.color;
let color = sprite(in.uv, in.layer & 0x7fffu) * in.color;
if color.a < 0.5 && (in.layer & 0x8000u) == 0u { discard; }
return apply_fog(vec4(color.rgb, 1.0), in.spherical, in.cylindrical);
}
@fragment fn fs_translucent(in: TerrainOut) -> @location(0) vec4<f32> {
let color = textureSample(sprites, sprite_sampler, in.uv, i32(in.layer & 0x7fffu)) * in.color;
let color = sprite(in.uv, in.layer & 0x7fffu) * in.color;
if color.a < 0.01 { discard; }
return apply_fog(color, in.spherical, in.cylindrical);
}