diff --git a/AGENTS.md b/AGENTS.md index 0656e40fc..a72c6723a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,6 +45,7 @@ Game workspace (root `Cargo.toml`); `launcher/` and `crates/horizon-telemetry-se | `horizon-friends`, `horizon-relay` | Play with Friends: invite codes, encrypted tunnel, the relay ([docs/play-with-friends.md](docs/play-with-friends.md)) | | `horizon-mods`, `horizon-mod-sdk`, `cargo-horizon-mod` | Sandboxed WebAssembly mods: runtime, SDK + WIT, `cargo horizon-mod` ([docs/mods.md](docs/mods.md)) | | `horizon-port-pack` | Porting Java modpacks ([docs/modpacks.md](docs/modpacks.md)) | +| `horizon-shader-api` | Horizon's own WGSL shader packs ([docs/api/shaders.md](docs/api/shaders.md)): `horizon-shaders.toml`, the `.hshader` package; shared by the game, the launcher and the registry | | `horizon-shaders` | Shader packs (the `shaders/` folder format), rebuilt clean-room from a written spec of the format; no wgpu | | `horizon-theme` | Design tokens and fonts for the launcher, the game's own menus and the website | | `horizon-telemetry`, `horizon-telemetry-server`, `horizon-bench` | Opt-in data collection, its ingest server, the benchmark report format | diff --git a/Cargo.lock b/Cargo.lock index 2d09d2d0e..25b278069 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1437,6 +1437,15 @@ dependencies = [ "ureq", ] +[[package]] +name = "horizon-shader-api" +version = "0.1.0" +dependencies = [ + "serde", + "toml", + "zip", +] + [[package]] name = "horizon-shaders" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index c6f2bc581..294e93aa9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [workspace] exclude = ["launcher", "crates/horizon-telemetry-server", "crates/horizon-mod-registry", "third_party/wgpu-hal"] -members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "xtask"] +members = ["crates/horizon-core", "crates/horizon-dualsense", "crates/horizon-threads", "crates/horizon-world", "crates/horizon-client", "crates/horizon-server-files", "crates/horizon-server", "crates/horizon-bots", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/cargo-horizon-mod", "crates/horizon-port-pack", "crates/horizon-shaders", "crates/horizon-shader-api", "crates/horizon-release-sign", "crates/horizon-mod-sdk/examples/coords-hud", "xtask"] resolver = "2" [workspace.package] diff --git a/crates/horizon-shader-api/Cargo.toml b/crates/horizon-shader-api/Cargo.toml new file mode 100644 index 000000000..5d9098055 --- /dev/null +++ b/crates/horizon-shader-api/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "horizon-shader-api" +version = "0.1.0" +edition.workspace = true +license.workspace = true +rust-version = "1.85" +description = "Horizon's own shader packs (WGSL, docs/api/shaders.md): horizon-shaders.toml, the .hshader package" + +[dependencies] +serde = { version = "1", features = ["derive"] } +toml = "1.1.6" +zip = { version = "2", default-features = false, features = ["deflate"] } + +[lints] +workspace = true diff --git a/crates/horizon-shader-api/src/lib.rs b/crates/horizon-shader-api/src/lib.rs new file mode 100644 index 000000000..418563089 --- /dev/null +++ b/crates/horizon-shader-api/src/lib.rs @@ -0,0 +1,10 @@ +//! Horizon's own shader packs (docs/api/shaders.md): WGSL written against +//! the renderer's stages, described by `horizon-shaders.toml` and shipped as +//! 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 manifest; +pub mod package; + +pub use manifest::{API, MANIFEST, Manifest, OptionKind, PackOption, SCHEMA, Stage}; +pub use package::{EXTENSION, Pack}; diff --git a/crates/horizon-shader-api/src/manifest.rs b/crates/horizon-shader-api/src/manifest.rs new file mode 100644 index 000000000..d03a4f213 --- /dev/null +++ b/crates/horizon-shader-api/src/manifest.rs @@ -0,0 +1,365 @@ +//! `horizon-shaders.toml`, a shader pack's manifest (schema 1, docs/shaders.md). +use serde::Deserialize; + +/// The manifest's file name at the root of a pack. +pub const MANIFEST: &str = "horizon-shaders.toml"; +/// The manifest schema this build reads. +pub const SCHEMA: u32 = 1; +/// The shader API line this build serves: the stages, their signatures and +/// the inputs a pack's WGSL may read. +pub const API: &str = "0.1"; +/// Full-screen passes a pack may chain. +pub const MAX_POST_PASSES: usize = 8; +/// Options a pack may declare. +pub const MAX_OPTIONS: usize = 64; +/// The most GPU time a pack may declare for itself, in milliseconds. +pub const MAX_GPU_MS: f32 = 16.0; + +/// A checked manifest. +#[derive(Clone, Debug, PartialEq)] +pub struct Manifest { + /// `[a-z0-9_]{1,64}`: the pack's settings key and registry id. + pub id: String, + pub name: String, + pub version: String, + /// The API line the pack is written for. + pub api: String, + pub description: String, + pub authors: Vec, + pub license: Option, + /// WGSL files put before every stage's own file, in order. + pub shared: Vec, + pub sky: Option, + pub material: Option, + /// Full-screen passes, in the order they run. + pub post: Vec, + pub options: Vec, + pub budget: Budget, +} + +/// One stage: the WGSL file that defines its function. +#[derive(Clone, Debug, Deserialize, PartialEq)] +#[serde(deny_unknown_fields)] +pub struct Stage { + pub file: String, + /// Shown in the GPU time overlay; the file name when absent. + #[serde(default)] + pub name: Option, +} + +/// An option the player can change: a WGSL `override` constant of the +/// same name, set when the pipelines are built. +#[derive(Clone, Debug, PartialEq)] +pub struct PackOption { + /// The `override`'s name in the pack's WGSL. + pub id: String, + pub name: String, + pub description: String, + pub kind: OptionKind, +} + +#[derive(Clone, Debug, PartialEq)] +pub enum OptionKind { + /// `override : bool`. + Bool { default: bool }, + /// `override : f32`; the slider moves by `step`. + Float { + default: f32, + min: f32, + max: f32, + step: f32, + }, + /// `override : i32`. + Int { default: i32, min: i32, max: i32 }, + /// `override : u32`, the index of the chosen value. + Choice { values: Vec, default: u32 }, +} + +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Budget { + /// The GPU time the pack aims to add to a frame, in milliseconds; the + /// overlay shows the pack over budget past it. + pub gpu_ms: Option, +} + +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct Raw { + schema: u32, + id: String, + name: String, + version: String, + api: String, + #[serde(default)] + description: String, + #[serde(default)] + authors: Vec, + license: Option, + #[serde(default)] + shared: Vec, + sky: Option, + material: Option, + #[serde(default)] + post: Vec, + #[serde(default)] + options: Vec, + #[serde(default)] + budget: RawBudget, +} + +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct RawOption { + id: String, + name: String, + #[serde(default)] + description: String, + #[serde(rename = "type")] + kind: String, + default: toml::Value, + min: Option, + max: Option, + step: Option, + values: Option>, +} + +#[derive(Default, Deserialize)] +#[serde(deny_unknown_fields)] +struct RawBudget { + gpu_ms: Option, +} + +impl Manifest { + pub fn parse(text: &str) -> Result { + let raw: Raw = toml::from_str(text).map_err(|e| format!("{MANIFEST}: {e}"))?; + let err = |e: String| format!("{MANIFEST}: {e}"); + if raw.schema != SCHEMA { + return Err(err(format!( + "schema {}; this Horizon reads {SCHEMA}", + raw.schema + ))); + } + if raw.api != API { + return Err(err(format!( + "written for shader API {}; this Horizon serves {API}", + raw.api + ))); + } + let id_ok = (1..=64).contains(&raw.id.len()) + && raw + .id + .bytes() + .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_'); + if !id_ok { + return Err(err(format!("id {:?} is not [a-z0-9_]{{1,64}}", raw.id))); + } + if raw.name.trim().is_empty() || raw.version.trim().is_empty() { + return Err(err("name and version can't be empty".into())); + } + if raw.sky.is_none() && raw.material.is_none() && raw.post.is_empty() { + return Err(err( + "no stage: give it a [sky], a [material] or a [[post]]".into() + )); + } + if raw.post.len() > MAX_POST_PASSES { + return Err(err(format!( + "{} post passes; a pack may chain {MAX_POST_PASSES}", + raw.post.len() + ))); + } + let stages = raw.sky.iter().chain(&raw.material).chain(&raw.post); + for file in raw.shared.iter().chain(stages.map(|s| &s.file)) { + if !crate::package::plain_path(file) || !file.ends_with(".wgsl") { + return Err(err(format!("{file:?} is not a plain path to a .wgsl file"))); + } + } + if raw.options.len() > MAX_OPTIONS { + return Err(err(format!( + "{} options; a pack may declare {MAX_OPTIONS}", + raw.options.len() + ))); + } + let mut options = Vec::with_capacity(raw.options.len()); + for (i, o) in raw.options.into_iter().enumerate() { + let id = o.id.clone(); + let option = o.check().map_err(|e| err(format!("option {id:?}: {e}")))?; + if options[..i].iter().any(|p: &PackOption| p.id == option.id) { + return Err(err(format!("option {id:?} is declared twice"))); + } + options.push(option); + } + let gpu_ms = match raw.budget.gpu_ms { + Some(ms) if !(ms > 0.0 && ms <= f64::from(MAX_GPU_MS)) => { + return Err(err(format!( + "budget.gpu_ms {ms} is not in (0, {MAX_GPU_MS}]" + ))); + } + ms => ms.map(|ms| ms as f32), + }; + Ok(Manifest { + id: raw.id, + name: raw.name, + version: raw.version, + api: raw.api, + description: raw.description, + authors: raw.authors, + license: raw.license, + shared: raw.shared, + sky: raw.sky, + material: raw.material, + post: raw.post, + options, + budget: Budget { gpu_ms }, + }) + } + + /// Every WGSL file the manifest names, shared files first, each once. + pub fn files(&self) -> Vec<&str> { + let mut files: Vec<&str> = Vec::new(); + let stages = self.sky.iter().chain(&self.material).chain(&self.post); + for file in self.shared.iter().chain(stages.map(|s| &s.file)) { + if !files.contains(&file.as_str()) { + files.push(file); + } + } + files + } +} + +/// A WGSL identifier the renderer leaves to packs: ASCII, not starting +/// with a digit, `_` or the renderer's own `horizon_` prefix. +pub fn pack_identifier(name: &str) -> bool { + let mut bytes = name.bytes(); + bytes.next().is_some_and(|b| b.is_ascii_alphabetic()) + && bytes.all(|b| b.is_ascii_alphanumeric() || b == b'_') + && name.len() <= 64 + && !name.starts_with("horizon_") +} + +impl RawOption { + fn check(self) -> Result { + if !pack_identifier(&self.id) { + return Err( + "the id must be a WGSL identifier: a letter, then letters, digits or _, up to 64, not starting with horizon_".into(), + ); + } + let int = |v: &toml::Value| { + v.as_integer() + .and_then(|i| i32::try_from(i).ok()) + .ok_or_else(|| format!("{v} is not a 32-bit integer")) + }; + let float = |v: &toml::Value| { + v.as_float() + .or_else(|| v.as_integer().map(|i| i as f64)) + .filter(|f| f.is_finite()) + .map(|f| f as f32) + .ok_or_else(|| format!("{v} is not a number")) + }; + let need = |v: Option, key: &str| v.ok_or_else(|| format!("needs {key}")); + let unused = |present: bool, key: &str| { + if present { + Err(format!("{key} doesn't apply to type = {:?}", self.kind)) + } else { + Ok(()) + } + }; + let kind = match self.kind.as_str() { + "bool" => { + unused(self.min.is_some() || self.max.is_some(), "min/max")?; + unused(self.step.is_some(), "step")?; + unused(self.values.is_some(), "values")?; + let default = self + .default + .as_bool() + .ok_or("default must be true or false")?; + OptionKind::Bool { default } + } + "float" => { + unused(self.values.is_some(), "values")?; + let (min, max) = ( + float(&need(self.min, "min")?)?, + float(&need(self.max, "max")?)?, + ); + let default = float(&self.default)?; + let step = self.step.map_or((max - min) / 100.0, |s| s as f32); + if !(min < max && (min..=max).contains(&default)) { + return Err(format!("needs min < max and default in [{min}, {max}]")); + } + if !(step > 0.0 && step <= max - min) { + return Err(format!("step {step} is not in (0, max - min]")); + } + OptionKind::Float { + default, + min, + max, + step, + } + } + "int" => { + unused(self.step.is_some(), "step")?; + unused(self.values.is_some(), "values")?; + let (min, max) = (int(&need(self.min, "min")?)?, int(&need(self.max, "max")?)?); + let default = int(&self.default)?; + if !(min < max && (min..=max).contains(&default)) { + return Err(format!("needs min < max and default in [{min}, {max}]")); + } + OptionKind::Int { default, min, max } + } + "choice" => { + unused(self.min.is_some() || self.max.is_some(), "min/max")?; + unused(self.step.is_some(), "step")?; + let values = self.values.ok_or("needs values")?; + if !(2..=32).contains(&values.len()) { + return Err("needs 2 to 32 values".into()); + } + if values + .iter() + .enumerate() + .any(|(i, v)| v.trim().is_empty() || values[..i].contains(v)) + { + return Err("values must be distinct and not empty".into()); + } + let default = self + .default + .as_str() + .and_then(|d| values.iter().position(|v| v == d)) + .ok_or("default must be one of the values")?; + OptionKind::Choice { + values, + default: default as u32, + } + } + other => { + return Err(format!("type {other:?} is not bool, float, int or choice")); + } + }; + Ok(PackOption { + id: self.id, + name: self.name, + description: self.description, + kind, + }) + } +} + +impl OptionKind { + /// The WGSL type of the option's `override`. + pub fn wgsl_type(&self) -> &'static str { + match self { + OptionKind::Bool { .. } => "bool", + OptionKind::Float { .. } => "f32", + OptionKind::Int { .. } => "i32", + OptionKind::Choice { .. } => "u32", + } + } + + /// The default as the pipeline constant wgpu takes. + pub fn default_constant(&self) -> f64 { + match *self { + OptionKind::Bool { default } => f64::from(u8::from(default)), + OptionKind::Float { default, .. } => f64::from(default), + OptionKind::Int { default, .. } => f64::from(default), + OptionKind::Choice { default, .. } => f64::from(default), + } + } +} diff --git a/crates/horizon-shader-api/src/package.rs b/crates/horizon-shader-api/src/package.rs new file mode 100644 index 000000000..af72afc4c --- /dev/null +++ b/crates/horizon-shader-api/src/package.rs @@ -0,0 +1,175 @@ +//! A shader pack on disk: a folder holding `horizon-shaders.toml`, or the +//! same files zipped as a `.hshader` (what the registry and the launcher +//! carry). Both read into one [`Pack`]. +use crate::manifest::{MANIFEST, Manifest}; +use std::{ + collections::BTreeMap, + io::{Read, Write}, + path::Path, +}; + +/// 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; +const MAX_OTHER: u64 = 1 << 20; +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. +const EXTRAS: [&str; 5] = [ + "README.md", + "LICENSE", + "LICENSE.md", + "LICENSE.txt", + "icon.png", +]; + +/// A pack read from a folder or a `.hshader`: its manifest and every file, +/// by path from the pack's root (`/`-separated). +#[derive(Debug)] +pub struct Pack { + pub manifest: Manifest, + pub files: BTreeMap>, +} + +/// A relative path made of plain parts: no root, `..`, `\`, empty or +/// hidden parts. +pub fn plain_path(path: &str) -> bool { + !path.is_empty() + && path.split('/').all(|part| { + !part.is_empty() + && !part.starts_with('.') + && part + .bytes() + .all(|b| b.is_ascii_alphanumeric() || b"._-".contains(&b)) + }) +} + +impl Pack { + /// Reads `path`: a `.hshader` file, or a folder (its hidden files and + /// folders, such as `.git`, are skipped). + pub fn read(path: &Path) -> Result { + let mut files = BTreeMap::new(); + if path.is_dir() { + read_dir(path, "", &mut files)?; + } else { + let file = std::fs::File::open(path).map_err(|e| format!("{}: {e}", path.display()))?; + let mut zip = zip::ZipArchive::new(file) + .map_err(|e| format!("{}: not a .{EXTENSION} (zip): {e}", path.display()))?; + if zip.len() > MAX_ENTRIES { + return Err(format!("over {MAX_ENTRIES} files in the package")); + } + for i in 0..zip.len() { + let mut entry = zip.by_index(i).map_err(|e| e.to_string())?; + if entry.is_dir() { + continue; + } + let name = entry.name().to_owned(); + let mut bytes = Vec::new(); + (&mut entry) + .take(MAX_OTHER.max(MAX_WGSL) + 1) + .read_to_end(&mut bytes) + .map_err(|e| format!("{name}: {e}"))?; + if files.insert(name.clone(), bytes).is_some() { + return Err(format!("{name} is in the package twice")); + } + } + } + Pack::from_files(files) + } + + /// Checks a pack's files: a manifest, the WGSL it names (as UTF-8), + /// nothing it doesn't use, and sizes within bounds. + pub fn from_files(files: BTreeMap>) -> Result { + let text = files + .get(MANIFEST) + .ok_or_else(|| format!("{MANIFEST}: missing at the pack's root"))?; + let manifest = Manifest::parse( + std::str::from_utf8(text).map_err(|_| format!("{MANIFEST}: not UTF-8"))?, + )?; + let used = manifest.files(); + let mut total = 0; + for (name, bytes) in &files { + if !plain_path(name) { + return Err(format!("{name:?} is not a plain path")); + } + let size = bytes.len() as u64; + total += size; + let max = if name.ends_with(".wgsl") { + if !used.contains(&name.as_str()) { + return Err(format!("{name} is not used by any stage or in shared")); + } + if std::str::from_utf8(bytes).is_err() { + return Err(format!("{name}: not UTF-8")); + } + MAX_WGSL + } else if name == MANIFEST || EXTRAS.contains(&name.as_str()) { + MAX_OTHER + } else { + return Err(format!( + "{name}: a pack holds only {MANIFEST}, .wgsl files and {}", + EXTRAS.join(", ") + )); + }; + if size > max { + return Err(format!("{name} is over {} KiB", max >> 10)); + } + } + if total > MAX_TOTAL { + return Err(format!("the pack is over {} MiB", MAX_TOTAL >> 20)); + } + if let Some(missing) = used.iter().find(|f| !files.contains_key(**f)) { + return Err(format!("{missing}: named in {MANIFEST} but missing")); + } + Ok(Pack { manifest, files }) + } + + /// A WGSL file's text (every file the manifest names is checked UTF-8). + pub fn source(&self, file: &str) -> Option<&str> { + self.files + .get(file) + .and_then(|b| std::str::from_utf8(b).ok()) + } + + /// The `.hshader` bytes: the files in path order, with fixed times and + /// permissions, so the same pack always gives the same bytes (and the + /// same SHA-256). + pub fn package(&self) -> Result, String> { + let mut zip = zip::ZipWriter::new(std::io::Cursor::new(Vec::new())); + let options = zip::write::SimpleFileOptions::default() + .compression_method(zip::CompressionMethod::Deflated) + .last_modified_time(zip::DateTime::default()) + .unix_permissions(0o644); + let err = |e: zip::result::ZipError| e.to_string(); + for (name, bytes) in &self.files { + zip.start_file(name.as_str(), options).map_err(err)?; + zip.write_all(bytes).map_err(|e| e.to_string())?; + } + Ok(zip.finish().map_err(err)?.into_inner()) + } +} + +fn read_dir(dir: &Path, prefix: &str, files: &mut BTreeMap>) -> Result<(), String> { + let entries = std::fs::read_dir(dir).map_err(|e| format!("{}: {e}", dir.display()))?; + for entry in entries { + let entry = entry.map_err(|e| format!("{}: {e}", dir.display()))?; + let name = entry.file_name().to_string_lossy().into_owned(); + if name.starts_with('.') { + continue; + } + let path = entry.path(); + let rel = format!("{prefix}{name}"); + if path.is_dir() { + read_dir(&path, &format!("{rel}/"), files)?; + } else { + let size = entry.metadata().map_err(|e| format!("{rel}: {e}"))?.len(); + if size > MAX_TOTAL { + return Err(format!("{rel} is over {} MiB", MAX_TOTAL >> 20)); + } + let bytes = std::fs::read(&path).map_err(|e| format!("{rel}: {e}"))?; + files.insert(rel, bytes); + } + } + Ok(()) +} diff --git a/crates/horizon-shader-api/tests/samples/schema-1/README.md b/crates/horizon-shader-api/tests/samples/schema-1/README.md new file mode 100644 index 000000000..6762a7892 --- /dev/null +++ b/crates/horizon-shader-api/tests/samples/schema-1/README.md @@ -0,0 +1 @@ +The schema 1 sample read by `tests/schema.rs`. Its WGSL is checked once the stages exist. diff --git a/crates/horizon-shader-api/tests/samples/schema-1/common.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/common.wgsl new file mode 100644 index 000000000..8fef8baf9 --- /dev/null +++ b/crates/horizon-shader-api/tests/samples/schema-1/common.wgsl @@ -0,0 +1,3 @@ +fn luminance(c: vec3) -> f32 { + return dot(c, vec3(0.2126, 0.7152, 0.0722)); +} diff --git a/crates/horizon-shader-api/tests/samples/schema-1/horizon-shaders.toml b/crates/horizon-shader-api/tests/samples/schema-1/horizon-shaders.toml new file mode 100644 index 000000000..6e8a545a7 --- /dev/null +++ b/crates/horizon-shader-api/tests/samples/schema-1/horizon-shaders.toml @@ -0,0 +1,59 @@ +# Schema 1 of horizon-shaders.toml with every key. Readers of later schemas +# keep reading this file (docs/api/stability.md, "Data formats"). +schema = 1 +id = "sample_pack" +name = "Sample Pack" +version = "1.0.0" +api = "0.1" +description = "Every key of schema 1." +authors = ["Horizon"] +license = "MIT" +shared = ["common.wgsl"] + +[sky] +file = "sky.wgsl" + +[material] +file = "material.wgsl" +name = "Terrain" + +[[post]] +file = "post/grade.wgsl" +name = "Colour grade" + +[[post]] +file = "post/vignette.wgsl" + +[[options]] +id = "saturation" +name = "Saturation" +description = "How colourful the picture is." +type = "float" +default = 1.1 +min = 0.0 +max = 2.0 +step = 0.05 + +[[options]] +id = "vignette" +name = "Vignette" +type = "bool" +default = true + +[[options]] +id = "samples" +name = "Samples" +type = "int" +default = 4 +min = 1 +max = 16 + +[[options]] +id = "tonemap" +name = "Tone mapping" +type = "choice" +values = ["None", "Soft", "Filmic"] +default = "Soft" + +[budget] +gpu_ms = 1.5 diff --git a/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl new file mode 100644 index 000000000..0ad42c6d9 --- /dev/null +++ b/crates/horizon-shader-api/tests/samples/schema-1/material.wgsl @@ -0,0 +1,3 @@ +fn material(input: MaterialInput) -> Surface { + return input.surface; +} diff --git a/crates/horizon-shader-api/tests/samples/schema-1/post/grade.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/post/grade.wgsl new file mode 100644 index 000000000..8daa1eab0 --- /dev/null +++ b/crates/horizon-shader-api/tests/samples/schema-1/post/grade.wgsl @@ -0,0 +1,8 @@ +override saturation: f32 = 1.1; +override tonemap: u32 = 1u; + +fn post(input: PostInput) -> vec4 { + let c = input.color.rgb; + let graded = mix(vec3(luminance(c)), c, saturation); + return vec4(select(graded, graded / (graded + 0.5) * 1.5, tonemap > 0u), input.color.a); +} diff --git a/crates/horizon-shader-api/tests/samples/schema-1/post/vignette.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/post/vignette.wgsl new file mode 100644 index 000000000..84f7261cb --- /dev/null +++ b/crates/horizon-shader-api/tests/samples/schema-1/post/vignette.wgsl @@ -0,0 +1,8 @@ +override vignette: bool = true; +override samples: i32 = 4; + +fn post(input: PostInput) -> vec4 { + let d = distance(input.uv, vec2(0.5)); + let dark = select(1.0, 1.0 - smoothstep(0.4, 0.9, d) * 0.5, vignette); + return vec4(input.color.rgb * dark, input.color.a); +} diff --git a/crates/horizon-shader-api/tests/samples/schema-1/sky.wgsl b/crates/horizon-shader-api/tests/samples/schema-1/sky.wgsl new file mode 100644 index 000000000..55ca0ac1d --- /dev/null +++ b/crates/horizon-shader-api/tests/samples/schema-1/sky.wgsl @@ -0,0 +1,3 @@ +fn sky(input: SkyInput) -> vec4 { + return input.color; +} diff --git a/crates/horizon-shader-api/tests/schema.rs b/crates/horizon-shader-api/tests/schema.rs new file mode 100644 index 000000000..2176805ee --- /dev/null +++ b/crates/horizon-shader-api/tests/schema.rs @@ -0,0 +1,238 @@ +//! Schema 1 of `horizon-shaders.toml` and the `.hshader` package. +use horizon_shader_api::{MANIFEST, Manifest, OptionKind, Pack}; +use std::{collections::BTreeMap, path::Path}; + +fn sample_dir() -> &'static Path { + Path::new(concat!( + env!("CARGO_MANIFEST_DIR"), + "/tests/samples/schema-1" + )) +} + +fn sample_text() -> String { + std::fs::read_to_string(sample_dir().join(MANIFEST)).unwrap() +} + +fn refused(text: &str) -> String { + Manifest::parse(text).expect_err("should be refused") +} + +#[test] +fn reads_every_key_of_schema_1() { + let m = Manifest::parse(&sample_text()).unwrap(); + assert_eq!( + ( + m.id.as_str(), + m.name.as_str(), + m.version.as_str(), + m.api.as_str() + ), + ("sample_pack", "Sample Pack", "1.0.0", "0.1") + ); + assert_eq!(m.authors, ["Horizon"]); + assert_eq!(m.license.as_deref(), Some("MIT")); + assert_eq!(m.sky.as_ref().unwrap().file, "sky.wgsl"); + assert_eq!( + m.material.as_ref().unwrap().name.as_deref(), + Some("Terrain") + ); + let post: Vec<_> = m.post.iter().map(|s| s.file.as_str()).collect(); + assert_eq!(post, ["post/grade.wgsl", "post/vignette.wgsl"]); + assert_eq!( + m.files(), + [ + "common.wgsl", + "sky.wgsl", + "material.wgsl", + "post/grade.wgsl", + "post/vignette.wgsl" + ] + ); + let kinds: Vec<_> = m.options.iter().map(|o| (o.id.as_str(), &o.kind)).collect(); + assert_eq!( + kinds, + [ + ( + "saturation", + &OptionKind::Float { + default: 1.1, + min: 0.0, + max: 2.0, + step: 0.05 + } + ), + ("vignette", &OptionKind::Bool { default: true }), + ( + "samples", + &OptionKind::Int { + default: 4, + min: 1, + max: 16 + } + ), + ( + "tonemap", + &OptionKind::Choice { + values: vec!["None".into(), "Soft".into(), "Filmic".into()], + default: 1 + } + ), + ] + ); + let types: Vec<_> = m.options.iter().map(|o| o.kind.wgsl_type()).collect(); + assert_eq!(types, ["f32", "bool", "i32", "u32"]); + let constants: Vec<_> = m + .options + .iter() + .map(|o| o.kind.default_constant()) + .collect(); + assert_eq!(constants, [f64::from(1.1f32), 1.0, 4.0, 1.0]); + assert_eq!(m.budget.gpu_ms, Some(1.5)); +} + +#[test] +fn the_smallest_manifest() { + let m = Manifest::parse( + "schema = 1\nid = \"p\"\nname = \"P\"\nversion = \"1\"\napi = \"0.1\"\n[[post]]\nfile = \"a.wgsl\"\n", + ) + .unwrap(); + assert!(m.sky.is_none() && m.options.is_empty() && m.budget.gpu_ms.is_none()); +} + +#[test] +fn refuses_what_this_build_does_not_read() { + let text = sample_text(); + let cases = [ + (text.replace("schema = 1", "schema = 2"), "schema 2"), + ( + text.replace("api = \"0.1\"", "api = \"0.2\""), + "shader API 0.2", + ), + ( + text.replace("\"sample_pack\"", "\"Sample\""), + "is not [a-z0-9_]", + ), + ( + text.replace("license = \"MIT\"", "licence = \"MIT\""), + "unknown field", + ), + ( + text.replace("gpu_ms = 1.5", "gpu_ms = 40.0"), + "budget.gpu_ms", + ), + ( + text.replace("\"common.wgsl\"", "\"../common.wgsl\""), + "not a plain path", + ), + ( + text.replace("\"sky.wgsl\"", "\"sky.glsl\""), + "not a plain path to a .wgsl", + ), + ( + text.replace("id = \"samples\"", "id = \"vignette\""), + "declared twice", + ), + ( + text.replace("id = \"samples\"", "id = \"horizon_samples\""), + "WGSL identifier", + ), + ( + text.replace("default = \"Soft\"", "default = \"Hard\""), + "one of the values", + ), + ( + text.replace("default = 1.1", "default = 3.0"), + "default in [0, 2]", + ), + ( + text.replace("default = 4", "default = 4.5"), + "not a 32-bit integer", + ), + ( + text.replace("type = \"bool\"", "type = \"color\""), + "is not bool", + ), + ( + text.replace("default = true", "default = true\nmin = 0"), + "doesn't apply", + ), + ]; + for (text, needle) in cases { + let e = refused(&text); + assert!(e.contains(needle), "{needle:?} not in {e:?}"); + assert!(e.starts_with(MANIFEST), "{e}"); + } + let no_stage = "schema = 1\nid = \"p\"\nname = \"P\"\nversion = \"1\"\napi = \"0.1\"\n"; + assert!(refused(no_stage).contains("no stage")); + let many = (0..9).map(|i| format!("[[post]]\nfile = \"p{i}.wgsl\"\n")); + assert!(refused(&format!("{no_stage}{}", many.collect::())).contains("9 post passes")); +} + +#[test] +fn reads_the_sample_folder_and_its_package_alike() { + let folder = Pack::read(sample_dir()).unwrap(); + assert_eq!(folder.files.len(), 7); + assert!( + folder + .source("post/grade.wgsl") + .unwrap() + .contains("fn post") + ); + let bytes = folder.package().unwrap(); + assert_eq!( + bytes, + folder.package().unwrap(), + "packaging is reproducible" + ); + let dir = std::env::temp_dir().join(format!("horizon-shader-api-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let path = dir.join("sample_pack.hshader"); + std::fs::write(&path, &bytes).unwrap(); + let packaged = Pack::read(&path).unwrap(); + std::fs::remove_dir_all(&dir).unwrap(); + assert_eq!(packaged.files, folder.files); + assert_eq!(packaged.manifest, folder.manifest); +} + +#[test] +fn refuses_files_a_pack_does_not_use() { + let base = || -> BTreeMap> { Pack::read(sample_dir()).unwrap().files }; + let mut files = base(); + files.insert("old.wgsl".into(), b"fn f() {}".to_vec()); + assert!( + Pack::from_files(files) + .unwrap_err() + .contains("old.wgsl is not used") + ); + let mut files = base(); + files.insert("run.sh".into(), Vec::new()); + assert!( + Pack::from_files(files) + .unwrap_err() + .contains("run.sh: a pack holds only") + ); + let mut files = base(); + files.remove("sky.wgsl"); + assert!( + Pack::from_files(files) + .unwrap_err() + .contains("sky.wgsl: named in") + ); + let mut files = base(); + files.insert("sky.wgsl".into(), vec![0xff, 0xfe]); + assert!(Pack::from_files(files).unwrap_err().contains("not UTF-8")); + let mut files = base(); + files.insert("post/grade.wgsl".into(), vec![b' '; 300 << 10]); + assert!( + Pack::from_files(files) + .unwrap_err() + .contains("over 256 KiB") + ); + let mut files = base(); + files.remove(MANIFEST); + assert!( + Pack::from_files(files) + .unwrap_err() + .contains("missing at the pack's root") + ); +} diff --git a/docs/api/shaders.md b/docs/api/shaders.md index 10d1ae3de..82b9acced 100644 --- a/docs/api/shaders.md +++ b/docs/api/shaders.md @@ -34,6 +34,49 @@ how the world is fed to the GPU. benchmark ([benchmark-report.md](../benchmark-report.md)) records the pack and its cost, so "fast" stays measured. - **Off by default.** Without a pack the renderer is vanilla's look, and no pack code runs. +## The pack format (schema 1) + +A pack is a folder, or the same files zipped as a `.hshader`, with `horizon-shaders.toml` at its root +(crate `horizon-shader-api`; the sample with every key is +`crates/horizon-shader-api/tests/samples/schema-1/`): + +```toml +schema = 1 # the manifest's format; a reader refuses schemas newer than it knows +id = "soft_light" # [a-z0-9_]{1,64}: the settings key and the registry id +name = "Soft Light" +version = "1.0.0" +api = "0.1" # the shader API line the WGSL is written for +description = "..." # optional, like authors and license +shared = ["common.wgsl"] # optional: WGSL put before every stage's file, in order + +[sky] # each stage is optional, but a pack has at least one +file = "sky.wgsl" + +[material] +file = "material.wgsl" + +[[post]] # full-screen passes, in the order they run (8 at most) +file = "post/grade.wgsl" +name = "Colour grade" # optional: the GPU time overlay's label + +[[options]] # 64 at most; `id` is the WGSL `override` it sets +id = "saturation" +name = "Saturation" +type = "float" # bool, float (min, max, step), int (min, max), choice (values) +default = 1.1 +min = 0.0 +max = 2.0 +step = 0.05 + +[budget] +gpu_ms = 1.5 # optional: the GPU time the pack aims to add (0 to 16 ms) +``` + +An option's `override` has the type of its kind: `bool`, `f32`, `i32`, or `u32` for a choice (the index of the +value). The pack holds only the manifest, the `.wgsl` files it names (each used, UTF-8, 256 KiB at most), +`README.md`, `LICENSE` (`.md`, `.txt`) and `icon.png`, under plain paths, 8 MiB in all. A `.hshader` is built +the same way every time (files in path order, fixed dates), so a pack's SHA-256 depends only on its files. + ## Guide, reference and examples None yet. When the first stage lands: a guide here, a generated reference (`shaders-reference.md`) and an example pack @@ -46,9 +89,10 @@ pack exist ([stability.md](stability.md)). ## Not there yet -Everything on this page. The order: the renderer hooks shared with the format loader, then the material and post +The stages and everything that runs a pack (the format above is read and checked). The order: the renderer hooks shared with the format loader, then the material and post stages with options and hot reload, then the overlay, lighting, sky and shadow stages. ## Changelog +- 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.