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.