Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 12 additions & 10 deletions crates/lumen/src/bin/lumen/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<PathBuf>,
/// 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,
}

Expand Down
2 changes: 1 addition & 1 deletion crates/lumen/src/bin/lumen/failure.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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),
}

Expand Down
178 changes: 178 additions & 0 deletions crates/lumen/src/bin/lumen/json.rs
Original file line number Diff line number Diff line change
@@ -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<Value>),
/// 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<String>, value: impl Into<Value>) -> 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<bool> for Value {
fn from(value: bool) -> Self {
Self::Bool(value)
}
}

impl From<u64> for Value {
fn from(value: u64) -> Self {
Self::Integer(value)
}
}

impl From<u32> for Value {
fn from(value: u32) -> Self {
Self::Integer(u64::from(value))
}
}

impl From<usize> 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<String> for Value {
fn from(value: String) -> Self {
Self::String(value)
}
}

impl From<Object> for Value {
fn from(value: Object) -> Self {
Self::Object(value)
}
}

impl From<Vec<Value>> for Value {
fn from(value: Vec<Value>) -> Self {
Self::Array(value)
}
}

impl<T: Into<Value>> From<Option<T>> for Value {
/// `None` is `null`.
fn from(value: Option<T>) -> Self {
value.map_or(Self::Null, Into::into)
}
}

/// An array of the values `items` gives.
pub(crate) fn array<T: Into<Value>>(items: impl IntoIterator<Item = T>) -> 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;
95 changes: 95 additions & 0 deletions crates/lumen/src/bin/lumen/json/tests.rs
Original file line number Diff line number Diff line change
@@ -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::<u32>::new()))
.with("none", None::<u32>)
.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}"#);
}
Loading
Loading