From 770118870b4d1d94d4eb837a6b062eccf49d3edb Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 15 Nov 2026 17:55:48 -0800 Subject: [PATCH 1/2] Changelog: the command writes JSON Lines under lumen-message/1 The first commit of flyingrobots/lumen#219: the changelog's entry for the command describes its standard output as the messages of ADR 0015. Issue: flyingrobots/lumen#219 Agent-Session: 7659171b-5ea2-4675-adcf-cb84ac79c847 Agent-Tool: Claude Code --- CHANGELOG.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 91ceaee..9889638 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,11 +20,14 @@ part was built. scene (`--scene reference|fixed-point`), renders it at `--width` by `--height` (each `1..=32768`, at most `2^27` pixels; default 320 by 180) with `--samples` (a power of two from 1 to 1024, default 4) and `--seed` (`0..=4294967295`, default 0) on `--threads` (`1..=256`, - default what the system reports) taking bands of `--band-rows` rows (default 1), prints a - report (the render's provenance, the threads and band height, the rays, the image hash, the - file and the wall-clock times) and, with `--out`, writes the PNG; `--stats` adds the scene, ray - and run statistics. `lumen stats` prints a scene's statistics without rendering; `--help` and - `--version` (with the Bunny commit). A refused command line or value exits 2 with a message + default what the system reports) taking bands of `--band-rows` rows (default 1), prints its + messages and, with `--out`, writes the PNG; `--stats` adds the scene, ray, traversal and run + statistics. `lumen stats` prints a scene's statistics without rendering; `--help` and + `--version` (with the Bunny commit). Standard output is JSON Lines: every line is one object + under `lumen-message/1` (`schemas/lumen-message-1.schema.json`, ADR 0015), of type + `provenance`, `result`, `timings`, `scene_statistics`, `ray_statistics`, + `traversal_statistics`, `run_statistics`, `help` or `version`; numbers are integers and times + are integer microseconds, information only (flyingrobots/lumen#219). A refused command line or value exits 2 with a message (and the usage text, except for a size); anything that fails after that exits 1. Arguments are read as OS strings; every option also takes `--option=value`; a separate value that reads as an option is refused; leading zeros are decimal. `--out` is checked before the render and From b271a7b47c8b455a6f4efb3a570e2ec8f51287a0 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 15 Nov 2026 18:04:32 -0800 Subject: [PATCH 2/2] wip: JSON writer, messages, schema and test parser; cli.rs half moved Not yet compiled or tested: the command writes lumen-message/1 messages (json.rs, messages.rs, stats.rs), schemas/lumen-message-1.schema.json, an independent test JSON parser and schema-subset validator (tests/json/), and part of tests/cli.rs moved off the key-value report. Paused by the maintainer. Issue: flyingrobots/lumen#219 Agent-Session: 7659171b-5ea2-4675-adcf-cb84ac79c847 Agent-Tool: Claude Code --- crates/lumen/src/bin/lumen/cli.rs | 22 +- crates/lumen/src/bin/lumen/failure.rs | 2 +- crates/lumen/src/bin/lumen/json.rs | 178 ++++ crates/lumen/src/bin/lumen/json/tests.rs | 95 ++ crates/lumen/src/bin/lumen/main.rs | 60 +- crates/lumen/src/bin/lumen/messages.rs | 125 +++ crates/lumen/src/bin/lumen/messages/tests.rs | 123 +++ crates/lumen/src/bin/lumen/report.rs | 87 -- crates/lumen/src/bin/lumen/stats.rs | 301 +++--- crates/lumen/src/bin/lumen/stats/tests.rs | 312 +++--- crates/lumen/src/bin/lumen/stats/traversal.rs | 71 +- crates/lumen/tests/cli.rs | 220 +++-- crates/lumen/tests/json/mod.rs | 393 ++++++++ crates/lumen/tests/json/schema.rs | 235 +++++ schemas/lumen-message-1.schema.json | 928 ++++++++++++++++++ 15 files changed, 2532 insertions(+), 620 deletions(-) create mode 100644 crates/lumen/src/bin/lumen/json.rs create mode 100644 crates/lumen/src/bin/lumen/json/tests.rs create mode 100644 crates/lumen/src/bin/lumen/messages.rs create mode 100644 crates/lumen/src/bin/lumen/messages/tests.rs delete mode 100644 crates/lumen/src/bin/lumen/report.rs create mode 100644 crates/lumen/tests/json/mod.rs create mode 100644 crates/lumen/tests/json/schema.rs create mode 100644 schemas/lumen-message-1.schema.json diff --git a/crates/lumen/src/bin/lumen/cli.rs b/crates/lumen/src/bin/lumen/cli.rs index dba385b..135b00e 100644 --- a/crates/lumen/src/bin/lumen/cli.rs +++ b/crates/lumen/src/bin/lumen/cli.rs @@ -31,12 +31,14 @@ usage: lumen render [--scene NAME] [--out FILE] [--width W] [--height H] [--samp Renders one of lumen's built-in scenes (reference, the default, fixed-point or canyon) on T threads, each taking bands of R whole rows, with N samples per pixel of a diffuse path (a shadow-casting -sun, a uniform sky and one bounce), writes it to a PNG file if --out is given, and prints the -image hash (SHA-256 of the raw RGBA8 bytes) and the timing. The image is the same for every -thread count and band height. --stats adds the scene's statistics and what the rays found -after the report (see docs/reference/cli.md). `lumen stats` builds the scene, renders nothing -and prints what it holds: triangles by material, bounds, lights, camera, the shape of its tree -and its memory. +sun, a uniform sky and one bounce), writes it to a PNG file if --out is given, and prints its +provenance, its result (the image hash, SHA-256 of the raw RGBA8 bytes) and its timings. The +image is the same for every thread count and band height. --stats adds the scene's statistics +and what the rays found (see docs/reference/cli.md). `lumen stats` builds the scene, renders +nothing and prints what it holds: triangles by material, bounds, lights, camera, the shape of +its tree and its memory. +Standard output is JSON Lines: each line is one JSON object of lumen-message/1, this text +included. --view NAME renders a debug view instead of the lit image: lit (the default), normals (the first hit's geometric normal as colour, back faces dimmer), shading-normals (the interpolated vertex normal where a triangle has them), depth (near white to far dark grey), primitive-id or @@ -80,19 +82,19 @@ pub(crate) enum Command { band: BandRows, /// The PNG file to write, with the bytes it was given, if any. out: Option, - /// Whether the report ends with the statistics. + /// Whether the statistics messages follow the render's. detail: Detail, /// What to draw: the lit image or a debug view. view: View, }, } -/// How much `render` reports. +/// How much `render` prints. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum Detail { - /// The report alone, as before statistics existed. + /// The render's messages alone: `provenance`, `result` and `timings`. Report, - /// The report, then the scene and ray statistics (`--stats`). + /// Those, then the four statistics messages (`--stats`). Statistics, } diff --git a/crates/lumen/src/bin/lumen/failure.rs b/crates/lumen/src/bin/lumen/failure.rs index 1a96b8d..39ed3ec 100644 --- a/crates/lumen/src/bin/lumen/failure.rs +++ b/crates/lumen/src/bin/lumen/failure.rs @@ -41,7 +41,7 @@ pub(crate) enum Failure { /// Why it could not be written. error: PublishError, }, - /// The report could not be written to standard output: exit code 1. + /// A message could not be written to standard output: exit code 1. Stdout(io::Error), } diff --git a/crates/lumen/src/bin/lumen/json.rs b/crates/lumen/src/bin/lumen/json.rs new file mode 100644 index 0000000..7ebb3a1 --- /dev/null +++ b/crates/lumen/src/bin/lumen/json.rs @@ -0,0 +1,178 @@ +//! The JSON the command writes (ADR 0015): objects, arrays, strings, integers, booleans and +//! `null`, and no float, so that every message is the same text on every platform. +//! +//! This is a writer only. Members keep the order they were added in, and a string is written +//! as RFC 8259 requires: `"` and `\` escaped, the control characters U+0000 to U+001F escaped +//! (`\b`, `\t`, `\n`, `\f` and `\r` in their short forms, the rest as `\u00XX` with lowercase +//! hex), and every other character, U+007F and non-ASCII included, written as itself in UTF-8. + +use core::fmt::Write as _; + +/// A JSON value, as the command writes it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) enum Value { + /// `null`. + Null, + /// `true` or `false`. + Bool(bool), + /// A non-negative integer: every count, size, seed and time the command prints is one. + Integer(u64), + /// A string. + String(String), + /// An array. + Array(Vec), + /// An object. + Object(Object), +} + +/// A JSON object: its members in the order they were added. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub(crate) struct Object(Vec<(String, Value)>); + +impl Object { + /// An object with no members. + pub(crate) fn new() -> Self { + Self(Vec::new()) + } + + /// This object with `key` added last, holding `value`. + #[must_use] + pub(crate) fn with(mut self, key: impl Into, value: impl Into) -> Self { + self.0.push((key.into(), value.into())); + self + } + + /// The members, in order. + pub(crate) fn members(&self) -> &[(String, Value)] { + &self.0 + } + + /// The object as one line of JSON, without a line end. + pub(crate) fn to_json(&self) -> String { + let mut out = String::new(); + write_object(&mut out, self); + out + } +} + +impl From for Value { + fn from(value: bool) -> Self { + Self::Bool(value) + } +} + +impl From for Value { + fn from(value: u64) -> Self { + Self::Integer(value) + } +} + +impl From for Value { + fn from(value: u32) -> Self { + Self::Integer(u64::from(value)) + } +} + +impl From for Value { + /// Lossless on every target Lumen builds for, none of whose `usize` is wider than 64 bits. + fn from(value: usize) -> Self { + Self::Integer(u64::try_from(value).unwrap_or(u64::MAX)) + } +} + +impl From<&str> for Value { + fn from(value: &str) -> Self { + Self::String(value.to_owned()) + } +} + +impl From for Value { + fn from(value: String) -> Self { + Self::String(value) + } +} + +impl From for Value { + fn from(value: Object) -> Self { + Self::Object(value) + } +} + +impl From> for Value { + fn from(value: Vec) -> Self { + Self::Array(value) + } +} + +impl> From> for Value { + /// `None` is `null`. + fn from(value: Option) -> Self { + value.map_or(Self::Null, Into::into) + } +} + +/// An array of the values `items` gives. +pub(crate) fn array>(items: impl IntoIterator) -> Value { + Value::Array(items.into_iter().map(Into::into).collect()) +} + +fn write_value(out: &mut String, value: &Value) { + match value { + Value::Null => out.push_str("null"), + Value::Bool(true) => out.push_str("true"), + Value::Bool(false) => out.push_str("false"), + // Writing to a `String` cannot fail. + Value::Integer(number) => { + let _ = write!(out, "{number}"); + } + Value::String(text) => write_string(out, text), + Value::Array(items) => { + out.push('['); + for (n, item) in items.iter().enumerate() { + if n > 0 { + out.push(','); + } + write_value(out, item); + } + out.push(']'); + } + Value::Object(object) => write_object(out, object), + } +} + +fn write_object(out: &mut String, object: &Object) { + out.push('{'); + for (n, (key, value)) in object.0.iter().enumerate() { + if n > 0 { + out.push(','); + } + write_string(out, key); + out.push(':'); + write_value(out, value); + } + out.push('}'); +} + +/// `text` as a JSON string, quotes included. +pub(crate) fn write_string(out: &mut String, text: &str) { + out.push('"'); + for c in text.chars() { + match c { + '"' => out.push_str("\\\""), + '\\' => out.push_str("\\\\"), + '\u{8}' => out.push_str("\\b"), + '\t' => out.push_str("\\t"), + '\n' => out.push_str("\\n"), + '\u{c}' => out.push_str("\\f"), + '\r' => out.push_str("\\r"), + '\u{0}'..='\u{1f}' => { + let _ = write!(out, "\\u{:04x}", u32::from(c)); + } + c => out.push(c), + } + } + out.push('"'); +} + +#[cfg(test)] +mod tests; diff --git a/crates/lumen/src/bin/lumen/json/tests.rs b/crates/lumen/src/bin/lumen/json/tests.rs new file mode 100644 index 0000000..c84df10 --- /dev/null +++ b/crates/lumen/src/bin/lumen/json/tests.rs @@ -0,0 +1,95 @@ +//! The JSON writer: each kind of value and every class of character, against text written by +//! hand from RFC 8259. + +use super::*; + +fn string(text: &str) -> String { + let mut out = String::new(); + write_string(&mut out, text); + out +} + +/// Oracle: RFC 8259, section 7, by hand. The two characters that must be escaped, the five short +/// escapes, and the control range exactly at its ends: U+0000 and U+001F are escaped, U+0020 +/// (the first character past the range) and U+007F (DEL, which JSON does not escape) are not. +#[test] +fn strings_escape_quotes_backslashes_and_exactly_the_control_characters() { + assert_eq!(string(""), r#""""#); + assert_eq!(string("a\"b"), r#""a\"b""#); + assert_eq!(string("a\\b"), r#""a\\b""#); + assert_eq!(string("/"), r#""/""#); + assert_eq!(string("\u{8}\t\n\u{c}\r"), r#""\b\t\n\f\r""#); + assert_eq!(string("\u{0}"), r#""\u0000""#); + assert_eq!(string("\u{1}"), r#""\u0001""#); + assert_eq!(string("\u{b}"), r#""\u000b""#); + assert_eq!(string("\u{1f}"), r#""\u001f""#); + assert_eq!(string("\u{20}"), r#"" ""#); + assert_eq!(string("\u{7f}"), "\"\u{7f}\""); +} + +/// Oracle: every character from U+0000 to U+00FF, by its class: below U+0020 the output is an +/// escape (six bytes, or two for the short forms), `"` and `\` are two bytes, and every other +/// character is itself. Witness count: 256 characters. +#[test] +fn every_character_up_to_u_00ff_is_escaped_only_if_it_must_be() { + let short = [('\u{8}', 'b'), ('\t', 't'), ('\n', 'n'), ('\u{c}', 'f'), ('\r', 'r')]; + for code in 0..=0xff_u32 { + let c = char::from_u32(code).expect("a scalar value"); + let inner = string(&c.to_string()); + let inner = &inner[1..inner.len() - 1]; + let letter = short.iter().find(|(s, _)| *s == c).map(|(_, letter)| *letter); + let expected = match (c, letter) { + ('"' | '\\', _) => format!("\\{c}"), + (_, Some(letter)) => format!("\\{letter}"), + _ if code < 0x20 => format!("\\u00{code:02x}"), + _ => c.to_string(), + }; + assert_eq!(inner, expected, "U+{code:04X}"); + if code < 0x20 { + assert!(inner.starts_with('\\') && inner.is_ascii(), "U+{code:04X}: {inner}"); + } + } +} + +/// Oracle: the UTF-8 bytes of each character, written as itself. +#[test] +fn non_ascii_is_written_as_utf_8() { + assert_eq!(string("é"), "\"\u{e9}\""); + assert_eq!(string("日本"), "\"\u{65e5}\u{672c}\""); + assert_eq!(string("\u{1f600}").as_bytes(), b"\"\xf0\x9f\x98\x80\""); + assert_eq!(string("\u{10ffff}").as_bytes(), b"\"\xf4\x8f\xbf\xbf\""); +} + +/// Oracle: decimal by hand, at both ends of `u64`. +#[test] +fn integers_are_decimal_at_both_ends_of_their_range() { + let line = |value: Value| Object::new().with("n", value).to_json(); + assert_eq!(line(Value::from(0_u64)), r#"{"n":0}"#); + assert_eq!(line(Value::from(u64::MAX)), r#"{"n":18446744073709551615}"#); + assert_eq!(line(Value::from(u32::MAX)), r#"{"n":4294967295}"#); + assert_eq!(line(Value::from(usize::MAX)), format!(r#"{{"n":{}}}"#, usize::MAX)); +} + +/// Oracle: the text by hand. Members keep their order; `None` is `null`; nesting closes in order. +#[test] +fn objects_and_arrays_keep_their_order_and_nest() { + let inner = Object::new().with("z", true).with("a", false); + let object = Object::new() + .with("b", Value::Null) + .with("a", inner) + .with("list", array([1_u32, 2, 3])) + .with("empty", array(Vec::::new())) + .with("none", None::) + .with("some", Some("x")) + .with("o", Object::new()); + assert_eq!( + object.to_json(), + r#"{"b":null,"a":{"z":true,"a":false},"list":[1,2,3],"empty":[],"none":null,"some":"x","o":{}}"# + ); +} + +/// Oracle: a key is a string like any other, so a key that needed escaping would be escaped. +#[test] +fn keys_are_written_as_strings() { + assert_eq!(Object::new().with("a\"b", 1_u32).to_json(), r#"{"a\"b":1}"#); +} diff --git a/crates/lumen/src/bin/lumen/main.rs b/crates/lumen/src/bin/lumen/main.rs index e04bff5..dc68d0e 100644 --- a/crates/lumen/src/bin/lumen/main.rs +++ b/crates/lumen/src/bin/lumen/main.rs @@ -6,16 +6,17 @@ clippy::disallowed_methods, clippy::disallowed_types, clippy::disallowed_macros, - reason = "time-instant, host-parallelism, std-env, std-fs, host-io, float-type: the command's \ - edge reads its arguments, writes the PNG to a file or standard output, times the \ - phases in seconds and asks the host for the default thread count; the library gets \ - only values" + reason = "time-instant, host-parallelism, std-env, std-fs, host-io: the command's edge reads \ + its arguments, writes the PNG to a file and its messages to standard output, times \ + the phases in microseconds and asks the host for the default thread count; the \ + library gets only values" )] mod cli; mod failure; +mod json; +mod messages; mod publish; -mod report; mod stats; use std::ffi::OsString; @@ -31,7 +32,7 @@ use lumen::{ RenderSettings, Schedule, View, BUNNY_REV, MAX_THREADS, }; use publish::Disk; -use report::{Report, Times}; +use messages::{emit, Outcome, Times}; fn main() -> ExitCode { match command(std::env::args_os().skip(1)) { @@ -46,8 +47,8 @@ fn main() -> ExitCode { /// Runs the command line `args` (after the program name). fn command(args: impl Iterator) -> Result<(), Failure> { match cli::parse(args).map_err(Failure::Usage)? { - Command::Help => println!("{USAGE}"), - Command::Version => println!("lumen {} (bunny {BUNNY_REV})", env!("CARGO_PKG_VERSION")), + Command::Help => print(&messages::help(USAGE))?, + Command::Version => print(&messages::version(env!("CARGO_PKG_VERSION"), BUNNY_REV))?, Command::Stats { scene } => describe(scene)?, Command::Render { scene, width, height, settings, threads, band, out, detail, view } => { let threads = threads.unwrap_or_else(available_threads); @@ -68,12 +69,16 @@ fn available_threads() -> u32 { .clamp(1, MAX_THREADS) } +/// Writes one message to standard output. +fn print(message: &json::Object) -> Result<(), Failure> { + emit(&mut io::stdout().lock(), message).map_err(Failure::Stdout) +} + /// Builds the chosen scene and prints its statistics: no render, no clock. fn describe(scene: BuiltinScene) -> Result<(), Failure> { let built = scene.build().map_err(Failure::Scene)?; let statistics = built.statistics().map_err(Failure::Statistics)?; - let mut stdout = io::stdout().lock(); - stats::write_stats(&mut stdout, scene.id(), &built, &statistics).map_err(Failure::Stdout) + print(&stats::scene_statistics(scene.id(), &built, &statistics)) } /// What to render: the scene, the view, the size, the settings and the schedule. @@ -86,9 +91,10 @@ struct Job { schedule: Schedule, } -/// Builds the chosen scene, checks that the PNG can be written if asked, renders it, hashes the -/// image, publishes the PNG, and prints -/// what was made and how long each part took. +/// Builds the chosen scene, checks that the PNG can be written if asked, prints the render's +/// `provenance`, renders it, hashes the image, publishes the PNG, and prints the `result` and +/// the `timings` (and with `--stats` the four statistics messages). Each message is flushed when +/// it is written (ADR 0015). /// /// The times are wall-clock readings of a monotonic clock (`Instant`), taken around each part; /// they are printed and never reach the image. @@ -102,6 +108,9 @@ fn run(job: Job, out: Option<&Path>, detail: Detail) -> Result<(), Failure> { .map_err(|error| Failure::Output { path: path.to_path_buf(), error })?; } let built = started.elapsed(); + let provenance = + RenderProvenance::named(scene.id(), &built_scene, size, settings).with_view(view); + print(&messages::provenance(&provenance))?; // Only `--stats` asks the workers and the traversals to count: without it the render does no // counting work for run or traversal statistics (ADR 0008). let (render, counted) = match detail { @@ -135,15 +144,12 @@ fn run(job: Job, out: Option<&Path>, detail: Detail) -> Result<(), Failure> { png: total.saturating_sub(hashed), total, }; - let report = Report { - provenance: RenderProvenance::named(scene.id(), &built_scene, size, settings) - .with_view(view), + let outcome = Outcome { schedule, workers: schedule.workers(size), rays: render.rays, hash, png: out.map(Path::to_path_buf).zip(written), - times, }; // Read after the clock stops, and only when asked: the statistics take no part in the times. let statistics = match detail { @@ -153,19 +159,15 @@ fn run(job: Job, out: Option<&Path>, detail: Detail) -> Result<(), Failure> { Some(built_scene.statistics().map_err(Failure::Statistics)?) } }; - let mut stdout = io::stdout().lock(); - report.write(&mut stdout).map_err(Failure::Stdout)?; + print(&messages::result(&provenance, &outcome))?; + print(&messages::timings(×))?; if let Some(scene_statistics) = statistics { - stats::write_scene_block(&mut stdout, &built_scene, &scene_statistics) - .and_then(|()| stats::write_rays(&mut stdout, &render.statistics, settings)) - .and_then(|()| { - counted.as_ref().map_or(Ok(()), |(run, traversal)| { - let outcomes = &render.statistics.outcomes; - stats::write_traversal(&mut stdout, traversal, outcomes) - .and_then(|()| stats::write_run(&mut stdout, run)) - }) - }) - .map_err(Failure::Stdout)?; + print(&stats::scene_statistics(scene.id(), &built_scene, &scene_statistics))?; + print(&stats::ray_statistics(&render.statistics, settings))?; + if let Some((run, traversal)) = &counted { + print(&stats::traversal_statistics(traversal))?; + print(&stats::run_statistics(run))?; + } } Ok(()) } diff --git a/crates/lumen/src/bin/lumen/messages.rs b/crates/lumen/src/bin/lumen/messages.rs new file mode 100644 index 0000000..35cdd20 --- /dev/null +++ b/crates/lumen/src/bin/lumen/messages.rs @@ -0,0 +1,125 @@ +//! The messages `lumen` writes to standard output: one JSON object per line under +//! `lumen-message/1` (ADR 0015, `schemas/lumen-message-1.schema.json`). This module holds the +//! messages of a render (`provenance`, `result`, `timings`), of `--help` (`help`) and of +//! `--version` (`version`); `stats.rs` holds the four statistics messages. + +use std::io::{self, Write}; +use std::path::PathBuf; +use std::time::Duration; + +use lumen::{ProvenanceValue, RayCount, RenderProvenance, Schedule}; + +use crate::json::{Object, Value}; + +/// The version tag every message carries in its `schema` member. +pub(crate) const MESSAGE_SCHEMA_ID: &str = "lumen-message/1"; + +/// A message of type `kind`: its `schema` and `type` members, to which the caller adds the rest. +pub(crate) fn message(kind: &'static str) -> Object { + Object::new().with("schema", MESSAGE_SCHEMA_ID).with("type", kind) +} + +/// Writes `message` as one line and flushes it, so that a caller reading the stream sees each +/// message when it is written (ADR 0015, "Messages are written as the work proceeds"). +pub(crate) fn emit(out: &mut impl Write, message: &Object) -> io::Result<()> { + let mut line = message.to_json(); + line.push('\n'); + out.write_all(line.as_bytes())?; + out.flush() +} + +/// `lumen --help`: the usage text, as one string. +pub(crate) fn help(usage: &str) -> Object { + message("help").with("usage", usage) +} + +/// `lumen --version`: the package version and the Bunny commit. +pub(crate) fn version(lumen: &str, bunny: &str) -> Object { + message("version").with("lumen", lumen).with("bunny", bunny) +} + +/// The render's provenance, written when the render starts: `RenderProvenance::fields()` in +/// order, each key with its hyphen written as an underscore, the size as `width` and `height`, +/// and an unnamed scene as `null`. +pub(crate) fn provenance(provenance: &RenderProvenance) -> Object { + provenance.fields().into_iter().fold(message("provenance"), |object, (name, value)| { + match value { + ProvenanceValue::Identity(identity) => object.with(member(name), identity), + ProvenanceValue::Unnamed => object.with(member(name), Value::Null), + ProvenanceValue::Content(content) => object.with(member(name), content.to_string()), + ProvenanceValue::Size(size) => { + object.with("width", size.width()).with("height", size.height()) + } + ProvenanceValue::Number(number) => object.with(member(name), number), + } + }) +} + +/// The member name of a provenance field: its name with `-` written as `_`. +fn member(field: &str) -> String { + field.replace('-', "_") +} + +/// What a render produced, written when it finishes. +pub(crate) struct Outcome { + /// The schedule asked for. + pub(crate) schedule: Schedule, + /// The workers that rendered: never more than the bands. + pub(crate) workers: u32, + /// The rays traced. + pub(crate) rays: RayCount, + /// The image hash. + pub(crate) hash: String, + /// The file written and its length in bytes, if `--out` was given. + pub(crate) png: Option<(PathBuf, u64)>, +} + +/// The `result` message: the size, the schedule, the rays, the image hash and the file. +pub(crate) fn result(provenance: &RenderProvenance, outcome: &Outcome) -> Object { + let Outcome { schedule, workers, rays, hash, png } = outcome; + let size = provenance.size(); + let rays = Object::new() + .with("total", rays.total()) + .with("closest", rays.closest) + .with("shadow", rays.shadow); + let png = png.as_ref().map(|(path, bytes)| { + Object::new().with("path", path.display().to_string()).with("bytes", *bytes) + }); + message("result") + .with("width", size.width()) + .with("height", size.height()) + .with("threads", *workers) + .with("threads_asked", schedule.threads()) + .with("band_rows", schedule.band().get()) + .with("rays", rays) + .with("image", hash.as_str()) + .with("png", png) +} + +/// The wall-clock parts of one run. +pub(crate) struct Times { + pub(crate) scene: Duration, + pub(crate) render: Duration, + pub(crate) hash: Duration, + pub(crate) png: Duration, + pub(crate) total: Duration, +} + +/// The `timings` message: each part's wall-clock time in whole microseconds, information only. +pub(crate) fn timings(times: &Times) -> Object { + message("timings") + .with("scene_us", micros(times.scene)) + .with("render_us", micros(times.render)) + .with("hash_us", micros(times.hash)) + .with("png_us", micros(times.png)) + .with("total_us", micros(times.total)) +} + +/// A duration in whole microseconds, rounded down, and `u64::MAX` for one longer than that +/// (about 584 942 years). +pub(crate) fn micros(duration: Duration) -> u64 { + u64::try_from(duration.as_micros()).unwrap_or(u64::MAX) +} + +#[cfg(test)] +mod tests; diff --git a/crates/lumen/src/bin/lumen/messages/tests.rs b/crates/lumen/src/bin/lumen/messages/tests.rs new file mode 100644 index 0000000..154194c --- /dev/null +++ b/crates/lumen/src/bin/lumen/messages/tests.rs @@ -0,0 +1,123 @@ +//! The render, help and version messages, against lines written by hand. + +use lumen::{reference_scene, ImageSize, RenderSettings, View, DEFAULT_BAND_ROWS}; + +use super::*; + +/// Oracle: the line by hand, from the library's provenance of a 40 by 24 render at 2 samples, +/// seed 5 (the values `tests/library.rs` pins), in the order of `RenderProvenance::fields()`. +#[test] +fn the_provenance_line_of_a_named_render() { + let scene = reference_scene().expect("builds"); + let size = ImageSize::new(40, 24).expect("size"); + let settings = RenderSettings::new(2, 5).expect("settings"); + let provenance = RenderProvenance::named("lumen-reference-scene/4", &scene, size, settings); + let want = format!( + concat!( + r#"{{"schema":"lumen-message/1","type":"provenance","scene":"lumen-reference-scene/4","#, + r#""integrator":"lumen-diffuse-path/1","shading":"bunny-diffuse-shading/1","#, + r#""sampler":"bunny-sobol-owen/1","tone":"bunny-tone-srgb/1","#, + r#""encoding":"bunny-rgba8-opaque/1","bunny":"{}","width":40,"height":24,"#, + r#""pixels":960,"samples":2,"seed":5,"bounces":1,"scene_content":"{}"}}"# + ), + lumen::BUNNY_REV, + scene.content_id() + ); + assert_eq!(self::provenance(&provenance).to_json(), want); +} + +/// Oracle: an unnamed scene's `scene` is `null`; a debug view's provenance names the view, one +/// sample and no bounce. +#[test] +fn an_unnamed_scene_is_null_and_a_view_names_itself() { + let scene = reference_scene().expect("builds"); + let size = ImageSize::new(4, 3).expect("size"); + let settings = RenderSettings::new(1, 0).expect("settings"); + let unnamed = self::provenance(&RenderProvenance::new(&scene, size, settings)).to_json(); + assert!(unnamed.contains(r#""type":"provenance","scene":null,"integrator":"#), "{unnamed}"); + let view = RenderProvenance::named("x/1", &scene, size, settings).with_view(View::Depth); + let line = self::provenance(&view).to_json(); + assert!(line.contains(r#""integrator":"lumen-view-depth/1""#), "{line}"); + assert!(line.contains(r#""samples":1,"seed":0,"bounces":0,"#), "{line}"); +} + +fn outcome(png: Option<(PathBuf, u64)>) -> (RenderProvenance, Outcome) { + let scene = reference_scene().expect("builds"); + let size = ImageSize::new(8, 4).expect("size"); + let settings = RenderSettings::new(1, 0).expect("settings"); + let provenance = RenderProvenance::named("x/1", &scene, size, settings); + let schedule = Schedule::new(6, DEFAULT_BAND_ROWS).expect("schedule"); + let rays = RayCount { closest: 40, shadow: 30 }; + (provenance, Outcome { schedule, workers: 4, rays, hash: "sha256:ab".to_owned(), png }) +} + +/// Oracle: the lines by hand, with distinct numbers so that no member is written under another's +/// name; without `--out`, `png` is `null`. +#[test] +fn the_result_line_with_and_without_a_file() { + let (provenance, without) = outcome(None); + assert_eq!( + result(&provenance, &without).to_json(), + concat!( + r#"{"schema":"lumen-message/1","type":"result","width":8,"height":4,"threads":4,"#, + r#""threads_asked":6,"band_rows":1,"rays":{"total":70,"closest":40,"shadow":30},"#, + r#""image":"sha256:ab","png":null}"# + ) + ); + let (provenance, with) = outcome(Some((PathBuf::from("dir/a \"b\".png"), 123))); + let line = result(&provenance, &with).to_json(); + assert!(line.ends_with(r#""png":{"path":"dir/a \"b\".png","bytes":123}}"#), "{line}"); +} + +/// Oracle: whole microseconds by hand, rounded down. +#[test] +fn the_timings_line_is_whole_microseconds() { + let times = Times { + scene: Duration::from_nanos(1_999), + render: Duration::from_secs(2), + hash: Duration::ZERO, + png: Duration::from_nanos(999), + total: Duration::from_millis(3), + }; + assert_eq!( + timings(×).to_json(), + concat!( + r#"{"schema":"lumen-message/1","type":"timings","scene_us":1,"render_us":2000000,"#, + r#""hash_us":0,"png_us":0,"total_us":3000}"# + ) + ); +} + +/// Range limit: `u64::MAX` microseconds is written as itself; one microsecond more, which a +/// `Duration` holds, saturates to it instead of wrapping. +#[test] +fn a_time_saturates_exactly_past_u64_max_microseconds() { + let at = Duration::from_micros(u64::MAX); + assert_eq!(micros(at), u64::MAX); + assert_eq!(micros(at - Duration::from_micros(1)), u64::MAX - 1); + assert_eq!(micros(at + Duration::from_micros(1)), u64::MAX); + assert_eq!(micros(Duration::MAX), u64::MAX); +} + +/// Oracle: the lines by hand; the usage text keeps its line ends, escaped. +#[test] +fn the_help_and_version_lines() { + assert_eq!( + help("usage: a\n b").to_json(), + r#"{"schema":"lumen-message/1","type":"help","usage":"usage: a\n b"}"# + ); + assert_eq!( + version("0.1.0", "abc").to_json(), + r#"{"schema":"lumen-message/1","type":"version","lumen":"0.1.0","bunny":"abc"}"# + ); +} + +/// Every message ends in exactly one line end and holds no other. +#[test] +fn a_message_is_written_as_one_line() { + let mut out = Vec::new(); + emit(&mut out, &help("a\nb\r\nc")).expect("writes"); + let text = String::from_utf8(out).expect("utf-8"); + assert_eq!(text.matches('\n').count(), 1, "{text}"); + assert!(text.ends_with("}\n") && !text.contains('\r'), "{text}"); +} diff --git a/crates/lumen/src/bin/lumen/report.rs b/crates/lumen/src/bin/lumen/report.rs deleted file mode 100644 index cecf988..0000000 --- a/crates/lumen/src/bin/lumen/report.rs +++ /dev/null @@ -1,87 +0,0 @@ -//! What `lumen render` prints: the render's provenance, the run's threads and band height, the ray -//! count, the image hash, the file written and the wall-clock times. - -use std::io::{self, Write}; -use std::path::PathBuf; -use std::time::Duration; - -use lumen::{ProvenanceValue, RayCount, RenderProvenance, Schedule}; - -/// The wall-clock parts of one run. -pub(crate) struct Times { - pub(crate) scene: Duration, - pub(crate) render: Duration, - pub(crate) hash: Duration, - pub(crate) png: Duration, - pub(crate) total: Duration, -} - -/// What `lumen render` prints: the provenance (facts about the image), then the facts of this -/// run (threads, band height, file, times), with the render's results (rays, hash) between them. -pub(crate) struct Report { - pub(crate) provenance: RenderProvenance, - pub(crate) schedule: Schedule, - pub(crate) workers: u32, - pub(crate) rays: RayCount, - pub(crate) hash: String, - pub(crate) png: Option<(PathBuf, u64)>, - pub(crate) times: Times, -} - -impl Report { - pub(crate) fn write(&self, out: &mut impl Write) -> io::Result<()> { - let Self { provenance, schedule, workers, rays, hash, png, times } = self; - for (name, value) in provenance.fields() { - match value { - ProvenanceValue::Identity(identity) => writeln!(out, "{name} {identity}")?, - ProvenanceValue::Unnamed => writeln!(out, "{name} (unnamed)")?, - ProvenanceValue::Content(content) => writeln!(out, "{name} {content}")?, - ProvenanceValue::Size(size) => { - writeln!(out, "{name} {}x{}", size.width(), size.height())?; - } - ProvenanceValue::Number(number) => writeln!(out, "{name} {number}")?, - } - } - writeln!( - out, - "threads {workers}\nthreads-asked {}\nband-rows {}\n\ - rays {} (closest {}, shadow {})\nimage {hash}", - schedule.threads(), - schedule.band().get(), - rays.total(), - rays.closest, - rays.shadow, - )?; - match png { - Some((path, bytes)) => writeln!(out, "png {} ({bytes} bytes)", path.display())?, - None => writeln!(out, "png none")?, - } - write_times(out, times, *rays) - } -} - -/// The wall-clock readings of this run: information only, never part of the image. -fn write_times(out: &mut impl Write, times: &Times, rays: RayCount) -> io::Result<()> { - let render = times.render.as_secs_f64(); - #[allow( - clippy::cast_precision_loss, - reason = "a ray count below 2^53 converts exactly; the rate is information only" - )] - let total_rays = rays.total() as f64; - let per_second = if render > 0.0 { total_rays / render } else { 0.0 }; - let ns_per_ray = render * 1e9 / total_rays.max(1.0); - writeln!( - out, - "scene-seconds {:.3} (information only)\n\ - render-seconds {render:.3} (information only)\n\ - hash-seconds {:.3} (information only)\n\ - png-seconds {:.3} (information only)\n\ - total-seconds {:.3} (information only: scene, render, hash and png)\n\ - rays-per-second {per_second:.0} (information only: wall clock, all threads)\n\ - ns-per-ray {ns_per_ray:.1} (information only: wall clock, all threads)", - times.scene.as_secs_f64(), - times.hash.as_secs_f64(), - times.png.as_secs_f64(), - times.total.as_secs_f64(), - ) -} diff --git a/crates/lumen/src/bin/lumen/stats.rs b/crates/lumen/src/bin/lumen/stats.rs index 44356e9..2c5e34b 100644 --- a/crates/lumen/src/bin/lumen/stats.rs +++ b/crates/lumen/src/bin/lumen/stats.rs @@ -1,12 +1,13 @@ -//! What `lumen stats` prints: a built scene's statistics as `key value` lines (ADR 0008). +//! The statistics messages (ADR 0008, ADR 0015): `scene_statistics`, which `lumen stats` and +//! `render --stats` print, and `ray_statistics`, `traversal_statistics` and `run_statistics`, +//! which `render --stats` adds. //! -//! Each line is a key with no spaces, one space, and its value: one token, or several separated -//! by single spaces (a vector's three components). Fixed-point values are printed in decimal -//! with six places, rounded to nearest with ties away from zero, from their exact raw integers. -//! docs/reference/cli.md, "Statistics", documents every key. +//! Every number is an integer. A fixed-point value is a string, in decimal with six places, +//! rounded to nearest with ties away from zero, from its exact raw integer, because a JSON +//! number would be read as a float. A mean is not printed: its total and its count are, and a +//! program divides. docs/reference/cli.md, "Statistics", documents every member. use core::fmt; -use std::io::{self, Write}; use bunny_linalg::FixedVec3; use bunny_num::FixedQ32_32; @@ -15,164 +16,141 @@ use lumen::{ TREE_LAYOUT, }; -/// Writes `lumen stats`: the scene's name, content identity and integrator, then its block. -pub(crate) fn write_stats( - out: &mut impl Write, - name: &str, - scene: &Scene, - stats: &SceneStatistics, -) -> io::Result<()> { - writeln!(out, "scene {name}")?; - writeln!(out, "scene-content {}", scene.content_id())?; - writeln!(out, "integrator {}", Integrator::for_scene(scene).id())?; - write_scene_block(out, scene, stats) +use crate::json::{array, Object, Value}; +use crate::messages::message; + +/// The `scene_statistics` message: the scene's name, content identity and integrator, then its +/// contents, lights and camera, its tree and its memory. +pub(crate) fn scene_statistics(name: &str, scene: &Scene, stats: &SceneStatistics) -> Object { + let object = message("scene_statistics") + .with("scene", name) + .with("scene_content", scene.content_id().to_string()) + .with("integrator", Integrator::for_scene(scene).id()); + let object = contents(object, scene, stats); + let object = lights_and_camera(object, scene); + object.with("tree", tree(stats)).with("memory", memory(stats)) } -/// The label of every `memory.` line: a byte count is this build's type sizes times the counts, -/// so it can differ between targets (a 32-bit `usize`, for one), unlike every other value. -pub(crate) const MEMORY_NOTE: &str = "(information only: this build's type sizes)"; - -/// The scene's statistics: its contents, lights and camera, its tree, its memory. -pub(crate) fn write_scene_block( - out: &mut impl Write, - scene: &Scene, - stats: &SceneStatistics, -) -> io::Result<()> { - write_contents(out, scene, stats)?; - write_lights_and_camera(out, scene)?; - write_tree(out, stats)?; - write_memory(out, stats) -} - -fn write_contents(out: &mut impl Write, scene: &Scene, stats: &SceneStatistics) -> io::Result<()> { +fn contents(object: Object, scene: &Scene, stats: &SceneStatistics) -> Object { let triangles = stats.triangles; - writeln!(out, "scene.triangles {triangles}")?; - // Lumen's triangles hold their own three vertices; none is shared. - writeln!(out, "scene.vertices {}", wide(triangles) * 3)?; - writeln!(out, "scene.triangles-smooth {}", stats.smooth_triangles)?; - writeln!(out, "scene.triangles-zero-area {}", stats.zero_area_triangles)?; - writeln!(out, "scene.materials {}", stats.triangles_by_material.len())?; - for (material, (count, albedo)) in - stats.triangles_by_material.iter().zip(scene.materials()).enumerate() - { - writeln!(out, "scene.material.{material}.triangles {count}")?; - writeln!(out, "scene.material.{material}.albedo {}", Channels(albedo.channels()))?; - } - writeln!(out, "scene.bounds-min {}", Vector(stats.bounds.min))?; - writeln!(out, "scene.bounds-max {}", Vector(stats.bounds.max)) + let albedos = scene.materials().iter().map(|albedo| channels(albedo.channels())); + object + .with("triangles", triangles) + // Lumen's triangles hold their own three vertices; none is shared. + .with("vertices", u64::try_from(triangles).unwrap_or(u64::MAX).saturating_mul(3)) + .with("triangles_smooth", stats.smooth_triangles) + .with("triangles_zero_area", stats.zero_area_triangles) + .with("material_triangles", array(stats.triangles_by_material.iter().copied())) + .with("material_albedo", array(albedos)) + .with("bounds_min", vector(stats.bounds.min)) + .with("bounds_max", vector(stats.bounds.max)) } -fn write_lights_and_camera(out: &mut impl Write, scene: &Scene) -> io::Result<()> { +fn lights_and_camera(object: Object, scene: &Scene) -> Object { let lighting = scene.lighting(); - match lighting.sun { - Some(sun) => { - writeln!(out, "light.sun present")?; - writeln!(out, "light.sun-toward {}", Vector(sun.toward_light()))?; - writeln!(out, "light.sun-irradiance {}", Channels(sun.irradiance()))?; - } - None => writeln!(out, "light.sun none")?, - } - writeln!(out, "light.sky {}", Channels(lighting.sky.radiance()))?; + let sun = lighting.sun.map(|sun| { + Object::new() + .with("toward", vector(sun.toward_light())) + .with("irradiance", channels(sun.irradiance())) + }); let camera = scene.camera(); - writeln!(out, "camera.position {}", Vector(camera.position))?; - writeln!(out, "camera.look {}", Vector(camera.look))?; - writeln!(out, "camera.up {}", Vector(camera.up))?; - writeln!(out, "camera.tan-half-fov {}", Fixed(camera.tan_half_fov)) + object + .with("light", Object::new().with("sun", sun).with("sky", channels(lighting.sky.radiance()))) + .with( + "camera", + Object::new() + .with("position", vector(camera.position)) + .with("look", vector(camera.look)) + .with("up", vector(camera.up)) + .with("tan_half_fov", fixed(camera.tan_half_fov)), + ) } -fn write_tree(out: &mut impl Write, stats: &SceneStatistics) -> io::Result<()> { +fn tree(stats: &SceneStatistics) -> Object { let tree = &stats.tree; - writeln!(out, "tree.builder {TREE_BUILDER}")?; - writeln!(out, "tree.layout {TREE_LAYOUT}")?; - writeln!(out, "tree.nodes {}", tree.nodes)?; - writeln!(out, "tree.interior-nodes {}", tree.interior_nodes)?; - writeln!(out, "tree.leaves {}", tree.leaves)?; - writeln!(out, "tree.leaf-depth-max {}", tree.max_leaf_depth)?; - writeln!(out, "tree.leaf-depth-total {}", tree.leaf_depth_total)?; - let leaves = wide(tree.leaves); - writeln!(out, "tree.leaf-depth-mean {}", Ratio(u128::from(tree.leaf_depth_total), leaves))?; - writeln!(out, "tree.leaf-triangles {}", tree.leaf_triangles)?; - writeln!(out, "tree.leaf-triangles-min {}", tree.min_leaf_triangles)?; - writeln!(out, "tree.leaf-triangles-max {}", tree.max_leaf_triangles)?; - write!(out, "tree.leaf-sizes")?; - for count in tree.leaf_sizes { - write!(out, " {count}")?; - } - writeln!(out) + Object::new() + .with("builder", TREE_BUILDER) + .with("layout", TREE_LAYOUT) + .with("nodes", tree.nodes) + .with("interior_nodes", tree.interior_nodes) + .with("leaves", tree.leaves) + .with("leaf_depth_max", tree.max_leaf_depth) + .with("leaf_depth_total", tree.leaf_depth_total) + .with("leaf_triangles", tree.leaf_triangles) + .with("leaf_triangles_min", tree.min_leaf_triangles) + .with("leaf_triangles_max", tree.max_leaf_triangles) + .with("leaf_sizes", array(tree.leaf_sizes)) } -fn write_memory(out: &mut impl Write, stats: &SceneStatistics) -> io::Result<()> { +/// The byte counts: this build's type sizes times the counts, so they can differ between +/// targets (a 32-bit `usize`, for one), unlike every other value; the schema marks them +/// information only. +fn memory(stats: &SceneStatistics) -> Object { let memory = &stats.memory; - for (name, bytes) in [ - ("triangles", memory.triangles), - ("surfaces", memory.surfaces), - ("vertex-normals", memory.vertex_normals), - ("material-indices", memory.material_indices), - ("materials", memory.materials), - ("tree-nodes", memory.tree_nodes), - ("tree-primitive-indices", memory.tree_primitive_indices), - ("total", memory.total()), - ] { - writeln!(out, "memory.{name}-bytes {bytes} {MEMORY_NOTE}")?; - } - Ok(()) + Object::new() + .with("triangles_bytes", memory.triangles) + .with("surfaces_bytes", memory.surfaces) + .with("vertex_normals_bytes", memory.vertex_normals) + .with("material_indices_bytes", memory.material_indices) + .with("materials_bytes", memory.materials) + .with("tree_nodes_bytes", memory.tree_nodes) + .with("tree_primitive_indices_bytes", memory.tree_primitive_indices) + .with("total_bytes", memory.total()) } -/// What a render's rays found (`render --stats`), after the scene block: per kind, then per +/// The `ray_statistics` message (`render --stats`): what the rays found, per kind, then per /// pixel. Every value is a function of the scene, the size and the settings. -pub(crate) fn write_rays( - out: &mut impl Write, - rays: &RayStatistics, - settings: RenderSettings, -) -> io::Result<()> { +pub(crate) fn ray_statistics(rays: &RayStatistics, settings: RenderSettings) -> Object { let found = &rays.outcomes; - for (key, value) in [ - ("camera", found.camera()), - ("camera-hits", found.camera_hits), - ("camera-misses", found.camera_misses), - ("bounce", found.bounce()), - ("bounce-hits", found.bounce_hits), - ("bounce-misses", found.bounce_misses), - ("bounce-rejected", found.rejected_bounces), - ("shadow", found.shadow()), - ("shadow-occluded", found.shadow_occluded), - ("shadow-unoccluded", found.shadow_unoccluded), - ("total", rays.count().total()), - ("pixels", rays.pixels), - ("samples-per-pixel", u64::from(settings.samples_per_pixel())), - ("samples", rays.samples), - ("per-pixel-min", if rays.pixels == 0 { 0 } else { rays.min_pixel_rays }), - ("per-pixel-max", rays.max_pixel_rays), - ] { - writeln!(out, "rays.{key} {value}")?; - } - let mean = Ratio(u128::from(rays.count().total()), u128::from(rays.pixels)); - writeln!(out, "rays.per-pixel-mean {mean}") + message("ray_statistics") + .with("camera", found.camera()) + .with("camera_hits", found.camera_hits) + .with("camera_misses", found.camera_misses) + .with("bounce", found.bounce()) + .with("bounce_hits", found.bounce_hits) + .with("bounce_misses", found.bounce_misses) + .with("bounce_rejected", found.rejected_bounces) + .with("shadow", found.shadow()) + .with("shadow_occluded", found.shadow_occluded) + .with("shadow_unoccluded", found.shadow_unoccluded) + .with("total", rays.count().total()) + .with("pixels", rays.pixels) + .with("samples_per_pixel", settings.samples_per_pixel()) + .with("samples", rays.samples) + .with("per_pixel_min", if rays.pixels == 0 { 0 } else { rays.min_pixel_rays }) + .with("per_pixel_max", rays.max_pixel_rays) } -/// The label of every per-worker line: which worker took which band depends on timing. -pub(crate) const RUN_NOTE: &str = "(information only: differs from run to run)"; - -/// How the work was spread (`render --stats`), after the ray lines: the band height, the band -/// count and the worker count, which follow from the size and the schedule, then each worker's -/// bands, rows, pixels and rays, which do not. -pub(crate) fn write_run(out: &mut impl Write, run: &RunStatistics) -> io::Result<()> { - writeln!(out, "run.band-rows {}", run.band_rows)?; - writeln!(out, "run.bands {}", run.bands)?; - writeln!(out, "run.workers {}", run.workers.len())?; - for (n, worker) in run.workers.iter().enumerate() { - let rays = worker.rays.total(); - writeln!(out, "run.worker.{n}.bands {} {RUN_NOTE}", worker.bands)?; - writeln!(out, "run.worker.{n}.rows {} {RUN_NOTE}", worker.rows)?; - writeln!(out, "run.worker.{n}.pixels {} {RUN_NOTE}", worker.pixels)?; - writeln!(out, "run.worker.{n}.rays {rays} {RUN_NOTE}")?; - } - Ok(()) +/// The `run_statistics` message (`render --stats`): the band height and the band count, which +/// follow from the size and the schedule, then each worker's bands, rows, pixels and rays, which +/// depend on timing (information only). +pub(crate) fn run_statistics(run: &RunStatistics) -> Object { + let workers = run.workers.iter().map(|worker| { + Object::new() + .with("bands", worker.bands) + .with("rows", worker.rows) + .with("pixels", worker.pixels) + .with("rays", worker.rays.total()) + }); + message("run_statistics") + .with("band_rows", run.band_rows) + .with("bands", run.bands) + .with("workers", array(workers)) +} + +/// A Q32.32 value as a decimal string with six places. +pub(crate) fn fixed(value: FixedQ32_32) -> Value { + Value::String(Fixed(value).to_string()) } -/// A count, widened for arithmetic: lossless, as no target's `usize` is wider than 128 bits. -fn wide(count: usize) -> u128 { - u128::try_from(count).unwrap_or(u128::MAX) +/// A point or direction: its three components. +fn vector(v: FixedVec3) -> Value { + array([fixed(v.x), fixed(v.y), fixed(v.z)]) +} + +/// Three channels, red, green and blue. +fn channels(channels: [FixedQ32_32; 3]) -> Value { + array(channels.map(fixed)) } /// A Q32.32 value in decimal with six places: `raw / 2^32`, rounded to nearest, ties away from @@ -190,43 +168,8 @@ impl fmt::Display for Fixed { } } -/// A point or direction: its three components, separated by spaces. -struct Vector(FixedVec3); - -impl fmt::Display for Vector { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "{} {} {}", Fixed(self.0.x), Fixed(self.0.y), Fixed(self.0.z)) - } -} - -/// Three channels, red, green and blue, separated by spaces. -struct Channels([FixedQ32_32; 3]); - -impl fmt::Display for Channels { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let [r, g, b] = self.0; - write!(f, "{} {} {}", Fixed(r), Fixed(g), Fixed(b)) - } -} - -/// `numerator / denominator` in decimal with two places, rounded to nearest, ties up: exact -/// integer arithmetic. Zero over zero is `0.00`. -pub(crate) struct Ratio(pub(crate) u128, pub(crate) u128); - -impl fmt::Display for Ratio { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self(numerator, denominator) = *self; - // A count of leaves or rays and a sum of them, each below 2^64: no product overflows. - let hundredths = match denominator { - 0 => 0, - d => (numerator * 200 + d) / (2 * d), - }; - write!(f, "{}.{:02}", hundredths / 100, hundredths % 100) - } -} - #[cfg(test)] mod tests; mod traversal; -pub(crate) use traversal::write_traversal; +pub(crate) use traversal::traversal_statistics; diff --git a/crates/lumen/src/bin/lumen/stats/tests.rs b/crates/lumen/src/bin/lumen/stats/tests.rs index c3afe08..f571d16 100644 --- a/crates/lumen/src/bin/lumen/stats/tests.rs +++ b/crates/lumen/src/bin/lumen/stats/tests.rs @@ -1,10 +1,11 @@ -//! The statistics text: the decimal forms, and every line for a scene small enough to count by -//! hand. +//! The statistics messages: the decimal form of a fixed-point value, and every member for a +//! scene small enough to count by hand. use bunny_optics::{Albedo, DirectionalLight, SkyLight}; use lumen::{CameraPlacement, Lighting, SceneSpec}; use super::*; +use crate::json::Value; const ONE: i64 = 1 << 32; @@ -32,18 +33,6 @@ fn fixed_point_values_print_in_decimal_with_six_places() { assert_eq!(fixed(i64::MIN), "-2147483648.000000"); } -/// Oracle: long division by hand, two places, ties up. -#[test] -fn ratios_print_with_two_places_rounded_to_nearest() { - assert_eq!(Ratio(0, 0).to_string(), "0.00"); - assert_eq!(Ratio(7, 7).to_string(), "1.00"); - assert_eq!(Ratio(2, 3).to_string(), "0.67"); - assert_eq!(Ratio(1, 8).to_string(), "0.13"); - assert_eq!(Ratio(1, 200).to_string(), "0.01"); - assert_eq!(Ratio(1, 201).to_string(), "0.00"); - assert_eq!(Ratio(426_614, 27_639).to_string(), "15.44"); -} - /// One triangle under a sun straight above, two materials (the second unused), seen from four /// units in front. fn one_triangle() -> Scene { @@ -67,98 +56,62 @@ fn one_triangle() -> Scene { .expect("builds") } +/// The `scene_statistics` line of the one-triangle scene. +fn one_triangle_line() -> String { + let scene = one_triangle(); + scene_statistics("a-name/1", &scene, &scene.statistics().expect("counts")).to_json() +} + /// Oracle: counting by hand. One triangle is one leaf at depth 0 with no compact node; its box -/// is its vertices' extent. The memory lines follow, each labelled as a fact about this build. +/// is its vertices' extent; the second material names no triangle. The memory member follows, +/// a fact about this build, checked by the next test. #[test] -fn every_line_of_a_one_triangle_scene() { +fn every_member_of_a_one_triangle_scene() { let scene = one_triangle(); - let mut text = Vec::new(); - write_scene_block(&mut text, &scene, &scene.statistics().expect("counts")).expect("writes"); - let want = "\ -scene.triangles 1 -scene.vertices 3 -scene.triangles-smooth 0 -scene.triangles-zero-area 0 -scene.materials 2 -scene.material.0.triangles 1 -scene.material.0.albedo 0.500000 0.500000 0.500000 -scene.material.1.triangles 0 -scene.material.1.albedo 1.000000 0.000000 0.000000 -scene.bounds-min -1.000000 -1.000000 0.000000 -scene.bounds-max 1.000000 1.000000 0.000000 -light.sun present -light.sun-toward 0.000000 1.000000 0.000000 -light.sun-irradiance 1.000000 2.000000 3.000000 -light.sky 0.500000 0.500000 1.000000 -camera.position 0.000000 0.000000 4.000000 -camera.look 0.000000 0.000000 -1.000000 -camera.up 0.000000 1.000000 0.000000 -camera.tan-half-fov 1.000000 -tree.builder bunny_broadphase::build_bvh_sah -tree.layout bunny_broadphase::compact_bvh -tree.nodes 1 -tree.interior-nodes 0 -tree.leaves 1 -tree.leaf-depth-max 0 -tree.leaf-depth-total 0 -tree.leaf-depth-mean 0.00 -tree.leaf-triangles 1 -tree.leaf-triangles-min 1 -tree.leaf-triangles-max 1 -tree.leaf-sizes 1 0 0 0 0 -"; - let text = String::from_utf8(text).expect("utf-8"); - let (counts, memory) = text.split_at(text.find("memory.").expect("memory lines")); - assert_eq!(counts, want); - assert_eq!(memory.lines().count(), 8, "{memory}"); - assert!(memory.lines().all(|line| line.ends_with(MEMORY_NOTE)), "{memory}"); + let want = format!( + concat!( + r#"{{"schema":"lumen-message/1","type":"scene_statistics","scene":"a-name/1","#, + r#""scene_content":"{}","integrator":"lumen-diffuse-path/1","#, + r#""triangles":1,"vertices":3,"triangles_smooth":0,"triangles_zero_area":0,"#, + r#""material_triangles":[1,0],"#, + r#""material_albedo":[["0.500000","0.500000","0.500000"],["1.000000","0.000000","0.000000"]],"#, + r#""bounds_min":["-1.000000","-1.000000","0.000000"],"#, + r#""bounds_max":["1.000000","1.000000","0.000000"],"#, + r#""light":{{"sun":{{"toward":["0.000000","1.000000","0.000000"],"#, + r#""irradiance":["1.000000","2.000000","3.000000"]}},"#, + r#""sky":["0.500000","0.500000","1.000000"]}},"#, + r#""camera":{{"position":["0.000000","0.000000","4.000000"],"#, + r#""look":["0.000000","0.000000","-1.000000"],"up":["0.000000","1.000000","0.000000"],"#, + r#""tan_half_fov":"1.000000"}},"#, + r#""tree":{{"builder":"bunny_broadphase::build_bvh_sah","#, + r#""layout":"bunny_broadphase::compact_bvh","nodes":1,"interior_nodes":0,"leaves":1,"#, + r#""leaf_depth_max":0,"leaf_depth_total":0,"leaf_triangles":1,"#, + r#""leaf_triangles_min":1,"leaf_triangles_max":1,"leaf_sizes":[1,0,0,0,0]}},"#, + r#""memory":{{"# + ), + scene.content_id() + ); + let line = one_triangle_line(); + assert!(line.starts_with(&want), "{line}\nwant {want}"); } /// Oracle: the sizes the one-triangle scene's buffers have on a 64-bit target (ADR 0007's /// measurements: a `TraceTriangle` is 72 bytes, an `Option` 224; an albedo is -/// three `i64`s; an index a `u32`). Another pointer width may differ, which is why the lines are -/// information only. +/// three `i64`s; an index a `u32`). Another pointer width may differ, which is why the schema +/// marks the member information only. #[cfg(target_pointer_width = "64")] #[test] -fn the_memory_lines_of_a_one_triangle_scene_on_a_64_bit_target() { - let scene = one_triangle(); - let mut text = Vec::new(); - write_scene_block(&mut text, &scene, &scene.statistics().expect("counts")).expect("writes"); - let text = String::from_utf8(text).expect("utf-8"); - let memory: Vec<&str> = text.lines().filter(|line| line.starts_with("memory.")).collect(); - let want: Vec = "\ -memory.triangles-bytes 72 -memory.surfaces-bytes 224 -memory.vertex-normals-bytes 0 -memory.material-indices-bytes 4 -memory.materials-bytes 48 -memory.tree-nodes-bytes 0 -memory.tree-primitive-indices-bytes 4 -memory.total-bytes 352 -" - .lines() - .map(|line| format!("{line} {MEMORY_NOTE}")) - .collect(); - assert_eq!(memory, want); -} - -/// Oracle: the header is the scene's name, its content identity and its integrator, as the -/// render report prints them. -#[test] -fn the_stats_command_starts_with_the_scene_it_describes() { - let scene = one_triangle(); - let mut text = Vec::new(); - write_stats(&mut text, "a-name/1", &scene, &scene.statistics().expect("counts")) - .expect("writes"); - let text = String::from_utf8(text).expect("utf-8"); - let want = format!( - "scene a-name/1\nscene-content {}\nintegrator lumen-diffuse-path/1\nscene.triangles 1\n", - scene.content_id() +fn the_memory_of_a_one_triangle_scene_on_a_64_bit_target() { + let want = concat!( + r#""memory":{"triangles_bytes":72,"surfaces_bytes":224,"vertex_normals_bytes":0,"#, + r#""material_indices_bytes":4,"materials_bytes":48,"tree_nodes_bytes":0,"#, + r#""tree_primitive_indices_bytes":4,"total_bytes":352}}"# ); - assert!(text.starts_with(&want), "{text}"); + let line = one_triangle_line(); + assert!(line.ends_with(want), "{line}"); } -/// Oracle: a scene without a sun has one `light.sun none` line and no sun direction. +/// Oracle: a scene without a sun has `"sun":null`, and no sun direction. #[test] fn a_scene_without_a_sun_says_so() { let base = lumen::reference_scene().expect("builds"); @@ -173,115 +126,116 @@ fn a_scene_without_a_sun_says_so() { camera: base.camera(), }) .expect("builds"); - let mut text = Vec::new(); - write_scene_block(&mut text, &scene, &scene.statistics().expect("counts")).expect("writes"); - let text = String::from_utf8(text).expect("utf-8"); - assert!(text.contains("\nlight.sun none\nlight.sky "), "{text}"); - assert!(!text.contains("light.sun-toward"), "{text}"); + let line = scene_statistics("x/1", &scene, &scene.statistics().expect("counts")).to_json(); + assert!(line.contains(r#""light":{"sun":null,"sky":["#), "{line}"); + assert!(!line.contains("toward"), "{line}"); } /// The command reference, `docs/reference/cli.md`, as it is in the repository. const REFERENCE: &str = include_str!("../../../../../../docs/reference/cli.md"); -/// Whether the command reference documents `key`, a key `lumen stats` or `render --stats` -/// prints. A material's or a worker's number is written `N` there, and the memory buffers are -/// listed by name under `memory.NAME-bytes`; a traversal key is `traversal.KIND.COUNTER` with its -/// `-mean` and `-max` forms, each counter named in the table. -fn documented(key: &str) -> bool { - let parts: Vec<&str> = key.split('.').collect(); - let general: String = parts - .iter() - .map(|part| if part.bytes().all(|b| b.is_ascii_digit()) { "N" } else { part }) - .collect::>() - .join("."); - let named = |text: &str| REFERENCE.contains(&format!("`{text}`")); - match parts.as_slice() { - ["memory", buffer] => { - named("memory.NAME-bytes") && named(buffer.strip_suffix("-bytes").unwrap_or(buffer)) +/// The section of the command reference about messages of type `kind`: from its heading, +/// ``### `kind` ``, to the next heading. +fn section(kind: &str) -> &'static str { + let heading = format!("### `{kind}`\n"); + let at = REFERENCE.find(&heading).unwrap_or_else(|| panic!("no section for {kind}")); + let rest = &REFERENCE[at + heading.len()..]; + &rest[..rest.find("\n#").unwrap_or(rest.len())] +} + +/// Every member path of `object`: its keys, a nested object's keys after a dot, and the keys of +/// an array's objects after `[].`. +fn paths(object: &Object, prefix: &str, out: &mut Vec) { + for (key, value) in object.members() { + let path = format!("{prefix}{key}"); + match value { + Value::Object(inner) => paths(inner, &format!("{path}."), out), + Value::Array(items) => { + for item in items { + if let Value::Object(inner) = item { + paths(inner, &format!("{path}[]."), out); + } + } + } + _ => {} } - ["run", "worker", _, field] => named(&general) || named(&format!(".{field}")), - ["traversal", _, "peak-stack"] => named("traversal.KIND.peak-stack"), - ["traversal", _, field] => { - let (counter, form) = field - .strip_suffix("-mean") - .map(|counter| (counter, "traversal.KIND.COUNTER-mean")) - .or_else(|| field.strip_suffix("-max").map(|c| (c, "traversal.KIND.COUNTER-max"))) - .unwrap_or((field, "traversal.KIND.COUNTER")); - named(form) && named(counter) + out.push(path); + } +} + +/// Whether the section for messages of type `kind` documents `path`. A traversal member is +/// `KIND.COUNTER` there, with `KIND` and every counter named, and its maximum `COUNTER_max`. +fn documented(kind: &str, path: &str) -> bool { + let text = section(kind); + let named = |name: &str| text.contains(&format!("`{name}`")); + if matches!(path, "schema" | "type") { + return true; + } + match path.split_once('.') { + Some((ray, counter)) if kind == "traversal_statistics" => { + named(ray) && (named(counter) || named(counter.trim_end_matches("_max"))) } - _ => named(&general), + _ => named(path), } } -/// Oracle: the command reference's key tables. Every key the statistics blocks print, for a -/// scene with a sun, two materials, a rendered run on two workers and the traversal lines (whose -/// keys do not depend on the counts), is documented there. -/// Witness count: the keys checked, more than the 31 the scene block alone prints. +/// Oracle: the command reference's member tables. Every member path the statistics messages +/// print, for a scene with a sun, two materials, a rendered run on two workers and the +/// traversal message, is documented in its message's section. +/// Witness count: the paths checked, more than the 40 the scene message alone holds. #[test] -fn every_printed_key_is_in_the_command_reference() { +fn every_printed_member_is_in_the_command_reference() { let scene = one_triangle(); let size = lumen::ImageSize::new(4, 3).expect("size"); let settings = lumen::RenderSettings::new(2, 0).expect("settings"); let schedule = lumen::Schedule::new(2, lumen::DEFAULT_BAND_ROWS).expect("schedule"); let (render, run) = lumen::render_traced_with_run(&scene, &scene, size, settings, schedule).expect("renders"); - let rays = render.statistics.outcomes; - let mut text = Vec::new(); - write_stats(&mut text, "a-name/1", &scene, &scene.statistics().expect("counts")) - .and_then(|()| write_rays(&mut text, &render.statistics, settings)) - .and_then(|()| write_traversal(&mut text, &lumen::TraversalStatistics::default(), &rays)) - .and_then(|()| write_run(&mut text, &run)) - .expect("writes"); - let text = String::from_utf8(text).expect("utf-8"); - let keys: Vec<&str> = text.lines().filter_map(|line| line.split(' ').next()).collect(); - let missing: Vec<&&str> = keys.iter().filter(|key| !documented(key)).collect(); - assert!(missing.is_empty(), "not in docs/reference/cli.md: {missing:?}"); - assert!(keys.len() > 31, "only {} keys checked", keys.len()); + let messages = [ + ("scene_statistics", scene_statistics("a/1", &scene, &scene.statistics().expect("counts"))), + ("ray_statistics", ray_statistics(&render.statistics, settings)), + ("traversal_statistics", traversal_statistics(&lumen::TraversalStatistics::default())), + ("run_statistics", run_statistics(&run)), + ]; + let mut checked = 0; + for (kind, message) in &messages { + let mut found = Vec::new(); + paths(message, "", &mut found); + let missing: Vec<&String> = found.iter().filter(|path| !documented(kind, path)).collect(); + assert!(missing.is_empty(), "{kind}: not in docs/reference/cli.md: {missing:?}"); + checked += found.len(); + } + assert!(checked > 40, "only {checked} members checked"); } -/// Oracle: the lines, written by hand from the values set. Camera rays: 3, whose box tests total -/// 10 (mean 3.33, most 5), leaf visits 2 (0.67, 1), peak stack 4; the other counters and kinds are -/// zero, and a kind with no rays has a mean of 0.00. Distinct values per counter, so a counter -/// printed under another's key, or a total printed as the most, is seen. +/// Oracle: the line, written by hand from the values set. Camera rays: box tests total 10 (most +/// 5), leaf visits 2 (most 1), peak stack 4; the other counters and kinds are zero. Distinct +/// values per counter, so a counter written under another's name, or a total written as the +/// most, is seen. #[test] -fn the_traversal_lines_of_known_counts() { +fn the_traversal_line_of_known_counts() { let mut traversal = lumen::TraversalStatistics::default(); let camera = &mut traversal.camera; (camera.total.box_tests, camera.most.box_tests) = (10, 5); (camera.total.leaf_visits, camera.most.leaf_visits) = (2, 1); camera.total.peak_stack = 4; - let mut rays = lumen::RayOutcomes::default(); - (rays.camera_hits, rays.camera_misses) = (2, 1); - let mut text = Vec::new(); - write_traversal(&mut text, &traversal, &rays).expect("writes"); - let text = String::from_utf8(text).expect("utf-8"); - let lines: Vec<&str> = text.lines().collect(); - assert_eq!(lines.len(), 3 * 19); - assert_eq!( - lines[..19], - [ - "traversal.camera.box-tests 10", - "traversal.camera.box-tests-mean 3.33", - "traversal.camera.box-tests-max 5", - "traversal.camera.box-entries 0", - "traversal.camera.box-entries-mean 0.00", - "traversal.camera.box-entries-max 0", - "traversal.camera.popped-skipped 0", - "traversal.camera.popped-skipped-mean 0.00", - "traversal.camera.popped-skipped-max 0", - "traversal.camera.interior-visits 0", - "traversal.camera.interior-visits-mean 0.00", - "traversal.camera.interior-visits-max 0", - "traversal.camera.leaf-visits 2", - "traversal.camera.leaf-visits-mean 0.67", - "traversal.camera.leaf-visits-max 1", - "traversal.camera.primitive-tests 0", - "traversal.camera.primitive-tests-mean 0.00", - "traversal.camera.primitive-tests-max 0", - "traversal.camera.peak-stack 4", - ] + traversal.shadow.total.primitive_tests = 7; + let zero = concat!( + r#"{"box_tests":0,"box_entries":0,"popped_skipped":0,"interior_visits":0,"#, + r#""leaf_visits":0,"primitive_tests":0,"box_tests_max":0,"box_entries_max":0,"#, + r#""popped_skipped_max":0,"interior_visits_max":0,"leaf_visits_max":0,"#, + r#""primitive_tests_max":0,"peak_stack":0}"# + ); + let want = format!( + concat!( + r#"{{"schema":"lumen-message/1","type":"traversal_statistics","#, + r#""camera":{{"box_tests":10,"box_entries":0,"popped_skipped":0,"interior_visits":0,"#, + r#""leaf_visits":2,"primitive_tests":0,"box_tests_max":5,"box_entries_max":0,"#, + r#""popped_skipped_max":0,"interior_visits_max":0,"leaf_visits_max":1,"#, + r#""primitive_tests_max":0,"peak_stack":4}},"bounce":{},"shadow":{}}}"# + ), + zero, + zero.replace(r#""primitive_tests":0"#, r#""primitive_tests":7"#) ); - assert_eq!(lines[19], "traversal.bounce.box-tests 0"); - assert_eq!(lines[38], "traversal.shadow.box-tests 0"); - assert_eq!(lines[56], "traversal.shadow.peak-stack 0"); + assert_eq!(traversal_statistics(&traversal).to_json(), want); } diff --git a/crates/lumen/src/bin/lumen/stats/traversal.rs b/crates/lumen/src/bin/lumen/stats/traversal.rs index 038f92e..a584e52 100644 --- a/crates/lumen/src/bin/lumen/stats/traversal.rs +++ b/crates/lumen/src/bin/lumen/stats/traversal.rs @@ -1,55 +1,40 @@ -//! The traversal lines of `render --stats`: per kind of ray, Bunny's traversal counts in all, per -//! ray on average and at most (ADR 0008). - -use std::io::{self, Write}; +//! The `traversal_statistics` message of `render --stats`: per kind of ray, Bunny's traversal +//! counts in all and at most (ADR 0008). use bunny_broadphase::TraversalCounts; -use lumen::{RayOutcomes, TraversalStatistics, TraversalWork}; +use lumen::{TraversalStatistics, TraversalWork}; -use super::Ratio; +use crate::json::Object; +use crate::messages::message; /// How a counter is read from Bunny's record. type Counter = fn(&TraversalCounts) -> u64; -/// The counters, as their keys name them, and how each is read. -const COUNTERS: [(&str, Counter); 6] = [ - ("box-tests", |c| c.box_tests), - ("box-entries", |c| c.box_entries), - ("popped-skipped", |c| c.popped_skipped), - ("interior-visits", |c| c.interior_visits), - ("leaf-visits", |c| c.leaf_visits), - ("primitive-tests", |c| c.primitive_tests), +/// The counters, as their members name them, the most any one ray took as the same name with +/// `_max`, and how each is read. +const COUNTERS: [(&str, &str, Counter); 6] = [ + ("box_tests", "box_tests_max", |c| c.box_tests), + ("box_entries", "box_entries_max", |c| c.box_entries), + ("popped_skipped", "popped_skipped_max", |c| c.popped_skipped), + ("interior_visits", "interior_visits_max", |c| c.interior_visits), + ("leaf_visits", "leaf_visits_max", |c| c.leaf_visits), + ("primitive_tests", "primitive_tests_max", |c| c.primitive_tests), ]; -/// What Bunny's traversals did (`render --stats`), after the ray lines: for camera, bounce and -/// shadow rays in turn, each counter's total, its mean per ray of that kind (two places, rounded -/// to nearest, ties up) and the most any one ray took, then the deepest stack of any ray. Every -/// value is a function of the scene, the size and the settings. -pub(crate) fn write_traversal( - out: &mut impl Write, - traversal: &TraversalStatistics, - rays: &RayOutcomes, -) -> io::Result<()> { - for (kind, work, count) in [ - ("camera", &traversal.camera, rays.camera()), - ("bounce", &traversal.bounce, rays.bounce()), - ("shadow", &traversal.shadow, rays.shadow()), - ] { - write_kind(out, kind, work, count)?; - } - Ok(()) +/// What Bunny's traversals did: for camera, bounce and shadow rays, each counter's total, then +/// the most any one ray took of each, then the deepest stack of any ray. The mean per ray is +/// the total over the kind's ray count in `ray_statistics`. Every value is a function of the +/// scene, the size and the settings. +pub(crate) fn traversal_statistics(traversal: &TraversalStatistics) -> Object { + message("traversal_statistics") + .with("camera", kind(&traversal.camera)) + .with("bounce", kind(&traversal.bounce)) + .with("shadow", kind(&traversal.shadow)) } -fn write_kind(out: &mut impl Write, kind: &str, work: &TraversalWork, rays: u64) -> io::Result<()> { - for (name, read) in COUNTERS { - let total = read(&work.total); - writeln!(out, "traversal.{kind}.{name} {total}")?; - writeln!( - out, - "traversal.{kind}.{name}-mean {}", - Ratio(u128::from(total), u128::from(rays)) - )?; - writeln!(out, "traversal.{kind}.{name}-max {}", read(&work.most))?; - } - writeln!(out, "traversal.{kind}.peak-stack {}", work.total.peak_stack) +fn kind(work: &TraversalWork) -> Object { + let totals = + COUNTERS.iter().fold(Object::new(), |o, (name, _, read)| o.with(*name, read(&work.total))); + let most = COUNTERS.iter().fold(totals, |o, (_, max, read)| o.with(*max, read(&work.most))); + most.with("peak_stack", work.total.peak_stack) } diff --git a/crates/lumen/tests/cli.rs b/crates/lumen/tests/cli.rs index da551a9..2413fd3 100644 --- a/crates/lumen/tests/cli.rs +++ b/crates/lumen/tests/cli.rs @@ -9,8 +9,8 @@ clippy::disallowed_methods, clippy::disallowed_types, clippy::disallowed_macros, - reason = "std-fs, std-process, std-env, float-type: runs the command in a scratch directory and \ - reads its files and timing lines; a test outside the deterministic core" + reason = "std-fs, std-process, std-env: runs the command in a scratch directory and reads its \ + files; a test outside the deterministic core" )] use std::ops::Deref; @@ -21,6 +21,8 @@ use std::time::{Duration, Instant}; use lumen::{render_reference, write_png, BuiltinScene, RenderSettings}; mod golden; +mod json; +use json::{messages, one, types, Json}; use golden::{ GOLDEN_96X54_4SPP, GOLDEN_CANYON_96X54_4SPP, GOLDEN_CANYON_CONTENT, GOLDEN_FIXED_POINT_96X54_4SPP, GOLDEN_FIXED_POINT_CONTENT, GOLDEN_REFERENCE_CONTENT, @@ -56,8 +58,10 @@ impl Scratch { command } + /// Runs the command with `args`. Whatever it wrote to standard output is checked line by + /// line against `lumen-message/1` ([`messages`]), so every run of every test checks it. fn lumen(&self, args: &[&str]) -> Output { - self.command().args(args).output().expect("lumen runs") + checked(self.command().args(args).output().expect("lumen runs")) } fn is_empty(&self) -> bool { @@ -83,12 +87,21 @@ fn path_str(path: &Path) -> &str { path.to_str().expect("utf-8 path") } -/// The value of the line `key value...` in the command's output. -fn field<'a>(stdout: &'a str, key: &str) -> &'a str { - stdout - .lines() - .find_map(|line| line.strip_prefix(key).and_then(|rest| rest.strip_prefix(' '))) - .unwrap_or_else(|| panic!("no {key} line in {stdout:?}")) +/// `output`, once its standard output has been checked by [`messages`]. +fn checked(output: Output) -> Output { + messages(&text(&output.stdout)); + output +} + +/// The messages of a run that succeeded, parsed and checked. +fn succeeded(output: &Output) -> Vec { + assert!(output.status.success(), "{}", text(&output.stderr)); + messages(&text(&output.stdout)) +} + +/// A string member as a `Json` value, for comparing a whole member. +fn string(text: &str) -> Json { + Json::String(text.to_owned()) } fn assert_refused(output: &Output, code: i32, message: &str) { @@ -99,7 +112,7 @@ fn assert_refused(output: &Output, code: i32, message: &str) { assert!(output.stdout.is_empty()); } -/// The arguments of a small render, the report's fields and the file it writes. +/// The arguments of a small render and the file it writes. fn small_render<'a>(out: &'a str, extra: &[&'a str]) -> Vec<&'a str> { let mut args = vec!["render", "--width", "40", "--height", "24", "--samples", "2", "--seed", "5"]; @@ -108,35 +121,51 @@ fn small_render<'a>(out: &'a str, extra: &[&'a str]) -> Vec<&'a str> { args } +/// A render prints `provenance`, `result` and `timings`, in that order and nothing else. #[test] -fn the_report_names_the_scene_the_settings_and_the_work() { +fn a_render_prints_its_provenance_result_and_timings() { let dir = Scratch::new("report"); let out = dir.file("a.png"); - let output = dir.lumen(&small_render(path_str(&out), &[])); - assert!(output.status.success(), "{}", text(&output.stderr)); - let stdout = text(&output.stdout); - assert_eq!(field(&stdout, "scene"), "lumen-reference-scene/4"); - assert_eq!(field(&stdout, "integrator"), "lumen-diffuse-path/1"); - assert_eq!(field(&stdout, "shading"), "bunny-diffuse-shading/1"); - assert_eq!(field(&stdout, "sampler"), "bunny-sobol-owen/1"); - assert_eq!(field(&stdout, "tone"), "bunny-tone-srgb/1"); - assert_eq!(field(&stdout, "encoding"), "bunny-rgba8-opaque/1"); - assert_eq!(field(&stdout, "bunny"), lumen::BUNNY_REV); - assert_eq!(field(&stdout, "size"), "40x24"); - assert_eq!(field(&stdout, "samples"), "2"); - assert_eq!(field(&stdout, "seed"), "5"); - assert_eq!(field(&stdout, "bounces"), "1"); - assert_eq!(field(&stdout, "pixels"), "960"); - assert_eq!(field(&stdout, "band-rows"), "1"); + let printed = succeeded(&dir.lumen(&small_render(path_str(&out), &[]))); + assert_eq!(types(&printed), ["provenance", "result", "timings"]); +} + +#[test] +fn the_provenance_names_the_scene_the_settings_and_the_work() { + let dir = Scratch::new("provenance"); + let out = dir.file("a.png"); + let printed = succeeded(&dir.lumen(&small_render(path_str(&out), &[]))); + let provenance = one(&printed, "provenance"); + assert_eq!(provenance.str("scene"), "lumen-reference-scene/4"); + assert_eq!(provenance.str("integrator"), "lumen-diffuse-path/1"); + assert_eq!(provenance.str("shading"), "bunny-diffuse-shading/1"); + assert_eq!(provenance.str("sampler"), "bunny-sobol-owen/1"); + assert_eq!(provenance.str("tone"), "bunny-tone-srgb/1"); + assert_eq!(provenance.str("encoding"), "bunny-rgba8-opaque/1"); + assert_eq!(provenance.str("bunny"), lumen::BUNNY_REV); + assert_eq!((provenance.int("width"), provenance.int("height")), (40, 24)); + assert_eq!(provenance.int("samples"), 2); + assert_eq!(provenance.int("seed"), 5); + assert_eq!(provenance.int("bounces"), 1); + assert_eq!(provenance.int("pixels"), 960); + let result = one(&printed, "result"); + assert_eq!((result.int("width"), result.int("height")), (40, 24)); + assert_eq!(result.int("band_rows"), 1); // As many workers as asked for, but never more than the 24 one-row bands. - let asked: u32 = field(&stdout, "threads-asked").parse().expect("a count"); - assert_eq!(field(&stdout, "threads").parse::(), Ok(asked.min(24))); + let asked = result.int("threads_asked"); + assert_eq!(result.int("threads"), asked.min(24)); } +/// Oracle: this test's own clock, read around the run, and the sum of the parts. The four parts +/// are consecutive spans of one clock that add up to the total exactly, and each is rounded down +/// to a whole microsecond, losing less than 1 us; so their sum is at most `total_us` and, being +/// an integer above `total_us - 4`, at least `total_us - 3`. The total cannot exceed the run's +/// wall time seen from outside. #[test] -fn the_report_times_every_stage() { +fn the_timings_cover_every_stage_in_microseconds() { let dir = Scratch::new("timings"); let out = dir.file("a.png"); + let started = Instant::now(); let output = dir.lumen(&[ "render", "--width", @@ -148,13 +177,13 @@ fn the_report_times_every_stage() { "--out", path_str(&out), ]); - assert!(output.status.success(), "{}", text(&output.stderr)); - let stdout = text(&output.stdout); - for timing in ["scene", "render", "hash", "png", "total"] { - let line = field(&stdout, &format!("{timing}-seconds")); - let seconds: f64 = line.split(' ').next().expect("value").parse().expect("number"); - assert!(seconds >= 0.0, "{timing}: {line}"); - } + let printed = succeeded(&output); + let outside = started.elapsed().as_micros(); + let timings = one(&printed, "timings"); + let parts: i128 = ["scene_us", "render_us", "hash_us", "png_us"].map(|p| timings.int(p)).iter().sum(); + let total = timings.int("total_us"); + assert!(parts <= total && total - parts <= 3, "{timings:?}"); + assert!(u128::try_from(total).expect("non-negative") <= outside, "{total} > {outside}"); } #[test] @@ -169,25 +198,25 @@ fn two_processes_write_the_same_file_and_print_the_same_hash() { }) .into(); assert_eq!(std::fs::read(&a).expect("a"), std::fs::read(&b).expect("b")); - assert_eq!(field(&outputs[0], "image"), field(&outputs[1], "image")); - assert_eq!(field(&outputs[0], "rays"), field(&outputs[1], "rays")); + let results: Vec> = outputs.iter().map(|stdout| messages(stdout)).collect(); + let (first, second) = (one(&results[0], "result"), one(&results[1], "result")); + assert_eq!(first.at("image"), second.at("image")); + assert_eq!(first.at("rays"), second.at("rays")); } #[test] fn the_printed_hash_ray_count_and_file_are_the_librarys() { let dir = Scratch::new("library-agrees"); let out = dir.file("a.png"); - let output = dir.lumen(&small_render(path_str(&out), &[])); - assert!(output.status.success(), "{}", text(&output.stderr)); - let stdout = text(&output.stdout); + let printed = succeeded(&dir.lumen(&small_render(path_str(&out), &[]))); + let result = one(&printed, "result"); let render = render_reference(40, 24, RenderSettings::new(2, 5).expect("valid")).expect("renders"); - assert_eq!(field(&stdout, "image"), render.image.hash()); + assert_eq!(result.str("image"), render.image.hash()); let r = render.rays; - assert_eq!( - field(&stdout, "rays"), - format!("{} (closest {}, shadow {})", r.total(), r.closest, r.shadow) - ); + assert_eq!(result.int("rays.total"), i128::from(r.total())); + assert_eq!(result.int("rays.closest"), i128::from(r.closest)); + assert_eq!(result.int("rays.shadow"), i128::from(r.shadow)); let mut expected = Vec::new(); write_png(&mut expected, &render.image).expect("writes to memory"); assert_eq!(std::fs::read(&out).expect("the file"), expected); @@ -197,16 +226,19 @@ fn the_printed_hash_ray_count_and_file_are_the_librarys() { fn help_prints_the_usage() { let dir = Scratch::new("help"); let help = dir.lumen(&["--help"]); - assert!(help.status.success()); - assert!(text(&help.stdout).starts_with("usage: lumen render")); + let printed = succeeded(&help); + assert_eq!(types(&printed), ["help"]); + assert!(printed[0].str("usage").starts_with("usage: lumen render")); } #[test] fn version_prints_the_package_version() { let dir = Scratch::new("version"); let version = dir.lumen(&["--version"]); - assert!(version.status.success()); - assert!(text(&version.stdout).starts_with(&format!("lumen {}", env!("CARGO_PKG_VERSION")))); + let printed = succeeded(&version); + assert_eq!(types(&printed), ["version"]); + assert_eq!(printed[0].str("lumen"), env!("CARGO_PKG_VERSION")); + assert_eq!(printed[0].str("bunny"), lumen::BUNNY_REV); } /// Each refusal exits with code 2 and its message, prints no panic and no report, and leaves @@ -264,9 +296,9 @@ fn bad_sizes_are_refused_before_anything_is_written() { } } -/// The report's lines that do not depend on the clock. -fn stable_lines(stdout: &str) -> Vec<&str> { - stdout.lines().filter(|line| !line.contains("information only")).collect() +/// The messages that do not depend on the clock: every one but `timings`. +fn stable_messages(stdout: &[u8]) -> Vec { + messages(&text(stdout)).into_iter().filter(|m| m.str("type") != "timings").collect() } /// A value that reads as an option is refused for every option that takes a value, writes @@ -292,8 +324,7 @@ fn an_option_looking_value_is_refused_unless_written_with_an_equals_sign() { let refused = dir.lumen(&["render", "--out", "--width"]); assert!(text(&refused.stderr).contains("write --out=--width"), "{}", text(&refused.stderr)); let output = dir.lumen(&["render", "--width=8", "--height=4", "--samples=1", "--out=--width"]); - assert!(output.status.success(), "{}", text(&output.stderr)); - assert_eq!(field(&text(&output.stdout), "png").split(' ').next(), Some("--width")); + assert_eq!(one(&succeeded(&output), "result").str("png.path"), "--width"); assert!(dir.file("--width").is_file()); // A negative number is a value, so a number option refuses it as a number. assert_refused(&dir.lumen(&["render", "--height", "-3"]), 2, "--height needs a whole number"); @@ -334,24 +365,28 @@ fn leading_zeros_mean_the_same_number_for_every_numeric_option() { "003", ]); assert!(plain.status.success() && zeros.status.success()); - let (plain, zeros) = (text(&plain.stdout), text(&zeros.stdout)); - assert_eq!(stable_lines(&plain), stable_lines(&zeros)); - assert_eq!(field(&zeros, "size"), "24x16"); + let (plain, zeros) = (stable_messages(&plain.stdout), stable_messages(&zeros.stdout)); + assert_eq!(plain, zeros); + let provenance = one(&zeros, "provenance"); + assert_eq!((provenance.int("width"), provenance.int("height")), (24, 16)); + assert_eq!((provenance.int("samples"), provenance.int("seed")), (2, 7)); + let result = one(&zeros, "result"); + assert_eq!((result.int("threads_asked"), result.int("band_rows")), (2, 3)); // The padded zero is still zero, and a padded refused value is refused. assert_refused(&dir.lumen(&["render", "--threads", "000"]), 2, "threads must be at least 1"); assert_refused(&dir.lumen(&["render", "--samples", "0003"]), 2, "must be a power of two"); } -/// The report's byte count is what the file holds. +/// The byte count in `result` is what the file holds, and the path is the one given. #[test] fn the_reported_byte_count_is_the_files_length() { let dir = Scratch::new("byte-count"); let out = dir.file("a.png"); - let output = dir.lumen(&small_render(path_str(&out), &[])); - assert!(output.status.success(), "{}", text(&output.stderr)); - let png = field(&text(&output.stdout), "png").to_owned(); + let printed = succeeded(&dir.lumen(&small_render(path_str(&out), &[]))); + let png = one(&printed, "result").at("png"); let length = std::fs::metadata(&out).expect("the file").len(); - assert_eq!(png, format!("{} ({length} bytes)", out.display())); + assert_eq!(png.str("path"), path_str(&out)); + assert_eq!(png.int("bytes"), i128::from(length)); } #[test] @@ -514,16 +549,15 @@ mod non_unicode { } #[test] -fn without_out_no_file_is_written_and_png_is_none() { +fn without_out_no_file_is_written_and_png_is_null() { let dir = Scratch::new("no-out"); let output = dir.lumen(&["render", "--width", "8", "--height", "4", "--samples", "1"]); - assert!(output.status.success(), "{}", text(&output.stderr)); - assert_eq!(field(&text(&output.stdout), "png"), "none"); + assert_eq!(one(&succeeded(&output), "result").at("png"), &Json::Null); assert!(dir.is_empty(), "a file was written"); } #[test] -fn the_report_names_the_threads_and_the_band_asked_for() { +fn the_result_names_the_threads_and_the_band_asked_for() { let dir = Scratch::new("threads-report"); for (threads, rows) in [("1", "32"), ("3", "5"), ("8", "1"), ("2", "7")] { let output = dir.lumen(&[ @@ -539,11 +573,12 @@ fn the_report_names_the_threads_and_the_band_asked_for() { "--band-rows", rows, ]); - assert!(output.status.success(), "{}", text(&output.stderr)); - let stdout = text(&output.stdout); - assert_eq!(field(&stdout, "threads-asked"), threads); - assert_eq!(field(&stdout, "threads"), threads); - assert_eq!(field(&stdout, "band-rows"), rows); + let printed = succeeded(&output); + let result = one(&printed, "result"); + let number = |text: &str| text.parse::().expect("a count"); + assert_eq!(result.int("threads_asked"), number(threads)); + assert_eq!(result.int("threads"), number(threads)); + assert_eq!(result.int("band_rows"), number(rows)); } } @@ -568,9 +603,9 @@ fn the_hash_and_ray_count_are_the_same_at_every_thread_count_and_band_height() { "--band-rows", rows, ]); - assert!(output.status.success(), "{}", text(&output.stderr)); - let stdout = text(&output.stdout); - seen.push((field(&stdout, "image").to_owned(), field(&stdout, "rays").to_owned())); + let printed = succeeded(&output); + let result = one(&printed, "result"); + seen.push((result.str("image").to_owned(), result.at("rays").clone())); } let render = render_reference(40, 24, RenderSettings::new(2, 5).expect("valid")).expect("renders"); @@ -578,12 +613,10 @@ fn the_hash_and_ray_count_are_the_same_at_every_thread_count_and_band_height() { assert!(seen.iter().all(|(_, rays)| *rays == seen[0].1), "{seen:?}"); } -fn render_scene(dir: &Scratch, size: [&str; 2], extra: &[&str]) -> String { +fn render_scene(dir: &Scratch, size: [&str; 2], extra: &[&str]) -> Vec { let mut args = vec!["render", "--width", size[0], "--height", size[1], "--samples", "4"]; args.extend_from_slice(extra); - let output = dir.lumen(&args); - assert!(output.status.success(), "{}", text(&output.stderr)); - text(&output.stdout) + succeeded(&dir.lumen(&args)) } /// `--scene` names the scene: the reported identity is that scene's. @@ -591,12 +624,12 @@ fn render_scene(dir: &Scratch, size: [&str; 2], extra: &[&str]) -> String { fn each_scene_reports_its_own_identity() { let dir = Scratch::new("scene-identity"); for scene in BuiltinScene::ALL { - let stdout = render_scene(&dir, ["8", "4"], &["--scene", scene.name()]); - assert_eq!(field(&stdout, "scene"), scene.id()); + let printed = render_scene(&dir, ["8", "4"], &["--scene", scene.name()]); + assert_eq!(one(&printed, "provenance").str("scene"), scene.id()); } } -/// The `scene-content` line (the last provenance line, after `bounces`) is the scene's golden +/// The provenance's `scene_content` (its last member, after `bounces`) is the scene's golden /// content identity, and the image is the one the library's golden hash records for it (96 by /// 54 pixels, 4 samples, seed 0). #[test] @@ -608,21 +641,23 @@ fn each_scene_renders_its_golden_image() { BuiltinScene::Canyon => (GOLDEN_CANYON_96X54_4SPP, GOLDEN_CANYON_CONTENT), }; for scene in BuiltinScene::ALL { - let stdout = render_scene(&dir, ["96", "54"], &["--scene", scene.name()]); + let printed = render_scene(&dir, ["96", "54"], &["--scene", scene.name()]); let (image, content) = golden(scene); - assert_eq!(field(&stdout, "image"), image, "{}", scene.name()); - let after_bounces = stdout.lines().skip_while(|line| *line != "bounces 1").nth(1); - assert_eq!(after_bounces, Some(format!("scene-content {content}").as_str())); + assert_eq!(one(&printed, "result").str("image"), image, "{}", scene.name()); + let provenance = one(&printed, "provenance"); + assert_eq!(provenance.keys().last(), Some(&"scene_content")); + assert_eq!(provenance.str("scene_content"), content, "{}", scene.name()); } } #[test] fn without_scene_the_reference_scene_is_rendered() { let dir = Scratch::new("default-scene"); - let stdout = render_scene(&dir, ["96", "54"], &[]); - assert_eq!(field(&stdout, "scene"), BuiltinScene::Reference.id()); - assert_eq!(field(&stdout, "scene-content"), GOLDEN_REFERENCE_CONTENT); - assert_eq!(field(&stdout, "image"), GOLDEN_96X54_4SPP); + let printed = render_scene(&dir, ["96", "54"], &[]); + let provenance = one(&printed, "provenance"); + assert_eq!(provenance.str("scene"), BuiltinScene::Reference.id()); + assert_eq!(provenance.str("scene_content"), GOLDEN_REFERENCE_CONTENT); + assert_eq!(one(&printed, "result").str("image"), GOLDEN_96X54_4SPP); } #[test] @@ -640,7 +675,8 @@ fn an_unknown_scene_is_a_usage_error_listing_the_scenes() { #[test] fn help_lists_the_scenes() { let dir = Scratch::new("help-scenes"); - let help = text(&dir.lumen(&["--help"]).stdout); + let printed = succeeded(&dir.lumen(&["--help"])); + let help = one(&printed, "help").str("usage"); for scene in BuiltinScene::ALL { assert!(help.contains(scene.name()), "{}", scene.name()); } diff --git a/crates/lumen/tests/json/mod.rs b/crates/lumen/tests/json/mod.rs new file mode 100644 index 0000000..bcadd97 --- /dev/null +++ b/crates/lumen/tests/json/mod.rs @@ -0,0 +1,393 @@ +//! A JSON parser and a JSON Schema validator for the tests, written from RFC 8259 and JSON Schema +//! 2020-12 and sharing no code with the command's writer (`src/bin/lumen/json.rs`), so that a +//! message the writer gets wrong is not read back the same wrong way. +//! +//! The parser takes the whole grammar of RFC 8259: any whitespace, every escape including +//! surrogate pairs, and numbers with fractions and exponents (kept as text, since the messages +//! hold none). It refuses what RFC 8259 refuses, and also a repeated key in one object, which +//! the RFC allows but no message may have. +//! +//! The validator takes the subset of JSON Schema 2020-12 that `schemas/lumen-message-1.schema.json` +//! uses, and refuses a schema with any other keyword, so the schema cannot use a keyword this +//! validator would silently skip. The subset: `type` (one name or a list), `const`, `enum`, +//! `properties`, `required`, `additionalProperties` (`true` or `false`), `items`, `minItems`, +//! `maxItems`, `minimum`, `maximum`, `minLength`, `maxLength`, `allOf`, `if` with `then`, +//! `$ref` to `#/$defs/NAME`, and the annotations `$schema`, `$id`, `$defs`, `title` and +//! `description`. `integer` means a number written without a fraction or an exponent, which is +//! stricter than JSON Schema (which also counts `1.0`), and is how the command writes them. + +#![allow(dead_code, reason = "each test crate that includes this module uses only what it needs")] + +/// A parsed JSON value. An object keeps its members in order. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) enum Json { + Null, + Bool(bool), + /// A number written as an integer, if it fits an `i128`. + Integer(i128), + /// Any other number, as written. + Number(String), + String(String), + Array(Vec), + Object(Vec<(String, Json)>), +} + +impl Json { + /// The member `key` of an object, or `None`. + pub(crate) fn get(&self, key: &str) -> Option<&Json> { + match self { + Json::Object(members) => members.iter().find(|(k, _)| k == key).map(|(_, v)| v), + _ => None, + } + } + + /// The member at `path`, keys separated by `.`; panics with the path if there is none. + pub(crate) fn at(&self, path: &str) -> &Json { + path.split('.').fold(self, |value, key| { + value.get(key).unwrap_or_else(|| panic!("no member {path:?} in {value:?}")) + }) + } + + /// The string at `path`. + pub(crate) fn str(&self, path: &str) -> &str { + match self.at(path) { + Json::String(text) => text, + other => panic!("{path}: not a string: {other:?}"), + } + } + + /// The integer at `path`. + pub(crate) fn int(&self, path: &str) -> i128 { + match self.at(path) { + Json::Integer(n) => *n, + other => panic!("{path}: not an integer: {other:?}"), + } + } + + /// The array at `path`. + pub(crate) fn array(&self, path: &str) -> &[Json] { + match self.at(path) { + Json::Array(items) => items, + other => panic!("{path}: not an array: {other:?}"), + } + } + + /// The member names of an object, in order. + pub(crate) fn keys(&self) -> Vec<&str> { + match self { + Json::Object(members) => members.iter().map(|(k, _)| k.as_str()).collect(), + _ => Vec::new(), + } + } +} + +/// Parses `text` as exactly one JSON value, with optional whitespace around it. +pub(crate) fn parse(text: &str) -> Result { + let mut parser = Parser { bytes: text.as_bytes(), at: 0 }; + parser.space(); + let value = parser.value(0)?; + parser.space(); + if parser.at != parser.bytes.len() { + return Err(format!("text after the value at byte {}", parser.at)); + } + Ok(value) +} + +struct Parser<'a> { + bytes: &'a [u8], + at: usize, +} + +/// Deeper nesting than any message has; a guard against runaway recursion. +const MAX_DEPTH: usize = 64; + +impl Parser<'_> { + fn peek(&self) -> Option { + self.bytes.get(self.at).copied() + } + + fn fail(&self, what: &str) -> Result { + Err(format!("{what} at byte {}", self.at)) + } + + fn space(&mut self) { + while matches!(self.peek(), Some(b' ' | b'\t' | b'\n' | b'\r')) { + self.at += 1; + } + } + + fn eat(&mut self, byte: u8) -> Result<(), String> { + if self.peek() == Some(byte) { + self.at += 1; + Ok(()) + } else { + self.fail(&format!("expected {:?}", char::from(byte))) + } + } + + fn literal(&mut self, word: &str, value: Json) -> Result { + if self.bytes[self.at..].starts_with(word.as_bytes()) { + self.at += word.len(); + Ok(value) + } else { + self.fail("unknown literal") + } + } + + fn value(&mut self, depth: usize) -> Result { + if depth > MAX_DEPTH { + return self.fail("too deep"); + } + match self.peek() { + Some(b'n') => self.literal("null", Json::Null), + Some(b't') => self.literal("true", Json::Bool(true)), + Some(b'f') => self.literal("false", Json::Bool(false)), + Some(b'"') => self.string().map(Json::String), + Some(b'[') => self.array(depth), + Some(b'{') => self.object(depth), + Some(b'-' | b'0'..=b'9') => self.number(), + _ => self.fail("expected a value"), + } + } + + fn array(&mut self, depth: usize) -> Result { + self.eat(b'[')?; + self.space(); + let mut items = Vec::new(); + if self.peek() == Some(b']') { + self.at += 1; + return Ok(Json::Array(items)); + } + loop { + self.space(); + items.push(self.value(depth + 1)?); + self.space(); + match self.peek() { + Some(b',') => self.at += 1, + Some(b']') => { + self.at += 1; + return Ok(Json::Array(items)); + } + _ => return self.fail("expected , or ]"), + } + } + } + + fn object(&mut self, depth: usize) -> Result { + self.eat(b'{')?; + self.space(); + let mut members: Vec<(String, Json)> = Vec::new(); + if self.peek() == Some(b'}') { + self.at += 1; + return Ok(Json::Object(members)); + } + loop { + self.space(); + if self.peek() != Some(b'"') { + return self.fail("expected a key"); + } + let key = self.string()?; + if members.iter().any(|(k, _)| *k == key) { + return self.fail(&format!("repeated key {key:?}")); + } + self.space(); + self.eat(b':')?; + self.space(); + let value = self.value(depth + 1)?; + members.push((key, value)); + self.space(); + match self.peek() { + Some(b',') => self.at += 1, + Some(b'}') => { + self.at += 1; + return Ok(Json::Object(members)); + } + _ => return self.fail("expected , or }"), + } + } + } + + fn digits(&mut self) -> usize { + let start = self.at; + while matches!(self.peek(), Some(b'0'..=b'9')) { + self.at += 1; + } + self.at - start + } + + /// `-? (0 | [1-9][0-9]*) (. [0-9]+)? ([eE] [+-]? [0-9]+)?` + fn number(&mut self) -> Result { + let start = self.at; + if self.peek() == Some(b'-') { + self.at += 1; + } + match self.peek() { + Some(b'0') => { + self.at += 1; + if matches!(self.peek(), Some(b'0'..=b'9')) { + return self.fail("leading zero"); + } + } + Some(b'1'..=b'9') => { + self.digits(); + } + _ => return self.fail("expected a digit"), + } + let mut integer = true; + if self.peek() == Some(b'.') { + self.at += 1; + integer = false; + if self.digits() == 0 { + return self.fail("expected a fraction digit"); + } + } + if matches!(self.peek(), Some(b'e' | b'E')) { + self.at += 1; + integer = false; + if matches!(self.peek(), Some(b'+' | b'-')) { + self.at += 1; + } + if self.digits() == 0 { + return self.fail("expected an exponent digit"); + } + } + let text = std::str::from_utf8(&self.bytes[start..self.at]).expect("ASCII"); + Ok(match (integer, text.parse::()) { + (true, Ok(n)) => Json::Integer(n), + _ => Json::Number(text.to_owned()), + }) + } + + fn hex4(&mut self) -> Result { + let Some(digits) = self.bytes.get(self.at..self.at + 4) else { + return self.fail("short \\u escape"); + }; + let mut value = 0; + for &d in digits { + let digit = match d { + b'0'..=b'9' => d - b'0', + b'a'..=b'f' => d - b'a' + 10, + b'A'..=b'F' => d - b'A' + 10, + _ => return self.fail("bad hex digit"), + }; + value = value * 16 + u32::from(digit); + } + self.at += 4; + Ok(value) + } + + fn string(&mut self) -> Result { + self.eat(b'"')?; + let mut out = String::new(); + loop { + let Some(byte) = self.peek() else { return self.fail("unterminated string") }; + match byte { + b'"' => { + self.at += 1; + return Ok(out); + } + b'\\' => { + self.at += 1; + let Some(escape) = self.peek() else { return self.fail("bad escape") }; + self.at += 1; + match escape { + b'"' => out.push('"'), + b'\\' => out.push('\\'), + b'/' => out.push('/'), + b'b' => out.push('\u{8}'), + b'f' => out.push('\u{c}'), + b'n' => out.push('\n'), + b'r' => out.push('\r'), + b't' => out.push('\t'), + b'u' => out.push(self.unicode_escape()?), + _ => return self.fail("unknown escape"), + } + } + 0x00..=0x1f => return self.fail("unescaped control character"), + _ => { + // One UTF-8 character: the input is a `&str`, so it is well formed. + let rest = std::str::from_utf8(&self.bytes[self.at..]).expect("utf-8"); + let c = rest.chars().next().expect("a character"); + out.push(c); + self.at += c.len_utf8(); + } + } + } + } + + /// The character of a `\uXXXX` escape, or of a surrogate pair of two. + fn unicode_escape(&mut self) -> Result { + let first = self.hex4()?; + let code = match first { + 0xd800..=0xdbff => { + if !self.bytes[self.at..].starts_with(b"\\u") { + return self.fail("lone high surrogate"); + } + self.at += 2; + let second = self.hex4()?; + if !(0xdc00..=0xdfff).contains(&second) { + return self.fail("high surrogate without a low one"); + } + 0x10000 + ((first - 0xd800) << 10) + (second - 0xdc00) + } + 0xdc00..=0xdfff => return self.fail("lone low surrogate"), + code => code, + }; + char::from_u32(code).map_or_else(|| self.fail("not a scalar value"), Ok) + } +} + +mod schema; + +pub(crate) use schema::{validate, Schema}; + +/// The committed schema of every line on standard output. +pub(crate) const MESSAGE_SCHEMA: &str = include_str!("../../../../schemas/lumen-message-1.schema.json"); + +/// The message types the command prints, written out here from ADR 0015 rather than read from +/// the schema or the command, so that a line of any other type fails. +pub(crate) const MESSAGE_TYPES: [&str; 9] = [ + "provenance", + "result", + "timings", + "scene_statistics", + "ray_statistics", + "traversal_statistics", + "run_statistics", + "help", + "version", +]; + +/// Every line of `stdout`, parsed and checked: the text is empty or ends in a line end; each +/// line is one JSON object whose `schema` is `lumen-message/1` and whose `type` is one of +/// [`MESSAGE_TYPES`]; and each validates against the committed schema. Panics on the first line +/// that does not, with the line. +pub(crate) fn messages(stdout: &str) -> Vec { + let schema = Schema::new(MESSAGE_SCHEMA).expect("the committed schema is in the subset"); + assert!(stdout.is_empty() || stdout.ends_with('\n'), "no line end at the end: {stdout:?}"); + stdout + .split_terminator('\n') + .map(|line| { + let value = parse(line).unwrap_or_else(|error| panic!("{error}: {line:?}")); + assert!(matches!(value, Json::Object(_)), "not an object: {line}"); + assert_eq!(value.get("schema"), Some(&Json::String("lumen-message/1".into())), "{line}"); + let kind = value.str("type"); + assert!(MESSAGE_TYPES.contains(&kind), "unknown type {kind:?}: {line}"); + let errors = validate(&schema, &value); + assert!(errors.is_empty(), "{line}\nbreaks the schema: {errors:#?}"); + value + }) + .collect() +} + +/// The one message of type `kind` in `messages`; panics if there is none or more than one. +pub(crate) fn one<'a>(messages: &'a [Json], kind: &str) -> &'a Json { + let found: Vec<&Json> = messages.iter().filter(|m| m.str("type") == kind).collect(); + assert_eq!(found.len(), 1, "{} messages of type {kind} in {messages:?}", found.len()); + found[0] +} + +/// The types of `messages`, in order. +pub(crate) fn types(messages: &[Json]) -> Vec<&str> { + messages.iter().map(|m| m.str("type")).collect() +} diff --git a/crates/lumen/tests/json/schema.rs b/crates/lumen/tests/json/schema.rs new file mode 100644 index 0000000..b6279d3 --- /dev/null +++ b/crates/lumen/tests/json/schema.rs @@ -0,0 +1,235 @@ +//! The JSON Schema subset validator (the keywords are listed in the parent module's comment). + +use super::{parse, Json}; + +/// A schema document, checked to use only the supported keywords. +pub(crate) struct Schema { + root: Json, +} + +/// The keywords this validator applies. +const APPLIED: [&str; 18] = [ + "type", + "const", + "enum", + "properties", + "required", + "additionalProperties", + "items", + "minItems", + "maxItems", + "minimum", + "maximum", + "minLength", + "maxLength", + "allOf", + "if", + "then", + "$ref", + "$defs", +]; + +/// The annotations it reads past. +const ANNOTATIONS: [&str; 4] = ["$schema", "$id", "title", "description"]; + +impl Schema { + /// Parses `text` and checks that every subschema uses only the supported keywords. + pub(crate) fn new(text: &str) -> Result { + let root = parse(text)?; + check_keywords(&root, "#")?; + Ok(Self { root }) + } + + /// The schema document. + pub(crate) fn document(&self) -> &Json { + &self.root + } +} + +fn check_keywords(schema: &Json, at: &str) -> Result<(), String> { + let Json::Object(members) = schema else { + return match schema { + Json::Bool(_) => Ok(()), + _ => Err(format!("{at}: a schema is an object or a boolean")), + }; + }; + for (key, value) in members { + if !APPLIED.contains(&key.as_str()) && !ANNOTATIONS.contains(&key.as_str()) { + return Err(format!("{at}: unsupported keyword {key:?}")); + } + let here = format!("{at}/{key}"); + match (key.as_str(), value) { + ("properties" | "$defs", Json::Object(inner)) => { + for (name, sub) in inner { + check_keywords(sub, &format!("{here}/{name}"))?; + } + } + ("items" | "if" | "then", sub) => check_keywords(sub, &here)?, + ("allOf", Json::Array(subs)) => { + for (n, sub) in subs.iter().enumerate() { + check_keywords(sub, &format!("{here}/{n}"))?; + } + } + ("additionalProperties", Json::Bool(_)) => {} + ("additionalProperties", _) => return Err(format!("{here}: only true or false")), + ("$ref", Json::String(target)) if target.starts_with("#/$defs/") => {} + ("$ref", _) => return Err(format!("{here}: only #/$defs/NAME")), + _ => {} + } + } + Ok(()) +} + +/// Validates `instance` against `schema`: the list of every violation, empty if it is valid. +pub(crate) fn validate(schema: &Schema, instance: &Json) -> Vec { + let mut errors = Vec::new(); + check(&schema.root, &schema.root, instance, "", &mut errors); + errors +} + +fn type_matches(name: &str, instance: &Json) -> bool { + match (name, instance) { + ("null", Json::Null) + | ("boolean", Json::Bool(_)) + | ("integer", Json::Integer(_)) + | ("number", Json::Integer(_) | Json::Number(_)) + | ("string", Json::String(_)) + | ("array", Json::Array(_)) + | ("object", Json::Object(_)) => true, + _ => false, + } +} + +fn integer(value: &Json) -> i128 { + match value { + Json::Integer(n) => *n, + other => panic!("the schema needs an integer here, not {other:?}"), + } +} + +/// Every violation of `schema` by `instance`, at the JSON Pointer `at`, added to `errors`. +#[allow(clippy::too_many_lines, reason = "one arm per keyword reads best as one match")] +fn check(root: &Json, schema: &Json, instance: &Json, at: &str, errors: &mut Vec) { + let members = match schema { + Json::Bool(true) => return, + Json::Bool(false) => return errors.push(format!("{at}: no value is allowed")), + Json::Object(members) => members, + _ => unreachable!("checked by check_keywords"), + }; + for (key, value) in members { + match key.as_str() { + "type" => { + let names: Vec<&str> = match value { + Json::String(name) => vec![name], + Json::Array(items) => items + .iter() + .map(|item| match item { + Json::String(name) => name.as_str(), + _ => panic!("a type is a name"), + }) + .collect(), + _ => panic!("type is a name or a list of names"), + }; + if !names.iter().any(|name| type_matches(name, instance)) { + errors.push(format!("{at}: not of type {names:?}: {instance:?}")); + } + } + "const" if instance != value => { + errors.push(format!("{at}: {instance:?} is not {value:?}")); + } + "enum" => { + let Json::Array(options) = value else { panic!("enum is a list") }; + if !options.contains(instance) { + errors.push(format!("{at}: {instance:?} is not one of {options:?}")); + } + } + "required" => { + let Json::Array(names) = value else { panic!("required is a list") }; + for name in names { + let Json::String(name) = name else { panic!("a required name") }; + if matches!(instance, Json::Object(_)) && instance.get(name).is_none() { + errors.push(format!("{at}: no member {name:?}")); + } + } + } + "properties" => { + let Json::Object(properties) = value else { panic!("properties is an object") }; + for (name, sub) in properties { + if let Some(member) = instance.get(name) { + check(root, sub, member, &format!("{at}/{name}"), errors); + } + } + } + "additionalProperties" => { + let (Json::Bool(false), Json::Object(instance)) = (value, instance) else { + continue; + }; + let listed = schema.get("properties"); + for (name, _) in instance { + if listed.and_then(|p| p.get(name)).is_none() { + errors.push(format!("{at}: member {name:?} is not allowed")); + } + } + } + "items" => { + if let Json::Array(items) = instance { + for (n, item) in items.iter().enumerate() { + check(root, value, item, &format!("{at}/{n}"), errors); + } + } + } + "minItems" | "maxItems" => { + if let Json::Array(items) = instance { + let length = i128::try_from(items.len()).expect("a length"); + let bound = integer(value); + let fails = if key == "minItems" { length < bound } else { length > bound }; + if fails { + errors.push(format!("{at}: {length} items breaks {key} {bound}")); + } + } + } + "minLength" | "maxLength" => { + if let Json::String(text) = instance { + let length = i128::try_from(text.chars().count()).expect("a length"); + let bound = integer(value); + let fails = if key == "minLength" { length < bound } else { length > bound }; + if fails { + errors.push(format!("{at}: length {length} breaks {key} {bound}")); + } + } + } + "minimum" | "maximum" => { + if let Json::Integer(n) = instance { + let bound = integer(value); + let fails = if key == "minimum" { *n < bound } else { *n > bound }; + if fails { + errors.push(format!("{at}: {n} breaks {key} {bound}")); + } + } + } + "allOf" => { + let Json::Array(subs) = value else { panic!("allOf is a list") }; + for sub in subs { + check(root, sub, instance, at, errors); + } + } + "if" => { + let mut trial = Vec::new(); + check(root, value, instance, at, &mut trial); + if let (true, Some(then)) = (trial.is_empty(), schema.get("then")) { + check(root, then, instance, at, errors); + } + } + "$ref" => { + let Json::String(target) = value else { panic!("$ref is a string") }; + let name = target.strip_prefix("#/$defs/").expect("checked"); + let sub = root + .get("$defs") + .and_then(|defs| defs.get(name)) + .unwrap_or_else(|| panic!("no definition {name}")); + check(root, sub, instance, at, errors); + } + _ => {} + } + } +} diff --git a/schemas/lumen-message-1.schema.json b/schemas/lumen-message-1.schema.json new file mode 100644 index 0000000..fb55018 --- /dev/null +++ b/schemas/lumen-message-1.schema.json @@ -0,0 +1,928 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "lumen-message/1", + "description": "Every line lumen writes to standard output: one JSON object, with schema lumen-message/1 and a type (ADR 0015). Within this version a member or a type may be added and none is removed, renamed or retyped: a consumer ignores a member it does not know, and a whole line whose type it does not know. Every number is an integer. The schema uses only type, const, enum, properties, required, additionalProperties, items, minItems, maxItems, minimum, maximum, minLength, maxLength, allOf, if, then and $ref to $defs.", + "type": "object", + "required": [ + "schema", + "type" + ], + "properties": { + "schema": { + "const": "lumen-message/1" + }, + "type": { + "description": "The message's type. The types of this version so far: provenance, result, timings, scene_statistics, ray_statistics, traversal_statistics, run_statistics, help, version.", + "type": "string" + } + }, + "additionalProperties": true, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "provenance" + } + } + }, + "then": { + "$ref": "#/$defs/provenance" + } + }, + { + "if": { + "properties": { + "type": { + "const": "result" + } + } + }, + "then": { + "$ref": "#/$defs/result" + } + }, + { + "if": { + "properties": { + "type": { + "const": "timings" + } + } + }, + "then": { + "$ref": "#/$defs/timings" + } + }, + { + "if": { + "properties": { + "type": { + "const": "scene_statistics" + } + } + }, + "then": { + "$ref": "#/$defs/scene_statistics" + } + }, + { + "if": { + "properties": { + "type": { + "const": "ray_statistics" + } + } + }, + "then": { + "$ref": "#/$defs/ray_statistics" + } + }, + { + "if": { + "properties": { + "type": { + "const": "traversal_statistics" + } + } + }, + "then": { + "$ref": "#/$defs/traversal_statistics" + } + }, + { + "if": { + "properties": { + "type": { + "const": "run_statistics" + } + } + }, + "then": { + "$ref": "#/$defs/run_statistics" + } + }, + { + "if": { + "properties": { + "type": { + "const": "help" + } + } + }, + "then": { + "$ref": "#/$defs/help" + } + }, + { + "if": { + "properties": { + "type": { + "const": "version" + } + } + }, + "then": { + "$ref": "#/$defs/version" + } + } + ], + "$defs": { + "count": { + "description": "A count: an integer from 0 to 2^64 - 1.", + "type": "integer", + "minimum": 0, + "maximum": 18446744073709551615 + }, + "micros": { + "description": "A time in whole microseconds, rounded down. Information only: a wall-clock reading, which differs from run to run; never compare it between runs.", + "type": "integer", + "minimum": 0, + "maximum": 18446744073709551615 + }, + "identity": { + "description": "A stable name and version, such as lumen-diffuse-path/1.", + "type": "string", + "minLength": 1 + }, + "sha256": { + "description": "sha256: and 64 lowercase hex digits.", + "type": "string", + "minLength": 71, + "maxLength": 71 + }, + "fixed": { + "description": "A Q32.32 fixed-point value in decimal with six places, from its exact raw integer, rounded to nearest with ties away from zero, such as \"-1.125000\". A string, because a JSON number would be read as a float.", + "type": "string", + "minLength": 8 + }, + "vector": { + "description": "A point or direction: x, y and z.", + "type": "array", + "items": { + "$ref": "#/$defs/fixed" + }, + "minItems": 3, + "maxItems": 3 + }, + "channels": { + "description": "Red, green and blue.", + "type": "array", + "items": { + "$ref": "#/$defs/fixed" + }, + "minItems": 3, + "maxItems": 3 + }, + "side": { + "description": "An image width or height in pixels, 1..=32768.", + "type": "integer", + "minimum": 1, + "maximum": 32768 + }, + "samples": { + "description": "Samples per pixel: a power of two from 1 to 1024.", + "type": "integer", + "minimum": 1, + "maximum": 1024 + }, + "threads": { + "description": "A thread count, 1..=256.", + "type": "integer", + "minimum": 1, + "maximum": 256 + }, + "band_rows": { + "description": "The rows in a band, 1..=2^32 - 1.", + "type": "integer", + "minimum": 1, + "maximum": 4294967295 + }, + "provenance": { + "description": "The render's provenance (RenderProvenance::fields() in order), written when the render starts.", + "type": "object", + "required": [ + "schema", + "type", + "scene", + "integrator", + "shading", + "sampler", + "tone", + "encoding", + "bunny", + "width", + "height", + "pixels", + "samples", + "seed", + "bounces", + "scene_content" + ], + "properties": { + "schema": { + "const": "lumen-message/1" + }, + "type": { + "const": "provenance" + }, + "scene": { + "description": "The scene's identity, or null for a scene given no name.", + "type": [ + "string", + "null" + ] + }, + "integrator": { + "$ref": "#/$defs/identity", + "description": "The integrator, or the debug view's identity." + }, + "shading": { + "description": "The shading contract, or none for a debug view that uses none.", + "type": "string", + "minLength": 1 + }, + "sampler": { + "$ref": "#/$defs/identity" + }, + "tone": { + "$ref": "#/$defs/identity" + }, + "encoding": { + "$ref": "#/$defs/identity" + }, + "bunny": { + "description": "The Bunny commit, 40 lowercase hex digits.", + "type": "string", + "minLength": 40, + "maxLength": 40 + }, + "width": { + "$ref": "#/$defs/side" + }, + "height": { + "$ref": "#/$defs/side" + }, + "pixels": { + "description": "width times height, at most 2^27.", + "type": "integer", + "minimum": 1, + "maximum": 134217728 + }, + "samples": { + "$ref": "#/$defs/samples" + }, + "seed": { + "description": "The sampler's seed, 0..=2^32 - 1.", + "type": "integer", + "minimum": 0, + "maximum": 4294967295 + }, + "bounces": { + "$ref": "#/$defs/count", + "description": "The bounces per path: 1 for the lit image, 0 for a debug view." + }, + "scene_content": { + "$ref": "#/$defs/sha256", + "description": "The scene's content identity (ADR 0005)." + } + }, + "additionalProperties": true + }, + "result": { + "description": "What the render produced, written when it finishes.", + "type": "object", + "required": [ + "schema", + "type", + "width", + "height", + "threads", + "threads_asked", + "band_rows", + "rays", + "image", + "png" + ], + "properties": { + "schema": { + "const": "lumen-message/1" + }, + "type": { + "const": "result" + }, + "width": { + "$ref": "#/$defs/side" + }, + "height": { + "$ref": "#/$defs/side" + }, + "threads": { + "$ref": "#/$defs/threads", + "description": "The workers that rendered: never more than the bands." + }, + "threads_asked": { + "$ref": "#/$defs/threads", + "description": "--threads, or what the system reports available." + }, + "band_rows": { + "$ref": "#/$defs/band_rows" + }, + "rays": { + "description": "Every ray traced, the closest-hit queries (camera and bounce rays) and the any-hit queries (shadow rays).", + "type": "object", + "required": [ + "total", + "closest", + "shadow" + ], + "properties": { + "total": { + "$ref": "#/$defs/count" + }, + "closest": { + "$ref": "#/$defs/count" + }, + "shadow": { + "$ref": "#/$defs/count" + } + }, + "additionalProperties": true + }, + "image": { + "$ref": "#/$defs/sha256", + "description": "The image hash: the SHA-256 of the raw RGBA8 bytes (ADR 0009)." + }, + "png": { + "description": "The file written, or null without --out.", + "type": [ + "object", + "null" + ], + "required": [ + "path", + "bytes" + ], + "properties": { + "path": { + "description": "The path as given (a path that is not Unicode in its lossy form).", + "type": "string" + }, + "bytes": { + "$ref": "#/$defs/count", + "description": "The bytes written: the PNG's length." + } + }, + "additionalProperties": true + } + }, + "additionalProperties": true + }, + "timings": { + "description": "Each part's wall-clock time in whole microseconds. Information only: a wall-clock reading, which differs from run to run; never compare it between runs.", + "type": "object", + "required": [ + "schema", + "type", + "scene_us", + "render_us", + "hash_us", + "png_us", + "total_us" + ], + "properties": { + "schema": { + "const": "lumen-message/1" + }, + "type": { + "const": "timings" + }, + "scene_us": { + "$ref": "#/$defs/micros" + }, + "render_us": { + "$ref": "#/$defs/micros" + }, + "hash_us": { + "$ref": "#/$defs/micros" + }, + "png_us": { + "$ref": "#/$defs/micros" + }, + "total_us": { + "$ref": "#/$defs/micros", + "description": "The whole command after argument parsing: scene, render, hash and png." + } + }, + "additionalProperties": true + }, + "scene_statistics": { + "description": "A built scene's statistics (ADR 0008): lumen stats, and render --stats.", + "type": "object", + "required": [ + "schema", + "type", + "scene", + "scene_content", + "integrator", + "triangles", + "vertices", + "triangles_smooth", + "triangles_zero_area", + "material_triangles", + "material_albedo", + "bounds_min", + "bounds_max", + "light", + "camera", + "tree", + "memory" + ], + "properties": { + "schema": { + "const": "lumen-message/1" + }, + "type": { + "const": "scene_statistics" + }, + "scene": { + "$ref": "#/$defs/identity" + }, + "scene_content": { + "$ref": "#/$defs/sha256" + }, + "integrator": { + "$ref": "#/$defs/identity" + }, + "triangles": { + "$ref": "#/$defs/count" + }, + "vertices": { + "$ref": "#/$defs/count" + }, + "triangles_smooth": { + "$ref": "#/$defs/count" + }, + "triangles_zero_area": { + "$ref": "#/$defs/count" + }, + "material_triangles": { + "description": "The triangles naming each material, in the material table's order.", + "type": "array", + "items": { + "$ref": "#/$defs/count" + } + }, + "material_albedo": { + "description": "Each material's albedo.", + "type": "array", + "items": { + "$ref": "#/$defs/channels" + } + }, + "bounds_min": { + "$ref": "#/$defs/vector" + }, + "bounds_max": { + "$ref": "#/$defs/vector" + }, + "light": { + "type": "object", + "required": [ + "sun", + "sky" + ], + "properties": { + "sun": { + "description": "The sun, or null for a scene without one.", + "type": [ + "object", + "null" + ], + "required": [ + "toward", + "irradiance" + ], + "properties": { + "toward": { + "$ref": "#/$defs/vector" + }, + "irradiance": { + "$ref": "#/$defs/channels" + } + }, + "additionalProperties": true + }, + "sky": { + "$ref": "#/$defs/channels" + } + }, + "additionalProperties": true + }, + "camera": { + "type": "object", + "required": [ + "position", + "look", + "up", + "tan_half_fov" + ], + "properties": { + "position": { + "$ref": "#/$defs/vector" + }, + "look": { + "$ref": "#/$defs/vector" + }, + "up": { + "$ref": "#/$defs/vector" + }, + "tan_half_fov": { + "$ref": "#/$defs/fixed" + } + }, + "additionalProperties": true + }, + "tree": { + "type": "object", + "required": [ + "builder", + "layout", + "nodes", + "interior_nodes", + "leaves", + "leaf_depth_max", + "leaf_depth_total", + "leaf_triangles", + "leaf_triangles_min", + "leaf_triangles_max", + "leaf_sizes" + ], + "properties": { + "builder": { + "type": "string" + }, + "layout": { + "type": "string" + }, + "nodes": { + "$ref": "#/$defs/count" + }, + "interior_nodes": { + "$ref": "#/$defs/count" + }, + "leaves": { + "$ref": "#/$defs/count" + }, + "leaf_depth_max": { + "$ref": "#/$defs/count" + }, + "leaf_depth_total": { + "$ref": "#/$defs/count" + }, + "leaf_triangles": { + "$ref": "#/$defs/count" + }, + "leaf_triangles_min": { + "$ref": "#/$defs/count" + }, + "leaf_triangles_max": { + "$ref": "#/$defs/count" + }, + "leaf_sizes": { + "description": "Leaves of 1, 2, 3 and 4 triangles, and of more.", + "type": "array", + "items": { + "$ref": "#/$defs/count" + }, + "minItems": 5, + "maxItems": 5 + } + }, + "additionalProperties": true + }, + "memory": { + "description": "Information only: this build's type sizes times the counts, which can differ between targets.", + "type": "object", + "required": [ + "triangles_bytes", + "surfaces_bytes", + "vertex_normals_bytes", + "material_indices_bytes", + "materials_bytes", + "tree_nodes_bytes", + "tree_primitive_indices_bytes", + "total_bytes" + ], + "properties": { + "triangles_bytes": { + "$ref": "#/$defs/count" + }, + "surfaces_bytes": { + "$ref": "#/$defs/count" + }, + "vertex_normals_bytes": { + "$ref": "#/$defs/count" + }, + "material_indices_bytes": { + "$ref": "#/$defs/count" + }, + "materials_bytes": { + "$ref": "#/$defs/count" + }, + "tree_nodes_bytes": { + "$ref": "#/$defs/count" + }, + "tree_primitive_indices_bytes": { + "$ref": "#/$defs/count" + }, + "total_bytes": { + "$ref": "#/$defs/count" + } + }, + "additionalProperties": true + } + }, + "additionalProperties": true + }, + "ray_statistics": { + "description": "What a render's rays found (render --stats): a function of the scene, the size and the settings.", + "type": "object", + "required": [ + "schema", + "type", + "camera", + "camera_hits", + "camera_misses", + "bounce", + "bounce_hits", + "bounce_misses", + "bounce_rejected", + "shadow", + "shadow_occluded", + "shadow_unoccluded", + "total", + "pixels", + "samples_per_pixel", + "samples", + "per_pixel_min", + "per_pixel_max" + ], + "properties": { + "schema": { + "const": "lumen-message/1" + }, + "type": { + "const": "ray_statistics" + }, + "camera": { + "$ref": "#/$defs/count" + }, + "camera_hits": { + "$ref": "#/$defs/count" + }, + "camera_misses": { + "$ref": "#/$defs/count" + }, + "bounce": { + "$ref": "#/$defs/count" + }, + "bounce_hits": { + "$ref": "#/$defs/count" + }, + "bounce_misses": { + "$ref": "#/$defs/count" + }, + "bounce_rejected": { + "$ref": "#/$defs/count" + }, + "shadow": { + "$ref": "#/$defs/count" + }, + "shadow_occluded": { + "$ref": "#/$defs/count" + }, + "shadow_unoccluded": { + "$ref": "#/$defs/count" + }, + "total": { + "$ref": "#/$defs/count" + }, + "pixels": { + "$ref": "#/$defs/count" + }, + "samples_per_pixel": { + "$ref": "#/$defs/samples" + }, + "samples": { + "$ref": "#/$defs/count" + }, + "per_pixel_min": { + "$ref": "#/$defs/count" + }, + "per_pixel_max": { + "$ref": "#/$defs/count" + } + }, + "additionalProperties": true + }, + "traversal_kind": { + "description": "Bunny's traversal counts for one kind of ray: each counter summed over the rays, its most for any one ray (_max), and the deepest stack.", + "type": "object", + "required": [ + "box_tests", + "box_entries", + "popped_skipped", + "interior_visits", + "leaf_visits", + "primitive_tests", + "box_tests_max", + "box_entries_max", + "popped_skipped_max", + "interior_visits_max", + "leaf_visits_max", + "primitive_tests_max", + "peak_stack" + ], + "properties": { + "box_tests": { + "$ref": "#/$defs/count" + }, + "box_entries": { + "$ref": "#/$defs/count" + }, + "popped_skipped": { + "$ref": "#/$defs/count" + }, + "interior_visits": { + "$ref": "#/$defs/count" + }, + "leaf_visits": { + "$ref": "#/$defs/count" + }, + "primitive_tests": { + "$ref": "#/$defs/count" + }, + "box_tests_max": { + "$ref": "#/$defs/count" + }, + "box_entries_max": { + "$ref": "#/$defs/count" + }, + "popped_skipped_max": { + "$ref": "#/$defs/count" + }, + "interior_visits_max": { + "$ref": "#/$defs/count" + }, + "leaf_visits_max": { + "$ref": "#/$defs/count" + }, + "primitive_tests_max": { + "$ref": "#/$defs/count" + }, + "peak_stack": { + "$ref": "#/$defs/count" + } + }, + "additionalProperties": true + }, + "traversal_statistics": { + "description": "What Bunny's traversals did (render --stats), per kind of ray.", + "type": "object", + "required": [ + "schema", + "type", + "camera", + "bounce", + "shadow" + ], + "properties": { + "schema": { + "const": "lumen-message/1" + }, + "type": { + "const": "traversal_statistics" + }, + "camera": { + "$ref": "#/$defs/traversal_kind" + }, + "bounce": { + "$ref": "#/$defs/traversal_kind" + }, + "shadow": { + "$ref": "#/$defs/traversal_kind" + } + }, + "additionalProperties": true + }, + "run_statistics": { + "description": "How the work was spread (render --stats).", + "type": "object", + "required": [ + "schema", + "type", + "band_rows", + "bands", + "workers" + ], + "properties": { + "schema": { + "const": "lumen-message/1" + }, + "type": { + "const": "run_statistics" + }, + "band_rows": { + "$ref": "#/$defs/band_rows" + }, + "bands": { + "$ref": "#/$defs/count" + }, + "workers": { + "description": "What each worker took and traced; which worker took which band depends on timing. Information only: the split differs from run to run; the totals do not.", + "type": "array", + "minItems": 1, + "maxItems": 256, + "items": { + "type": "object", + "required": [ + "bands", + "rows", + "pixels", + "rays" + ], + "properties": { + "bands": { + "$ref": "#/$defs/count" + }, + "rows": { + "$ref": "#/$defs/count" + }, + "pixels": { + "$ref": "#/$defs/count" + }, + "rays": { + "$ref": "#/$defs/count" + } + }, + "additionalProperties": true + } + } + }, + "additionalProperties": true + }, + "help": { + "description": "lumen --help: the usage text.", + "type": "object", + "required": [ + "schema", + "type", + "usage" + ], + "properties": { + "schema": { + "const": "lumen-message/1" + }, + "type": { + "const": "help" + }, + "usage": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": true + }, + "version": { + "description": "lumen --version.", + "type": "object", + "required": [ + "schema", + "type", + "lumen", + "bunny" + ], + "properties": { + "schema": { + "const": "lumen-message/1" + }, + "type": { + "const": "version" + }, + "lumen": { + "description": "The package version.", + "type": "string", + "minLength": 1 + }, + "bunny": { + "description": "The Bunny commit the binary was built against.", + "type": "string", + "minLength": 40, + "maxLength": 40 + } + }, + "additionalProperties": true + } + } +}