From 608d1a70a74f80abd392fe458ab36d7ae42b0d67 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 25 Oct 2026 15:27:43 +0100 Subject: [PATCH] Horizon shader packs: the stages of API 0.1 and their generated reference Three stages, each a WGSL function with a fixed signature that Horizon calls inside its own pass: sky (fn sky(input: SkyInput) -> vec4), material (fn material(input: MaterialInput) -> Surface) and post (fn post(input: PostInput) -> vec4). A stage's WGSL is a generated prelude (the frame uniform, the stage's structs, its resources in bind group 3, the post helpers), the pack's shared files, its own file, then the entry points; each part is located so errors point at the pack's file and line. The frame is the Rust struct the renderer will upload; its WGSL, its offsets and docs/api/shaders-reference.md are generated from it, and tests check that the preludes compile, that naga's layout of the WGSL is the Rust layout, that the sample pack's stages compile, and that the reference is up to date. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 2 + crates/horizon-shader-api/Cargo.toml | 4 + crates/horizon-shader-api/src/inputs.rs | 218 ++++++++++++++ crates/horizon-shader-api/src/lib.rs | 5 + crates/horizon-shader-api/src/package.rs | 4 +- crates/horizon-shader-api/src/reference.rs | 88 ++++++ crates/horizon-shader-api/src/stages.rs | 265 ++++++++++++++++++ crates/horizon-shader-api/tests/reference.rs | 119 ++++++++ .../tests/samples/schema-1/README.md | 2 +- .../tests/samples/schema-1/material.wgsl | 3 +- docs/api/shaders-reference.md | 152 ++++++++++ docs/api/shaders.md | 6 +- 12 files changed, 862 insertions(+), 6 deletions(-) create mode 100644 crates/horizon-shader-api/src/inputs.rs create mode 100644 crates/horizon-shader-api/src/reference.rs create mode 100644 crates/horizon-shader-api/src/stages.rs create mode 100644 crates/horizon-shader-api/tests/reference.rs create mode 100644 docs/api/shaders-reference.md diff --git a/Cargo.lock b/Cargo.lock index 25b278069..7586c5d11 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1441,6 +1441,8 @@ dependencies = [ name = "horizon-shader-api" version = "0.1.0" dependencies = [ + "bytemuck", + "naga", "serde", "toml", "zip", diff --git a/crates/horizon-shader-api/Cargo.toml b/crates/horizon-shader-api/Cargo.toml index 5d9098055..249019042 100644 --- a/crates/horizon-shader-api/Cargo.toml +++ b/crates/horizon-shader-api/Cargo.toml @@ -7,9 +7,13 @@ rust-version = "1.85" description = "Horizon's own shader packs (WGSL, docs/api/shaders.md): horizon-shaders.toml, the .hshader package" [dependencies] +bytemuck = { version = "1.24", features = ["derive"] } serde = { version = "1", features = ["derive"] } toml = "1.1.6" zip = { version = "2", default-features = false, features = ["deflate"] } +[dev-dependencies] +naga = { version = "30.0.1", features = ["wgsl-in"] } + [lints] workspace = true diff --git a/crates/horizon-shader-api/src/inputs.rs b/crates/horizon-shader-api/src/inputs.rs new file mode 100644 index 000000000..5bc82fd82 --- /dev/null +++ b/crates/horizon-shader-api/src/inputs.rs @@ -0,0 +1,218 @@ +//! What a pack's WGSL reads: the frame uniform every stage sees, which the +//! renderer fills and uploads as the Rust struct below, and the stage input +//! and output structs. The WGSL of each is generated from these definitions +//! (`Struct::wgsl`), and so is the reference (docs/api/shaders-reference.md). + +/// One field of a WGSL struct, for the prelude and the reference. +#[derive(Debug)] +pub struct Field { + pub name: &'static str, + pub ty: &'static str, + /// Its meaning, unit and range. + pub doc: &'static str, +} + +/// A struct a pack's WGSL can name. +#[derive(Debug)] +pub struct Struct { + pub name: &'static str, + pub doc: &'static str, + pub fields: &'static [Field], +} + +impl Struct { + pub fn wgsl(&self) -> String { + let mut out = format!("struct {} {{\n", self.name); + for f in self.fields { + out += &format!(" {}: {},\n", f.name, f.ty); + } + out + "}\n" + } +} + +/// The WGSL type of a Rust field the renderer uploads. +pub trait Wgsl { + const TYPE: &'static str; +} + +macro_rules! wgsl_types { + ($($rust:ty => $wgsl:literal),* $(,)?) => { + $(impl Wgsl for $rust { + const TYPE: &'static str = $wgsl; + })* + }; +} + +wgsl_types! { + f32 => "f32", + u32 => "u32", + i32 => "i32", + [f32; 2] => "vec2", + [f32; 3] => "vec3", + [f32; 4] => "vec4", + [[f32; 4]; 4] => "mat4x4", +} + +/// A uniform struct: the Rust type the renderer uploads, and its WGSL. +macro_rules! uniform { + ($(#[doc = $doc:literal])* $name:ident { + $($(#[doc = $fdoc:literal])* $field:ident: $ty:ty,)* + }) => { + $(#[doc = $doc])* + #[repr(C)] + #[derive(Clone, Copy, Debug, Default, PartialEq, bytemuck::Pod, bytemuck::Zeroable)] + pub struct $name { + $($(#[doc = $fdoc])* pub $field: $ty,)* + } + + impl $name { + pub const WGSL: Struct = Struct { + name: stringify!($name), + doc: concat!($($doc, "\n"),*), + fields: &[$(Field { + name: stringify!($field), + ty: <$ty as Wgsl>::TYPE, + doc: concat!($($fdoc),*), + }),*], + }; + /// Each field's byte offset, in `WGSL.fields`' order. + pub const OFFSETS: &'static [usize] = &[$(std::mem::offset_of!($name, $field)),*]; + } + }; +} + +uniform! { + /// The frame, as `frame` in every stage. Positions and directions are + /// in world axes relative to the camera (x east, y up, z south), so they + /// stay precise far from the world's origin; depth is reversed (1 near, + /// 0 at the far plane and in the sky). + Frame { + /// Camera-relative world to view space: the camera's rotation. + view: [[f32; 4]; 4], + /// View to clip space (reversed depth, wgpu's clip space: z 0..1). + projection: [[f32; 4]; 4], + /// View to camera-relative world space. + view_inverse: [[f32; 4]; 4], + /// Clip to view space. + projection_inverse: [[f32; 4]; 4], + /// The camera's world position, in blocks (about a millimetre of precision 10 000 blocks out). + camera_position: [f32; 3], + /// Seconds since the pack was loaded, wrapping to 0 every hour. + time: f32, + /// Unit vector toward the sun (below the horizon at night). + sun_direction: [f32; 3], + /// The time of day, 0..1: 0 sunrise, 0.25 noon, 0.5 sunset, 0.75 midnight. + day_time: f32, + /// Unit vector toward the moon. + moon_direction: [f32; 3], + /// Vanilla's GameTime: (game time % 24000 + partial tick) / 24000, 0..1. + game_time: f32, + /// Vanilla's sky colour this frame, 0..1. + sky_color: [f32; 3], + /// Rain strength, 0..1. + rain: f32, + /// Vanilla's fog colour this frame (also the clear colour), 0..1. + fog_color: [f32; 3], + /// Thunder strength, 0..1. + thunder: f32, + /// The size of the world's picture, in pixels (the resolution scale applied). + resolution: [f32; 2], + /// Block and sky light at the camera, 0..1 (level / 15). + eye_light: [f32; 2], + /// Where vanilla's fog starts, in blocks from the camera. + fog_start: f32, + /// Where vanilla's fog is full, in blocks. + fog_end: f32, + /// The render distance, in blocks. + render_distance: f32, + /// The far plane, in blocks. + far: f32, + /// Night vision strength, 0..1. + night_vision: f32, + /// Blindness strength, 0..1. + blindness: f32, + /// The darkness effect's strength, 0..1. + darkness: f32, + /// The Brightness option, 0..1 (Moody to Bright). + brightness: f32, + /// What the camera is in: 0 air, 1 water, 2 lava, 3 powder snow. + eye_in: u32, + /// 0 the Overworld, -1 the Nether, 1 the End, 2 any other dimension. + dimension: i32, + /// Frames drawn since the pack was loaded (wraps). + frame_index: u32, + /// 1 while F1 hides the HUD, else 0. + hide_gui: u32, + } +} + +macro_rules! fields { + ($($name:ident: $ty:literal = $doc:literal,)*) => { + &[$(Field { name: stringify!($name), ty: $ty, doc: $doc }),*] + }; +} + +/// The post stage's input: one pixel of the picture. +pub const POST_INPUT: Struct = Struct { + name: "PostInput", + doc: "One pixel of the picture, for `fn post(input: PostInput) -> vec4`.", + fields: fields! { + uv: "vec2" = "Where the pixel is, 0..1 from the top left.", + pixel: "vec2" = "The pixel's centre, in pixels from the top left.", + color: "vec4" = "The previous pass's colour here (the world's picture for the first pass).", + depth: "f32" = "The world's depth here, reversed: 0 is the sky.", + }, +}; + +/// The material stage's input: one point of a block's surface. +pub const MATERIAL_INPUT: Struct = Struct { + name: "MaterialInput", + doc: "One point of a block's surface, for `fn material(input: MaterialInput) -> Surface`.", + fields: fields! { + albedo: "vec4" = "The block texture's colour here (alpha 0..1).", + tint: "vec4" = "The vertex colour: biome tint, face shade and ambient occlusion.", + light: "vec2" = "Block and sky light, 0..1, smoothed over the face.", + lightmap: "vec3" = "Vanilla's light colour for that light this frame.", + position: "vec3" = "The point, camera-relative, in blocks.", + uv: "vec2" = "The texture coordinate inside the block atlas.", + translucent: "bool" = "Drawn in the translucent pass (water, stained glass, ice).", + }, +}; + +/// What the material stage returns. +pub const SURFACE: Struct = Struct { + name: "Surface", + doc: "What `material` returns. Vanilla's own is `albedo * tint * vec4(lightmap, 1.0)`; \ + Horizon then applies the alpha test (cutout and translucent) and fog.", + fields: fields! { + color: "vec4" = "The lit colour, 0..1, with its alpha.", + }, +}; + +/// The sky stage's input: one direction of the sky. +pub const SKY_INPUT: Struct = Struct { + name: "SkyInput", + doc: "One direction of the sky, for `fn sky(input: SkyInput) -> vec4`. The sun, moon, \ + stars and clouds are drawn over the result.", + fields: fields! { + direction: "vec3" = "Unit view ray, camera-relative world axes.", + color: "vec4" = "Vanilla's sky colour along the ray (sky, fog and sunrise).", + }, +}; + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn frame_fields_carry_their_docs() { + let wgsl = Frame::WGSL; + assert_eq!(wgsl.fields.len(), 28); + assert!(wgsl.fields.iter().all(|f| !f.doc.trim().is_empty())); + assert_eq!(std::mem::size_of::(), 4 * 64 + 9 * 16); + assert!( + wgsl.wgsl() + .contains(" camera_position: vec3,\n time: f32,\n") + ); + } +} diff --git a/crates/horizon-shader-api/src/lib.rs b/crates/horizon-shader-api/src/lib.rs index 418563089..1d85e7a5e 100644 --- a/crates/horizon-shader-api/src/lib.rs +++ b/crates/horizon-shader-api/src/lib.rs @@ -3,8 +3,13 @@ //! a folder or a `.hshader`. This crate reads and checks packs; the game, the //! launcher and the registry all use it, so a pack is judged the same way //! everywhere. +pub mod inputs; pub mod manifest; pub mod package; +pub mod reference; +pub mod stages; +pub use inputs::Frame; pub use manifest::{API, MANIFEST, Manifest, OptionKind, PackOption, SCHEMA, Stage}; pub use package::{EXTENSION, Pack}; +pub use stages::{Composed, StageKind, compose}; diff --git a/crates/horizon-shader-api/src/package.rs b/crates/horizon-shader-api/src/package.rs index af72afc4c..d95e8d321 100644 --- a/crates/horizon-shader-api/src/package.rs +++ b/crates/horizon-shader-api/src/package.rs @@ -11,9 +11,9 @@ use std::{ /// A packaged pack's extension. pub const EXTENSION: &str = "hshader"; /// Bytes per WGSL file, per other file, and in all. -const MAX_WGSL: u64 = 256 << 10; +pub const MAX_WGSL: u64 = 256 << 10; const MAX_OTHER: u64 = 1 << 20; -const MAX_TOTAL: u64 = 8 << 20; +pub const MAX_TOTAL: u64 = 8 << 20; /// Files in a `.hshader`. const MAX_ENTRIES: usize = 512; /// Files a pack may hold beside its manifest and WGSL. diff --git a/crates/horizon-shader-api/src/reference.rs b/crates/horizon-shader-api/src/reference.rs new file mode 100644 index 000000000..9847ccf90 --- /dev/null +++ b/crates/horizon-shader-api/src/reference.rs @@ -0,0 +1,88 @@ +//! docs/api/shaders-reference.md, generated from the stages and inputs this +//! crate defines (`tests/reference.rs` fails when the file drifts). +use crate::inputs::{Frame, SURFACE, Struct}; +use crate::manifest::{API, MAX_GPU_MS, MAX_OPTIONS, MAX_POST_PASSES}; +use crate::package::{MAX_TOTAL, MAX_WGSL}; +use crate::stages::{GROUP, StageKind}; + +fn table(s: &Struct, offsets: Option<&[usize]>) -> String { + let mut out = format!("### `{}`\n\n{}\n\n", s.name, one_line(s.doc)); + out += if offsets.is_some() { + "| Field | Type | Offset | Meaning |\n| --- | --- | --- | --- |\n" + } else { + "| Field | Type | Meaning |\n| --- | --- | --- |\n" + }; + for (i, f) in s.fields.iter().enumerate() { + let offset = offsets.map_or(String::new(), |o| format!(" {} |", o[i])); + out += &format!( + "| `{}` | `{}` |{offset} {} |\n", + f.name, + f.ty, + one_line(f.doc) + ); + } + out + "\n" +} + +fn one_line(doc: &str) -> String { + doc.split_whitespace().collect::>().join(" ") +} + +pub fn markdown() -> String { + let mut out = format!( + "# Shader API reference ({API})\n\n\ + Generated from `crates/horizon-shader-api` (`HORIZON_WRITE_DOCS=1 cargo test -p horizon-shader-api --test reference`\n\ + rewrites it; the test fails when it drifts). The API's design and pack format: [shaders.md](shaders.md).\n\n\ + A stage is a function your WGSL defines, with the signature below; Horizon puts the prelude (these structs, the\n\ + resources and helpers) before your files and calls the function from its own pass. Your files declare no\n\ + bindings and no entry points, and no names starting with `horizon_`.\n\n\ + ## Stages\n\n\ + | Stage | In `horizon-shaders.toml` | Your function |\n| --- | --- | --- |\n" + ); + for kind in StageKind::ALL { + let key = match kind { + StageKind::Post => "[[post]]", + StageKind::Sky => "[sky]", + StageKind::Material => "[material]", + }; + out += &format!("| {} | `{key}` | `{}` |\n", kind.name(), kind.signature()); + } + out += "\n"; + for kind in StageKind::ALL { + out += &format!("## {}\n\n`{}`\n\n", kind.name(), kind.signature()); + out += &table(kind.input(), None); + if kind == StageKind::Material { + out += &table(&SURFACE, None); + } + out += &format!( + "Resources (bind group {GROUP}):\n\n| Binding | Declaration | Meaning |\n| --- | --- | --- |\n" + ); + for r in kind.resources() { + out += &format!("| {} | `{}` | {} |\n", r.binding, r.ty, r.doc); + } + out += "\n"; + if kind == StageKind::Post { + out += "Helpers:\n\n\ + - `fn depth_at(uv: vec2) -> f32`: the world's depth at `uv`.\n\ + - `fn view_position(uv: vec2, depth: f32) -> vec3`: the camera-relative position, in blocks, of\n \ + the point at `uv` and `depth`.\n\n"; + } + } + out += "## The frame\n\n"; + out += &table(&Frame::WGSL, Some(Frame::OFFSETS)); + out += &format!( + "## Options\n\n\ + Each `[[options]]` entry sets the WGSL `override` of the same name when the pipelines are built:\n\n\ + | `type` | Keys | The `override` |\n| --- | --- | --- |\n\ + | `bool` | `default` | `override : bool` |\n\ + | `float` | `default`, `min`, `max`, `step` | `override : f32` |\n\ + | `int` | `default`, `min`, `max` | `override : i32` |\n\ + | `choice` | `values`, `default` (one of them) | `override : u32`, the value's index |\n\n\ + ## Limits\n\n\ + - {MAX_POST_PASSES} post passes, {MAX_OPTIONS} options, `budget.gpu_ms` up to {MAX_GPU_MS}.\n\ + - {} KiB per WGSL file, {} MiB per pack.\n", + MAX_WGSL >> 10, + MAX_TOTAL >> 20 + ); + out +} diff --git a/crates/horizon-shader-api/src/stages.rs b/crates/horizon-shader-api/src/stages.rs new file mode 100644 index 000000000..12bd3e038 --- /dev/null +++ b/crates/horizon-shader-api/src/stages.rs @@ -0,0 +1,265 @@ +//! The stages a pack can fill, each a WGSL function with a fixed signature +//! that Horizon calls inside its own passes, and the WGSL put around a +//! pack's files to build a stage: the prelude before (the inputs and the +//! resources), the entry points after. +use crate::inputs::{Frame, MATERIAL_INPUT, POST_INPUT, SKY_INPUT, SURFACE, Struct}; +use crate::package::Pack; + +/// The bind group of a pack's resources; groups 0 to 2 are the renderer's. +pub const GROUP: u32 = 3; + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum StageKind { + /// The sky's colour along each view ray, before the sun, moon and stars. + Sky, + /// The colour of block surfaces (terrain), before the alpha test and fog. + Material, + /// A full-screen pass over the world's picture, under the hand and HUD. + Post, +} + +/// A resource a stage reads, declared by its prelude. +#[derive(Debug)] +pub struct Resource { + pub binding: u32, + pub name: &'static str, + pub ty: &'static str, + pub doc: &'static str, +} + +const FRAME: Resource = Resource { + binding: 0, + name: "frame", + ty: "var frame: Frame", + doc: "The frame (`Frame`).", +}; + +const POST_RESOURCES: [Resource; 6] = [ + FRAME, + Resource { + binding: 1, + name: "scene_color", + ty: "var scene_color: texture_2d", + doc: "The world's picture before any pass.", + }, + Resource { + binding: 2, + name: "scene_depth", + ty: "var scene_depth: texture_depth_2d", + doc: "The world's depth, reversed (1 near, 0 far and sky).", + }, + Resource { + binding: 3, + name: "previous", + ty: "var previous: texture_2d", + doc: "The previous pass's output (`scene_color` for the first pass).", + }, + Resource { + binding: 4, + name: "linear_sampler", + ty: "var linear_sampler: sampler", + doc: "Bilinear filtering, clamped to the edges.", + }, + Resource { + binding: 5, + name: "nearest_sampler", + ty: "var nearest_sampler: sampler", + doc: "Nearest texel, clamped to the edges.", + }, +]; + +/// Functions the post prelude gives packs. +const POST_HELPERS: &str = "\ +// The world's depth at `uv` (reversed: 0 is the sky). +fn depth_at(uv: vec2) -> f32 { + let size = vec2(textureDimensions(scene_depth)); + let texel = vec2(clamp(uv * size, vec2(0.0), size - 1.0)); + return textureLoad(scene_depth, texel, 0); +} +// The camera-relative world position, in blocks, of the point at `uv` and `depth`. +fn view_position(uv: vec2, depth: f32) -> vec3 { + let clip = vec4(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, depth, 1.0); + let view = frame.projection_inverse * clip; + return (frame.view_inverse * vec4(view.xyz / view.w, 0.0)).xyz; +} +"; + +/// The post stage's entry points, as the renderer builds them: a full-screen +/// triangle, and a fragment that calls the pack's `post` for each pixel. +const POST_ENTRIES: &str = "\ +struct HorizonPostOut { + @builtin(position) position: vec4, + @location(0) uv: vec2, +} +@vertex fn horizon_vs_post(@builtin(vertex_index) i: u32) -> HorizonPostOut { + let p = vec2(f32((i << 1u) & 2u), f32(i & 2u)); + var out: HorizonPostOut; + out.position = vec4(p * 2.0 - 1.0, 0.0, 1.0); + out.uv = vec2(p.x, 1.0 - p.y); + return out; +} +@fragment fn horizon_fs_post(in: HorizonPostOut) -> @location(0) vec4 { + let color = textureSampleLevel(previous, linear_sampler, in.uv, 0.0); + return post(PostInput(in.uv, in.position.xy, color, depth_at(in.uv))); +} +"; + +/// Entry points with the material stage's inputs: the renderer calls +/// `material` from its own terrain shader in the same way. +const MATERIAL_ENTRIES: &str = "\ +struct HorizonMaterialIn { + @builtin(position) position: vec4, + @location(0) albedo: vec4, + @location(1) tint: vec4, + @location(2) light: vec2, + @location(3) lightmap: vec3, + @location(4) world: vec3, + @location(5) uv: vec2, + @location(6) @interpolate(flat) translucent: u32, +} +@fragment fn horizon_fs_material(in: HorizonMaterialIn) -> @location(0) vec4 { + let input = MaterialInput(in.albedo, in.tint, in.light, in.lightmap, in.world, in.uv, in.translucent != 0u); + return material(input).color; +} +"; + +/// Entry points with the sky stage's inputs: the renderer calls `sky` from +/// its own sky shader in the same way. +const SKY_ENTRIES: &str = "\ +struct HorizonSkyIn { + @builtin(position) position: vec4, + @location(0) direction: vec3, + @location(1) color: vec4, +} +@fragment fn horizon_fs_sky(in: HorizonSkyIn) -> @location(0) vec4 { + return sky(SkyInput(normalize(in.direction), in.color)); +} +"; + +impl StageKind { + pub const ALL: [StageKind; 3] = [StageKind::Sky, StageKind::Material, StageKind::Post]; + + /// The manifest's name for the stage (`[sky]`, `[material]`, `[[post]]`). + pub fn name(self) -> &'static str { + match self { + StageKind::Sky => "sky", + StageKind::Material => "material", + StageKind::Post => "post", + } + } + + /// The function a pack defines: it has the stage's name. + pub fn function(self) -> &'static str { + self.name() + } + + pub fn input(self) -> &'static Struct { + match self { + StageKind::Sky => &SKY_INPUT, + StageKind::Material => &MATERIAL_INPUT, + StageKind::Post => &POST_INPUT, + } + } + + /// The type the function returns. + pub fn output(self) -> &'static str { + match self { + StageKind::Material => SURFACE.name, + StageKind::Sky | StageKind::Post => "vec4", + } + } + + /// `fn (input: ) -> `. + pub fn signature(self) -> String { + format!( + "fn {}(input: {}) -> {}", + self.function(), + self.input().name, + self.output() + ) + } + + pub fn resources(self) -> &'static [Resource] { + match self { + StageKind::Post => &POST_RESOURCES, + StageKind::Sky | StageKind::Material => std::slice::from_ref(&FRAME), + } + } + + /// Everything the pack's files may use, declared before them. + pub fn prelude(self) -> String { + let mut out = + String::from("// Horizon shader API prelude (docs/api/shaders-reference.md)\n"); + out += &Frame::WGSL.wgsl(); + out += &self.input().wgsl(); + if self == StageKind::Material { + out += &SURFACE.wgsl(); + } + for r in self.resources() { + out += &format!("@group({GROUP}) @binding({}) {};\n", r.binding, r.ty); + } + if self == StageKind::Post { + out += POST_HELPERS; + } + out + } + + /// The entry points put after the pack's files. + pub fn entries(self) -> &'static str { + match self { + StageKind::Sky => SKY_ENTRIES, + StageKind::Material => MATERIAL_ENTRIES, + StageKind::Post => POST_ENTRIES, + } + } +} + +/// A stage's WGSL, and where each part of it came from. +#[derive(Debug)] +pub struct Composed { + pub text: String, + /// (the file, or `` / ``, its byte range in `text`). + pub parts: Vec<(String, std::ops::Range)>, +} + +impl Composed { + /// The file, line and column (1-based) of a byte offset in `text`. + pub fn locate(&self, offset: usize) -> (&str, usize, usize) { + let (file, range) = self + .parts + .iter() + .find(|(_, r)| r.contains(&offset)) + .or(self.parts.last()) + .expect("a composed stage has parts"); + let before = &self.text[range.start..offset.clamp(range.start, range.end)]; + let line = before.matches('\n').count() + 1; + let column = before.len() - before.rfind('\n').map_or(0, |i| i + 1) + 1; + (file, line, column) + } +} + +/// The WGSL of the stage `kind` whose own file is `file`: the prelude, the +/// pack's shared files in order, the file, then the entry points. +pub fn compose(pack: &Pack, kind: StageKind, file: &str) -> Composed { + let mut composed = Composed { + text: String::new(), + parts: Vec::new(), + }; + let mut push = |name: &str, text: &str| { + let start = composed.text.len(); + composed.text += text; + if !text.ends_with('\n') { + composed.text.push('\n'); + } + composed + .parts + .push((name.to_owned(), start..composed.text.len())); + }; + push("", &kind.prelude()); + for shared in pack.manifest.shared.iter().filter(|s| *s != file) { + push(shared, pack.source(shared).unwrap_or_default()); + } + push(file, pack.source(file).unwrap_or_default()); + push("", kind.entries()); + composed +} diff --git a/crates/horizon-shader-api/tests/reference.rs b/crates/horizon-shader-api/tests/reference.rs new file mode 100644 index 000000000..fc548590b --- /dev/null +++ b/crates/horizon-shader-api/tests/reference.rs @@ -0,0 +1,119 @@ +//! The stages' WGSL against the Rust definitions: the preludes compile, the +//! frame's WGSL layout is the uploaded struct's, and +//! docs/api/shaders-reference.md is up to date. Rewrite the reference with +//! `HORIZON_WRITE_DOCS=1 cargo test -p horizon-shader-api --test reference`. +use horizon_shader_api::{Frame, Pack, StageKind, compose, reference}; +use std::path::Path; + +const DOC: &str = "docs/api/shaders-reference.md"; + +fn root() -> &'static Path { + Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/../..")) +} + +fn validate(text: &str) -> naga::Module { + let module = naga::front::wgsl::parse_str(text) + .unwrap_or_else(|e| panic!("{}\n{text}", e.emit_to_string(text))); + naga::valid::Validator::new( + naga::valid::ValidationFlags::all(), + naga::valid::Capabilities::default(), + ) + .validate(&module) + .unwrap_or_else(|e| panic!("{}\n{text}", e.emit_to_string(text))); + module +} + +/// Vanilla's look, written as each stage. +fn vanilla(kind: StageKind) -> &'static str { + match kind { + StageKind::Sky => "fn sky(input: SkyInput) -> vec4 { return input.color; }\n", + StageKind::Material => { + "fn material(input: MaterialInput) -> Surface {\n \ + return Surface(input.albedo * input.tint * vec4(input.lightmap, 1.0));\n}\n" + } + StageKind::Post => "fn post(input: PostInput) -> vec4 { return input.color; }\n", + } +} + +#[test] +fn every_stage_compiles_with_vanilla_s_function() { + for kind in StageKind::ALL { + let text = format!("{}{}{}", kind.prelude(), vanilla(kind), kind.entries()); + let module = validate(&text); + assert!( + module + .entry_points + .iter() + .all(|e| e.name.starts_with("horizon_")), + "{kind:?}" + ); + } +} + +#[test] +fn the_frame_s_wgsl_layout_is_the_uploaded_struct_s() { + let text = format!("{}{}", StageKind::Sky.prelude(), vanilla(StageKind::Sky)); + let module = validate(&text); + let (_, ty) = module + .types + .iter() + .find(|(_, t)| t.name.as_deref() == Some("Frame")) + .expect("Frame in the prelude"); + let naga::TypeInner::Struct { members, span } = &ty.inner else { + panic!("Frame is a struct") + }; + assert_eq!(*span as usize, std::mem::size_of::()); + let wgsl: Vec<_> = members + .iter() + .map(|m| (m.name.clone().unwrap(), m.offset as usize)) + .collect(); + let rust: Vec<_> = Frame::WGSL + .fields + .iter() + .zip(Frame::OFFSETS) + .map(|(f, &o)| (f.name.to_owned(), o)) + .collect(); + assert_eq!(wgsl, rust); +} + +#[test] +fn the_sample_pack_s_stages_compile() { + let dir = root().join("crates/horizon-shader-api/tests/samples/schema-1"); + let pack = Pack::read(&dir).unwrap(); + let m = &pack.manifest; + let stages = [ + (StageKind::Sky, m.sky.iter().collect::>()), + (StageKind::Material, m.material.iter().collect()), + (StageKind::Post, m.post.iter().collect()), + ]; + for (kind, list) in stages { + for stage in list { + let composed = compose(&pack, kind, &stage.file); + validate(&composed.text); + // Errors point into the pack's own file. + let part = composed.parts.iter().find(|(f, _)| *f == stage.file); + let part = part.unwrap().1.clone(); + let needle = format!("fn {}(", kind.function()); + let at = part.start + composed.text[part].find(&needle).unwrap(); + let source = pack.source(&stage.file).unwrap(); + let line = source.lines().position(|l| l.starts_with(&needle)).unwrap() + 1; + assert_eq!(composed.locate(at), (stage.file.as_str(), line, 1)); + } + } +} + +#[test] +fn the_reference_is_up_to_date() { + let path = root().join(DOC); + let want = reference::markdown(); + if std::env::var_os("HORIZON_WRITE_DOCS").is_some() { + std::fs::write(&path, &want).unwrap(); + } + let have = std::fs::read_to_string(&path) + .unwrap_or_default() + .replace("\r\n", "\n"); + assert!( + have == want, + "{DOC} is out of date: HORIZON_WRITE_DOCS=1 cargo test -p horizon-shader-api --test reference" + ); +} diff --git a/crates/horizon-shader-api/tests/samples/schema-1/README.md b/crates/horizon-shader-api/tests/samples/schema-1/README.md index 6762a7892..a8ad4583b 100644 --- a/crates/horizon-shader-api/tests/samples/schema-1/README.md +++ b/crates/horizon-shader-api/tests/samples/schema-1/README.md @@ -1 +1 @@ -The schema 1 sample read by `tests/schema.rs`. Its WGSL is checked once the stages exist. +The schema 1 sample read by `tests/schema.rs`; `tests/reference.rs` compiles its stages. diff --git a/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl index 0ad42c6d9..830470a6b 100644 --- a/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl +++ b/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl @@ -1,3 +1,4 @@ fn material(input: MaterialInput) -> Surface { - return input.surface; + let lit = input.albedo * input.tint * vec4(input.lightmap, 1.0); + return Surface(vec4(lit.rgb * (0.9 + 0.1 * luminance(lit.rgb)), lit.a)); } diff --git a/docs/api/shaders-reference.md b/docs/api/shaders-reference.md new file mode 100644 index 000000000..ed574978d --- /dev/null +++ b/docs/api/shaders-reference.md @@ -0,0 +1,152 @@ +# Shader API reference (0.1) + +Generated from `crates/horizon-shader-api` (`HORIZON_WRITE_DOCS=1 cargo test -p horizon-shader-api --test reference` +rewrites it; the test fails when it drifts). The API's design and pack format: [shaders.md](shaders.md). + +A stage is a function your WGSL defines, with the signature below; Horizon puts the prelude (these structs, the +resources and helpers) before your files and calls the function from its own pass. Your files declare no +bindings and no entry points, and no names starting with `horizon_`. + +## Stages + +| Stage | In `horizon-shaders.toml` | Your function | +| --- | --- | --- | +| sky | `[sky]` | `fn sky(input: SkyInput) -> vec4` | +| material | `[material]` | `fn material(input: MaterialInput) -> Surface` | +| post | `[[post]]` | `fn post(input: PostInput) -> vec4` | + +## sky + +`fn sky(input: SkyInput) -> vec4` + +### `SkyInput` + +One direction of the sky, for `fn sky(input: SkyInput) -> vec4`. The sun, moon, stars and clouds are drawn over the result. + +| Field | Type | Meaning | +| --- | --- | --- | +| `direction` | `vec3` | Unit view ray, camera-relative world axes. | +| `color` | `vec4` | Vanilla's sky colour along the ray (sky, fog and sunrise). | + +Resources (bind group 3): + +| Binding | Declaration | Meaning | +| --- | --- | --- | +| 0 | `var frame: Frame` | The frame (`Frame`). | + +## material + +`fn material(input: MaterialInput) -> Surface` + +### `MaterialInput` + +One point of a block's surface, for `fn material(input: MaterialInput) -> Surface`. + +| Field | Type | Meaning | +| --- | --- | --- | +| `albedo` | `vec4` | The block texture's colour here (alpha 0..1). | +| `tint` | `vec4` | The vertex colour: biome tint, face shade and ambient occlusion. | +| `light` | `vec2` | Block and sky light, 0..1, smoothed over the face. | +| `lightmap` | `vec3` | Vanilla's light colour for that light this frame. | +| `position` | `vec3` | The point, camera-relative, in blocks. | +| `uv` | `vec2` | The texture coordinate inside the block atlas. | +| `translucent` | `bool` | Drawn in the translucent pass (water, stained glass, ice). | + +### `Surface` + +What `material` returns. Vanilla's own is `albedo * tint * vec4(lightmap, 1.0)`; Horizon then applies the alpha test (cutout and translucent) and fog. + +| Field | Type | Meaning | +| --- | --- | --- | +| `color` | `vec4` | The lit colour, 0..1, with its alpha. | + +Resources (bind group 3): + +| Binding | Declaration | Meaning | +| --- | --- | --- | +| 0 | `var frame: Frame` | The frame (`Frame`). | + +## post + +`fn post(input: PostInput) -> vec4` + +### `PostInput` + +One pixel of the picture, for `fn post(input: PostInput) -> vec4`. + +| Field | Type | Meaning | +| --- | --- | --- | +| `uv` | `vec2` | Where the pixel is, 0..1 from the top left. | +| `pixel` | `vec2` | The pixel's centre, in pixels from the top left. | +| `color` | `vec4` | The previous pass's colour here (the world's picture for the first pass). | +| `depth` | `f32` | The world's depth here, reversed: 0 is the sky. | + +Resources (bind group 3): + +| Binding | Declaration | Meaning | +| --- | --- | --- | +| 0 | `var frame: Frame` | The frame (`Frame`). | +| 1 | `var scene_color: texture_2d` | The world's picture before any pass. | +| 2 | `var scene_depth: texture_depth_2d` | The world's depth, reversed (1 near, 0 far and sky). | +| 3 | `var previous: texture_2d` | The previous pass's output (`scene_color` for the first pass). | +| 4 | `var linear_sampler: sampler` | Bilinear filtering, clamped to the edges. | +| 5 | `var nearest_sampler: sampler` | Nearest texel, clamped to the edges. | + +Helpers: + +- `fn depth_at(uv: vec2) -> f32`: the world's depth at `uv`. +- `fn view_position(uv: vec2, depth: f32) -> vec3`: the camera-relative position, in blocks, of + the point at `uv` and `depth`. + +## The frame + +### `Frame` + +The frame, as `frame` in every stage. Positions and directions are in world axes relative to the camera (x east, y up, z south), so they stay precise far from the world's origin; depth is reversed (1 near, 0 at the far plane and in the sky). + +| Field | Type | Offset | Meaning | +| --- | --- | --- | --- | +| `view` | `mat4x4` | 0 | Camera-relative world to view space: the camera's rotation. | +| `projection` | `mat4x4` | 64 | View to clip space (reversed depth, wgpu's clip space: z 0..1). | +| `view_inverse` | `mat4x4` | 128 | View to camera-relative world space. | +| `projection_inverse` | `mat4x4` | 192 | Clip to view space. | +| `camera_position` | `vec3` | 256 | The camera's world position, in blocks (about a millimetre of precision 10 000 blocks out). | +| `time` | `f32` | 268 | Seconds since the pack was loaded, wrapping to 0 every hour. | +| `sun_direction` | `vec3` | 272 | Unit vector toward the sun (below the horizon at night). | +| `day_time` | `f32` | 284 | The time of day, 0..1: 0 sunrise, 0.25 noon, 0.5 sunset, 0.75 midnight. | +| `moon_direction` | `vec3` | 288 | Unit vector toward the moon. | +| `game_time` | `f32` | 300 | Vanilla's GameTime: (game time % 24000 + partial tick) / 24000, 0..1. | +| `sky_color` | `vec3` | 304 | Vanilla's sky colour this frame, 0..1. | +| `rain` | `f32` | 316 | Rain strength, 0..1. | +| `fog_color` | `vec3` | 320 | Vanilla's fog colour this frame (also the clear colour), 0..1. | +| `thunder` | `f32` | 332 | Thunder strength, 0..1. | +| `resolution` | `vec2` | 336 | The size of the world's picture, in pixels (the resolution scale applied). | +| `eye_light` | `vec2` | 344 | Block and sky light at the camera, 0..1 (level / 15). | +| `fog_start` | `f32` | 352 | Where vanilla's fog starts, in blocks from the camera. | +| `fog_end` | `f32` | 356 | Where vanilla's fog is full, in blocks. | +| `render_distance` | `f32` | 360 | The render distance, in blocks. | +| `far` | `f32` | 364 | The far plane, in blocks. | +| `night_vision` | `f32` | 368 | Night vision strength, 0..1. | +| `blindness` | `f32` | 372 | Blindness strength, 0..1. | +| `darkness` | `f32` | 376 | The darkness effect's strength, 0..1. | +| `brightness` | `f32` | 380 | The Brightness option, 0..1 (Moody to Bright). | +| `eye_in` | `u32` | 384 | What the camera is in: 0 air, 1 water, 2 lava, 3 powder snow. | +| `dimension` | `i32` | 388 | 0 the Overworld, -1 the Nether, 1 the End, 2 any other dimension. | +| `frame_index` | `u32` | 392 | Frames drawn since the pack was loaded (wraps). | +| `hide_gui` | `u32` | 396 | 1 while F1 hides the HUD, else 0. | + +## Options + +Each `[[options]]` entry sets the WGSL `override` of the same name when the pipelines are built: + +| `type` | Keys | The `override` | +| --- | --- | --- | +| `bool` | `default` | `override : bool` | +| `float` | `default`, `min`, `max`, `step` | `override : f32` | +| `int` | `default`, `min`, `max` | `override : i32` | +| `choice` | `values`, `default` (one of them) | `override : u32`, the value's index | + +## Limits + +- 8 post passes, 64 options, `budget.gpu_ms` up to 16. +- 256 KiB per WGSL file, 8 MiB per pack. diff --git a/docs/api/shaders.md b/docs/api/shaders.md index 82b9acced..a5ba0986d 100644 --- a/docs/api/shaders.md +++ b/docs/api/shaders.md @@ -79,8 +79,9 @@ the same way every time (files in path order, fixed dates), so a pack's SHA-256 ## Guide, reference and examples -None yet. When the first stage lands: a guide here, a generated reference (`shaders-reference.md`) and an example pack -in the repository that the renderer's tests load. +- [shaders-reference.md](shaders-reference.md): every stage's signature, input and output structs, resources and + helpers, the frame's fields with their units, option types and limits, generated from `crates/horizon-shader-api`. +- The guide and an example pack come with `horizon-shader check`. ## Stability @@ -94,5 +95,6 @@ stages with options and hot reload, then the overlay, lighting, sky and shadow s ## Changelog +- 2026-10-25: the stages of API 0.1 (sky, material, post), their inputs and the generated reference. - 2026-10-25: the pack format, schema 1: `horizon-shaders.toml` and the `.hshader` package. - 2026-10-24: the earlier shader pack code was removed; this API is designed from scratch.