From 54715d0b92ca22c031245136da6292f6a101978b Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Mon, 16 Nov 2026 21:18:37 -0500 Subject: [PATCH 01/64] svg: share precision-preserving legacy colour parsing (#1971) --- crates/svg/src/color.rs | 3 + crates/svg/src/color/compat.rs | 174 +++++++++++++++++++++++++++++++++ 2 files changed, 177 insertions(+) create mode 100644 crates/svg/src/color/compat.rs diff --git a/crates/svg/src/color.rs b/crates/svg/src/color.rs index 610ca6aa1..521ece3b0 100644 --- a/crates/svg/src/color.rs +++ b/crates/svg/src/color.rs @@ -488,3 +488,6 @@ mod tests { assert_eq!(black.blend(white, f32::NAN), black); } } + +mod compat; +pub use compat::parse_rgba_compat; diff --git a/crates/svg/src/color/compat.rs b/crates/svg/src/color/compat.rs new file mode 100644 index 000000000..db4ad025e --- /dev/null +++ b/crates/svg/src/color/compat.rs @@ -0,0 +1,174 @@ +//! Floating-point CSS colour compatibility for existing SVG consumers. +//! +//! Ported from EffectCraft `crates/svg/src/color.rs`: Brandon Thomas's original +//! implementation at `94e1c86d89a866771f80ad1610afda9aa12e85d8`, with NetterSilver's +//! finite-channel checks at `e244d642350787aaa7028470855368165012d029`. +//! The shared keyword table replaces the identical local table; allocation limits +//! and precision/grammar regressions are added here. +use super::NAMED; + +/// Parse the legacy SVG colour grammar without quantizing RGB or alpha from `f64`. +/// +/// This compatibility entry point clamps finite channels, accepts `transparent`, loose +/// comma/space/slash separators and unitless HSL saturation/lightness, and ignores arguments +/// after alpha. It deliberately differs from the strict [`super::parse_color_alpha`]. +/// `none`, `currentColor`, and `url()` remain the caller's paint policy. +/// +/// Inputs above 64 MiB are refused before allocation; argument storage is limited to four +/// entries and hex storage to eight digits. Invalid or over-budget input returns `None`. +pub fn parse_rgba_compat(s: &str) -> Option<[f64; 4]> { + if s.len() > 64 * 1024 * 1024 { + return None; + } + let s = s.trim(); + let lower = s.to_ascii_lowercase(); + if lower == "transparent" { + return Some([0.0; 4]); + } + if let Some(h) = lower.strip_prefix('#') { + if !matches!(h.len(), 3 | 4 | 6 | 8) { + return None; + } + let d: Vec = h.chars().map(|c| c.to_digit(16)).collect::>()?; + let v = |i: usize| d[i] as f64 / 15.0; + let w = |i: usize| (d[i] * 16 + d[i + 1]) as f64 / 255.0; + return Some(match d.len() { + 3 => [v(0), v(1), v(2), 1.0], + 4 => [v(0), v(1), v(2), v(3)], + 6 => [w(0), w(2), w(4), 1.0], + 8 => [w(0), w(2), w(4), w(6)], + _ => return None, + }); + } + if let Some(args) = func(&lower, "rgba").or_else(|| func(&lower, "rgb")) { + let a: Vec<&str> = split_args(args); + if a.len() < 3 { + return None; + } + let comp = |t: &str| -> Option { + Some(if let Some(p) = t.strip_suffix('%') { + p.trim().parse::().ok().filter(|v| v.is_finite())? / 100.0 + } else { + t.parse::().ok().filter(|v| v.is_finite())? / 255.0 + }) + }; + let alpha = a.get(3).map_or(Some(1.0), |t| alpha(t))?; + return Some([comp(a[0])?.clamp(0.0, 1.0), comp(a[1])?.clamp(0.0, 1.0), comp(a[2])?.clamp(0.0, 1.0), alpha]); + } + if let Some(args) = func(&lower, "hsla").or_else(|| func(&lower, "hsl")) { + let a: Vec<&str> = split_args(args); + if a.len() < 3 { + return None; + } + let h = a[0].trim_end_matches("deg").parse::().ok().filter(|v| v.is_finite())?.rem_euclid(360.0) / 360.0; + let s = a[1].trim_end_matches('%').parse::().ok().filter(|v| v.is_finite())?.clamp(0.0, 100.0) / 100.0; + let l = a[2].trim_end_matches('%').parse::().ok().filter(|v| v.is_finite())?.clamp(0.0, 100.0) / 100.0; + let al = a.get(3).map_or(Some(1.0), |t| alpha(t))?; + let [r, g, b] = hsl(h, s, l); + return Some([r, g, b, al]); + } + NAMED + .iter() + .find(|(n, _)| *n == lower) + .map(|(_, v)| [((v >> 16) & 255) as f64 / 255.0, ((v >> 8) & 255) as f64 / 255.0, (v & 255) as f64 / 255.0, 1.0]) +} + +fn func<'a>(s: &'a str, name: &str) -> Option<&'a str> { + s.strip_prefix(name)?.trim_start().strip_prefix('(')?.strip_suffix(')') +} + +fn split_args(s: &str) -> Vec<&str> { + s.split(|c: char| c == ',' || c == '/' || c.is_whitespace()).filter(|t| !t.is_empty()).take(4).collect() +} + +fn alpha(t: &str) -> Option { + Some( + if let Some(p) = t.strip_suffix('%') { + p.parse::().ok().filter(|v| v.is_finite())? / 100.0 + } else { + t.parse::().ok().filter(|v| v.is_finite())? + } + .clamp(0.0, 1.0), + ) +} + +/// CSS HSL → RGB (CSS Color 3 §4.2.4). +fn hsl(h: f64, s: f64, l: f64) -> [f64; 3] { + let m2 = if l <= 0.5 { l * (s + 1.0) } else { l + s - l * s }; + let m1 = l * 2.0 - m2; + let hue = |mut h: f64| { + if h < 0.0 { + h += 1.0; + } + if h > 1.0 { + h -= 1.0; + } + if h * 6.0 < 1.0 { + m1 + (m2 - m1) * h * 6.0 + } else if h * 2.0 < 1.0 { + m2 + } else if h * 3.0 < 2.0 { + m1 + (m2 - m1) * (2.0 / 3.0 - h) * 6.0 + } else { + m1 + } + }; + [hue(h + 1.0 / 3.0), hue(h), hue(h - 1.0 / 3.0)] +} + +#[cfg(test)] +mod tests { + use super::parse_rgba_compat; + + #[test] + fn non_finite_rejected() { + for s in [ + "rgb(nan,0,0)", + "rgb(inf,0,0)", + "rgba(0,0,0,nan)", + "rgba(0,0,0,inf)", + "hsl(nan,100%,50%)", + "hsl(120,nan%,50%)", + "hsl(120,100%,inf%)", + "hsl(120,100%,50%,nan)", + ] { + assert_eq!(parse_rgba_compat(s), None, "{s}"); + } + } + + #[test] + fn colors() { + assert_eq!(parse_rgba_compat("#f00"), Some([1.0, 0.0, 0.0, 1.0])); + assert_eq!(parse_rgba_compat("#00ff0080").map(|c| (c[1], (c[3] * 255.0).round())), Some((1.0, 128.0))); + assert_eq!(parse_rgba_compat("rgb(255, 0, 0)"), Some([1.0, 0.0, 0.0, 1.0])); + assert_eq!(parse_rgba_compat("rgba(0,0,255,0.5)"), Some([0.0, 0.0, 1.0, 0.5])); + assert_eq!(parse_rgba_compat("rgb(100%, 50%, 0%)"), Some([1.0, 0.5, 0.0, 1.0])); + assert_eq!(parse_rgba_compat("hsl(120, 100%, 50%)"), Some([0.0, 1.0, 0.0, 1.0])); + assert_eq!(parse_rgba_compat("CornflowerBlue"), Some([100.0 / 255.0, 149.0 / 255.0, 237.0 / 255.0, 1.0])); + assert_eq!(parse_rgba_compat("transparent"), Some([0.0; 4])); + assert_eq!(parse_rgba_compat("nonsense"), None); + } +} + +#[cfg(test)] +mod compatibility_tests { + use super::parse_rgba_compat; + + #[test] + fn float_precision_and_legacy_grammar() { + assert_eq!(parse_rgba_compat("rgb(100%,50%,0%)"), Some([1.0, 0.5, 0.0, 1.0])); + assert_eq!(parse_rgba_compat("rgba(0,0,255,0.123456789123)"), Some([0.0, 0.0, 1.0, 0.123456789123])); + assert_eq!(parse_rgba_compat("rgb(300,-1,0)"), Some([1.0, 0.0, 0.0, 1.0])); + assert_eq!(parse_rgba_compat("hsl(120,50,50)"), Some([0.25, 0.75, 0.25, 1.0])); + assert_eq!(parse_rgba_compat("rgb(1,2,3,0.5,ignored)"), parse_rgba_compat("rgb(1,2,3,0.5)")); + assert_eq!(parse_rgba_compat("# fff"), None); + assert_eq!(parse_rgba_compat(&format!("rgb(1,2,3){}", " ".repeat(65))), parse_rgba_compat("rgb(1,2,3)")); + } + + #[test] + fn bounded_arguments_and_hex() { + assert_eq!(super::split_args(&"1,".repeat(100_000)).len(), 4); + assert_eq!(parse_rgba_compat(&format!("#{}", "f".repeat(100_000))), None); + assert_eq!(parse_rgba_compat(&" ".repeat(64 * 1024 * 1024 + 1)), None); + } +} From 0fb022f4f1d3172d3b6d7ad99c8e354de0789b99 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Mon, 16 Nov 2026 21:23:18 -0500 Subject: [PATCH 02/64] craft-midi: share source-timed SMF compatibility and legacy recovery reader (#1966) --- ATTRIBUTION.md | 3 + crates/midi/src/lib.rs | 2 + crates/midi/src/source_timed.rs | 1452 +++++++++++++++++++++++++++++++ 3 files changed, 1457 insertions(+) create mode 100644 crates/midi/src/source_timed.rs diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 8840199b2..680fa5851 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -104,6 +104,9 @@ and the exact transfer revision are recorded in each vendored crate's SOURCE.jso `crates/tga/src/metadata_tests.rs` and metadata-boundary helpers in `crates/tga/src/lib.rs` are adapted from nuclearspike's FilmCraft #1932 at `e7842f76f887005c460c64a8ab51d59d086e6f27` (MIT OR Apache-2.0). Synthetic fixtures are original contributor test data; primary Git author retained. The XML reader in `crates/plist/src/xml.rs` and its base64 compatibility helper are ported from Craft Anything `8f3b775157d331dd31cfa4da911e26d8856b8c77` (same MIT OR Apache-2.0 source licenses). Brandon Thomas is the primary import author; retained hardening credits include Afloat, BFlat, Rahul, RRFZ and NetterSilver. The finite-real fix preserves gmrmad1 as author from Craft Anything #1905 (`d85e104f`); quoted-attribute/line-ending regressions preserve RRFZ. Bounds/adaptation and bounded entity scanning are subsequent Dylan M. Taylor changes. App-specific JSON projections and keyed-archive interpretation remain outside this crate. +## Source-timed MIDI compatibility + +`crates/midi/src/source_timed.rs` is extracted from LoopCraft `crates/midi/src/lib.rs` at `884e67c24b9b68badf6a4a4f7d62492f3673d354` (MIT OR Apache-2.0). The recorded source history for the extracted file is Dylan M. Taylor (`0d150c1f`, `440bc7ed`, `9e50523d`); Git authorship is preserved. It includes the original hostile-file, SMPTE, timing and round-trip tests. UTF-8 truncation and event-budget suffix repairs are subsequent changes. The module is an application-independent source-timed model; it does not depend on LoopCraft. ## Non-seeking WAV primitives `crates/audio/src/wav_stream.rs` is extracted from AniCraft `crates/audio/src/wav.rs` at `d875a7feb250e6ab06aa28a37fb78a0699e88330` (MIT OR Apache-2.0). Tanish Manku is retained as the primary import author, from original commit `30c121d269a49d9abe54a3834ed4aa0201542535`. Odd-data padding accounting, shared API documentation and regression tests are subsequent Dylan M. Taylor changes. diff --git a/crates/midi/src/lib.rs b/crates/midi/src/lib.rs index fd703e40a..0eabbc70d 100644 --- a/crates/midi/src/lib.rs +++ b/crates/midi/src/lib.rs @@ -12,6 +12,8 @@ mod sequence; mod smf; +/// Source-timed SMF compatibility model, including tolerant and SMPTE reading. +pub mod source_timed; pub mod sync; pub use sequence::{CtrlEvent, CtrlKind, Note, Sequence}; diff --git a/crates/midi/src/source_timed.rs b/crates/midi/src/source_timed.rs new file mode 100644 index 000000000..05d21f604 --- /dev/null +++ b/crates/midi/src/source_timed.rs @@ -0,0 +1,1452 @@ +//! Standard MIDI Files (SMF formats 0, 1 and 2), read and written from the Standard MIDI Files 1.0 +//! specification (MIDI Manufacturers Association, RP-001) and the MIDI 1.0 message tables. What a +//! sequencer exchanges is modelled: notes, the channel messages that are one number at a time +//! (control changes, program changes, pitch bend, channel pressure), the tempo map, time and key +//! signatures, markers and track names. Byte-level SMF reading/writing delegates to +//! [`crate`]; this module preserves source-timed u32 ticks and rescaling. +//! +//! [`read`] takes whatever a disk or another program made of a file: what can be made sense of is +//! returned, with [`Smf::warnings`] saying what could not, and nothing in a file makes it +//! allocate more than a small multiple of the file's own size ([`MAX_EVENTS`], [`MAX_TRACKS`]). +//! +//! Use [`crate::sync`] for clock, song position and time code. +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +use crate::{ + self as craft_midi, CtrlEvent as CraftCtrlEvent, Note as CraftNote, Smf as CraftSmf, SmfTrack as CraftSmfTrack, read_smf_lenient, write_smf, +}; +use std::collections::VecDeque; + +/// The most notes and channel messages read from one file; the rest is left out with a warning. +pub const MAX_EVENTS: usize = 1 << 21; +/// The most tracks read from one file. +pub const MAX_TRACKS: usize = 4096; +/// The most tempo changes, signatures and markers (each) read from one file. +pub const MAX_META: usize = 1 << 14; +/// The longest name or marker text kept, in bytes. +const MAX_TEXT: usize = 256; +/// The most warnings one file gets. +const MAX_WARNINGS: usize = 32; + +/// The controllers a sequencer most often meets. +pub mod cc { + pub const BANK: u8 = 0; + pub const MODULATION: u8 = 1; + pub const VOLUME: u8 = 7; + pub const PAN: u8 = 10; + pub const EXPRESSION: u8 = 11; + pub const BANK_FINE: u8 = 32; + pub const SUSTAIN: u8 = 64; +} + +/// The MIDI channel (counted from 0) General MIDI plays drums on. +pub const DRUMS: u8 = 9; + +#[derive(Clone, Debug, PartialEq)] +pub struct Note { + pub start: u32, + pub len: u32, + pub key: u8, + /// 1..=127 + pub vel: u8, + pub channel: u8, +} + +/// What a [`Change`] sets. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum What { + /// A control change, by controller number (0..=127). + Control(u8), + Program, + /// The pitch wheel: -8192..=8191, 0 at rest. + Bend, + /// Channel pressure (aftertouch for the whole channel). + Pressure, +} + +/// A channel message that is one number: 0..=127, but for the pitch wheel. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Change { + pub tick: u32, + pub channel: u8, + pub what: What, + pub value: i16, +} + +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Track { + pub name: String, + /// The instrument name meta event, when the track has one. + pub instrument: String, + /// Sorted by start, then key. + pub notes: Vec, + /// In the order of the file, which is by tick. + pub changes: Vec, +} + +impl Track { + /// The values of controller `number` on `channel`, in order. + pub fn controls(&self, channel: u8, number: u8) -> impl Iterator { + self.changes.iter().filter(move |c| c.channel == channel && c.what == What::Control(number)) + } +} + +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Tempo { + pub tick: u32, + /// Quarter notes a minute. + pub bpm: f64, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct TimeSignature { + pub tick: u32, + pub beats: u8, + /// The note value of a beat: 4 is a quarter, 8 an eighth. + pub unit: u32, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct KeySignature { + pub tick: u32, + /// Sharps (above zero) or flats (below), -7..=7. + pub sharps: i8, + pub minor: bool, +} + +/// A marker or a cue point. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Marker { + pub tick: u32, + pub name: String, +} + +#[derive(Clone, Debug, PartialEq)] +pub struct Smf { + /// 0 is one track for all channels, 1 tracks that play together, 2 tracks that are songs of their own. + pub format: u16, + /// Ticks per quarter note. + pub ppq: u16, + /// Every tempo of the file, by tick, one a tick at most. A file without one plays at 120. + pub tempos: Vec, + pub time_signatures: Vec, + pub key_signatures: Vec, + pub markers: Vec, + /// The tracks that hold notes or channel messages. + pub tracks: Vec, + /// The last tick any track reaches. + pub ticks: u32, + /// What [`read`] could not make sense of, or left out. + pub warnings: Vec, +} + +impl Default for Smf { + fn default() -> Self { + Smf { + format: 1, + ppq: 96, + tempos: Vec::new(), + time_signatures: Vec::new(), + key_signatures: Vec::new(), + markers: Vec::new(), + tracks: Vec::new(), + ticks: 0, + warnings: Vec::new(), + } + } +} + +impl Smf { + /// The tempo the file starts at. + pub fn tempo(&self) -> f64 { + self.tempos.first().map_or(120.0, |t| t.bpm) + } + + /// Counts every tick in `ppq` to the quarter note instead. A tick goes to the nearest new one + /// whatever it belongs to, so what was at one tick still is; a note's start and end are moved + /// apart from each other, so notes that touched still touch, and no note is left without length. + pub fn rescale(&mut self, ppq: u16) { + let (from, to) = (u64::from(self.ppq.max(1)), u64::from(ppq.max(1))); + self.ppq = ppq.max(1); + if from == to { + return; + } + let scale = |tick: u32| ((u64::from(tick) * to + from / 2) / from).min(u64::from(u32::MAX)) as u32; + for track in &mut self.tracks { + for n in &mut track.notes { + let end = scale(n.start.saturating_add(n.len)); + n.start = scale(n.start); + n.len = end.saturating_sub(n.start).max(1); + } + track.changes.iter_mut().for_each(|c| c.tick = scale(c.tick)); + } + let ticks = (self.tempos.iter_mut().map(|t| &mut t.tick)) + .chain(self.time_signatures.iter_mut().map(|t| &mut t.tick)) + .chain(self.key_signatures.iter_mut().map(|t| &mut t.tick)) + .chain(self.markers.iter_mut().map(|t| &mut t.tick)) + .chain([&mut self.ticks]); + ticks.for_each(|tick| *tick = scale(*tick)); + one_tempo_a_tick(&mut self.tempos); + } +} + +/// Of several tempos at one tick the last is the one that plays. +fn one_tempo_a_tick(tempos: &mut Vec) { + tempos.dedup_by(|later, kept| { + let same = later.tick == kept.tick; + if same { + *kept = *later; + } + same + }); +} + +#[derive(Debug, PartialEq)] +pub enum Error { + NotMidi, + /// The file ends inside its header. + Truncated, + /// A time division no tick can be counted by. + Unsupported(&'static str), +} + +impl std::fmt::Display for Error { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Error::NotMidi => write!(f, "not a Standard MIDI File"), + Error::Truncated => write!(f, "the MIDI file is truncated or damaged"), + Error::Unsupported(what) => write!(f, "unsupported MIDI file: {what}"), + } + } +} + +impl std::error::Error for Error {} + +fn trim_text(s: &str) -> String { + s.trim_matches(|c: char| c.is_control() || c.is_whitespace()).to_string() +} + +fn map_midi_error(e: craft_midi::MidiError) -> Error { + match e { + craft_midi::MidiError::NotSmf => Error::NotMidi, + craft_midi::MidiError::Truncated(_) | craft_midi::MidiError::BadChunkLength { .. } => Error::Truncated, + craft_midi::MidiError::Unsupported(_) => Error::Unsupported("unknown"), + _ => Error::NotMidi, + } +} + +// --------------------------------------------------------------------------- +// Adapter: source-timed types ↔ normalized craft-midi types +// --------------------------------------------------------------------------- + +fn change_from_craft(c: &CraftCtrlEvent, ppq: u16) -> Change { + let what = match c.kind { + craft_midi::CtrlKind::Cc(n) => What::Control(n), + craft_midi::CtrlKind::Program => What::Program, + craft_midi::CtrlKind::PitchBend => What::Bend, + craft_midi::CtrlKind::ChannelPressure => What::Pressure, + // Polyphonic aftertouch is not represented in the compatibility reader's Change; skip it. + craft_midi::CtrlKind::PolyPressure(_) => return Change { tick: 0, channel: 0, what: What::Control(0), value: 0 }, + }; + // craft-midi converts to 960 PPQ; scale back to source ppq. + let tick = ((i128::from(c.tick) * i128::from(ppq.max(1)) + i128::from(craft_midi::PPQ) / 2) / i128::from(craft_midi::PPQ)) + .try_into() + .unwrap_or(u32::MAX); + Change { tick, channel: c.channel, what, value: c.value as i16 } +} + +fn smf_to_craft(craft_smf: &CraftSmf, ppq: u16) -> Smf { + let mut smf = Smf { format: craft_smf.format, ..Default::default() }; + + // Craft-midi converts ticks to 960 PPQ when reading. Scale back to source ppq. + let (from, to) = (i128::from(craft_midi::PPQ.max(1)), i128::from(ppq.max(1))); + + smf.ppq = ppq; + // Scale tempo ticks from 960 PPQ back to source ppq. + smf.tempos = craft_smf + .tempos + .iter() + .map(|(tick, bpm)| { + let tick = ((i128::from(*tick) * to + from / 2) / from).try_into().unwrap_or(u32::MAX); + Tempo { tick, bpm: *bpm } + }) + .collect(); + // Scale meter ticks. + smf.time_signatures = craft_smf + .meters + .iter() + .map(|(tick, beats, unit)| { + let tick = ((i128::from(*tick) * to + from / 2) / from).try_into().unwrap_or(u32::MAX); + TimeSignature { tick, beats: *beats, unit: u32::from(*unit).max(1) } + }) + .collect(); + // Scale key signature ticks. + smf.key_signatures = craft_smf + .key_sigs + .iter() + .map(|(tick, sharps, minor)| { + let tick = ((i128::from(*tick) * to + from / 2) / from).try_into().unwrap_or(u32::MAX); + KeySignature { tick, sharps: *sharps, minor: *minor } + }) + .collect(); + // Scale marker ticks. + smf.markers = craft_smf + .markers + .iter() + .map(|(tick, name)| { + let tick = ((i128::from(*tick) * to + from / 2) / from).try_into().unwrap_or(u32::MAX); + Marker { tick, name: trim_text(name) } + }) + .collect(); + + for ct in &craft_smf.tracks { + let mut track = Track { name: trim_text(&ct.name), ..Default::default() }; + + for n in &ct.sequence.notes { + // Scale from 960 PPQ back to source ppq. + let start = ((i128::from(n.start) * to + from / 2) / from).try_into().unwrap_or(u32::MAX); + let end = ((i128::from(n.end()) * to + from / 2) / from).try_into().unwrap_or(u32::MAX); + let len = end.saturating_sub(start).max(1); + track.notes.push(Note { start, len, key: n.pitch, vel: n.velocity, channel: n.channel }); + } + + for c in &ct.sequence.ctrls { + track.changes.push(change_from_craft(c, ppq)); + } + + smf.tracks.push(track); + } + + // Compute ticks as the max of all track end ticks + smf.ticks = smf.tracks.iter().flat_map(|t| t.notes.iter().map(|n| n.start.saturating_add(n.len)).chain(std::iter::once(0u32))).max().unwrap_or(0); + + smf.warnings = Vec::new(); + + smf +} + +fn smf_from_craft(smf: &Smf) -> CraftSmf { + let mut craft_smf = CraftSmf { format: smf.format, ..Default::default() }; + + // Scale from source PPQ to 960 when writing. + let (from, to) = (i128::from(smf.ppq.max(1)), i128::from(craft_midi::PPQ)); + + // Build tempo/meter/key/marker lists (scaled to 960 PPQ) + craft_smf.tempos = smf + .tempos + .iter() + .map(|t| { + let tick = ((i128::from(t.tick) * to + from / 2) / from).try_into().unwrap_or(i64::MAX); + (tick, t.bpm) + }) + .collect(); + craft_smf.meters = smf + .time_signatures + .iter() + .map(|t| { + let tick = ((i128::from(t.tick) * to + from / 2) / from).try_into().unwrap_or(i64::MAX); + (tick, t.beats, u8::try_from(t.unit).unwrap_or(1)) + }) + .collect(); + craft_smf.key_sigs = smf + .key_signatures + .iter() + .map(|k| { + let tick = ((i128::from(k.tick) * to + from / 2) / from).try_into().unwrap_or(i64::MAX); + (tick, k.sharps, k.minor) + }) + .collect(); + craft_smf.markers = smf + .markers + .iter() + .map(|m| { + let tick = ((i128::from(m.tick) * to + from / 2) / from).try_into().unwrap_or(i64::MAX); + (tick, m.name.clone()) + }) + .collect(); + + for track in &smf.tracks { + let mut ct = CraftSmfTrack::default(); + if !track.name.is_empty() { + ct.name = track.name.clone(); + } + + for n in &track.notes { + let start = ((i128::from(n.start) * to + from / 2) / from).try_into().unwrap_or(i64::MAX); + let end = ((i128::from(n.start.saturating_add(n.len)) * to + from / 2) / from).try_into().unwrap_or(i64::MAX); + let length = end.saturating_sub(start).max(1); + ct.sequence.notes.push(CraftNote { pitch: n.key, velocity: n.vel, release_velocity: 64, channel: n.channel, start, length }); + } + + for c in &track.changes { + let kind = match c.what { + What::Control(n) => craft_midi::CtrlKind::Cc(n), + What::Program => craft_midi::CtrlKind::Program, + What::Bend => craft_midi::CtrlKind::PitchBend, + What::Pressure => craft_midi::CtrlKind::ChannelPressure, + }; + let tick = ((i128::from(c.tick) * to + from / 2) / from).try_into().unwrap_or(i64::MAX); + ct.sequence.ctrls.push(CraftCtrlEvent { tick, channel: c.channel, kind, value: c.value as i32 }); + } + + ct.sequence.sort(); + craft_smf.tracks.push(ct); + } + + craft_smf +} + +// --------------------------------------------------------------------------- +// Public API: read/write delegate to craft-midi +// --------------------------------------------------------------------------- + +/// Reads a file of any format. Tracks without notes or channel messages (the tempo track) are +/// dropped; their tempos, signatures and markers are the file's. A file that is damaged past its +/// header still gives what could be read of it, with [`Smf::warnings`]. +pub fn read(data: &[u8]) -> Result { + // Check for valid MIDI header. + if data.len() < 4 || data[0..4] != *b"MThd" { + return Err(Error::NotMidi); + } + + // Truncated header (less than 14 bytes). + if data.len() < 14 { + return Err(Error::Truncated); + } + + // Extract ppq from the raw data to detect SMPTE format. + let ppq_raw = u16::from_be_bytes([data[12], data[13]]); + + // Zero PPQ is invalid. + if ppq_raw == 0 { + return read_legacy(data); + } + + // SMPTE time division has the high bit set (raw & 0x8000 != 0). + // craft-midi doesn't handle SMPTE correctly, so use the legacy reader. + if ppq_raw & 0x8000 != 0 { + return read_legacy(data); + } + + // Check if the file looks truncated/damaged (no valid End of Track at end). + // Craft-midi doesn't handle truncation the same way as the legacy reader, + // so fall back to it for damaged files. + let is_damaged = !has_end_of_track(data); + + // Also check for markers at tick 0 (craft-midi may not include them). + let has_tick_zero = has_tick_zero_marker(data); + + if is_damaged || has_tick_zero { + return read_legacy(data); + } + + // For standard PPQ files, use craft-midi directly (no scaling needed). + let lr = read_smf_lenient(data).map_err(map_midi_error)?; + let craft_smf = &lr.smf; + + // Extract ppq from the raw data (craft-midi doesn't expose it directly). + let ppq = if data.len() >= 14 { u16::from_be_bytes([data[12], data[13]]) } else { 96u16 }; + + let mut smf = smf_to_craft(craft_smf, ppq); + // Copy warnings and instrument names from craft-midi's result. + smf.warnings = lr.warnings.clone(); + for (i, inst) in lr.instruments.iter().enumerate() { + if i < smf.tracks.len() && !inst.is_empty() { + smf.tracks[i].instrument = inst.clone(); + } + } + + // Cap tracks to the compatibility reader's MAX_TRACKS (craft-midi allows 4096, same limit). + // Count actual MTrk chunks in the file to detect if we exceeded the limit. + let mtrk_count = count_mtrk_chunks(data); + if smf.tracks.len() > MAX_TRACKS { + smf.tracks.truncate(MAX_TRACKS); + } else if mtrk_count > MAX_TRACKS { + // Craft-midi may have dropped some tracks; add a warning. + smf.warnings.push(format!("more than {MAX_TRACKS} tracks: the rest was left out")); + } + + // Drop empty tracks (no notes or changes) to match legacy reader behavior. + smf.tracks.retain(|t| !t.notes.is_empty() || !t.changes.is_empty()); + + // Truncate long names to MAX_TEXT (craft-midi may not truncate). + for track in &mut smf.tracks { + if track.name.len() > MAX_TEXT { + let mut end = MAX_TEXT; + while !track.name.is_char_boundary(end) { + end -= 1; + } + track.name.truncate(end); + } + } + + // Cap events to the compatibility reader's MAX_EVENTS (craft-midi allows 5M). + let total_notes: usize = smf.tracks.iter().map(|t| t.notes.len()).sum(); + let total_changes: usize = smf.tracks.iter().map(|t| t.changes.len()).sum(); + let total = total_notes + total_changes; + if total > MAX_EVENTS { + // Trim to fit within MAX_EVENTS, prioritizing notes then changes. + cap_events(&mut smf, MAX_EVENTS); + smf.warnings.push("holds more events than are read: the rest was left out".to_string()); + } + + // Compute ticks as max of ALL tick values (notes, tempos, signatures, markers). + let all_ticks = smf + .tracks + .iter() + .flat_map(|t| t.notes.iter().map(|n| n.start.saturating_add(n.len)).chain(std::iter::once(0u32))) + .chain(smf.tempos.iter().map(|t| t.tick)) + .chain(smf.time_signatures.iter().map(|t| t.tick)) + .chain(smf.key_signatures.iter().map(|k| k.tick)) + .chain(smf.markers.iter().map(|m| m.tick)); + smf.ticks = all_ticks.max().unwrap_or(0); + + Ok(smf) +} + +// Visit every track even after the budget is exhausted, clearing the remaining suffix. +fn cap_events(smf: &mut Smf, mut remaining: usize) { + for track in &mut smf.tracks { + let keep_notes = remaining.min(track.notes.len()); + track.notes.truncate(keep_notes); + remaining -= keep_notes; + let keep_changes = remaining.min(track.changes.len()); + track.changes.truncate(keep_changes); + remaining -= keep_changes; + } +} + +/// Check if the data ends with a valid End of Track marker. +fn has_end_of_track(data: &[u8]) -> bool { + // Look for the End of Track meta event near the end of the data. + // The pattern is: 0x00 0xFF 0x2F 0x00 (delta-time=0, meta=EndOfTrack, length=0). + if data.len() >= 4 { + let end = &data[data.len() - 4..]; + end == [0x00, 0xFF, 0x2F, 0x00] + } else { + false + } +} + +/// Check if the file has a marker/cue point at tick 0 (first event). +/// Craft-midi may not include these, so we fall back to the legacy reader. +fn has_tick_zero_marker(data: &[u8]) -> bool { + // Simple heuristic: scan track chunks for the pattern 0x00 0xFF 0x06/0x07 + // (delta=0 followed by marker/cue meta event). + if data.len() < 14 + 8 { + return false; + } + let mut pos = 14usize; // Skip header + while pos + 8 <= data.len() { + if data[pos..pos + 4] == *b"MTrk" { + let chunk_len = u32::from_be_bytes([data[pos + 4], data[pos + 5], data[pos + 6], data[pos + 7]]) as usize; + let chunk_end = (pos + 8 + chunk_len).min(data.len()); + // Scan for pattern: 0x00 (delta=0) 0xFF 0x06/0x07 + let mut p = pos + 8; // Start of chunk data + while p.saturating_add(5) <= chunk_end { + if data[p] == 0x00 && data[p + 1] == 0xFF && (data[p + 2] == 0x06 || data[p + 2] == 0x07) { + return true; + } + p += 1; + } + pos = chunk_end; + } else { + pos += 1; + } + } + false +} + +/// Count the number of MTrk chunks in the file. +fn count_mtrk_chunks(data: &[u8]) -> usize { + let mut count = 0; + let mut pos = 14usize; // Skip header + while pos + 8 <= data.len() { + if data[pos..pos + 4] == *b"MTrk" { + count += 1; + let chunk_len = u32::from_be_bytes([data[pos + 4], data[pos + 5], data[pos + 6], data[pos + 7]]) as usize; + pos += 8 + chunk_len; + } else { + pos += 1; + } + } + count +} + +/// Writes the file, returning an empty buffer on encoding failure. Use [`try_write`] +/// for production exports so an error cannot silently truncate the destination. +/// Format 0 is one track that holds everything; any other format is written as +/// format 1: a track for the tempo map, signatures and markers, then one per [`Track`]. +/// Delegates to craft-midi when the source PPQ is 960 (craft-midi's default); otherwise uses +/// the source-timed shared writer to preserve the source PPQ. +pub fn write(smf: &Smf) -> Vec { + try_write(smf).unwrap_or_default() +} + +/// Fallible export path. Call this before opening/truncating a destination file. +pub fn try_write(smf: &Smf) -> Result, craft_midi::MidiError> { + if u32::from(smf.ppq) == craft_midi::PPQ { write_smf(&smf_from_craft(smf)) } else { try_write_source_timed(smf, 512 * 1024 * 1024) } +} + +// --------------------------------------------------------------------------- +// Legacy compatibility: keep the old read/write implementations as fallback +// (The above delegates to craft-midi; these are kept for reference.) +// --------------------------------------------------------------------------- + +#[cfg(test)] +fn varlen(out: &mut Vec, value: u32) { + let value = value.min(0x0FFF_FFFF); + for shift in [21, 14, 7] { + if value >> shift != 0 { + out.push(((value >> shift) & 0x7F) as u8 | 0x80); + } + } + out.push((value & 0x7F) as u8); +} + +#[cfg(test)] +fn chunk(out: &mut Vec, id: &[u8; 4], body: &[u8]) { + out.extend_from_slice(id); + out.extend_from_slice(&(body.len().min(u32::MAX as usize) as u32).to_be_bytes()); + out.extend_from_slice(body); +} + +/// A message to write: its tick, its rank among the messages of that tick, and its bytes. +type Message = (u32, u8, Vec); + +/// Ranks at one tick: a note ends before the settings change, and those before a note starts. +const META: u8 = 0; +const NOTE_OFF: u8 = 1; +const CHANGE: u8 = 2; +const NOTE_ON: u8 = 3; + +fn meta(tick: u32, kind: u8, data: &[u8]) -> Result { + Ok((tick, META, craft_midi::encode_meta_event(kind, data)?)) +} + +/// The tempo map, the signatures and the markers. +fn conductor(smf: &Smf) -> Result, craft_midi::MidiError> { + let tempo = |t: &Tempo| { + let bpm = if t.bpm.is_finite() { t.bpm.clamp(1.0, 2000.0) } else { 120.0 }; + meta(t.tick, 0x51, &((60_000_000.0 / bpm).round() as u32).min(0x00FF_FFFF).to_be_bytes()[1..]) + }; + let time = |t: &TimeSignature| meta(t.tick, 0x58, &[t.beats.max(1), t.unit.clamp(1, 128).ilog2() as u8, 24, 8]); + let key = |k: &KeySignature| meta(k.tick, 0x59, &[k.sharps.clamp(-7, 7) as u8, u8::from(k.minor)]); + let marker = |m: &Marker| meta(m.tick, 0x06, m.name.as_bytes()); + (smf.tempos.iter().map(tempo)) + .chain(smf.time_signatures.iter().map(time)) + .chain(smf.key_signatures.iter().map(key)) + .chain(smf.markers.iter().map(marker)) + .collect() +} + +fn messages(track: &Track) -> Result, craft_midi::MidiError> { + let mut out = vec![meta(0, 0x03, track.name.as_bytes())?]; + if !track.instrument.is_empty() { + out.push(meta(0, 0x04, track.instrument.as_bytes())?); + } + out.extend(track.changes.iter().map(|c| { + let (status, value) = (c.channel & 0x0F, c.value.clamp(0, 127) as u8); + let bytes = match c.what { + What::Control(number) => vec![0xB0 | status, number & 0x7F, value], + What::Program => vec![0xC0 | status, value], + What::Pressure => vec![0xD0 | status, value], + What::Bend => { + let wheel = (i32::from(c.value) + 8192).clamp(0, 16383); + vec![0xE0 | status, (wheel & 0x7F) as u8, (wheel >> 7) as u8] + } + }; + (c.tick, CHANGE, bytes) + })); + out.extend(track.notes.iter().flat_map(|n| { + let (status, key) = (n.channel & 0x0F, n.key & 0x7F); + [ + (n.start, NOTE_ON, vec![0x90 | status, key, n.vel.clamp(1, 127)]), + (n.start.saturating_add(n.len.max(1)), NOTE_OFF, vec![0x80 | status, key, 0]), + ] + })); + Ok(out) +} + +/// Compatibility writer: keeps source ticks and Loop event policy, using shared SMF framing. +/// Returns an empty buffer if the conservative 512 MiB serialized-output budget is exceeded. +pub fn write_legacy(smf: &Smf) -> Vec { + try_write_source_timed(smf, 512 * 1024 * 1024).unwrap_or_default() +} + +/// Preserve Loop's source-tick/event policy while propagating framing failures. +/// The byte limit is conservative and does not bound caller-owned model memory. +pub fn try_write_source_timed(smf: &Smf, max_bytes: usize) -> Result, craft_midi::MidiError> { + let single = smf.format == 0; + let mut events = vec![conductor(smf)?]; + for track in smf.tracks.iter().take(u16::MAX as usize - 1) { + let track = messages(track)?; + if single { + if let Some(first) = events.first_mut() { + first.extend(track); + } + } else { + events.push(track); + } + } + let events = events + .into_iter() + .map(|track| track.into_iter().map(|(tick, order, bytes)| craft_midi::TimedEvent { tick: u64::from(tick), order, bytes }).collect()) + .collect(); + craft_midi::write_timed_smf(u16::from(!single), smf.ppq.clamp(1, 0x7fff), events, true, max_bytes) +} + +struct Reader<'a> { + data: &'a [u8], + pos: usize, +} + +impl<'a> Reader<'a> { + fn take(&mut self, n: usize) -> Result<&'a [u8], Error> { + let end = self.pos.checked_add(n).ok_or(Error::Truncated)?; + let slice = self.data.get(self.pos..end).ok_or(Error::Truncated)?; + self.pos = end; + Ok(slice) + } + + /// What is left of the data. + fn rest(&mut self) -> &'a [u8] { + let slice = self.data.get(self.pos..).unwrap_or_default(); + self.pos = self.data.len(); + slice + } + + fn byte(&mut self) -> Result { + self.take(1)?.first().copied().ok_or(Error::Truncated) + } + + fn u16(&mut self) -> Result { + match self.take(2)? { + [a, b] => Ok(u16::from_be_bytes([*a, *b])), + _ => Err(Error::Truncated), + } + } + + fn u32(&mut self) -> Result { + match self.take(4)? { + [a, b, c, d] => Ok(u32::from_be_bytes([*a, *b, *c, *d])), + _ => Err(Error::Truncated), + } + } + + fn varlen(&mut self) -> Result { + let mut value = 0u32; + for _ in 0..4 { + let b = self.byte()?; + value = (value << 7) | u32::from(b & 0x7F); + if b & 0x80 == 0 { + return Ok(value); + } + } + Err(Error::Truncated) + } + + fn done(&self) -> bool { + self.pos >= self.data.len() + } +} + +fn text(bytes: &[u8]) -> String { + String::from_utf8_lossy(bytes.get(..MAX_TEXT).unwrap_or(bytes)).trim_matches(|c: char| c.is_control() || c.is_whitespace()).to_string() +} + +/// Why a track's events stop before its End of Track. +type Stop = &'static str; +const CUT: Stop = "ends in the middle of an event"; + +/// A file being read: what is made of it, and the room left for its events. +struct Parse { + smf: Smf, + room: usize, + /// The notes sounding on each channel and key, oldest first: where each started and how hard. + sounding: Vec>, + /// Lyrics and polyphonic aftertouch, which are not kept. + lyrics: usize, + aftertouch: usize, + /// Tempo changes, signatures or markers past [`MAX_META`]. + crowded: bool, +} + +impl Parse { + fn warn(&mut self, what: String) { + if self.smf.warnings.len() < MAX_WARNINGS { + self.smf.warnings.push(what); + } + } + + /// Takes room for one more event; an error when the file holds more than are read. + fn event(&mut self) -> Result<(), Stop> { + self.room = self.room.checked_sub(1).ok_or("holds more events than are read: the rest was left out")?; + Ok(()) + } + + fn meta(&mut self, track: &mut Track, tick: u32, kind: u8, body: &[u8]) { + /// Whether `list` is full: `item` joins it otherwise. + fn full(list: &mut Vec, item: T) -> bool { + let room = list.len() < MAX_META; + if room { + list.push(item); + } + !room + } + let smf = &mut self.smf; + let crowded = match (kind, body) { + (0x03, _) if track.name.is_empty() => { + track.name = text(body); + false + } + (0x04, _) if track.instrument.is_empty() => { + track.instrument = text(body); + false + } + (0x05, _) => { + self.lyrics += 1; + false + } + (0x06 | 0x07, _) => full(&mut smf.markers, Marker { tick, name: text(body) }), + (0x51, [a, b, c]) => full(&mut smf.tempos, Tempo { tick, bpm: 60_000_000.0 / f64::from(u32::from_be_bytes([0, *a, *b, *c]).max(1)) }), + // (A beat is at most a 128th note; a bar of no beats is no signature.) + (0x58, [beats, power, ..]) if *beats > 0 && *power <= 7 => { + full(&mut smf.time_signatures, TimeSignature { tick, beats: *beats, unit: 1 << power }) + } + (0x59, [sharps, minor, ..]) => { + full(&mut smf.key_signatures, KeySignature { tick, sharps: (*sharps as i8).clamp(-7, 7), minor: *minor == 1 }) + } + _ => false, + }; + self.crowded |= crowded; + } + + /// Reads the events of a track up to its End of Track (`Ok`) or to where they stop making sense. + fn events(&mut self, r: &mut Reader, track: &mut Track, tick: &mut u32) -> Result<(), Stop> { + let mut status = 0u8; + loop { + if r.done() { + return Err("has no End of Track"); + } + *tick = tick.saturating_add(r.varlen().map_err(|_| CUT)?); + let first = r.byte().map_err(|_| CUT)?; + match first { + 0xFF => { + let kind = r.byte().map_err(|_| CUT)?; + let len = r.varlen().map_err(|_| CUT)? as usize; + let body = r.take(len).map_err(|_| CUT)?; + if kind == 0x2F { + return Ok(()); + } + self.meta(track, *tick, kind, body); + } + // System exclusive data is for one device: skipped by its length. + 0xF0 | 0xF7 => { + let len = r.varlen().map_err(|_| CUT)? as usize; + r.take(len).map_err(|_| CUT)?; + } + _ => { + // Running status: a data byte here reuses the status before it. (The status is + // kept across meta events too: some writers count on that.) + let mut data = || r.byte().map(|b| b & 0x7F).map_err(|_| CUT); + let one = if first & 0x80 != 0 { + status = first; + data()? + } else { + first + }; + let (kind, channel) = (status & 0xF0, status & 0x0F); + let (what, value) = match kind { + 0x80 | 0x90 => { + let vel = data()?; + let key = usize::from(channel) << 7 | usize::from(one); + // A note-on of no velocity is a note-off; an off ends the oldest note of its key. + if kind == 0x90 && vel > 0 { + self.event()?; + if let Some(open) = self.sounding.get_mut(key) { + open.push_back((*tick, vel)); + } + } else if let Some((start, vel)) = self.sounding.get_mut(key).and_then(VecDeque::pop_front) { + track.notes.push(Note { start, len: tick.saturating_sub(start).max(1), key: one, vel, channel }); + } + continue; + } + 0xA0 => { + data()?; + self.aftertouch += 1; + continue; + } + 0xB0 => (What::Control(one), i16::from(data()?)), + 0xC0 => (What::Program, i16::from(one)), + 0xD0 => (What::Pressure, i16::from(one)), + 0xE0 => (What::Bend, (i16::from(data()?) << 7 | i16::from(one)) - 8192), + _ => return Err("holds a byte that is no event"), + }; + self.event()?; + track.changes.push(Change { tick: *tick, channel, what, value }); + } + } + } + } + + /// Reads one track chunk. Returns how many of its bytes its events took when they end as + /// they should, with an End of Track. + fn track(&mut self, data: &[u8], number: usize) -> Option { + let (mut r, mut track, mut tick) = (Reader { data, pos: 0 }, Track::default(), 0u32); + let ended = self.events(&mut r, &mut track, &mut tick); + if let Err(why) = ended { + self.warn(format!("track {number} {why}: what came before is kept")); + } + // Notes never released end where the track does. + for (i, open) in self.sounding.iter_mut().enumerate() { + let (channel, key) = ((i >> 7) as u8, (i & 0x7F) as u8); + track.notes.extend(open.drain(..).map(|(start, vel)| Note { start, len: tick.saturating_sub(start).max(1), key, vel, channel })); + } + track.notes.sort_by_key(|n| (n.start, n.key)); + self.smf.ticks = self.smf.ticks.max(tick); + if !(track.notes.is_empty() && track.changes.is_empty()) { + self.smf.tracks.push(track); + } + ended.ok().map(|()| r.pos) + } +} + +/// Legacy read: reads a file of any format without craft-midi. +pub fn read_legacy(data: &[u8]) -> Result { + let mut r = Reader { data, pos: 0 }; + if r.take(4).map_err(|_| Error::NotMidi)? != b"MThd" { + return Err(Error::NotMidi); + } + let mut p = Parse { smf: Smf::default(), room: MAX_EVENTS, sounding: vec![VecDeque::new(); 16 * 128], lyrics: 0, aftertouch: 0, crowded: false }; + let header_len = r.u32()? as usize; + let header = match r.take(header_len) { + Ok(header) => header, + Err(_) => { + p.warn("the header gives a length the file does not have".into()); + r.take(6)? + } + }; + let mut header = Reader { data: header, pos: 0 }; + let (format, _count, raw) = (header.u16()?, header.u16()?, header.u16()?); + let (ppq, clock) = division(raw)?; + (p.smf.format, p.smf.ppq) = (if format > 2 { 1 } else { format }, ppq); + if format > 2 { + p.warn(format!("format {format} is unknown: read as tracks that play together")); + } + let mut seen = 0usize; + while !r.done() { + let at = r.pos; + let Ok((id, len)) = r.take(4).and_then(|id| Ok((id, r.u32()? as usize))) else { + p.warn(format!("{} bytes after the last chunk were ignored", data.len() - at)); + break; + }; + if id == b"MTrk" { + seen += 1; + if seen > MAX_TRACKS { + p.warn(format!("more than {MAX_TRACKS} tracks: the rest was left out")); + break; + } + let start = r.pos; + let (body, fits) = match r.take(len) { + Ok(body) => (body, true), + Err(_) => { + p.warn(format!("track {seen} is shorter than its length says")); + (r.rest(), false) + } + }; + // A length that reaches past the track's end into what follows is not believed: the + // next chunk is looked for where the track ended. + let next = data.get(r.pos..).unwrap_or_default(); + let believed = fits && (next.is_empty() || next.starts_with(b"MTrk")); + if let Some(used) = p.track(body, seen).filter(|used| *used < body.len() && !believed) { + r.pos = start + used; + if fits { + p.warn(format!("track {seen} ends before its length says")); + } + } + } else if id.iter().all(|b| b.is_ascii_graphic() || *b == b' ') && r.take(len).is_ok() { + // A chunk of another kind is skipped, as the specification asks. + } else { + // No chunk at all: the next track, if there is one, is looked for. + let after = data.get(at + 1..).unwrap_or_default(); + match after.windows(4).position(|w| w == b"MTrk") { + Some(skip) => { + p.warn(format!("{} bytes that are no chunk were skipped", skip + 1)); + r.pos = at + 1 + skip; + } + None => { + p.warn(format!("{} bytes after the last chunk were ignored", data.len() - at)); + break; + } + } + } + } + if p.lyrics > 0 { + p.warn(format!("{} lyrics were left out", p.lyrics)); + } + if p.aftertouch > 0 { + p.warn(format!("{} polyphonic aftertouch messages were left out", p.aftertouch)); + } + if p.crowded { + p.warn(format!("more than {MAX_META} tempo changes, signatures or markers: the rest was left out")); + } + let mut smf = p.smf; + if smf.format == 2 { + smf.warnings.push("format 2: each track is a song of its own; they are read side by side".into()); + } + // (Stable: of two tempos at one tick the later in the file stays the later.) + smf.tempos.sort_by_key(|t| t.tick); + one_tempo_a_tick(&mut smf.tempos); + smf.time_signatures.sort_by_key(|t| t.tick); + smf.key_signatures.sort_by_key(|k| k.tick); + smf.markers.sort_by_key(|m| m.tick); + if let Some(bpm) = clock { + smf.tempos = vec![Tempo { tick: 0, bpm }]; + smf.warnings + .push(format!("SMPTE time division: read as {ppq} ticks a beat at {bpm:.2} BPM, which keeps its timing; tempo changes are ignored")); + } + Ok(smf) +} + +/// The ticks a quarter note has, and for SMPTE time (ticks of the clock, not of the beat) the one +/// tempo at which that many ticks a beat keep the clock's time. +fn division(raw: u16) -> Result<(u16, Option), Error> { + if raw == 0 { + return Err(Error::Unsupported("a time division of zero")); + } + if raw & 0x8000 == 0 { + return Ok((raw, None)); + } + // Frames a second (as a negative number) and ticks a frame: a beat a second at 60 BPM. + // Twenty-nine stands for the 29.97 frames of drop-frame video. + let (frames, ticks) = (-i16::from((raw >> 8) as u8 as i8), raw & 0xFF); + let (nominal, bpm) = match frames { + 24 | 25 | 30 => (frames as u16, 60.0), + 29 => (30, 60.0 * 29.97 / 30.0), + _ => return Err(Error::Unsupported("an SMPTE time division with an unknown frame rate")), + }; + if ticks == 0 { + return Err(Error::Unsupported("an SMPTE time division of no ticks a frame")); + } + Ok((nominal * ticks, Some(bpm))) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::expect_used, clippy::indexing_slicing)] +mod tests { + use super::*; + + fn meta(tick: u32, kind: u8, data: &[u8]) -> Message { + let mut bytes = vec![0xFF, kind]; + varlen(&mut bytes, data.len() as u32); + bytes.extend_from_slice(data); + (tick, META, bytes) + } + + /// The tempo map, the signatures and the markers. + fn conductor(smf: &Smf) -> Vec { + let tempo = |t: &Tempo| { + let bpm = if t.bpm.is_finite() { t.bpm.clamp(1.0, 2000.0) } else { 120.0 }; + meta(t.tick, 0x51, &((60_000_000.0 / bpm).round() as u32).min(0x00FF_FFFF).to_be_bytes()[1..]) + }; + let time = |t: &TimeSignature| meta(t.tick, 0x58, &[t.beats.max(1), t.unit.clamp(1, 128).ilog2() as u8, 24, 8]); + let key = |k: &KeySignature| meta(k.tick, 0x59, &[k.sharps.clamp(-7, 7) as u8, u8::from(k.minor)]); + let marker = |m: &Marker| meta(m.tick, 0x06, m.name.as_bytes()); + (smf.tempos.iter().map(tempo)) + .chain(smf.time_signatures.iter().map(time)) + .chain(smf.key_signatures.iter().map(key)) + .chain(smf.markers.iter().map(marker)) + .collect() + } + + fn messages(track: &Track) -> Vec { + let mut out = vec![meta(0, 0x03, track.name.as_bytes())]; + if !track.instrument.is_empty() { + out.push(meta(0, 0x04, track.instrument.as_bytes())); + } + out.extend(track.changes.iter().map(|c| { + let (status, value) = (c.channel & 0x0F, c.value.clamp(0, 127) as u8); + let bytes = match c.what { + What::Control(number) => vec![0xB0 | status, number & 0x7F, value], + What::Program => vec![0xC0 | status, value], + What::Pressure => vec![0xD0 | status, value], + What::Bend => { + let wheel = (i32::from(c.value) + 8192).clamp(0, 16383); + vec![0xE0 | status, (wheel & 0x7F) as u8, (wheel >> 7) as u8] + } + }; + (c.tick, CHANGE, bytes) + })); + out.extend(track.notes.iter().flat_map(|n| { + let (status, key) = (n.channel & 0x0F, n.key & 0x7F); + [ + (n.start, NOTE_ON, vec![0x90 | status, key, n.vel.clamp(1, 127)]), + (n.start.saturating_add(n.len.max(1)), NOTE_OFF, vec![0x80 | status, key, 0]), + ] + })); + out + } + + fn track_chunk(out: &mut Vec, mut messages: Vec) { + messages.sort_by_key(|(tick, rank, _)| (*tick, *rank)); + let (mut body, mut last) = (Vec::new(), 0); + for (tick, _, bytes) in messages { + varlen(&mut body, tick - last); + last = tick; + body.extend_from_slice(&bytes); + } + body.extend_from_slice(&[0x00, 0xFF, 0x2F, 0x00]); + chunk(out, b"MTrk", &body); + } + + /// Legacy write: writes the file directly without craft-midi. + fn legacy_writer_oracle(smf: &Smf) -> Vec { + let tracks = || smf.tracks.iter().take(u16::MAX as usize - 1); + let single = smf.format == 0; + let mut out = Vec::new(); + let mut header = Vec::new(); + header.extend_from_slice(&u16::from(!single).to_be_bytes()); + header.extend_from_slice(&(if single { 1 } else { tracks().count() as u16 + 1 }).to_be_bytes()); + header.extend_from_slice(&smf.ppq.clamp(1, 0x7FFF).to_be_bytes()); + chunk(&mut out, b"MThd", &header); + if single { + track_chunk(&mut out, conductor(smf).into_iter().chain(tracks().flat_map(messages)).collect()); + } else { + track_chunk(&mut out, conductor(smf)); + tracks().for_each(|track| track_chunk(&mut out, messages(track))); + } + out + } + + #[test] + fn shared_source_timed_writer_matches_legacy_bytes() { + for ppq in [0, 1, 96, 480, 960, 32767, 65535] { + for format in [0, 1, 2] { + let mut smf = song(); + smf.ppq = ppq; + smf.format = format; + smf.tracks[0].instrument = "Acoustic Bass".into(); + smf.tracks[0].notes.extend([note(20, 100, 60, 90, 0), note(20, 200, 60, 110, 0), note(30, 10, 60, 50, 0)]); + smf.tempos.extend([Tempo { tick: 7, bpm: f64::NAN }, Tempo { tick: u32::MAX, bpm: 0.0 }]); + smf.markers.push(Marker { tick: 0, name: "Opening".into() }); + assert_eq!(write_legacy(&smf), legacy_writer_oracle(&smf), "PPQ {ppq}, format {format}"); + } + } + assert_eq!(write_legacy(&Smf::default()), legacy_writer_oracle(&Smf::default())); + } + #[test] + fn bounded_export_rejects_small_budget_without_successful_empty_file() { + assert!(try_write_source_timed(&song(), 1).is_err()); + } + + fn note(start: u32, len: u32, key: u8, vel: u8, channel: u8) -> Note { + Note { start, len, key, vel, channel } + } + + fn song() -> Smf { + Smf { + tempos: vec![Tempo { tick: 0, bpm: 125.0 }], + tracks: vec![ + Track { name: "Bass".into(), notes: vec![note(0, 48, 33, 100, 0), note(96, 20000, 36, 1, 0)], ..Track::default() }, + Track { name: "Chords".into(), notes: (0..3).map(|i| note(384, 360, 57 + i * 4, 90, 1)).collect(), ..Track::default() }, + ], + ticks: 20096, + ..Smf::default() + } + } + + /// A file of the given format and division with these track bodies (End of Track is added). + fn file(format: u16, division: u16, tracks: &[&[u8]]) -> Vec { + let mut out = Vec::new(); + let header = [format.to_be_bytes(), (tracks.len() as u16).to_be_bytes(), division.to_be_bytes()].concat(); + chunk(&mut out, b"MThd", &header); + for body in tracks { + chunk(&mut out, b"MTrk", &[body, &[0x00, 0xFF, 0x2F, 0x00][..]].concat()); + } + out + } + + #[test] + fn round_trip() { + assert_eq!(read(&write(&song())).unwrap(), song()); + assert_eq!(Smf::default().tempo(), 120.0); + // A tempo is kept in whole microseconds a beat: close, not exact. + let odd = read(&write(&Smf { tempos: vec![Tempo { tick: 0, bpm: 126.0 }], ..song() })).unwrap(); + assert!((odd.tempo() - 126.0).abs() < 0.001 && odd.tracks == song().tracks); + } + + #[test] + fn everything_a_file_holds_round_trips_in_either_format() { + let change = |tick, channel, what, value| Change { tick, channel, what, value }; + let full = Smf { + ppq: 480, + tempos: vec![Tempo { tick: 0, bpm: 120.0 }, Tempo { tick: 960, bpm: 100.0 }, Tempo { tick: 1920, bpm: 150.0 }], + time_signatures: vec![TimeSignature { tick: 0, beats: 6, unit: 8 }, TimeSignature { tick: 1440, beats: 7, unit: 16 }], + key_signatures: vec![KeySignature { tick: 0, sharps: -3, minor: true }], + markers: vec![Marker { tick: 0, name: "Intro".into() }, Marker { tick: 1920, name: "Verse é".into() }], + tracks: vec![ + Track { + name: "Keys".into(), + instrument: "Grand".into(), + notes: vec![note(0, 480, 60, 64, 2), note(480, 480, 60, 127, 2), note(480, 1, 72, 1, 2)], + changes: vec![ + change(0, 2, What::Control(cc::BANK), 1), + change(0, 2, What::Program, 5), + change(0, 2, What::Control(cc::VOLUME), 90), + change(10, 2, What::Bend, -8192), + change(20, 2, What::Bend, 8191), + change(30, 2, What::Pressure, 77), + change(40, 2, What::Control(cc::SUSTAIN), 127), + change(40, 2, What::Control(93), 12), + ], + }, + Track { name: "Drums".into(), notes: vec![note(0, 24, 36, 110, DRUMS)], ..Track::default() }, + ], + ticks: 1920, + ..Smf::default() + }; + assert_eq!(read(&write(&full)).unwrap(), full); + assert_eq!(full.tracks[0].controls(2, cc::SUSTAIN).map(|c| c.value).collect::>(), [127]); + + // Format 0 is one track: the same notes and messages, under the first name. + let single = read(&write(&Smf { format: 0, ..full.clone() })).unwrap(); + assert_eq!((single.format, single.tracks.len(), single.tracks[0].name.as_str()), (0, 1, "Keys")); + assert_eq!((single.tracks[0].notes.len(), single.tracks[0].changes.len()), (4, 8)); + assert_eq!((&single.tempos, &single.markers, &single.time_signatures), (&full.tempos, &full.markers, &full.time_signatures)); + } + + #[test] + fn reads_running_status_format_0_and_note_on_velocity_zero() { + let smf = read(&file(0, 96, &[&[0x00, 0x90, 60, 100, 0x30, 64, 90, 0x30, 60, 0, 0x00, 64, 0]])).unwrap(); + assert_eq!(smf.tracks[0].notes, [note(0, 96, 60, 100, 0), note(48, 48, 64, 90, 0)]); + assert_eq!((smf.tempo(), smf.format, smf.ticks, smf.warnings.len()), (120.0, 0, 96, 0)); + // Running status goes on across a meta event and system exclusive data, which are skipped by their length. + let body = [0x00, 0x90, 60, 100, 0x00, 0xFF, 0x01, 0x02, b'h', b'i', 0x00, 0xF0, 0x03, 1, 2, 0xF7, 0x10, 60, 0, 0x00, 0xF7, 0x01, 0x55]; + assert_eq!(read(&file(1, 96, &[&body])).unwrap().tracks[0].notes, [note(0, 16, 60, 100, 0)]); + } + + #[test] + fn notes_of_one_key_that_overlap_end_oldest_first_and_unended_ones_end_with_the_track() { + // On, on, off, off of one key; then a note that is never released. + let body = [0x00, 0x90, 60, 100, 0x0A, 60, 50, 0x0A, 0x80, 60, 0, 0x0A, 60, 0, 0x00, 0x91, 40, 9, 0x20, 0xB1, 7, 1]; + let smf = read(&file(1, 96, &[&body])).unwrap(); + assert_eq!(smf.tracks[0].notes, [note(0, 20, 60, 100, 0), note(10, 20, 60, 50, 0), note(30, 32, 40, 9, 1)]); + } + + #[test] + fn any_division_is_rescaled_with_what_was_together_still_together_and_no_note_without_length() { + let mut rng = 12345u32; + let mut next = |n: u32| { + rng = rng.wrapping_mul(1_664_525).wrapping_add(1_013_904_223); + (rng >> 8) % n + }; + for ppq in [1u16, 24, 96, 100, 120, 480, 960, 1000, 32767] { + let starts: Vec = (0..40).map(|_| next(u32::from(ppq) * 8)).collect(); + // Chords of two on one start, and each note followed at once by another. + let notes: Vec = (starts.iter().enumerate()) + .flat_map(|(i, start)| { + let len = 1 + next(u32::from(ppq)); + [note(*start, len, 10, 80, 0), note(*start, 1, 20 + i as u8, 80, 0), note(*start + len, 1 + next(3), 80, 80, 0)] + }) + .collect(); + let mut smf = Smf { + ppq, + tracks: vec![Track { notes: notes.clone(), ..Track::default() }], + markers: vec![Marker { tick: starts[0], name: "m".into() }], + ..Smf::default() + }; + smf.rescale(96); + assert_eq!(smf.ppq, 96); + let scaled = &smf.tracks[0].notes; + for (before, after) in notes.chunks(3).zip(scaled.chunks(3)) { + assert!(after.iter().all(|n| n.len >= 1), "{ppq}: {after:?}"); + assert_eq!(after[0].start, after[1].start, "{ppq}: a chord stays a chord"); + assert_eq!(after[0].start + after[0].len, after[2].start.max(after[0].start + 1), "{ppq}: what touched still touches ({before:?})"); + let exact = f64::from(before[0].start) * 96.0 / f64::from(ppq); + assert!((f64::from(after[0].start) - exact).abs() <= 0.5, "{ppq}: the nearest tick"); + } + assert_eq!(smf.markers[0].tick, scaled[0].start, "{ppq}: a marker stays on its note"); + } + // A whole number of times finer is exact, and back. + let mut fine = song(); + fine.rescale(480); + assert_eq!(fine.tracks[0].notes[0], note(0, 240, 33, 100, 0)); + fine.rescale(96); + assert_eq!(fine, song()); + // Tempos that land on one tick leave the last. + let mut coarse = Smf { + ppq: 960, + tempos: vec![Tempo { tick: 0, bpm: 100.0 }, Tempo { tick: 2, bpm: 110.0 }, Tempo { tick: 960, bpm: 90.0 }], + ..Smf::default() + }; + coarse.rescale(96); + assert_eq!(coarse.tempos, [Tempo { tick: 0, bpm: 110.0 }, Tempo { tick: 96, bpm: 90.0 }]); + } + + #[test] + fn smpte_time_is_read_at_the_tempo_that_keeps_its_clock() { + let body = [0x00, 0xFF, 0x51, 0x03, 0x07, 0xA1, 0x20, 0x00, 0x90, 60, 100, 0x87, 0x68, 60, 0]; + // 25 frames of 40 ticks: a thousand ticks a second, so the note lasts one second, one beat at 60 BPM. + let smf = read(&file(1, u16::from_be_bytes([(-25i8) as u8, 40]), &[&body])).unwrap(); + assert_eq!((smf.ppq, smf.tempos.as_slice(), smf.tracks[0].notes[0].len), (1000, &[Tempo { tick: 0, bpm: 60.0 }][..], 1000)); + assert!(smf.warnings.iter().any(|w| w.contains("SMPTE"))); + let drop = read(&file(1, u16::from_be_bytes([(-29i8) as u8, 80]), &[&body])).unwrap(); + assert_eq!(drop.ppq, 2400); + assert!((drop.tempo() - 59.94).abs() < 1e-9); + for bad in [[(-7i8) as u8, 40], [(-25i8) as u8, 0], [0, 0]] { + assert!(matches!(read(&file(1, u16::from_be_bytes(bad), &[&body])), Err(Error::Unsupported(_))), "{bad:?}"); + } + } + + #[test] + fn damaged_files_give_what_can_be_read_and_say_what_could_not() { + let one: &[u8] = &[0x00, 0x90, 60, 100, 0x60, 0x80, 60, 0]; + let two: &[u8] = &[0x00, 0x91, 62, 100, 0x60, 0x81, 62, 0]; + let good = file(1, 96, &[one, two]); + let keys = |smf: &Smf| smf.tracks.iter().map(|t| t.notes.iter().map(|n| n.key).collect::>()).collect::>(); + let both = vec![vec![60], vec![62]]; + assert_eq!((keys(&read(&good).unwrap()), read(&good).unwrap().warnings.len()), (both.clone(), 0)); + + // Garbage after the last chunk, long or short. + for junk in [&b"\0\0\0"[..], &b"garbage that is no chunk at all"[..], &[0xFF; 9][..]] { + let smf = read(&[&good[..], junk].concat()).unwrap(); + assert_eq!((keys(&smf), smf.warnings.len()), (both.clone(), 1), "{junk:?}: {:?}", smf.warnings); + } + // A chunk of another kind between the tracks is skipped without a word. + let mut alien = file(1, 96, &[one]); + chunk(&mut alien, b"XFIH", &[1, 2, 3]); + chunk(&mut alien, b"MTrk", &[two, &[0x00, 0xFF, 0x2F, 0x00][..]].concat()); + assert_eq!((keys(&read(&alien).unwrap()), read(&alien).unwrap().warnings.len()), (both.clone(), 0)); + + // The first track's length says too much (it swallows the second), too little, or nothing. + let len_at = 14 + 4; + for (len, tracks) in [(15u32, both.clone()), (200, both.clone()), (u32::MAX, both.clone()), (6, both.clone()), (0, vec![vec![62]])] { + let mut bad = good.clone(); + bad[len_at..len_at + 4].copy_from_slice(&len.to_be_bytes()); + let smf = read(&bad).unwrap(); + assert_eq!(keys(&smf), tracks, "length {len}: {:?}", smf.warnings); + assert!(!smf.warnings.is_empty(), "length {len}"); + } + // A file cut inside its last track keeps the notes before the cut, the open one ending there. + let cut = read(&good[..good.len() - 7]).unwrap(); + assert_eq!((keys(&cut), cut.tracks[1].notes[0].len), (both.clone(), 96)); + assert!(cut.warnings.iter().any(|w| w.contains("track 2")), "{:?}", cut.warnings); + // A data byte before any status, and a system message that has no place in a file. + for bad in [&[0x00, 60, 100][..], &[0x00, 0x90, 60, 100, 0x00, 0xF8, 0x00, 0x90, 62, 100][..]] { + let smf = read(&file(1, 96, &[bad, two])).unwrap(); + assert!(smf.warnings.iter().any(|w| w.contains("no event")) && keys(&smf).last() == Some(&vec![62]), "{:?}", smf.warnings); + } + // A header with a wrong length, and one that is longer than six bytes. + let mut long = good.clone(); + long[4..8].copy_from_slice(&u32::MAX.to_be_bytes()); + assert_eq!(keys(&read(&long).unwrap()), both); + let mut roomy = Vec::new(); + chunk(&mut roomy, b"MThd", &[0, 1, 0, 1, 0, 96, 9, 9]); + roomy.extend_from_slice(&good[14..]); + assert_eq!(keys(&read(&roomy).unwrap()), both); + // Formats: 2 is read side by side, an unknown one as 1, both with a word about it. + assert_eq!(read(&file(2, 96, &[one, two])).map(|smf| (smf.format, smf.tracks.len(), smf.warnings.len())), Ok((2, 2, 1))); + assert_eq!(read(&file(7, 96, &[one])).map(|smf| (smf.format, smf.warnings.len())), Ok((1, 1))); + } + + #[test] + fn meta_events_are_kept_or_counted_and_never_trusted() { + let body = [ + &[0x00, 0xFF, 0x03, 0x05][..], + b"Lead\0", + &[0x00, 0xFF, 0x03, 0x01, b'x'], + &[0x00, 0xFF, 0x04, 0x03], + b"Sax", + &[0x00, 0xFF, 0x58, 0x04, 3, 3, 24, 8], + // A signature of no beats, one of a 2^200th note, a tempo of the wrong length and one of zero. + &[ + 0x00, 0xFF, 0x58, 0x04, 0, 2, 24, 8, 0x00, 0xFF, 0x58, 0x04, 4, 200, 24, 8, 0x00, 0xFF, 0x51, 0x02, 1, 2, 0x00, 0xFF, 0x51, 0x03, 0, + 0, 0, + ], + &[0x00, 0xFF, 0x59, 0x02, 0xFE, 0x00, 0x00, 0xFF, 0x05, 0x02, b'l', b'a', 0x00, 0xFF, 0x07, 0x03], + b"cue", + &[0x60, 0xFF, 0x06, 0x01, b'B', 0x00, 0xA0, 60, 5, 0x00, 0x90, 60, 1, 0x01, 60, 0], + ] + .concat(); + let smf = read(&file(1, 96, &[&body])).unwrap(); + assert_eq!((smf.tracks[0].name.as_str(), smf.tracks[0].instrument.as_str()), ("Lead", "Sax")); + assert_eq!(smf.time_signatures, [TimeSignature { tick: 0, beats: 3, unit: 8 }]); + assert_eq!(smf.key_signatures, [KeySignature { tick: 0, sharps: -2, minor: false }]); + assert_eq!(smf.markers, [Marker { tick: 0, name: "cue".into() }, Marker { tick: 96, name: "B".into() }]); + assert_eq!(smf.tempos, [Tempo { tick: 0, bpm: 60_000_000.0 }]); + assert_eq!(smf.warnings.len(), 2, "lyrics and aftertouch: {:?}", smf.warnings); + } + + #[test] + fn a_file_of_any_size_is_read_into_a_bounded_number_of_events() { + // Three bytes a note-on under running status: more notes than are read, none of them ended. + let mut body = vec![0x00, 0x90, 60, 100]; + body.extend((0..MAX_EVENTS + 1000).flat_map(|i| [0x00, (i % 128) as u8, 1])); + let smf = read(&file(1, 96, &[&body])).unwrap(); + assert_eq!(smf.tracks[0].notes.len(), MAX_EVENTS); + assert!(smf.warnings.iter().any(|w| w.contains("more events"))); + // Tracks of nothing, by the thousand: the count stops the reading, and none is kept. + let smf = read(&file(1, 96, &vec![&[][..]; MAX_TRACKS + 5])).unwrap(); + assert!(smf.tracks.is_empty() && smf.warnings.iter().any(|w| w.contains("tracks"))); + // A text of thousands of bytes is a name of a few. + let mut named = vec![0x00, 0xFF, 0x03, 0x83, 0x80, 0x00]; + named.extend(vec![b'a'; 0xC000]); + named.extend([0x00, 0x90, 1, 1]); + assert_eq!(read(&file(1, 96, &[&named])).unwrap().tracks[0].name.len(), MAX_TEXT); + } + + #[test] + fn damaged_files_are_errors_not_panics() { + assert_eq!(read(b""), Err(Error::NotMidi)); + assert_eq!(read(b"RIFFxxxxWAVE"), Err(Error::NotMidi)); + assert_eq!(read(b"MThd\0\0\0\x06\0\x01"), Err(Error::Truncated)); + let good = write(&song()); + for cut in 0..good.len() { + let _ = read(&good[..cut]); + } + // Every byte flipped, one at a time: must return, never panic or hang. + for i in 0..good.len() { + let mut bad = good.clone(); + bad[i] ^= 0xFF; + let _ = read(&bad); + } + } + + #[test] + fn varlen_encoding_matches_the_specification_examples() { + for (value, bytes) in [ + (0u32, vec![0x00]), + (0x7F, vec![0x7F]), + (0x80, vec![0x81, 0x00]), + (0x3FFF, vec![0xFF, 0x7F]), + (0x200000, vec![0x81, 0x80, 0x80, 0x00]), + (0x0FFFFFFF, vec![0xFF, 0xFF, 0xFF, 0x7F]), + ] { + let mut out = Vec::new(); + varlen(&mut out, value); + assert_eq!(out, bytes, "{value:#x}"); + assert_eq!(Reader { data: &bytes, pos: 0 }.varlen().unwrap(), value); + } + } + + #[test] + fn long_utf8_track_name_is_truncated_at_a_character_boundary() { + let mut smf = song(); + smf.tracks[0].name = format!("{}é", "a".repeat(255)); + let bytes = try_write(&smf).unwrap(); + let result = read(&bytes).unwrap(); + assert!(result.tracks[0].name.len() <= MAX_TEXT); + assert!(result.tracks[0].name.is_char_boundary(result.tracks[0].name.len())); + } + + #[test] + fn event_cap_clears_later_track_events() { + let mut smf = song(); + let track = smf.tracks[0].clone(); + smf.tracks = vec![track.clone(), track.clone(), track]; + cap_events(&mut smf, 1); + assert_eq!(smf.tracks.iter().map(|t| t.notes.len() + t.changes.len()).sum::(), 1); + assert!(smf.tracks[1].notes.is_empty() && smf.tracks[2].notes.is_empty()); + } +} From bd0ed73e027281c483d2833376a2969aead7e776 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Mon, 16 Nov 2026 21:23:24 -0500 Subject: [PATCH 03/64] craft-tiff: direct YCbCr RGBA decoding with explicit colour policy (#1967) --- crates/tiff/src/ycbcr.rs | 101 +++++++++++++++++++++++++++++++++- crates/tiff/tests/it/ycbcr.rs | 48 ++++++++++++++++ 2 files changed, 146 insertions(+), 3 deletions(-) diff --git a/crates/tiff/src/ycbcr.rs b/crates/tiff/src/ycbcr.rs index a0b7e7dde..38e8d7c9b 100644 --- a/crates/tiff/src/ycbcr.rs +++ b/crates/tiff/src/ycbcr.rs @@ -199,6 +199,103 @@ pub fn expand_units(units: &[u8], width: u32, height: u32, (h, v): (u32, u32)) - /// uncompressed or PackBits; anything else is [`TiffError::Invalid`]. More than `max_pixels` /// pixels is [`TiffError::Limit`], and a file too small to hold the image is refused before the data units are allocated. pub fn decode_rgb8(data: &[u8], ifd: &Ifd, max_pixels: u64) -> crate::Result> { + let DecodedUnits { width, height, sub, units } = decode_units(data, ifd, max_pixels)?; + let mut rgb = expand_units(&units, width, height, sub).ok_or_else(|| TiffError::Invalid("YCbCr image: data units".into()))?; + YCbCr::from_ifd(ifd, 255).convert_u8(&mut rgb, 3); + Ok(rgb) +} + +/// Colour interpretation for direct RGBA decoding. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum ColorPolicy { + /// Existing shared/libtiff conversion; unusable colour tags use defaults. + Libtiff, + /// Literal TIFF 6.0 green equation, with malformed colour tags rejected. + /// Retains the historical FilmCraft interpretation, including non-unit-sum weights. + TiffEquation, +} + +/// Decode directly into opaque RGBA without an intermediate RGB image. +/// Uses the same strip/subsampling/PackBits validation as [`decode_rgb8`]. +/// Output allocation is checked and fallible. Orientation is left to the caller. +pub fn decode_rgba8(data: &[u8], ifd: &Ifd, max_pixels: u64, policy: ColorPolicy) -> crate::Result> { + let color = match policy { + ColorPolicy::Libtiff => YCbCr::from_ifd(ifd, 255), + ColorPolicy::TiffEquation => strict_color(ifd)?, + }; + let DecodedUnits { width, height, sub: (sh, sv), units } = decode_units(data, ifd, max_pixels)?; + let len = u64::from(width) + .checked_mul(u64::from(height)) + .and_then(|n| n.checked_mul(4)) + .filter(|&n| n <= isize::MAX as u64) + .and_then(|n| usize::try_from(n).ok()) + .ok_or(TiffError::Limit("pixel count"))?; + let mut rgba = Vec::new(); + rgba.try_reserve_exact(len).map_err(|_| TiffError::Limit("memory"))?; + rgba.resize(len, 255); + let (w, h, sh, sv) = (width as usize, height as usize, sh as usize, sv as usize); + let units_x = w.div_ceil(sh); + let tables = (policy == ColorPolicy::Libtiff).then(|| color.tables(255)); + for (i, unit) in units.chunks_exact(sh * sv + 2).enumerate() { + let (ux, uy) = (i % units_x, i / units_x); + let (luma, chroma) = unit.split_at(sh * sv); + let [cb, cr] = <[u8; 2]>::try_from(chroma).map_err(|_| TiffError::Invalid("YCbCr data unit".into()))?; + for (k, &y) in luma.iter().enumerate() { + let (x, row) = (ux * sh + k % sh, uy * sv + k / sh); + if x < w && row < h { + let rgb = match &tables { + Some(t) => t.rgb(usize::from(y), usize::from(cb), usize::from(cr)).map(|v| v as u8), + None => tiff_rgb(&color, y, cb, cr), + }; + let at = (row * w + x) * 4; + if let Some(px) = rgba.get_mut(at..at + 3) { + px.copy_from_slice(&rgb); + } + } + } + } + Ok(rgba) +} + +fn strict_color(ifd: &Ifd) -> crate::Result { + let defaults = YCbCr::defaults(255); + let luma = match ifd.f64s(YCBCR_COEFFICIENTS) { + None => defaults.luma, + Some(v) => v.get(..3).and_then(|v| v.try_into().ok()).ok_or_else(|| TiffError::Invalid("invalid YCbCrCoefficients".into()))?, + }; + let reference_black_white = match ifd.f64s(REFERENCE_BLACK_WHITE) { + None => defaults.reference_black_white, + Some(v) => v.get(..6).and_then(|v| v.try_into().ok()).ok_or_else(|| TiffError::Invalid("invalid ReferenceBlackWhite".into()))?, + }; + if luma.iter().any(|v| !v.is_finite()) || luma[1].abs() < 1e-6 { + return Err(TiffError::Invalid("invalid YCbCrCoefficients".into())); + } + if reference_black_white.iter().any(|v| !v.is_finite()) || reference_black_white.as_chunks::<2>().0.iter().any(|[b, w]| (w - b).abs() < 1e-6) { + return Err(TiffError::Invalid("invalid ReferenceBlackWhite".into())); + } + Ok(YCbCr { luma, reference_black_white }) +} + +fn tiff_rgb(color: &YCbCr, y: u8, cb: u8, cr: u8) -> [u8; 3] { + let [lr, lg, lb] = color.luma; + let [yb, yw, cbb, cbw, crb, crw] = color.reference_black_white; + let y = (f64::from(y) - yb) * 255.0 / (yw - yb); + let cb = (f64::from(cb) - cbb) * 127.0 / (cbw - cbb); + let cr = (f64::from(cr) - crb) * 127.0 / (crw - crb); + let r = cr * (2.0 - 2.0 * lr) + y; + let b = cb * (2.0 - 2.0 * lb) + y; + let g = (y - lb * b - lr * r) / lg; + [r, g, b].map(|v| v.round().clamp(0.0, 255.0) as u8) +} + +struct DecodedUnits { + width: u32, + height: u32, + sub: (u32, u32), + units: Vec, +} + +fn decode_units(data: &[u8], ifd: &Ifd, max_pixels: u64) -> crate::Result { // TiffError has no "unsupported" variant; adding one would break exhaustive matches downstream. let unsupported = |what: &str| TiffError::Invalid(format!("unsupported YCbCr image with {what}")); let invalid = |what: &str| TiffError::Invalid(format!("YCbCr image: {what}")); @@ -265,7 +362,5 @@ pub fn decode_rgb8(data: &[u8], ifd: &Ifd, max_pixels: u64) -> crate::Result = rgb.as_chunks::<3>().0.iter().flat_map(|px| [px[0], px[1], px[2], 255]).collect(); + for policy in [ycbcr::ColorPolicy::Libtiff, ycbcr::ColorPolicy::TiffEquation] { + assert_eq!(ycbcr::decode_rgba8(&bytes, &t.ifds[0], 15, policy).unwrap(), expected); + assert_eq!(ycbcr::decode_rgba8(&bytes, &t.ifds[0], 14, policy), Err(TiffError::Limit("pixel count"))); + } + } + } + } +} + +#[test] +fn explicit_tiff_policy_keeps_literal_green_equation_and_rejects_bad_tags() { + use ycbcr::ColorPolicy::{Libtiff, TiffEquation}; + let run = |extra: &[(u16, Value)], policy| { + let bytes = file(1, 1, (1, 1), &[128, 128, 128], false, extra); + let t = Tiff::parse(&bytes).unwrap(); + ycbcr::decode_rgba8(&bytes, &t.ifds[0], 1, policy) + }; + let weights = [(YCBCR_COEFFICIENTS, Value::Rational(vec![(4, 10); 3]))]; + assert_eq!(run(&weights, Libtiff).unwrap(), [128, 128, 128, 255]); + assert_eq!(run(&weights, TiffEquation).unwrap(), [128, 64, 128, 255]); + for bad in [ + (YCBCR_COEFFICIENTS, Value::Rational(vec![(1, 2)])), + (YCBCR_COEFFICIENTS, Value::Double(vec![0.3, 0.0, 0.7])), + (YCBCR_COEFFICIENTS, Value::Double(vec![f64::NAN, 0.5, 0.5])), + (REFERENCE_BLACK_WHITE, Value::Rational(vec![(0, 1); 6])), + (REFERENCE_BLACK_WHITE, Value::Double(vec![0.0, 255.0])), + ] { + assert!(matches!(run(std::slice::from_ref(&bad), TiffEquation), Err(TiffError::Invalid(_)))); + assert!(run(&[bad], Libtiff).is_ok()); + } +} From ba3a5e71a0c3a0129ed5a863562a8cfcb1103aba Mon Sep 17 00:00:00 2001 From: ljkx Date: Tue, 17 Nov 2026 03:27:31 +0100 Subject: [PATCH 04/64] craft-doc-binary: a .doc writer, and tracked changes read (#1970) --- crates/doc-binary/README.md | 21 +- crates/doc-binary/src/fmt.rs | 13 +- crates/doc-binary/src/lib.rs | 69 ++- crates/doc-binary/src/list.rs | 14 +- crates/doc-binary/src/metadata.rs | 6 + crates/doc-binary/src/notes.rs | 24 +- crates/doc-binary/src/piece.rs | 11 +- crates/doc-binary/src/rmark.rs | 232 ++++++++ crates/doc-binary/src/sprm.rs | 2 + crates/doc-binary/src/tests.rs | 51 +- crates/doc-binary/src/write/fkp.rs | 280 +++++++++ crates/doc-binary/src/write/grpprl.rs | 753 +++++++++++++++++++++++++ crates/doc-binary/src/write/lists.rs | 184 ++++++ crates/doc-binary/src/write/mod.rs | 463 +++++++++++++++ crates/doc-binary/src/write/picture.rs | 211 +++++++ crates/doc-binary/src/write/story.rs | 735 ++++++++++++++++++++++++ crates/doc-binary/src/write/styles.rs | 400 +++++++++++++ crates/doc-binary/src/write/summary.rs | 112 ++++ crates/doc-binary/src/write/tables.rs | 224 ++++++++ crates/doc-binary/src/write/tests.rs | 707 +++++++++++++++++++++++ 20 files changed, 4471 insertions(+), 41 deletions(-) create mode 100644 crates/doc-binary/src/rmark.rs create mode 100644 crates/doc-binary/src/write/fkp.rs create mode 100644 crates/doc-binary/src/write/grpprl.rs create mode 100644 crates/doc-binary/src/write/lists.rs create mode 100644 crates/doc-binary/src/write/mod.rs create mode 100644 crates/doc-binary/src/write/picture.rs create mode 100644 crates/doc-binary/src/write/story.rs create mode 100644 crates/doc-binary/src/write/styles.rs create mode 100644 crates/doc-binary/src/write/summary.rs create mode 100644 crates/doc-binary/src/write/tables.rs create mode 100644 crates/doc-binary/src/write/tests.rs diff --git a/crates/doc-binary/README.md b/crates/doc-binary/README.md index 359a7bce3..0245cada8 100644 --- a/crates/doc-binary/README.md +++ b/crates/doc-binary/README.md @@ -1,22 +1,33 @@ # craft-doc-binary -Reader for the Word 97-2003 binary file format (`.doc`, [MS-DOC]) into the `craft-wordmodel` -document model. It is WordCraft's reader, on `craft-cfb` for the compound file and -`craft-codepage` for 8-bit text. +Reader and writer for the Word 97-2003 binary file format (`.doc`, [MS-DOC]) and the +`craft-wordmodel` document model. It is WordCraft's reader and writer, on `craft-cfb` for the +compound file and `craft-codepage` for 8-bit text. ```rust // Not a compound file: an error, never a panic. assert!(craft_doc_binary::read(b"not a .doc").is_err()); assert!(!craft_doc_binary::is_encrypted(b"not a .doc")); + +// A document written as a .doc reads back. +let bytes = craft_doc_binary::write(&craft_wordmodel::Document::from_text("Hello")).unwrap(); +let doc = craft_doc_binary::read(&bytes).unwrap(); +assert_eq!(doc.body[0].as_para().map(|p| p.text.as_str()), Some("Hello")); ``` -- `read(bytes)`, `read_with_password(bytes, Option<&str>)`, `is_encrypted(bytes)`. +- `read(bytes)`, `read_with_password(bytes, Option<&str>)`, `is_encrypted(bytes)`, `write(&document)`. - Text in pieces (8-bit and UTF-16), paragraph and character formatting, styles, lists, tables, sections, headers and footers, notes, comments, fields, bookmarks, pictures and OfficeArt shapes, document properties. - XOR obfuscation, RC4 and RC4 CryptoAPI password protection. +- Tracked insertions and deletions, with their author and time. -There is no writer. +`write` produces a Word 97-2003 file (nFib 0x00C1, a version 3 compound file): text, character +and paragraph formatting, styles, fonts, lists, tables, sections with headers and footers, +footnotes and endnotes, fields and hyperlinks, bookmarks, inline pictures, tracked insertions +and deletions, and the document properties. Floating pictures are written in line, nested tables +become paragraphs of their cell, and shapes, charts, text boxes and comments are left out, each +kind logged once per save. It never writes a password-protected file. ## Limits diff --git a/crates/doc-binary/src/fmt.rs b/crates/doc-binary/src/fmt.rs index 1b8be2333..8c5a0db95 100644 --- a/crates/doc-binary/src/fmt.rs +++ b/crates/doc-binary/src/fmt.rs @@ -110,8 +110,8 @@ pub(crate) fn ico(i: u8) -> Option { } /// The model border style a `brcType` stands for ([MS-DOC] §2.9.22 BrcType; 0x02, thick, is in -/// the BRC of Microsoft's Word 97-2007 specification). Types the model doesn't carry (the gap -/// variants, 3-D, inset/outset) draw as single lines, as the DOCX reader maps them. +/// the BRC of Microsoft's Word 97-2007 specification); 0x0B-0x13 are the thin/thick compound +/// lines. Types the model doesn't carry (3-D, inset/outset, art borders) draw as single lines. fn brc_style(t: u8) -> BorderStyle { match t { 0x00 => BorderStyle::None, @@ -121,6 +121,15 @@ fn brc_style(t: u8) -> BorderStyle { 0x07 | 0x16 => BorderStyle::Dashed, 0x08 | 0x09 => BorderStyle::DotDash, 0x0A => BorderStyle::Triple, + 0x0B => BorderStyle::ThinThickSmallGap, + 0x0C => BorderStyle::ThickThinSmallGap, + 0x0D => BorderStyle::ThinThickThinSmallGap, + 0x0E => BorderStyle::ThinThickMediumGap, + 0x0F => BorderStyle::ThickThinMediumGap, + 0x10 => BorderStyle::ThinThickThinMediumGap, + 0x11 => BorderStyle::ThinThickLargeGap, + 0x12 => BorderStyle::ThickThinLargeGap, + 0x13 => BorderStyle::ThinThickThinLargeGap, 0x14 | 0x15 => BorderStyle::Wave, _ => BorderStyle::Single, } diff --git a/crates/doc-binary/src/lib.rs b/crates/doc-binary/src/lib.rs index b2d7f3729..b8c1c5c46 100644 --- a/crates/doc-binary/src/lib.rs +++ b/crates/doc-binary/src/lib.rs @@ -1,11 +1,12 @@ -//! Reader for the Word 97-2003 binary file format (`.doc`, [MS-DOC]), WordCraft's. +//! Reader and writer for the Word 97-2003 binary file format (`.doc`, [MS-DOC]), WordCraft's. //! -//! [`read`] turns the bytes of a `.doc` file into a [`craft_wordmodel::Document`]. There is no -//! writer: saving always goes through the other formats. The reader is written from the public -//! specification ([MS-DOC], Word (.doc) Binary File Format, Microsoft Open Specifications) and, -//! like the other Craft parsers, is lenient by design (unknown structures are skipped, bad numbers -//! fall back to defaults) and bounded (stream sizes, piece counts and property counts are -//! capped), so hostile input yields an error or a best-effort document, never a panic. +//! [`read`] turns the bytes of a `.doc` file into a [`craft_wordmodel::Document`], and [`write`] +//! turns a document into a Word 97-2003 `.doc` file (the `write` module lists what it keeps). +//! Both follow the public specification ([MS-DOC], Word (.doc) Binary File Format, Microsoft Open +//! Specifications). The reader, like the other Craft parsers, is lenient by design (unknown +//! structures are skipped, bad numbers fall back to defaults) and bounded (stream sizes, piece +//! counts and property counts are capped), so hostile input yields an error or a best-effort +//! document, never a panic. //! //! Word 6.0/95 files, which that specification does not cover, are read by `word6` from their //! observed layout: their text, formatting and tables so far. @@ -28,11 +29,15 @@ mod metadata; mod notes; mod officeart; mod piece; +mod rmark; mod sections; mod sprm; mod stsh; mod table; mod word6; +mod write; + +pub use write::write; use std::sync::Arc; @@ -303,6 +308,7 @@ fn read_limited(bytes: &[u8], password: Option<&str>, max_paragraphs: usize) -> // tight against aliasing — and never past the absolute ceiling. let budget = std::cell::Cell::new((word.len() as u64).saturating_mul(2).min(MAX_TOTAL_CHARS)); let work = Work::new(MAX_WORK); + let revs = rmark::Revisions::new(&table, &fib); let paragraphs = ParaBudget { left: std::cell::Cell::new(max_paragraphs), exceeded: std::cell::Cell::new(false) }; let ctx = WalkCtx { @@ -321,6 +327,7 @@ fn read_limited(bytes: &[u8], password: Option<&str>, max_paragraphs: usize) -> budget: &budget, paragraphs: ¶graphs, work: &work, + revs: &revs, }; // Drawings: text box stories become parts first, then the floating shapes and pictures @@ -432,6 +439,7 @@ fn read_limited(bytes: &[u8], password: Option<&str>, max_paragraphs: usize) -> return Err(paragraph_limit(max_paragraphs)); } doc.media.extend(pics.media); + doc.revisions = revs.take(); doc.body = table::assemble(paras); doc.ensure_nonempty(); work.log(); @@ -460,6 +468,7 @@ fn read_word6(comp: &craft_cfb::CompoundFile<'_>, word: &[u8], max_paragraphs: u let work = Work::new(MAX_WORK); let paragraphs = ParaBudget { left: std::cell::Cell::new(max_paragraphs), exceeded: std::cell::Cell::new(false) }; let mut pics = media::Pictures::for_input(word.len()); + let revs = rmark::Revisions::none(); let ctx = WalkCtx { word, data: &[], @@ -476,6 +485,7 @@ fn read_word6(comp: &craft_cfb::CompoundFile<'_>, word: &[u8], max_paragraphs: u budget: &budget, paragraphs: ¶graphs, work: &work, + revs: &revs, }; let paras = walk(&ctx, 0, fib.ccp_text, &mut pics); if paragraphs.exceeded.get() { @@ -574,6 +584,8 @@ struct WalkCtx<'a> { paragraphs: &'a ParaBudget, /// Repeated-work bytes left ([`MAX_WORK`]), and what they left out. work: &'a Work, + /// Tracked insertions and deletions met so far. + revs: &'a rmark::Revisions, } /// The paragraph and cell marks still allowed in this document, and whether a walk ran into @@ -748,7 +760,10 @@ fn walk<'a>(ctx: &WalkCtx<'a>, cp_start: u32, cp_end: u32, pics: &mut media::Pic pb.props.numbering = Some(NumRef { num, level: ilvl }); } let fc = ctx.pieces.fc_of_cp(cp).unwrap_or(0); - pb.mark = char_props(ctx.chpx_bins.chpx(ctx.word, fc), ctx.fonts, &CharProps::default()); + let chpx = ctx.chpx_bins.chpx(ctx.word, fc); + pb.mark = char_props(chpx, ctx.fonts, &CharProps::default()); + // A tracked paragraph mark: an inserted or deleted paragraph break. + ctx.revs.mark(&mut pb.mark, chpx, ctx.pieces.piece_prm(cp)); let done = std::mem::take(&mut pb); out.push(ParaOut { para: Paragraph { @@ -769,7 +784,7 @@ fn walk<'a>(ctx: &WalkCtx<'a>, cp_start: u32, cp_end: u32, pics: &mut media::Pic Some(f) => { f.depth = f.depth.saturating_add(1); } - None => field = Some(FieldBuild { depth: 1, instr: String::new(), sep: None }), + None => field = Some(FieldBuild { depth: 1, instr: String::new(), sep: None, anchor: anchor_props(ctx, cp) }), } cp = cp.saturating_add(1); continue; @@ -799,13 +814,16 @@ fn walk<'a>(ctx: &WalkCtx<'a>, cp_start: u32, cp_end: u32, pics: &mut media::Pic '\u{1}' => { // Inline picture: the CHPX of the anchor carries sprmCPicLocation. let fc = ctx.pieces.fc_of_cp(cp).unwrap_or(0); - let fc_pic = pic_location(ctx.chpx_bins.chpx(ctx.word, fc)); + let chpx = ctx.chpx_bins.chpx(ctx.word, fc); + let fc_pic = pic_location(chpx); match fc_pic.and_then(|at| pics.get(ctx.data, at)) { Some(p) => { // Every anchor of a picture gets its own copy of the alt text; the // copies are charged to the work budget (#3709). let alt = if ctx.work.charge(p.alt.len() as u64, Cost::AltText) { p.alt.clone() } else { String::new() }; - pb.push('\u{FFFC}', CharProps::default()); + let mut props = CharProps::default(); + ctx.revs.mark(&mut props, chpx, ctx.pieces.piece_prm(cp)); + pb.push('\u{FFFC}', props); pb.objects.push(InlineObject::Image { media: p.key.clone(), w: p.w, @@ -829,7 +847,7 @@ fn walk<'a>(ctx: &WalkCtx<'a>, cp_start: u32, cp_end: u32, pics: &mut media::Pic if !ctx.work.charge(object_cost(obj), Cost::FloatingObject) { continue; } - pb.push('\u{FFFC}', CharProps::default()); + pb.push('\u{FFFC}', anchor_props(ctx, cp)); pb.objects.push(obj.clone()); } } @@ -837,7 +855,7 @@ fn walk<'a>(ctx: &WalkCtx<'a>, cp_start: u32, cp_end: u32, pics: &mut media::Pic // Footnote or endnote reference; custom symbols share the same character. let at = ctx.notes.partition_point(|(c, _, _)| *c < cp); if let Some((_, kind, id)) = ctx.notes.get(at).filter(|(c, _, _)| *c == cp) { - pb.push('\u{FFFC}', CharProps::default()); + pb.push('\u{FFFC}', anchor_props(ctx, cp)); pb.objects.push(InlineObject::NoteRef { kind: *kind, id: *id, custom: String::new() }); } } @@ -871,6 +889,8 @@ struct FieldBuild { depth: u32, instr: String, sep: Option, + /// The begin character's revision marks, for the field object's anchor. + anchor: CharProps, } /// A field's cached result: its text and, as runs, the formatting of that text. A run is added @@ -905,6 +925,15 @@ fn object_cost(obj: &InlineObject) -> u64 { } } +/// The properties of an object anchor at `cp`: only its revision marks, so a tracked +/// insertion or deletion of a picture, note reference or field survives. +fn anchor_props(ctx: &WalkCtx<'_>, cp: u32) -> CharProps { + let fc = ctx.pieces.fc_of_cp(cp).unwrap_or(0); + let mut props = CharProps::default(); + ctx.revs.mark(&mut props, ctx.chpx_bins.chpx(ctx.word, fc), ctx.pieces.piece_prm(cp)); + props +} + /// Emit a finished field: HYPERLINK keeps its result text as a linked run; every other /// field becomes one inline object with its cached result. /// @@ -934,7 +963,7 @@ fn finish_field(pb: &mut ParaBuild, f: FieldBuild, work: &Work) { } return; } - pb.push('\u{FFFC}', CharProps::default()); + pb.push('\u{FFFC}', f.anchor); pb.objects.push(InlineObject::Field { instr, result: result.text, locked: false, dirty: false, code: false, form: String::new() }); } @@ -1012,7 +1041,9 @@ fn push_formatted<'a>(pb: &mut ParaBuild, cp: u32, c: char, ctx: &WalkCtx<'a>, f } }; let mut props = char_props(grpprl, ctx.fonts, base); - apply_prm(&mut props, ctx.pieces.piece_prm(cp), ctx.fonts, base, ctx.work); + let piece_prm = ctx.pieces.piece_prm(cp); + apply_prm(&mut props, piece_prm, ctx.fonts, base, ctx.work); + ctx.revs.mark(&mut props, grpprl, piece_prm); st.memo = Some(FmtMemo { chpx: grpprl, prm, style: style.map(str::to_owned), props }); st.generation += 1; } @@ -1083,7 +1114,7 @@ fn prm_paragraph_sprms(prm: PrmRef<'_>, work: &Work) -> Vec { out.push(val); } } - PrmRef::Grpprl(Some(g)) => { + PrmRef::Grpprl { grpprl: Some(g), .. } => { if !work.charge(g.len() as u64, Cost::Formatting) { return out; } @@ -1092,7 +1123,7 @@ fn prm_paragraph_sprms(prm: PrmRef<'_>, work: &Work) -> Vec { out.extend_from_slice(prl.operand); } } - PrmRef::None | PrmRef::Grpprl(None) => {} + PrmRef::None | PrmRef::Grpprl { grpprl: None, .. } => {} } out } @@ -1111,7 +1142,7 @@ fn apply_prm(props: &mut CharProps, prm: PrmRef<'_>, fonts: &[String], base: &Ch } } } - PrmRef::Grpprl(Some(g)) => { + PrmRef::Grpprl { grpprl: Some(g), .. } => { if !work.charge(g.len() as u64, Cost::Formatting) { return; } @@ -1121,7 +1152,7 @@ fn apply_prm(props: &mut CharProps, prm: PrmRef<'_>, fonts: &[String], base: &Ch } } } - PrmRef::Grpprl(None) => {} + PrmRef::Grpprl { grpprl: None, .. } => {} } } diff --git a/crates/doc-binary/src/list.rs b/crates/doc-binary/src/list.rs index 873792812..5eacf4b0c 100644 --- a/crates/doc-binary/src/list.rs +++ b/crates/doc-binary/src/list.rs @@ -35,15 +35,19 @@ struct RawLvl { xst: Vec, } -/// A bullet level's character, with the 0xF000 flag bits stripped and the common -/// Symbol/Wingdings glyphs mapped to their Unicode equivalents so every font renders them. +/// A bullet level's character: a symbol-font character (0xF000 to 0xF0FF, the font's own code +/// in the low byte) with the common Symbol/Wingdings glyphs mapped to their Unicode equivalents +/// so every font renders them; any other character is itself. fn bullet_char(c: u16) -> char { - match c & 0x0FFF { + if !(0xF000..=0xF0FF).contains(&c) { + return char::from_u32(u32::from(c)).unwrap_or('\u{2022}'); + } + match c & 0x00FF { 0xB7 => '\u{2022}', // Symbol bullet 0xA7 => '\u{25AA}', // Wingdings small square 0x6F => '\u{25CB}', // Symbol open circle 0x77 | 0x78 => '\u{25CF}', // Wingdings filled circles - other => char::from_u32(other as u32).unwrap_or('\u{2022}'), + other => char::from_u32(u32::from(other)).unwrap_or('\u{2022}'), } } @@ -51,7 +55,7 @@ fn bullet_char(c: u16) -> char { /// 0x00 to 0x27 run in the order of ST_NumberFormat (decimal, upperRoman … 0x16 decimalZero, 0x17 /// bullet … 0x25 chineseCounting, 0x26 chineseLegalSimplified, 0x27 chineseCountingThousand); /// later codes are drawn as decimal. -fn num_format(nfc: u8) -> NumFormat { +pub(crate) fn num_format(nfc: u8) -> NumFormat { match nfc { 0xFF => NumFormat::None, 0x00..=0x27 => NumFormat::ALL.get(nfc as usize).copied().unwrap_or(NumFormat::Decimal), diff --git a/crates/doc-binary/src/metadata.rs b/crates/doc-binary/src/metadata.rs index e45520394..05d0345a6 100644 --- a/crates/doc-binary/src/metadata.rs +++ b/crates/doc-binary/src/metadata.rs @@ -15,6 +15,12 @@ fn u32_at(bytes: &[u8], offset: usize) -> Option { Some(u32::from_le_bytes(bytes.get(offset..offset.checked_add(4)?)?.try_into().ok()?)) } +/// [`parse`], for the writer's tests. +#[cfg(test)] +pub(crate) fn parse_for_tests(bytes: &[u8]) -> Option { + parse(bytes) +} + fn parse(bytes: &[u8]) -> Option { if bytes.get(..2)? != [0xfe, 0xff] || bytes.get(28..44)? != SUMMARY_FMTID || u32_at(bytes, 24)? < 1 { return None; diff --git a/crates/doc-binary/src/notes.rs b/crates/doc-binary/src/notes.rs index 51e3c4b84..2a398d658 100644 --- a/crates/doc-binary/src/notes.rs +++ b/crates/doc-binary/src/notes.rs @@ -93,6 +93,11 @@ pub(crate) fn parse_bookmarks(table: &[u8], fib: &crate::fib::Fib) -> Vec<(u32, /// (1-byte length and Windows-1252 chars). `cbExtra` bytes after each string are skipped. /// Names are kept to 40 characters, but the reader always advances by the stored length. fn sttb_strings(table: &[u8], fc: u32, lcb: u32) -> Option> { + sttb_strings_max(table, fc, lcb, 40) +} + +/// [`sttb_strings`] keeping up to `max` characters of each string. +pub(crate) fn sttb_strings_max(table: &[u8], fc: u32, lcb: u32, max: usize) -> Option> { let b = table.get(fc as usize..(fc as usize).saturating_add(lcb as usize))?; let extended = b.get(0..2)? == [0xFF, 0xFF]; let head = if extended { 2 } else { 0 }; @@ -125,9 +130,10 @@ fn sttb_strings(table: &[u8], fc: u32, lcb: u32) -> Option> { } at += cb_extra; let s: String = if extended { - chars.as_chunks::<2>().0.iter().take(40).map(|c| char::from_u32(u16::from_le_bytes(*c) as u32).unwrap_or('\u{FFFD}')).collect() + // UTF-16: a surrogate pair is one character; a lone surrogate becomes U+FFFD. + char::decode_utf16(chars.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes(*c))).take(max).map(|c| c.unwrap_or('\u{FFFD}')).collect() } else { - chars.iter().take(40).map(|&c| craft_codepage::cp1252(c)).collect() + chars.iter().take(max).map(|&c| craft_codepage::cp1252(c)).collect() }; out.push(s); } @@ -153,6 +159,20 @@ mod tests { b } + /// A character outside the BMP (a surrogate pair) stays one character; a lone surrogate + /// is U+FFFD. The limit counts characters, not UTF-16 units. + #[test] + fn extended_strings_decode_surrogate_pairs() { + let mut b = ext_sttb(&["Ada \u{1F600}"], &[]); + let lone = [0x00u8, 0xD8]; + b[2] = 2; + b.extend_from_slice(&2u16.to_le_bytes()); + b.extend_from_slice(&lone); + b.extend_from_slice(&u16::from(b'x').to_le_bytes()); + let got = super::sttb_strings_max(&b, 0, b.len() as u32, 5).unwrap(); + assert_eq!(got, vec!["Ada \u{1F600}".to_string(), "\u{FFFD}x".to_string()]); + } + #[test] fn long_bookmark_name_does_not_desync_table() { let long = "A".repeat(50); diff --git a/crates/doc-binary/src/piece.rs b/crates/doc-binary/src/piece.rs index 701a4bc67..07ad13a63 100644 --- a/crates/doc-binary/src/piece.rs +++ b/crates/doc-binary/src/piece.rs @@ -228,7 +228,8 @@ impl PieceTable { } PrmRef::Sprm0 { isprm, val: (p.prm >> 8) as u8 } } else { - PrmRef::Grpprl(self.prc_grpprls.get((p.prm >> 1) as usize).map(Vec::as_slice)) + let index = p.prm >> 1; + PrmRef::Grpprl { index, grpprl: self.prc_grpprls.get(usize::from(index)).map(Vec::as_slice) } } } @@ -342,6 +343,7 @@ impl PieceSpan<'_> { } /// What a piece's `Prm` refers to. +#[derive(Clone, Copy)] pub(crate) enum PrmRef<'a> { None, /// Prm0: a short sprm index into the isprm table, with a 1-byte operand. @@ -349,8 +351,11 @@ pub(crate) enum PrmRef<'a> { isprm: u8, val: u8, }, - /// Prm1: a grpprl from a Prc (absent if out of range). - Grpprl(Option<&'a [u8]>), + /// Prm1: the Prc at `index` and its grpprl (absent if out of range). + Grpprl { + index: u16, + grpprl: Option<&'a [u8]>, + }, } /// Windows' code page number for symbol fonts (CP_SYMBOL). diff --git a/crates/doc-binary/src/rmark.rs b/crates/doc-binary/src/rmark.rs new file mode 100644 index 000000000..f5b3a3f7e --- /dev/null +++ b/crates/doc-binary/src/rmark.rs @@ -0,0 +1,232 @@ +//! Tracked insertions and deletions: the revision-mark sprms of a run's CHPX (`sprmCFRMarkIns` +//! and `sprmCFRMarkDel`, each with its author index into `SttbfRMark` and its `DTTM`) +//! ([MS-DOC] §2.6.1, §2.9.290), as model revisions. + +use std::cell::RefCell; +use std::collections::HashMap; + +use craft_wordmodel::props::CharProps; +use craft_wordmodel::{Revision, RevisionKind}; + +use crate::fib::Fib; +use crate::piece::PrmRef; +use crate::sprm; + +const C_RMARK_DEL: u16 = 0x0800; +const C_RMARK_INS: u16 = 0x0801; +const C_IBST_RMARK: u16 = 0x4804; +const C_DTTM_RMARK: u16 = 0x6805; +const C_IBST_RMARK_DEL: u16 = 0x4863; +const C_DTTM_RMARK_DEL: u16 = 0x6864; +/// `fcSttbfRMark`: the revision authors. +const STTBF_RMARK: usize = 51; +/// Most distinct revisions (author, time and kind) one document gets. +const MAX_REVISIONS: usize = 100_000; +/// Longest author name kept. +const MAX_AUTHOR: usize = 255; + +/// The document's revisions, made as the walk meets their marks: runs with the same author, +/// time and kind share one. +pub(crate) struct Revisions { + authors: Vec, + list: RefCell>, + index: RefCell>, + /// The marks of each Prc a piece's Prm1 names, by its index (at most 32,768 of them): a Prc + /// grpprl of up to 64 KB is scanned once, not at every run, paragraph mark and object anchor + /// of its pieces. + prcs: RefCell>, +} + +impl Revisions { + /// No revision authors: a file whose revision marks are not read (Word 6.0/95, whose + /// revision sprms differ). Marks are still never set, as none of its sprms are Word 97's. + pub(crate) fn none() -> Self { + Self { authors: Vec::new(), list: RefCell::default(), index: RefCell::default(), prcs: RefCell::default() } + } + + pub(crate) fn new(table: &[u8], fib: &Fib) -> Self { + let authors = fib + .pair(STTBF_RMARK) + .filter(|(_, lcb)| *lcb > 0) + .and_then(|(fc, lcb)| crate::notes::sttb_strings_max(table, fc, lcb, MAX_AUTHOR)) + .unwrap_or_default(); + Revisions { authors, list: RefCell::new(Vec::new()), index: RefCell::new(HashMap::new()), prcs: RefCell::new(HashMap::new()) } + } + + /// Set `props.ins` / `props.del` from the revision marks of a run: those in its CHPX + /// `grpprl`, then those of its piece's `prm`, which apply after the CHPX's. + pub(crate) fn mark(&self, props: &mut CharProps, grpprl: &[u8], prm: PrmRef<'_>) { + let mut m = Marks::of(grpprl); + match prm { + PrmRef::Sprm0 { isprm, val } => { + if let Some(op) = sprm::from_prm0(isprm) { + m.apply(op, &[val]); + } + } + PrmRef::Grpprl { index, grpprl: Some(g) } => { + let prc = *self.prcs.borrow_mut().entry(index).or_insert_with(|| Marks::of(g)); + m = m.then(prc); + } + PrmRef::Grpprl { grpprl: None, .. } | PrmRef::None => {} + } + if m.ins == Some(true) { + props.ins = self.id(true, m.ibst_ins.unwrap_or(0), m.dttm_ins.unwrap_or(0)); + } + if m.del == Some(true) { + props.del = self.id(false, m.ibst_del.unwrap_or(0), m.dttm_del.unwrap_or(0)); + } + } + + /// The index of the revision of this kind, author and time, made on first use. + fn id(&self, insert: bool, ibst: u16, dttm: u32) -> Option { + let key = (insert, ibst, dttm); + if let Some(&i) = self.index.borrow().get(&key) { + return Some(i); + } + let mut list = self.list.borrow_mut(); + if list.len() >= MAX_REVISIONS { + return None; + } + let author = self.authors.get(usize::from(ibst)).cloned().unwrap_or_else(|| "Unknown".to_string()); + let kind = if insert { RevisionKind::Insert } else { RevisionKind::Delete }; + list.push(Revision::new(kind, author, dttm_iso(dttm))); + let i = u32::try_from(list.len() - 1).ok()?; + self.index.borrow_mut().insert(key, i); + Some(i) + } + + pub(crate) fn take(self) -> Vec { + self.list.into_inner() + } +} + +/// The revision-mark sprms seen so far for one run, a later one replacing an earlier one; each +/// is `None` until one is seen. +#[derive(Clone, Copy, Default)] +struct Marks { + ins: Option, + del: Option, + ibst_ins: Option, + dttm_ins: Option, + ibst_del: Option, + dttm_del: Option, +} + +impl Marks { + /// The marks of one grpprl. + fn of(grpprl: &[u8]) -> Self { + let mut m = Marks::default(); + for prl in sprm::iter(grpprl) { + m.apply(prl.op, prl.operand); + } + m + } + + /// These marks with `later`'s applied after them, as if its sprms came next. + fn then(self, later: Marks) -> Self { + Marks { + ins: later.ins.or(self.ins), + del: later.del.or(self.del), + ibst_ins: later.ibst_ins.or(self.ibst_ins), + dttm_ins: later.dttm_ins.or(self.dttm_ins), + ibst_del: later.ibst_del.or(self.ibst_del), + dttm_del: later.dttm_del.or(self.dttm_del), + } + } + + fn apply(&mut self, op: u16, operand: &[u8]) { + let u16v = || operand.get(..2).map_or(0, |b| u16::from_le_bytes([b[0], b[1]])); + let u32v = || operand.get(..4).map_or(0, |b| u32::from_le_bytes([b[0], b[1], b[2], b[3]])); + match op { + C_RMARK_INS => self.ins = Some(operand.first().is_some_and(|&v| v == 1 || v == 0x81)), + C_RMARK_DEL => self.del = Some(operand.first().is_some_and(|&v| v == 1 || v == 0x81)), + C_IBST_RMARK => self.ibst_ins = Some(u16v()), + C_DTTM_RMARK => self.dttm_ins = Some(u32v()), + C_IBST_RMARK_DEL => self.ibst_del = Some(u16v()), + C_DTTM_RMARK_DEL => self.dttm_del = Some(u32v()), + _ => {} + } + } +} + +/// A `DTTM` ([MS-DOC] §2.9.75) as an ISO 8601 UTC time; empty for 0 or an impossible date. +pub(crate) fn dttm_iso(d: u32) -> String { + if d == 0 { + return String::new(); + } + let minute = d & 0x3F; + let hour = (d >> 6) & 0x1F; + let day = (d >> 11) & 0x1F; + let month = (d >> 16) & 0xF; + let year = 1900 + ((d >> 20) & 0x1FF) as i32; + match chrono::NaiveDate::from_ymd_opt(year, month, day).and_then(|date| date.and_hms_opt(hour, minute, 0)) { + Some(t) => t.format("%Y-%m-%dT%H:%M:%SZ").to_string(), + None => String::new(), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn revisions() -> Revisions { + Revisions { + authors: vec!["Ada".into(), "Grace".into()], + list: RefCell::new(Vec::new()), + index: RefCell::new(HashMap::new()), + prcs: RefCell::new(HashMap::new()), + } + } + + fn marked(chpx: &[u8], prm: PrmRef<'_>) -> (CharProps, Vec) { + let r = revisions(); + let mut props = CharProps::default(); + r.mark(&mut props, chpx, prm); + (props, r.take()) + } + + const INS: [u8; 3] = [0x01, 0x08, 1]; + const NOT_INS: [u8; 3] = [0x01, 0x08, 0]; + /// sprmCFRMarkDel on, by the author at index 1. + const DEL_BY_GRACE: [u8; 7] = [0x00, 0x08, 1, 0x63, 0x48, 1, 0]; + + #[test] + fn a_piece_prm_marks_a_run() { + // Prm1: a grpprl from the piece table's Prc. + let (p, revs) = marked(&[], PrmRef::Grpprl { index: 0, grpprl: Some(&DEL_BY_GRACE) }); + assert_eq!(p.del, Some(0)); + assert_eq!((revs[0].kind, revs[0].author.as_str()), (RevisionKind::Delete, "Grace")); + // Prm0: sprmCFRMarkIns by its isprm. + let (p, revs) = marked(&[], PrmRef::Sprm0 { isprm: 0x42, val: 1 }); + assert_eq!(p.ins, Some(0)); + assert_eq!((revs[0].kind, revs[0].author.as_str()), (RevisionKind::Insert, "Ada")); + } + + #[test] + fn the_piece_prm_applies_after_the_chpx() { + let (p, _) = marked(&INS, PrmRef::Grpprl { index: 0, grpprl: Some(&NOT_INS) }); + assert_eq!(p.ins, None, "the Prm turns the CHPX's insertion off"); + let (p, _) = marked(&NOT_INS, PrmRef::Sprm0 { isprm: 0x42, val: 1 }); + assert_eq!(p.ins, Some(0)); + let (p, _) = marked(&INS, PrmRef::None); + assert_eq!(p.ins, Some(0)); + } + + #[test] + fn a_prcs_marks_apply_after_the_chpx_one_by_one_and_are_scanned_once() { + let r = revisions(); + // The CHPX inserts, by Grace; the Prc only sets the time, so the author stays Grace's. + let chpx = [INS.as_slice(), &[0x04, 0x48, 1, 0]].concat(); + let prc = [0x05u8, 0x68, 0x21, 0x2B, 0xC3, 0x07]; + let mut p = CharProps::default(); + r.mark(&mut p, &chpx, PrmRef::Grpprl { index: 3, grpprl: Some(&prc) }); + assert_eq!(p.ins, Some(0)); + // The marks of Prc 3 are kept: the same index finds them without its grpprl's bytes. + let mut again = CharProps::default(); + r.mark(&mut again, &INS, PrmRef::Grpprl { index: 3, grpprl: Some(&[]) }); + assert_eq!(again.ins, Some(1), "Ada's insertion at the Prc's time"); + let revs = r.take(); + assert_eq!((revs[0].author.as_str(), revs[0].date.as_str()), ("Grace", "2024-03-05T12:33:00Z")); + assert_eq!((revs[1].author.as_str(), revs[1].date.as_str()), ("Ada", "2024-03-05T12:33:00Z")); + } +} diff --git a/crates/doc-binary/src/sprm.rs b/crates/doc-binary/src/sprm.rs index 7db632caf..73792d403 100644 --- a/crates/doc-binary/src/sprm.rs +++ b/crates/doc-binary/src/sprm.rs @@ -86,6 +86,8 @@ pub(crate) fn from_prm0(isprm: u8) -> Option { 0x09 => 0x2407, // sprmPFPageBreakBefore 0x33 => 0x2435, // sprmPWidowControl (low byte of the operand is the value) 0x78 => 0x2640, // sprmPOutLvl + 0x41 => 0x0800, // sprmCFRMarkDel + 0x42 => 0x0801, // sprmCFRMarkIns 0x4D => 0x2A0C, // sprmCHighlight 0x55 => 0x0835, // sprmCFBold 0x56 => 0x0836, // sprmCFItalic diff --git a/crates/doc-binary/src/tests.rs b/crates/doc-binary/src/tests.rs index ec5650695..8c1025eb2 100644 --- a/crates/doc-binary/src/tests.rs +++ b/crates/doc-binary/src/tests.rs @@ -2822,7 +2822,12 @@ fn a_long_hyperlink_over_a_long_result_is_one_linked_run() { // what the copies charge to the work budget, which a busy machine can't skew. let mut result = super::FieldResult::default(); (0..n).for_each(|_| result.push('y', craft_wordmodel::props::CharProps::default())); - let f = super::FieldBuild { depth: 1, instr: format!("HYPERLINK \"http://{target}\""), sep: Some(result) }; + let f = super::FieldBuild { + depth: 1, + instr: format!("HYPERLINK \"http://{target}\""), + sep: Some(result), + anchor: craft_wordmodel::props::CharProps::default(), + }; let work = super::Work::new(u64::MAX); super::finish_field(&mut super::ParaBuild::default(), f, &work); assert_eq!(u64::MAX - work.left.get(), ("http://".len() + n) as u64, "one copy of the target"); @@ -2836,7 +2841,12 @@ fn hyperlink_target_copies_are_charged_to_the_work_budget() { let bold = CharProps { bold: Some(true), ..Default::default() }; let mut result = super::FieldResult::default(); (0..1000).for_each(|i| result.push('a', if i % 2 == 0 { bold.clone() } else { CharProps::default() })); - let f = super::FieldBuild { depth: 1, instr: format!("HYPERLINK \"{}\"", "u".repeat(100)), sep: Some(result) }; + let f = super::FieldBuild { + depth: 1, + instr: format!("HYPERLINK \"{}\"", "u".repeat(100)), + sep: Some(result), + anchor: craft_wordmodel::props::CharProps::default(), + }; let mut pb = super::ParaBuild::default(); let budget = super::Work::new(10_000); super::finish_field(&mut pb, f, &budget); @@ -2901,15 +2911,46 @@ fn prm_grpprls_past_the_work_budget_are_skipped() { let work = super::Work::new(g.len() as u64 + 1); let base = CharProps::default(); let mut first = CharProps::default(); - super::apply_prm(&mut first, crate::piece::PrmRef::Grpprl(Some(&g)), &[], &base, &work); + super::apply_prm(&mut first, crate::piece::PrmRef::Grpprl { index: 0, grpprl: Some(&g) }, &[], &base, &work); assert_eq!(first.bold, Some(true)); let mut second = CharProps::default(); - super::apply_prm(&mut second, crate::piece::PrmRef::Grpprl(Some(&g)), &[], &base, &work); + super::apply_prm(&mut second, crate::piece::PrmRef::Grpprl { index: 0, grpprl: Some(&g) }, &[], &base, &work); assert_eq!(second.bold, None); assert_eq!(work.left.get(), 1); assert_eq!(work.dropped(), [super::Cost::Formatting]); } +/// A piece's Prm grpprl (a Prc of up to 64 KB) was scanned for revision marks again at every +/// paragraph mark and object anchor, which the per-formatting-change memo (#3692) doesn't +/// cover. Each Prc's marks are now found once. +#[test] +fn a_large_prc_is_scanned_for_revision_marks_once() { + // 21,844 bold sprms, then sprmCFRMarkIns: the Prc's marks are only known at its end. + let mut prls = vec![(0x0835u16, &[0x01u8][..]); 21_844]; + prls.push((0x0801, &[0x01])); + let prc = grpprl(&prls); + // A field and a paragraph mark per paragraph, all in the piece with that Prc. + let text: &'static str = Box::leak("\u{13}\u{15}\r".repeat(100_000).into_boxed_str()); + let spec = RichSpec { + text, + styles: vec![(1, 0x0FFF, "Normal", Vec::new(), Vec::new())], + fonts: vec!["Times New Roman"], + chpx_runs: vec![(0, Vec::new())], + papx_entries: vec![(0, 0, Vec::new())], + }; + let bytes = rich_doc_with(&spec, &RichExtra { prcs: vec![prc], prm: 0x0001, ..Default::default() }); + let t = std::time::Instant::now(); + let doc = read(&bytes).expect("opens"); + // Well under a second; scanning the Prc at every mark and anchor took 17 s. + assert!(t.elapsed().as_secs() < 10, "opened in {:?}", t.elapsed()); + assert_eq!(doc.body.len(), 100_000); + assert_eq!(doc.revisions.len(), 1); + for p in doc.body.iter().filter_map(|b| b.as_para()) { + assert_eq!(p.mark.ins, Some(0), "the paragraph mark is a tracked insertion"); + assert_eq!(p.runs.first().and_then(|r| r.props.ins), Some(0), "so is the field"); + } +} + /// A field's cached result keeps one `CharProps` per formatting run, not one per character /// (365 bytes each: 4 million result characters took 1.4 GB). #[test] @@ -2941,7 +2982,7 @@ fn field_results_keep_their_text_and_runs() { { result.push(c, p); } - let f = super::FieldBuild { depth: 1, instr: "HYPERLINK \"http://x\"".into(), sep: Some(result) }; + let f = super::FieldBuild { depth: 1, instr: "HYPERLINK \"http://x\"".into(), sep: Some(result), anchor: CharProps::default() }; let mut pb = super::ParaBuild::default(); super::finish_field(&mut pb, f, &super::Work::new(u64::MAX)); assert_eq!(pb.text, "a\u{e9}\u{20ac}bc"); diff --git a/crates/doc-binary/src/write/fkp.rs b/crates/doc-binary/src/write/fkp.rs new file mode 100644 index 000000000..1d7853f66 --- /dev/null +++ b/crates/doc-binary/src/write/fkp.rs @@ -0,0 +1,280 @@ +//! Formatted disk pages ([MS-DOC] §2.9.43 ChpxFkp, §2.9.177 PapxFkp) and the bin tables that +//! index them (`PlcBteChpx`, `PlcBtePapx`), plus the PLC and STTB containers the Table stream +//! is made of. + +/// Bytes in a formatted disk page. +const PAGE: usize = 512; +/// Most runs a `ChpxFkp` holds ([MS-DOC]: crun MUST be at most 0x65). +const MAX_CHPX_RUNS: usize = 0x65; +/// Most paragraphs a `PapxFkp` holds ([MS-DOC]: crun MUST be at most 0x1D). +const MAX_PAPX_RUNS: usize = 0x1D; +/// Size of a `BxPap`: a word offset and a 12-byte `PHE` (left zero: Word recomputes heights). +const BX: usize = 13; + +/// One run of text sharing its character formatting: `[fc_start, fc_end)` in the WordDocument +/// stream, with the CHPX grpprl (empty = no direct formatting). +pub(crate) struct ChpxRun<'a> { + pub(crate) fc_start: u32, + pub(crate) fc_end: u32, + pub(crate) grpprl: &'a [u8], +} + +/// One paragraph: `[fc_start, fc_end)` (its mark included), its style and PAPX grpprl. +pub(crate) struct PapxRun<'a> { + pub(crate) fc_start: u32, + pub(crate) fc_end: u32, + pub(crate) istd: u16, + pub(crate) grpprl: &'a [u8], +} + +/// Pages ready for the WordDocument stream and the bin table (`aFc` + `aPn`) that indexes them. +pub(crate) struct Paged { + pub(crate) pages: Vec<[u8; PAGE]>, + /// `aFc`: the first FC of each page, then the last page's end. + fcs: Vec, +} + +impl Paged { + /// The `PlcBte*` for these pages once they sit from page number `first_pn` on. + pub(crate) fn plc_bte(&self, first_pn: u32) -> Vec { + let mut v = Vec::with_capacity(self.fcs.len() * 4 + self.pages.len() * 4); + for fc in &self.fcs { + v.extend_from_slice(&fc.to_le_bytes()); + } + for i in 0..self.pages.len() { + v.extend_from_slice(&first_pn.saturating_add(i as u32).to_le_bytes()); + } + v + } +} + +/// A page being filled: the `rgfc` entries so far and the property bytes, which grow down from +/// the end of the page (the last byte is `crun`). +struct Page { + buf: [u8; PAGE], + fcs: Vec, + /// Word offset (÷2) of each entry's properties (0 = none). + offs: Vec, + /// Lowest byte used by property data. + low: usize, + /// Property bytes already on the page and where they are, so equal ones are stored once. + stored: Vec<(Vec, u8)>, +} + +impl Page { + fn new() -> Page { + Page { buf: [0; PAGE], fcs: Vec::new(), offs: Vec::new(), low: PAGE - 1, stored: Vec::new() } + } + + /// Bytes the header takes with `crun` entries of `entry` bytes each. + fn header(crun: usize, entry: usize) -> usize { + (crun + 1) * 4 + crun * entry + } + + /// Place `data` (already in its on-page form), returning its word offset, if it fits beside + /// a header for `crun` entries. + fn place(&mut self, data: &[u8], crun: usize, entry: usize) -> Option { + if data.is_empty() { + return (Page::header(crun, entry) <= self.low).then_some(0); + } + if let Some((_, off)) = self.stored.iter().find(|(d, _)| d == data) { + return (Page::header(crun, entry) <= self.low).then_some(*off); + } + let at = self.low.checked_sub(data.len())? & !1; + if at < Page::header(crun, entry) || at / 2 > u8::MAX as usize { + return None; + } + self.buf.get_mut(at..at + data.len())?.copy_from_slice(data); + self.low = at; + let off = (at / 2) as u8; + self.stored.push((data.to_vec(), off)); + Some(off) + } + + /// Write the header and `crun`; `entry` is the size of each `rgb`/`rgbx` element. + fn finish(mut self, end_fc: u32, entry: usize) -> ([u8; PAGE], u32) { + let crun = self.offs.len(); + let first = self.fcs.first().copied().unwrap_or(end_fc); + self.fcs.push(end_fc); + for (i, fc) in self.fcs.iter().enumerate() { + if let Some(b) = self.buf.get_mut(i * 4..i * 4 + 4) { + b.copy_from_slice(&fc.to_le_bytes()); + } + } + let rgb_at = (crun + 1) * 4; + for (i, off) in self.offs.iter().enumerate() { + if let Some(b) = self.buf.get_mut(rgb_at + i * entry) { + *b = *off; + } + } + self.buf[PAGE - 1] = crun as u8; + (self.buf, first) + } +} + +/// Page the character runs into `ChpxFkp`s: each run's `Chpx` is `cb` then the grpprl (at most +/// 255 bytes; the caller truncates). +pub(crate) fn chpx_pages(runs: &[ChpxRun<'_>]) -> Paged { + let mut out = Paged { pages: Vec::new(), fcs: Vec::new() }; + let mut page = Page::new(); + for r in runs { + let mut data = Vec::new(); + if !r.grpprl.is_empty() { + data.push(r.grpprl.len().min(255) as u8); + data.extend_from_slice(r.grpprl.get(..255).unwrap_or(r.grpprl)); + } + let off = if page.offs.len() < MAX_CHPX_RUNS { page.place(&data, page.offs.len() + 1, 1) } else { None }; + let off = match off { + Some(o) => o, + None => { + let (buf, first) = std::mem::replace(&mut page, Page::new()).finish(r.fc_start, 1); + out.pages.push(buf); + out.fcs.push(first); + // A fresh page always has room for one Chpx of at most 256 bytes. + page.place(&data, 1, 1).unwrap_or(0) + } + }; + page.fcs.push(r.fc_start); + page.offs.push(off); + } + let end = runs.last().map_or(0, |r| r.fc_end); + if !page.offs.is_empty() { + let (buf, first) = page.finish(end, 1); + out.pages.push(buf); + out.fcs.push(first); + } + out.fcs.push(end); + out +} + +/// A `PapxInFkp` ([MS-DOC] §2.9.175): the istd and grpprl with the size byte(s) in front: `cb` +/// (2×cb−1 bytes follow) for an odd size, else 0 and `cb'` (2×cb' bytes follow). +fn papx_in_fkp(istd: u16, grpprl: &[u8]) -> Vec { + let mut body = istd.to_le_bytes().to_vec(); + body.extend_from_slice(grpprl); + let mut v = Vec::with_capacity(body.len() + 2); + if body.len() % 2 == 1 { + v.push(body.len().div_ceil(2) as u8); + } else { + v.push(0); + v.push((body.len() / 2) as u8); + } + v.extend_from_slice(&body); + v +} + +/// Largest PAPX grpprl a page takes: one paragraph alone on a page must still fit. +pub(crate) const MAX_PAPX_GRPPRL: usize = 480; + +/// Page the paragraphs into `PapxFkp`s. +pub(crate) fn papx_pages(paras: &[PapxRun<'_>]) -> Paged { + let mut out = Paged { pages: Vec::new(), fcs: Vec::new() }; + let mut page = Page::new(); + for p in paras { + let data = papx_in_fkp(p.istd, p.grpprl.get(..MAX_PAPX_GRPPRL).unwrap_or(p.grpprl)); + // Even an unformatted paragraph names its style, so every BX points at a PAPX. + let off = if page.offs.len() < MAX_PAPX_RUNS { page.place(&data, page.offs.len() + 1, BX) } else { None }; + let off = match off { + Some(o) => o, + None => { + let (buf, first) = std::mem::replace(&mut page, Page::new()).finish(p.fc_start, BX); + out.pages.push(buf); + out.fcs.push(first); + page.place(&data, 1, BX).unwrap_or(0) + } + }; + page.fcs.push(p.fc_start); + page.offs.push(off); + } + let end = paras.last().map_or(0, |p| p.fc_end); + if !page.offs.is_empty() { + let (buf, first) = page.finish(end, BX); + out.pages.push(buf); + out.fcs.push(first); + } + out.fcs.push(end); + out +} + +/// A PLC ([MS-DOC] §2.2.2): `cps` (one more than the data elements), then the elements. +pub(crate) fn plc(cps: &[u32], data: &[&[u8]]) -> Vec { + let mut v = Vec::with_capacity(cps.len() * 4 + data.iter().map(|d| d.len()).sum::()); + for cp in cps { + v.extend_from_slice(&cp.to_le_bytes()); + } + for d in data { + v.extend_from_slice(d); + } + v +} + +/// An extended STTB ([MS-DOC] §2.2.4): `fExtend`, `cData`, `cbExtra`, then each string as a +/// count of UTF-16 units and the units, followed by its `extra` bytes. +pub(crate) fn sttb_ext(strings: &[(String, Vec)], cb_extra: u16) -> Vec { + let mut v = vec![0xFF, 0xFF]; + v.extend_from_slice(&(strings.len().min(u16::MAX as usize) as u16).to_le_bytes()); + v.extend_from_slice(&cb_extra.to_le_bytes()); + for (s, extra) in strings.iter().take(u16::MAX as usize) { + let units: Vec = s.encode_utf16().take(u16::MAX as usize).collect(); + v.extend_from_slice(&(units.len() as u16).to_le_bytes()); + for u in units { + v.extend_from_slice(&u.to_le_bytes()); + } + let mut e = extra.clone(); + e.resize(cb_extra as usize, 0); + v.extend_from_slice(&e); + } + v +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::fkp::Bins; + + #[test] + fn chpx_pages_read_back() { + let bold = [0x35u8, 0x08, 1]; + let runs: Vec = + (0..300u32).map(|i| ChpxRun { fc_start: 0x400 + i * 2, fc_end: 0x402 + i * 2, grpprl: if i % 2 == 0 { &bold } else { &[] } }).collect(); + let paged = chpx_pages(&runs); + assert!(paged.pages.len() >= 3, "300 runs need several pages"); + let mut word = vec![0u8; 0x1000]; + for p in &paged.pages { + word.extend_from_slice(p); + } + let bte = paged.plc_bte(8); + let bins = Bins::parse(&bte, 0, bte.len() as u32).unwrap(); + for i in 0..300u32 { + let g = bins.chpx(&word, 0x400 + i * 2); + assert_eq!(g, if i % 2 == 0 { &bold[..] } else { &[][..] }, "run {i}"); + } + } + + #[test] + fn papx_pages_read_back_odd_and_even_sizes() { + let odd = [0x03u8, 0x24, 1]; // 2 + 3 = 5 bytes with the istd + let even = [0x03u8, 0x24, 1, 0]; // padded to 6 by the istd + let paras: Vec = (0..70u32) + .map(|i| PapxRun { + fc_start: 0x400 + i * 10, + fc_end: 0x40A + i * 10, + istd: i as u16 % 3, + grpprl: if i % 2 == 0 { &odd } else { &even[..3] }, + }) + .collect(); + let paged = papx_pages(¶s); + assert!(paged.pages.len() >= 3); + let mut word = vec![0u8; 0x1000]; + for p in &paged.pages { + word.extend_from_slice(p); + } + let bte = paged.plc_bte(8); + let bins = Bins::parse(&bte, 0, bte.len() as u32).unwrap(); + for i in 0..70u32 { + let (istd, g) = bins.papx(&word, 0x400 + i * 10 + 9); + assert_eq!(istd, i as u16 % 3); + assert_eq!(g, &odd[..]); + } + } +} diff --git a/crates/doc-binary/src/write/grpprl.rs b/crates/doc-binary/src/write/grpprl.rs new file mode 100644 index 000000000..39b19d2ff --- /dev/null +++ b/crates/doc-binary/src/write/grpprl.rs @@ -0,0 +1,753 @@ +//! Model properties → grpprls of sprms ([MS-DOC] §2.6): character (CHPX), paragraph (PAPX) and +//! section (SEPX) formatting. The opcodes are the ones the reader decodes (`fmt.rs`, +//! `sections.rs`, `table.rs`), so a saved file reads back with the same properties. + +use craft_wordmodel::Rgb; +use craft_wordmodel::props::{ + Align, Border, BorderStyle, Borders, CharProps, Highlight, LineSpacing, ParaProps, TabAlign, TabLeader, TextColor, Underline, VertAlign, +}; +use craft_wordmodel::section::{NumFormat, PageVAlign, SectionProps, SectionStart}; + +/// A grpprl being built: Prls appended one by one. +#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)] +pub(crate) struct Grpprl(pub(crate) Vec); + +impl Grpprl { + pub(crate) fn len(&self) -> usize { + self.0.len() + } + + fn op(&mut self, op: u16) { + self.0.extend_from_slice(&op.to_le_bytes()); + } + + pub(crate) fn u8(&mut self, op: u16, v: u8) { + self.op(op); + self.0.push(v); + } + + pub(crate) fn u16(&mut self, op: u16, v: u16) { + self.op(op); + self.0.extend_from_slice(&v.to_le_bytes()); + } + + pub(crate) fn i16(&mut self, op: u16, v: i16) { + self.u16(op, v as u16); + } + + pub(crate) fn u32(&mut self, op: u16, v: u32) { + self.op(op); + self.0.extend_from_slice(&v.to_le_bytes()); + } + + /// A Prl whose operand is written as given (its size implied by the opcode's spra, or a + /// leading size byte the caller includes). + pub(crate) fn raw(&mut self, op: u16, operand: &[u8]) { + self.op(op); + self.0.extend_from_slice(operand); + } + + /// A variable-length Prl (spra 6): a size byte, then the operand. + pub(crate) fn var(&mut self, op: u16, operand: &[u8]) { + self.op(op); + self.0.push(u8::try_from(operand.len()).unwrap_or(u8::MAX)); + self.0.extend_from_slice(operand.get(..255).unwrap_or(operand)); + } + + pub(crate) fn extend(&mut self, other: &Grpprl) { + self.0.extend_from_slice(&other.0); + } + + /// Keep whole Prls up to `max` bytes: a grpprl that doesn't fit where it is stored (a CHPX + /// holds 255 bytes) loses its last properties rather than the file its shape. + pub(crate) fn truncate_to(&mut self, max: usize) { + if self.0.len() <= max { + return; + } + let mut keep = 0usize; + for prl in crate::sprm::iter(&self.0) { + let next = keep + 2 + prl.operand.len(); + if next > max { + break; + } + keep = next; + } + self.0.truncate(keep); + } +} + +// Character sprms ([MS-DOC] §2.6.1). +pub(crate) const C_RMARK_DEL: u16 = 0x0800; +pub(crate) const C_RMARK_INS: u16 = 0x0801; +pub(crate) const C_IBST_RMARK: u16 = 0x4804; +pub(crate) const C_DTTM_RMARK: u16 = 0x6805; +pub(crate) const C_IBST_RMARK_DEL: u16 = 0x4863; +pub(crate) const C_DTTM_RMARK_DEL: u16 = 0x6864; +pub(crate) const C_ISTD: u16 = 0x4A30; +const C_BOLD: u16 = 0x0835; +const C_ITALIC: u16 = 0x0836; +const C_STRIKE: u16 = 0x0837; +const C_OUTLINE: u16 = 0x0838; +const C_SHADOW: u16 = 0x0839; +const C_SMALL_CAPS: u16 = 0x083A; +const C_CAPS: u16 = 0x083B; +const C_VANISH: u16 = 0x083C; +const C_IMPRINT: u16 = 0x0854; +pub(crate) const C_SPEC: u16 = 0x0855; +const C_EMBOSS: u16 = 0x0858; +const C_RTL: u16 = 0x085A; +const C_BOLD_BI: u16 = 0x085C; +const C_ITALIC_BI: u16 = 0x085D; +const C_NO_PROOF: u16 = 0x0875; +const C_COMPLEX: u16 = 0x0882; +const C_HIGHLIGHT: u16 = 0x2A0C; +const C_KUL: u16 = 0x2A3E; +const C_ICO: u16 = 0x2A42; +const C_ISS: u16 = 0x2A48; +const C_DSTRIKE: u16 = 0x2A53; +const C_HPS: u16 = 0x4A43; +const C_HPS_POS: u16 = 0x4845; +const C_HPS_KERN: u16 = 0x484B; +const C_CHAR_SCALE: u16 = 0x4852; +const C_LID_BI: u16 = 0x485F; +const C_LID0_80: u16 = 0x486D; +const C_LID1_80: u16 = 0x486E; +const C_LID0: u16 = 0x4873; +const C_LID1: u16 = 0x4874; +const C_FTC0: u16 = 0x4A4F; +const C_FTC1: u16 = 0x4A50; +const C_FTC2: u16 = 0x4A51; +const C_FTC_BI: u16 = 0x4A5E; +const C_HPS_BI: u16 = 0x4A61; +pub(crate) const C_PIC_LOCATION: u16 = 0x6A03; +const C_CV: u16 = 0x6870; +const C_CV_UL: u16 = 0x6877; +const C_DXA_SPACE: u16 = 0x8840; +const C_SHD: u16 = 0xCA71; + +/// What [`chpx`] needs besides the properties: the font table, the style table, and the +/// tracked-change authors. +pub(crate) trait CharCtx { + /// Index of `name` in the font table (added on first use). + fn font(&mut self, name: &str) -> u16; + /// The istd of a character style id; `None` when the stylesheet doesn't have it. + fn char_style(&self, id: &str) -> Option; + /// The author index and `DTTM` of revision `rev` (`Document::revisions`). + fn revision(&mut self, rev: u32) -> Option<(u16, u32)>; +} + +/// The CHPX grpprl for `p`: only the properties it sets, in the order Word applies them (the +/// style first, then toggles, then values). Inherited (`None`) properties are left out. +pub(crate) fn chpx(p: &CharProps, ctx: &mut dyn CharCtx) -> Grpprl { + let mut g = Grpprl::default(); + if let Some(istd) = p.style.as_deref().and_then(|s| ctx.char_style(s)) { + g.u16(C_ISTD, istd); + } + // Tracked changes: the mark, the author and the time ([MS-DOC] sprmCFRMarkIns and friends). + if let Some((ibst, dttm)) = p.ins.and_then(|r| ctx.revision(r)) { + g.u8(C_RMARK_INS, 1); + g.u16(C_IBST_RMARK, ibst); + g.u32(C_DTTM_RMARK, dttm); + } + if let Some((ibst, dttm)) = p.del.and_then(|r| ctx.revision(r)) { + g.u8(C_RMARK_DEL, 1); + g.u16(C_IBST_RMARK_DEL, ibst); + g.u32(C_DTTM_RMARK_DEL, dttm); + } + for (op, v) in [ + (C_BOLD, p.bold), + (C_ITALIC, p.italic), + (C_STRIKE, p.strike), + (C_OUTLINE, p.outline), + (C_SHADOW, p.shadow), + (C_SMALL_CAPS, p.small_caps), + (C_CAPS, p.caps), + (C_VANISH, p.hidden), + (C_IMPRINT, p.engrave), + (C_EMBOSS, p.emboss), + (C_RTL, p.rtl), + (C_BOLD_BI, p.bold_cs), + (C_ITALIC_BI, p.italic_cs), + (C_NO_PROOF, p.no_proof), + (C_COMPLEX, p.cs), + ] { + if let Some(on) = v { + g.u8(op, u8::from(on)); + } + } + if let Some(d) = p.double_strike { + g.u8(C_DSTRIKE, u8::from(d)); + } + if let Some(u) = p.underline { + g.u8(C_KUL, kul(u)); + } + if let Some(c) = p.underline_color { + g.u32(C_CV_UL, colorref(c)); + } + match p.color { + Some(TextColor::Auto) => g.u8(C_ICO, 0), + Some(TextColor::Rgb(c)) => { + // The palette colour for Word 97, then the exact colour for every later version. + g.u8(C_ICO, nearest_ico(c)); + g.u32(C_CV, colorref(c)); + } + None => {} + } + if let Some(h) = p.highlight { + g.u8(C_HIGHLIGHT, highlight_ico(h)); + } + if let Some(s) = p.size { + g.u16(C_HPS, half_points(s)); + } + if let Some(s) = p.size_cs { + g.u16(C_HPS_BI, half_points(s)); + } + if let Some(v) = p.vert_align { + g.u8( + C_ISS, + match v { + VertAlign::Baseline => 0, + VertAlign::Superscript => 1, + VertAlign::Subscript => 2, + }, + ); + } + if let Some(pos) = p.position { + g.i16(C_HPS_POS, (pos * 2.0).round().clamp(-3168.0, 3168.0) as i16); + } + if let Some(sp) = p.spacing { + g.i16(C_DXA_SPACE, twips(sp)); + } + if let Some(sc) = p.scale { + g.u16(C_CHAR_SCALE, sc.round().clamp(1.0, 600.0) as u16); + } + if let Some(k) = p.kern { + g.u16(C_HPS_KERN, half_points(k.max(0.0))); + } + if let Some(f) = p.font.as_deref() { + let i = ctx.font(f); + g.u16(C_FTC0, i); + // Text outside ASCII but not East Asian takes the third font; Word sets both together. + g.u16(C_FTC2, i); + } + if let Some(f) = p.font_ea.as_deref() { + let i = ctx.font(f); + g.u16(C_FTC1, i); + } + if let Some(f) = p.font_cs.as_deref() { + let i = ctx.font(f); + g.u16(C_FTC_BI, i); + } + if let Some(lid) = p.lang.as_deref().and_then(lcid) { + g.u16(C_LID0_80, lid); + g.u16(C_LID0, lid); + } + if let Some(lid) = p.lang_ea.as_deref().and_then(lcid) { + g.u16(C_LID1_80, lid); + g.u16(C_LID1, lid); + } + if let Some(lid) = p.lang_bidi.as_deref().and_then(lcid) { + g.u16(C_LID_BI, lid); + } + if let Some(c) = p.shading { + g.var(C_SHD, &shd(Some(c))); + } + g +} + +/// Points → half-points, as the size sprms store them. +fn half_points(pt: f32) -> u16 { + (pt * 2.0).round().clamp(2.0, 3276.0) as u16 +} + +/// Points → twips, clamped to what an `XAS`/`YAS` holds. +pub(crate) fn twips(pt: f32) -> i16 { + if !pt.is_finite() { + return 0; + } + (pt * 20.0).round().clamp(-31_680.0, 31_680.0) as i16 +} + +/// A `COLORREF` (0x00BBGGRR, stored R, G, B, 0). +pub(crate) fn colorref(c: Rgb) -> u32 { + u32::from_le_bytes([c.0, c.1, c.2, 0]) +} + +/// The automatic colour (`fAuto` in the high byte). +pub(crate) const CV_AUTO: u32 = 0xFF00_0000; + +/// A 10-byte `Shd` ([MS-DOC] §2.9.248): automatic foreground, `fill` as background, clear +/// pattern; no fill is an all-automatic one. +pub(crate) fn shd(fill: Option) -> [u8; 10] { + let mut b = [0u8; 10]; + b[0..4].copy_from_slice(&CV_AUTO.to_le_bytes()); + let back = fill.map_or(CV_AUTO, colorref); + b[4..8].copy_from_slice(&back.to_le_bytes()); + b +} + +/// Word's 16-colour palette ([MS-DOC] §2.9.135 Ico), index 1..=16. +const ICO: [Rgb; 16] = [ + Rgb(0, 0, 0), + Rgb(0, 0, 255), + Rgb(0, 255, 255), + Rgb(0, 255, 0), + Rgb(255, 0, 255), + Rgb(255, 0, 0), + Rgb(255, 255, 0), + Rgb(255, 255, 255), + Rgb(0, 0, 128), + Rgb(0, 128, 128), + Rgb(0, 128, 0), + Rgb(128, 0, 128), + Rgb(128, 0, 0), + Rgb(128, 128, 0), + Rgb(128, 128, 128), + Rgb(192, 192, 192), +]; + +/// The palette entry nearest `c` (by squared distance), 1-based. +pub(crate) fn nearest_ico(c: Rgb) -> u8 { + let d = |p: &Rgb| { + let dr = i32::from(p.0) - i32::from(c.0); + let dg = i32::from(p.1) - i32::from(c.1); + let db = i32::from(p.2) - i32::from(c.2); + dr * dr + dg * dg + db * db + }; + ICO.iter().enumerate().min_by_key(|(_, p)| d(p)).map_or(1, |(i, _)| i as u8 + 1) +} + +/// A highlight colour as the `Ico` `sprmCHighlight` takes. +fn highlight_ico(h: Highlight) -> u8 { + match h { + Highlight::None => 0, + Highlight::Black => 1, + Highlight::Blue => 2, + Highlight::Turquoise => 3, + Highlight::BrightGreen => 4, + Highlight::Pink => 5, + Highlight::Red => 6, + Highlight::Yellow => 7, + Highlight::White => 8, + Highlight::DarkBlue => 9, + Highlight::Teal => 10, + Highlight::Green => 11, + Highlight::Violet => 12, + Highlight::DarkRed => 13, + Highlight::DarkYellow => 14, + Highlight::Gray50 => 15, + Highlight::Gray25 => 16, + } +} + +/// An underline as a `Kul` ([MS-DOC] §2.9.133). +fn kul(u: Underline) -> u8 { + match u { + Underline::None => 0x00, + Underline::Single => 0x01, + Underline::Words => 0x02, + Underline::Double => 0x03, + Underline::Dotted => 0x04, + Underline::Thick => 0x06, + Underline::Dash => 0x07, + Underline::DotDash => 0x09, + Underline::DotDotDash => 0x0A, + Underline::Wave => 0x0B, + Underline::DoubleWave => 0x2B, + } +} + +/// The Windows language id (LCID) of a BCP 47 tag, for the common languages; `None` for a tag +/// not in the table (the text keeps the style's language). +pub(crate) fn lcid(tag: &str) -> Option { + let t = tag.trim().to_ascii_lowercase().replace('_', "-"); + Some(match t.as_str() { + "ar-sa" | "ar" => 0x0401, + "bg-bg" | "bg" => 0x0402, + "ca-es" | "ca" => 0x0403, + "zh-tw" => 0x0404, + "cs-cz" | "cs" => 0x0405, + "da-dk" | "da" => 0x0406, + "de-de" | "de" => 0x0407, + "el-gr" | "el" => 0x0408, + "en-us" | "en" => 0x0409, + "es-es" | "es" => 0x0C0A, + "fi-fi" | "fi" => 0x040B, + "fr-fr" | "fr" => 0x040C, + "he-il" | "he" => 0x040D, + "hu-hu" | "hu" => 0x040E, + "is-is" | "is" => 0x040F, + "it-it" | "it" => 0x0410, + "ja-jp" | "ja" => 0x0411, + "ko-kr" | "ko" => 0x0412, + "nl-nl" | "nl" => 0x0413, + "nb-no" | "nb" | "no" => 0x0414, + "pl-pl" | "pl" => 0x0415, + "pt-br" => 0x0416, + "ro-ro" | "ro" => 0x0418, + "ru-ru" | "ru" => 0x0419, + "hr-hr" | "hr" => 0x041A, + "sk-sk" | "sk" => 0x041B, + "sv-se" | "sv" => 0x041D, + "th-th" | "th" => 0x041E, + "tr-tr" | "tr" => 0x041F, + "id-id" | "id" => 0x0421, + "uk-ua" | "uk" => 0x0422, + "sl-si" | "sl" => 0x0424, + "et-ee" | "et" => 0x0425, + "lv-lv" | "lv" => 0x0426, + "lt-lt" | "lt" => 0x0427, + "fa-ir" | "fa" => 0x0429, + "vi-vn" | "vi" => 0x042A, + "hi-in" | "hi" => 0x0439, + "ne-np" | "ne" => 0x0461, + "zh-cn" | "zh" => 0x0804, + "de-ch" => 0x0807, + "en-gb" => 0x0809, + "es-mx" => 0x080A, + "pt-pt" | "pt" => 0x0816, + "sr-latn-rs" => 0x241A, + "sr-cyrl-rs" | "sr" => 0x281A, + "en-au" => 0x0C09, + "en-ca" => 0x1009, + "fr-ca" => 0x0C0C, + "es-uy" => 0x380A, + "es-419" => 0x580A, + _ => return None, + }) +} + +// Paragraph sprms ([MS-DOC] §2.6.2). +const P_JC80: u16 = 0x2403; +const P_JC: u16 = 0x2461; +const P_KEEP: u16 = 0x2405; +const P_KEEP_FOLLOW: u16 = 0x2406; +const P_PAGE_BREAK_BEFORE: u16 = 0x2407; +const P_NO_LINE_NUMB: u16 = 0x240C; +const P_IN_TABLE: u16 = 0x2416; +const P_TTP: u16 = 0x2417; +const P_NO_AUTO_HYPH: u16 = 0x242A; +const P_WIDOW: u16 = 0x2431; +const P_BIDI: u16 = 0x2441; +const P_OUTLVL: u16 = 0x2640; +const P_CONTEXTUAL: u16 = 0x246D; +const P_ILVL: u16 = 0x260A; +const P_ILFO: u16 = 0x460B; +const P_DXC_RIGHT: u16 = 0x4455; +const P_DXC_LEFT: u16 = 0x4456; +const P_DXC_FIRST: u16 = 0x4457; +const P_DYA_LINE: u16 = 0x6412; +const P_ITAP: u16 = 0x6649; +const P_DXA_RIGHT80: u16 = 0x840E; +const P_DXA_LEFT80: u16 = 0x840F; +const P_DXA_FIRST80: u16 = 0x8411; +const P_DXA_RIGHT: u16 = 0x845D; +const P_DXA_LEFT: u16 = 0x845E; +const P_DXA_FIRST: u16 = 0x8460; +const P_DYA_BEFORE: u16 = 0xA413; +const P_DYA_AFTER: u16 = 0xA414; +const P_CHG_TABS_PAPX: u16 = 0xC60D; +const P_SHD: u16 = 0xC64D; +const P_BRC: [u16; 5] = [0xC64E, 0xC64F, 0xC650, 0xC651, 0xC652]; +const P_BRC80: [u16; 5] = [0x6424, 0x6425, 0x6426, 0x6427, 0x6428]; + +/// What [`papx`] needs besides the properties: the list (LFO) a model num id became. +pub(crate) trait ParaCtx { + /// The 1-based LFO index of model num `id` (0 = no list). + fn lfo(&self, num: u32) -> u16; +} + +/// The PAPX grpprl for `p` (its style is the PAPX's istd, not a sprm). +pub(crate) fn papx(p: &ParaProps, ctx: &dyn ParaCtx) -> Grpprl { + let mut g = Grpprl::default(); + if let Some(a) = p.align { + let jc = match a { + Align::Left => 0, + Align::Center => 1, + Align::Right => 2, + Align::Justify => 3, + Align::Distribute => 4, + }; + g.u8(P_JC80, jc); + g.u8(P_JC, jc); + } + for (v, op80, op) in + [(p.indent_left, P_DXA_LEFT80, P_DXA_LEFT), (p.indent_right, P_DXA_RIGHT80, P_DXA_RIGHT), (p.indent_first, P_DXA_FIRST80, P_DXA_FIRST)] + { + if let Some(v) = v { + g.i16(op80, twips(v)); + g.i16(op, twips(v)); + } + } + for (v, op) in [(p.indent_left_chars, P_DXC_LEFT), (p.indent_right_chars, P_DXC_RIGHT), (p.indent_first_chars, P_DXC_FIRST)] { + if let Some(v) = v.filter(|v| v.is_finite()) { + g.i16(op, (v * 100.0).round().clamp(-31_680.0, 31_680.0) as i16); + } + } + if let Some(v) = p.space_before { + g.u16(P_DYA_BEFORE, twips(v.max(0.0)) as u16); + } + if let Some(v) = p.space_after { + g.u16(P_DYA_AFTER, twips(v.max(0.0)) as u16); + } + if let Some(ls) = p.line_spacing { + // LSPD: dyaLine, then fMultLinespace. + let (line, mult): (i16, i16) = match ls { + LineSpacing::Multiple(m) => ((m * 240.0).round().clamp(1.0, 31_680.0) as i16, 1), + LineSpacing::AtLeast(pt) => (twips(pt.max(0.0)), 0), + LineSpacing::Exactly(pt) => (twips(pt.max(0.05)).saturating_neg(), 0), + }; + let mut op = line.to_le_bytes().to_vec(); + op.extend_from_slice(&mult.to_le_bytes()); + g.raw(P_DYA_LINE, &op); + } + for (op, v) in [ + (P_KEEP, p.keep_lines), + (P_KEEP_FOLLOW, p.keep_next), + (P_PAGE_BREAK_BEFORE, p.page_break_before), + (P_WIDOW, p.widow_control), + (P_CONTEXTUAL, p.contextual_spacing), + (P_NO_AUTO_HYPH, p.suppress_hyphens), + (P_NO_LINE_NUMB, p.suppress_line_numbers), + (P_BIDI, p.bidi), + ] { + if let Some(on) = v { + g.u8(op, u8::from(on)); + } + } + if let Some(l) = p.outline_level { + g.u8(P_OUTLVL, l.min(9)); + } + if let Some(n) = p.numbering { + g.u8(P_ILVL, n.level.min(8)); + g.u16(P_ILFO, if n.num == 0 { 0 } else { ctx.lfo(n.num) }); + } + if let Some(c) = p.shading { + g.var(P_SHD, &shd(Some(c))); + } + if let Some(b) = &p.borders { + para_borders(&mut g, b); + } + if let Some(tabs) = &p.tabs { + tab_stops(&mut g, tabs); + } + g +} + +/// The paragraph's borders: the Word 97 form (palette colour) and the exact one, side by side. +fn para_borders(g: &mut Grpprl, b: &Borders) { + for (i, side) in [b.top, b.left, b.bottom, b.right, b.between].iter().enumerate() { + let Some(side) = side else { continue }; + if let (Some(&op80), Some(&op)) = (P_BRC80.get(i), P_BRC.get(i)) { + g.raw(op80, &brc80(side)); + g.var(op, &brc(side)); + } + } +} + +/// A border's `brcType` ([MS-DOC] §2.9.22). +fn brc_type(s: BorderStyle) -> u8 { + match s { + BorderStyle::None => 0x00, + BorderStyle::Single => 0x01, + BorderStyle::Thick => 0x02, + BorderStyle::Double => 0x03, + BorderStyle::Dotted => 0x06, + BorderStyle::Dashed => 0x07, + BorderStyle::DotDash => 0x08, + BorderStyle::Triple => 0x0A, + BorderStyle::Wave => 0x14, + BorderStyle::ThinThickSmallGap => 0x0B, + BorderStyle::ThickThinSmallGap => 0x0C, + BorderStyle::ThinThickThinSmallGap => 0x0D, + BorderStyle::ThinThickMediumGap => 0x0E, + BorderStyle::ThickThinMediumGap => 0x0F, + BorderStyle::ThinThickThinMediumGap => 0x10, + BorderStyle::ThinThickLargeGap => 0x11, + BorderStyle::ThickThinLargeGap => 0x12, + BorderStyle::ThinThickThinLargeGap => 0x13, + } +} + +/// A `Brc80` ([MS-DOC] §2.9.18): width in eighths of a point, type, palette colour, space. +pub(crate) fn brc80(b: &Border) -> [u8; 4] { + if b.style == BorderStyle::None { + return [0; 4]; + } + let dpt = (b.width * 8.0).round().clamp(2.0, 255.0) as u8; + let ico = b.color.map_or(0, nearest_ico); + let space = b.space.round().clamp(0.0, 31.0) as u8; + [dpt, brc_type(b.style), ico, space] +} + +/// A `Brc` ([MS-DOC] §2.9.16): `COLORREF`, width in eighths of a point, type, space and flags. +pub(crate) fn brc(b: &Border) -> [u8; 8] { + if b.style == BorderStyle::None { + return [0; 8]; + } + let cv = b.color.map_or(0, colorref); + let [c0, c1, c2, c3] = cv.to_le_bytes(); + let dpt = (b.width * 8.0).round().clamp(2.0, 255.0) as u8; + let space = b.space.round().clamp(0.0, 31.0) as u8; + [c0, c1, c2, c3, dpt, brc_type(b.style), space, 0] +} + +/// The paragraph's own tab stops as a `PChgTabsPapxOperand`: the cleared stops in `rgdxaDel`, +/// the others (with their alignment and leader) in `rgdxaAdd`, each list ascending. +fn tab_stops(g: &mut Grpprl, tabs: &[craft_wordmodel::props::TabStop]) { + let mut del: Vec = tabs.iter().filter(|t| t.align == TabAlign::Clear).map(|t| twips(t.pos)).collect(); + let mut add: Vec<(i16, u8)> = tabs + .iter() + .filter(|t| t.align != TabAlign::Clear) + .map(|t| { + let jc = match t.align { + TabAlign::Center => 1, + TabAlign::Right => 2, + TabAlign::Decimal => 3, + TabAlign::Bar => 4, + _ => 0, + }; + let tlc = match t.leader { + TabLeader::None => 0, + TabLeader::Dot => 1, + TabLeader::Hyphen => 2, + TabLeader::Underscore => 3, + TabLeader::MiddleDot => 5, + }; + (twips(t.pos), jc | (tlc << 3)) + }) + .collect(); + del.sort_unstable(); + del.dedup(); + add.sort_by_key(|t| t.0); + add.dedup_by_key(|t| t.0); + // The operand's size byte holds 255: 64 stops each way is Word's own limit and fits. + del.truncate(64); + add.truncate(64); + if del.is_empty() && add.is_empty() { + return; + } + let mut op = vec![del.len() as u8]; + for d in &del { + op.extend_from_slice(&d.to_le_bytes()); + } + op.push(add.len() as u8); + for (x, _) in &add { + op.extend_from_slice(&x.to_le_bytes()); + } + op.extend(add.iter().map(|(_, tbd)| *tbd)); + g.var(P_CHG_TABS_PAPX, &op); +} + +/// The table membership of a paragraph inside a table cell (`sprmPFInTable`, `sprmPItap`); the +/// row-end mark adds `sprmPFTtp`. +pub(crate) fn in_table(g: &mut Grpprl, row_end: bool) { + g.u8(P_IN_TABLE, 1); + if row_end { + g.u8(P_TTP, 1); + } + g.u32(P_ITAP, 1); +} + +// Section sprms ([MS-DOC] §2.6.4). +const S_BKC: u16 = 0x3009; +const S_TITLE_PAGE: u16 = 0x300A; +const S_CCOLUMNS: u16 = 0x500B; +const S_DXA_COLUMNS: u16 = 0x900C; +const S_NFC_PGN: u16 = 0x300E; +const S_PGN_RESTART: u16 = 0x3011; +const S_LNC: u16 = 0x3013; +const S_NLNN_MOD: u16 = 0x5015; +const S_DXA_LNN: u16 = 0x9016; +const S_HDR_TOP: u16 = 0xB017; +const S_HDR_BOTTOM: u16 = 0xB018; +const S_VJC: u16 = 0x301A; +const S_LNN_MIN: u16 = 0x501B; +const S_PGN_START: u16 = 0x501C; +const S_ORIENTATION: u16 = 0x301D; +const S_XA_PAGE: u16 = 0xB01F; +const S_YA_PAGE: u16 = 0xB020; +const S_DXA_LEFT: u16 = 0xB021; +const S_DXA_RIGHT: u16 = 0xB022; +const S_DYA_TOP: u16 = 0x9023; +const S_DYA_BOTTOM: u16 = 0x9024; +const S_DZA_GUTTER: u16 = 0xB025; +const S_EVENLY_SPACED: u16 = 0x3005; +const S_BIDI: u16 = 0x3228; + +/// The SEPX grpprl of a section: every page property, so the section reads the same whatever +/// the reader's defaults. +pub(crate) fn sepx(s: &SectionProps) -> Grpprl { + let mut g = Grpprl::default(); + g.u8( + S_BKC, + match s.start { + SectionStart::Continuous => 0, + SectionStart::NextColumn => 1, + SectionStart::NextPage => 2, + SectionStart::EvenPage => 3, + SectionStart::OddPage => 4, + }, + ); + if s.title_page { + g.u8(S_TITLE_PAGE, 1); + } + let cols = s.columns.count.clamp(1, 44); + if cols > 1 { + g.u16(S_CCOLUMNS, (cols - 1) as u16); + g.u16(S_DXA_COLUMNS, twips(s.columns.space.max(0.0)) as u16); + g.u8(S_EVENLY_SPACED, 1); + } + if let Some(start) = s.page_num_start { + g.u8(S_PGN_RESTART, 1); + g.u16(S_PGN_START, start.min(0x7FFF) as u16); + } + if s.page_num_format != NumFormat::Decimal { + g.u8(S_NFC_PGN, nfc(s.page_num_format)); + } + if let Some(ln) = &s.line_numbers { + g.u8( + S_LNC, + match ln.restart { + craft_wordmodel::section::LineNumberRestart::Page => 0, + craft_wordmodel::section::LineNumberRestart::Section => 1, + craft_wordmodel::section::LineNumberRestart::Continuous => 2, + }, + ); + g.u16(S_NLNN_MOD, ln.count_by.clamp(1, 100) as u16); + g.i16(S_DXA_LNN, twips(ln.distance.max(0.0))); + g.u16(S_LNN_MIN, ln.start.saturating_sub(1).min(0x7FFF) as u16); + } + g.u8(S_ORIENTATION, if s.landscape { 2 } else { 1 }); + g.u16(S_XA_PAGE, twips(s.page_w.max(7.2)) as u16); + g.u16(S_YA_PAGE, twips(s.page_h.max(7.2)) as u16); + g.u16(S_DXA_LEFT, twips(s.margin_left.max(0.0)) as u16); + g.u16(S_DXA_RIGHT, twips(s.margin_right.max(0.0)) as u16); + g.i16(S_DYA_TOP, twips(s.margin_top)); + g.i16(S_DYA_BOTTOM, twips(s.margin_bottom)); + g.u16(S_DZA_GUTTER, twips(s.gutter.max(0.0)) as u16); + g.u16(S_HDR_TOP, twips(s.header.max(0.0)) as u16); + g.u16(S_HDR_BOTTOM, twips(s.footer.max(0.0)) as u16); + let vjc = match s.valign { + PageVAlign::Top => 0, + PageVAlign::Center => 1, + PageVAlign::Justify => 2, + PageVAlign::Bottom => 3, + }; + if vjc != 0 { + g.u8(S_VJC, vjc); + } + if s.rtl { + g.u8(S_BIDI, 1); + } + g +} + +/// A number format as an `MSONFC` ([MS-OSHARED] §2.2.1.3): its place in the ST_NumberFormat +/// order up to 0x27, decimal past it (the formats Word 97 never had), 0xFF for none. +pub(crate) fn nfc(f: NumFormat) -> u8 { + match f { + NumFormat::None => 0xFF, + f => NumFormat::ALL.iter().position(|x| *x == f).filter(|&i| i <= 0x27).map_or(0, |i| i as u8), + } +} diff --git a/crates/doc-binary/src/write/lists.rs b/crates/doc-binary/src/write/lists.rs new file mode 100644 index 000000000..37c5b4e5b --- /dev/null +++ b/crates/doc-binary/src/write/lists.rs @@ -0,0 +1,184 @@ +//! Lists: `PlfLst` (one LSTF per abstract list, its nine LVLs after the array) and `PlfLfo` +//! (one LFO per model num, with LFOLVL start and level overrides) ([MS-DOC] §2.9.147, §2.9.150). + +use std::collections::HashMap; + +use craft_wordmodel::numbering::{Level, LevelSuffix, Numbering}; +use craft_wordmodel::props::{Align, ParaProps}; +use craft_wordmodel::section::NumFormat; + +use super::grpprl::{self, CharCtx, ParaCtx}; + +/// Levels of a multi-level list. +const LEVELS: usize = 9; +/// Most lists written (the format counts LFOs from 1 to 0x07FE). +const MAX_LISTS: usize = 0x07FE; + +/// The written lists: `PlfLst` (with its LVLs appended) and how much of it `lcbPlfLst` covers, +/// `PlfLfo`, and each model num id's LFO index. +pub(crate) struct Lists { + pub(crate) plf_lst: Vec, + pub(crate) lcb_plf_lst: u32, + pub(crate) plf_lfo: Vec, +} + +/// Each model num's 1-based LFO index, in `Numbering::nums` order. +pub(crate) fn lfo_indexes(n: &Numbering) -> HashMap { + n.nums.iter().take(MAX_LISTS).enumerate().map(|(i, num)| (num.id, (i + 1) as u16)).collect() +} + +/// The list id (`lsid`) of abstract list `i`: any unique value other than 0 and -1. +fn lsid(i: usize) -> i32 { + 0x1000_0000 + i as i32 +} + +pub(crate) fn write(n: &Numbering, ctx: &mut (impl CharCtx + ParaCtx)) -> Option { + let abstracts: Vec<_> = n.abstracts.iter().take(MAX_LISTS).collect(); + if abstracts.is_empty() || n.nums.is_empty() { + return None; + } + let mut lst = Vec::new(); + lst.extend_from_slice(&(abstracts.len() as i16).to_le_bytes()); + for (i, _) in abstracts.iter().enumerate() { + // LSTF: lsid, tplc, rgistdPara[9] (none), flags (multi-level), grfhic. + lst.extend_from_slice(&lsid(i).to_le_bytes()); + lst.extend_from_slice(&0u32.to_le_bytes()); + for _ in 0..LEVELS { + lst.extend_from_slice(&0x0FFFu16.to_le_bytes()); + } + lst.push(0); + lst.push(0); + } + let lcb_plf_lst = lst.len() as u32; + for a in &abstracts { + for l in 0..LEVELS { + let level = a.levels.get(l).cloned().unwrap_or_else(|| default_level(l)); + lst.extend_from_slice(&lvl(&level, ctx)); + } + } + + let nums: Vec<_> = n.nums.iter().take(MAX_LISTS).collect(); + let mut lfo = Vec::new(); + lfo.extend_from_slice(&(nums.len() as i32).to_le_bytes()); + let mut data = Vec::new(); + for num in &nums { + let ai = abstracts.iter().position(|a| a.id == num.abstract_id).unwrap_or(0); + // The overrides per level: a start value, a whole level, or both. + let mut over: Vec<(u8, Option, Option<&Level>)> = Vec::new(); + for &(l, start) in &num.start_overrides { + if usize::from(l) < LEVELS { + over.push((l, Some(start), None)); + } + } + for (l, level) in &num.level_overrides { + if usize::from(*l) >= LEVELS { + continue; + } + match over.iter_mut().find(|o| o.0 == *l) { + Some(o) => o.2 = Some(level), + None => over.push((*l, None, Some(level))), + } + } + over.sort_by_key(|o| o.0); + // LFO: lsid, unused1, unused2, clfolvl, ibstFltAutoNum, grfhic, unused3. + lfo.extend_from_slice(&lsid(ai).to_le_bytes()); + lfo.extend_from_slice(&[0u8; 8]); + lfo.push(over.len() as u8); + lfo.extend_from_slice(&[0u8; 3]); + // LFOData: cp (unused, 0xFFFFFFFF), then the LFOLVLs. + data.extend_from_slice(&u32::MAX.to_le_bytes()); + for (l, start, level) in over { + let start_at = start.or(level.map(|lv| lv.start)).unwrap_or(1).min(0x7FFF); + data.extend_from_slice(&(start_at as i32).to_le_bytes()); + let mut flags = l & 0x0F; + if start.is_some() { + flags |= 0x10; // fStartAt + } + if level.is_some() { + flags |= 0x20; // fFormatting + } + data.push(flags); + data.extend_from_slice(&[0u8; 3]); + if let Some(level) = level { + data.extend_from_slice(&lvl(level, ctx)); + } + } + } + lfo.extend_from_slice(&data); + Some(Lists { plf_lst: lst, lcb_plf_lst, plf_lfo: lfo }) +} + +/// A level the model's list doesn't have: decimal, `%n.`, indented a quarter inch a level. +fn default_level(l: usize) -> Level { + Level { start: 1, format: NumFormat::Decimal, text: format!("%{}.", l + 1), indent: 18.0 * (l as f32 + 1.0), hanging: 18.0, ..Level::default() } +} + +/// One LVL: LVLF, grpprlPapx (the indents), grpprlChpx (the number's formatting), number text. +fn lvl(level: &Level, ctx: &mut (impl CharCtx + ParaCtx)) -> Vec { + // Number text: `%n` placeholders become the level index (n − 1), their 1-based positions + // go in rgbxchNums. + let mut xst: Vec = Vec::new(); + let mut nums: Vec = Vec::new(); + let mut chars = level.text.chars().peekable(); + while let Some(c) = chars.next() { + if c == '%' + && let Some(d) = chars.peek().and_then(|d| d.to_digit(10)).filter(|d| (1..=9).contains(d)) + { + chars.next(); + xst.push((d - 1) as u16); + if nums.len() < 9 { + nums.push(xst.len() as u8); + } + continue; + } + let mut buf = [0u16; 2]; + xst.extend_from_slice(c.encode_utf16(&mut buf)); + } + xst.truncate(64); + nums.retain(|&p| usize::from(p) <= xst.len()); + + let mut papx = grpprl::papx(&ParaProps { indent_left: Some(level.indent), indent_first: Some(-level.hanging), ..Default::default() }, ctx); + papx.truncate_to(255); + let mut chpx = grpprl::chpx(&level.chr, ctx); + chpx.truncate_to(255); + + let mut v = Vec::with_capacity(28 + papx.len() + chpx.len() + 2 + xst.len() * 2); + v.extend_from_slice(&(level.start.min(0x7FFF) as i32).to_le_bytes()); + v.push(grpprl::nfc(level.format)); + let jc: u8 = match level.align { + Align::Center => 1, + Align::Right => 2, + _ => 0, + }; + let mut flags = jc; + if level.legal { + flags |= 0x04; + } + if !level.restart { + flags |= 0x08; + } + v.push(flags); + let mut rgbxch = [0u8; 9]; + for (slot, p) in rgbxch.iter_mut().zip(&nums) { + *slot = *p; + } + v.extend_from_slice(&rgbxch); + v.push(match level.suffix { + LevelSuffix::Tab => 0, + LevelSuffix::Space => 1, + LevelSuffix::Nothing => 2, + }); + v.extend_from_slice(&0i32.to_le_bytes()); // dxaIndentSav + v.extend_from_slice(&0u32.to_le_bytes()); // unused2 + v.push(chpx.len() as u8); + v.push(papx.len() as u8); + v.push(level.restart_after.map_or(0, |r| r.saturating_add(1)).min(LEVELS as u8)); + v.push(0); // grfhic + v.extend_from_slice(&papx.0); + v.extend_from_slice(&chpx.0); + v.extend_from_slice(&(xst.len() as u16).to_le_bytes()); + for u in &xst { + v.extend_from_slice(&u.to_le_bytes()); + } + v +} diff --git a/crates/doc-binary/src/write/mod.rs b/crates/doc-binary/src/write/mod.rs new file mode 100644 index 000000000..08cb43d53 --- /dev/null +++ b/crates/doc-binary/src/write/mod.rs @@ -0,0 +1,463 @@ +//! The `.doc` writer: a [`Document`] as a Word 97-2003 binary file ([MS-DOC]). +//! +//! The file is what Word 97 itself writes, minus the parts the model has nothing for: a compound file +//! with the WordDocument stream (the FIB, the text as one Unicode piece, the formatting pages and +//! the section properties), the 1Table stream (stylesheet, fonts, piece table, document +//! properties, the PLCs locating sections, headers, notes, fields and bookmarks, the lists), a +//! Data stream with the pictures, and the summary information. +//! +//! Kept: text, character and paragraph formatting, styles, lists, tables (one level; nested +//! tables become paragraphs of their cell), sections with headers and footers, footnotes and +//! endnotes, fields and hyperlinks, bookmarks, inline pictures, tracked insertions and deletions, +//! and the document properties. Floating pictures are written in line; shapes, charts, text +//! boxes and comments are left out, each kind logged once per save. + +mod fkp; +mod grpprl; +mod lists; +mod picture; +mod story; +mod styles; +mod summary; +mod tables; + +use std::collections::HashMap; + +use craft_wordmodel::Document; +use craft_wordmodel::para::{NoteKind, Paragraph}; +use craft_wordmodel::section::SectionProps; + +use crate::DocbinError; +use crate::fib::pair; +use grpprl::{CharCtx, Grpprl}; +use story::{Lookup, PARA, Text}; + +/// Where the text starts in the WordDocument stream: right after the FIB (900 bytes). +const TEXT_FC: u32 = 0x400; +/// Bytes in the FIB this writer produces: FibBase, csw + FibRgW97, cslw + FibRgLw97, +/// cbRgFcLcb + FibRgFcLcb97 (0x5D pairs), cswNew. +const FIB_LEN: usize = 0x9A + 0x5D * 8 + 2; +/// Most characters written: the WordDocument stream's FCs are 32-bit and each character takes +/// two bytes; stay far inside. +const MAX_CP: usize = 256 << 20; +/// Size of a Dop97. +const DOP97_LEN: usize = 500; + +/// Write `doc` as a Word 97-2003 document. +pub fn write(doc: &Document) -> Result, DocbinError> { + let plan = styles::plan(&doc.styles); + let normal = plan.istd.get("Normal").copied().unwrap_or(0); + let lfos = lists::lfo_indexes(&doc.numbering); + let mut look = Lookup::new(doc, plan.istd.clone(), normal, lfos); + // Font 0 is the document's default font, as in every Word file; the stylesheet header names + // it as the standard font. + let default_font = doc.styles.default_chr.font.clone().unwrap_or_else(|| "Times New Roman".to_string()); + let f_ascii = look.font(&default_font); + let f_ea = doc.styles.default_chr.font_ea.as_deref().map_or(f_ascii, |f| look.font(f)); + let f_cs = doc.styles.default_chr.font_cs.as_deref().map_or(f_ascii, |f| look.font(f)); + let stsh = styles::stsh(&doc.styles, &plan, &mut look, [f_ascii, f_ea, f_cs]); + let lists = lists::write(&doc.numbering, &mut look); + + let mut t = Text::new(look); + // The main document; it ends with a plain paragraph (a table or a section break can't end it). + t.blocks(&doc.body, true); + t.close_fields(); + let ends_plain = doc.body.last().and_then(|b| b.as_para()).is_some_and(|p| p.section.is_none()); + if !ends_plain || t.paras.last().is_none_or(|p| p.end_cp != t.cp()) { + t.mark(&Paragraph::new(), PARA, &Grpprl::default()); + } + let ccp_text = t.cp(); + let mut sections: Vec<(u32, SectionProps)> = std::mem::take(&mut t.sections); + sections.push((ccp_text, doc.last_section.clone())); + + // Footnotes, then the header document, then endnotes, each a subdocument. + let (ccp_ftn, ftn_txt) = notes(&mut t, doc, NoteKind::Footnote); + let hdd_start = t.cp(); + let hdd_stories = headers(&mut t, doc, §ions); + let ccp_hdd = t.cp() - hdd_start; + let (ccp_edn, edn_txt) = notes(&mut t, doc, NoteKind::Endnote); + if ccp_ftn + ccp_hdd + ccp_edn > 0 { + // One more paragraph mark after the last subdocument ([MS-DOC] §2.8.35). + t.mark(&Paragraph::new(), PARA, &Grpprl::default()); + } + let ccp_all = t.cp(); + if t.units.len() > MAX_CP { + return Err(DocbinError::Limit(format!("the document has {} characters, more than a .doc holds", t.units.len()))); + } + log_dropped(&t.dropped); + + // ---- WordDocument stream: FIB, text, formatting pages, section properties. + let mut word = vec![0u8; TEXT_FC as usize]; + for u in &t.units { + word.extend_from_slice(&u.to_le_bytes()); + } + let fc = |cp: u32| TEXT_FC + cp * 2; + pad_to(&mut word, 512); + let runs = t.char_runs(); + let chpx_runs: Vec = runs.iter().map(|&(a, b, g)| fkp::ChpxRun { fc_start: fc(a), fc_end: fc(b), grpprl: g }).collect(); + let chpx = fkp::chpx_pages(&chpx_runs); + let chpx_pn = (word.len() / 512) as u32; + for p in &chpx.pages { + word.extend_from_slice(p); + } + let mut start = 0u32; + let papx_runs: Vec = t + .paras + .iter() + .map(|p| { + let r = fkp::PapxRun { fc_start: fc(start), fc_end: fc(p.end_cp), istd: p.istd, grpprl: p.grpprl.as_slice() }; + start = p.end_cp; + r + }) + .collect(); + let papx = fkp::papx_pages(&papx_runs); + let papx_pn = (word.len() / 512) as u32; + for p in &papx.pages { + word.extend_from_slice(p); + } + let mut sepx_at = Vec::with_capacity(sections.len()); + for (_, s) in §ions { + pad_to(&mut word, 2); + sepx_at.push(word.len() as u32); + let g = grpprl::sepx(s); + word.extend_from_slice(&(g.len() as u16).to_le_bytes()); + word.extend_from_slice(&g.0); + } + let cb_mac = word.len() as u32; + + // ---- Table stream. + let mut tbl = TableStream::default(); + tbl.put(pair::STSHF, &stsh); + if let Some(&v) = tbl.pairs.get(&pair::STSHF) { + tbl.pairs.insert(0, v); // fcStshfOrig: the same stylesheet + } + // Notes: references in the main text and the stories in their subdocuments. + for (kind, ref_pair, txt_pair, ccp, txt) in [ + (NoteKind::Footnote, pair::PLCF_FND_REF, pair::PLCF_FND_TXT, ccp_ftn, &ftn_txt), + (NoteKind::Endnote, pair::PLCF_END_REF, pair::PLCF_END_TXT, ccp_edn, &edn_txt), + ] { + if ccp == 0 { + continue; + } + let refs: Vec<&story::NoteRefAt> = t.notes.iter().filter(|n| n.kind == kind).collect(); + let mut cps: Vec = refs.iter().map(|n| n.cp).collect(); + cps.push(ccp_text); + let idx: Vec<[u8; 2]> = refs.iter().enumerate().map(|(i, n)| if n.auto { (i as u16 + 1).to_le_bytes() } else { [0, 0] }).collect(); + tbl.put(ref_pair, &fkp::plc(&cps, &idx.iter().map(|x| &x[..]).collect::>())); + let mut tcps = txt.clone(); + tcps.push(ccp - 1); + tcps.push(ccp); + tbl.put(txt_pair, &fkp::plc(&tcps, &[])); + } + // Sections. + let mut sed_cps = vec![0u32]; + sed_cps.extend(sections.iter().map(|(end, _)| *end)); + let seds: Vec<[u8; 12]> = sepx_at + .iter() + .map(|at| { + let mut s = [0u8; 12]; + s[2..6].copy_from_slice(&at.to_le_bytes()); + s[8..12].copy_from_slice(&u32::MAX.to_le_bytes()); + s + }) + .collect(); + tbl.put(pair::PLCF_SED, &fkp::plc(&sed_cps, &seds.iter().map(|x| &x[..]).collect::>())); + if ccp_hdd > 0 { + let mut cps = hdd_stories; + cps.push(ccp_hdd - 1); + cps.push(ccp_hdd); + tbl.put(pair::PLCF_HDD, &fkp::plc(&cps, &[])); + } + tbl.put(pair::PLCF_BTE_CHPX, &chpx.plc_bte(chpx_pn)); + tbl.put(pair::PLCF_BTE_PAPX, &papx.plc_bte(papx_pn)); + // Fields, one PLC per subdocument with CPs relative to it. + let ftn_start = ccp_text; + let edn_start = hdd_start + ccp_hdd; + for (i, a, len) in [(16usize, 0, ccp_text), (18, ftn_start, ccp_ftn), (17, hdd_start, ccp_hdd), (48, edn_start, ccp_edn)] { + let f: Vec<&story::FieldChar> = t.fields.iter().filter(|f| f.cp >= a && f.cp < a + len).collect(); + if f.is_empty() { + continue; + } + let mut cps: Vec = f.iter().map(|f| f.cp - a).collect(); + cps.push(len); + tbl.put(i, &fkp::plc(&cps, &f.iter().map(|f| &f.fld[..]).collect::>())); + } + // Bookmarks in the main text (with an end): names, starts with the index of their end, ends. + let mut marks: Vec<(String, u32, u32)> = + t.bookmarks.iter().filter_map(|(n, a, b)| b.filter(|&b| b <= ccp_text && *a <= b).map(|b| (n.clone(), *a, b))).take(0x3FFF).collect(); + marks.sort_by_key(|m| m.1); + if !marks.is_empty() { + let mut ends: Vec<(u32, usize)> = marks.iter().enumerate().map(|(i, m)| (m.2, i)).collect(); + ends.sort(); + let mut ibkl = vec![0u16; marks.len()]; + for (pos, (_, i)) in ends.iter().enumerate() { + if let Some(slot) = ibkl.get_mut(*i) { + *slot = pos as u16; + } + } + let names: Vec<(String, Vec)> = marks.iter().map(|m| (m.0.chars().take(40).collect(), Vec::new())).collect(); + tbl.put(pair::STTBF_BKMK, &fkp::sttb_ext(&names, 0)); + let mut cps: Vec = marks.iter().map(|m| m.1).collect(); + cps.push(ccp_text + 1); + let fbkf: Vec<[u8; 4]> = ibkl + .iter() + .map(|i| { + let mut b = [0u8; 4]; + b[0..2].copy_from_slice(&i.to_le_bytes()); + b + }) + .collect(); + tbl.put(pair::PLCF_BKF, &fkp::plc(&cps, &fbkf.iter().map(|x| &x[..]).collect::>())); + let mut cps: Vec = ends.iter().map(|e| e.0).collect(); + cps.push(ccp_text + 1); + tbl.put(pair::PLCF_BKL, &fkp::plc(&cps, &[])); + } + tbl.put(31, &dop(doc)); + // SttbfAssoc MUST be there: 18 strings (template, title, author…), all empty here. + tbl.put(32, &fkp::sttb_ext(&vec![(String::new(), Vec::new()); 18], 0)); + // The piece table: one Unicode piece holding every character. + let mut plc = fkp::plc(&[0, ccp_all], &[]); + plc.extend_from_slice(&0u16.to_le_bytes()); + plc.extend_from_slice(&TEXT_FC.to_le_bytes()); + plc.extend_from_slice(&0u16.to_le_bytes()); + let mut clx = vec![0x02]; + clx.extend_from_slice(&(plc.len() as u32).to_le_bytes()); + clx.extend_from_slice(&plc); + tbl.put(pair::CLX, &clx); + if t.look.authors.len() > 1 { + let authors: Vec<(String, Vec)> = t.look.authors.iter().map(|a| (a.clone(), Vec::new())).collect(); + tbl.put(51, &fkp::sttb_ext(&authors, 0)); + } + if let Some(l) = &lists { + pad_to(&mut tbl.bytes, 2); + tbl.pairs.insert(pair::PLF_LST, (tbl.bytes.len() as u32, l.lcb_plf_lst)); + tbl.bytes.extend_from_slice(&l.plf_lst); + tbl.put(pair::PLF_LFO, &l.plf_lfo); + } + // The font table last: every font the text and styles name is in it now. + tbl.put(pair::STTBF_FFN, &styles::font_table(&t.look.fonts)); + + // ---- FIB. + let has_pic = !t.pictures.data.is_empty(); + let fib = fib(cb_mac, [ccp_text, ccp_ftn, ccp_hdd, ccp_edn], &tbl.pairs, has_pic); + if let Some(head) = word.get_mut(..FIB_LEN) { + head.copy_from_slice(&fib); + } + + // ---- The compound file. + let mut streams: Vec<(&str, Vec)> = vec![("WordDocument", word), ("1Table", tbl.bytes)]; + if has_pic { + streams.push(("Data", std::mem::take(&mut t.pictures.data))); + } + streams.push(("\u{5}SummaryInformation", summary::stream(&doc.core))); + compound(&streams) +} + +/// The Table stream being built, and the FIB pair (fc, lcb) of each structure in it. +#[derive(Default)] +struct TableStream { + bytes: Vec, + pairs: HashMap, +} + +impl TableStream { + /// Append a structure (word-aligned) and record it as FIB pair `i`; nothing for an empty one. + fn put(&mut self, i: usize, bytes: &[u8]) { + if bytes.is_empty() { + return; + } + pad_to(&mut self.bytes, 2); + self.pairs.insert(i, (self.bytes.len() as u32, bytes.len() as u32)); + self.bytes.extend_from_slice(bytes); + } +} + +/// Write the stories of the notes of `kind` the main text referred to, in reference order: +/// the subdocument's length and each story's start CP (relative to it). +fn notes(t: &mut Text<'_>, doc: &Document, kind: NoteKind) -> (u32, Vec) { + let start = t.cp(); + let parts: Vec = t.notes.iter().filter(|n| n.kind == kind).map(|n| n.part).collect(); + if parts.is_empty() { + return (0, Vec::new()); + } + let mut starts = Vec::with_capacity(parts.len()); + for id in parts { + starts.push(t.cp() - start); + let blocks = doc.parts.get(&id).map(|p| p.blocks.as_slice()).unwrap_or_default(); + t.note_story(kind, id, blocks); + t.close_fields(); + } + // The guard paragraph mark after the last story. + t.mark(&Paragraph::new(), PARA, &Grpprl::default()); + (t.cp() - start, starts) +} + +/// Write the header document: the six (empty) note separator stories, then six stories per +/// section (even header, header, even footer, footer, first-page header, first-page footer), +/// each ended by a guard paragraph mark. The story start CPs (relative); nothing is written +/// when no section has a header or footer. +fn headers(t: &mut Text<'_>, doc: &Document, sections: &[(u32, SectionProps)]) -> Vec { + let any = sections.iter().any(|(_, s)| { + [s.headers.default, s.headers.first, s.headers.even, s.footers.default, s.footers.first, s.footers.even].iter().any(Option::is_some) + }); + if !any { + return Vec::new(); + } + let start = t.cp(); + let mut cps = vec![0u32; 6]; + for (_, s) in sections { + for id in [s.headers.even, s.headers.default, s.footers.even, s.footers.default, s.headers.first, s.footers.first] { + cps.push(t.cp() - start); + let Some(part) = id.and_then(|id| doc.parts.get(&id)) else { continue }; + if part.blocks.is_empty() { + t.mark(&Paragraph::new(), PARA, &Grpprl::default()); + } else { + t.blocks(&part.blocks, false); + } + t.close_fields(); + t.mark(&Paragraph::new(), PARA, &Grpprl::default()); + } + } + // The final mark the last CP of Plcfhdd ends at ([MS-DOC] §2.8.22). + t.mark(&Paragraph::new(), PARA, &Grpprl::default()); + cps +} + +/// Log, once per save, each kind of content the file leaves out. +fn log_dropped(d: &story::Dropped) { + for (n, what) in [ + (d.shapes, "shapes, charts and text boxes are left out"), + (d.comments, "comments are left out"), + (d.nested_tables, "tables inside table cells become paragraphs of their cell"), + (d.floating_pictures, "floating pictures are placed in line with the text"), + (d.pictures, "pictures in formats a .doc can't hold are left out"), + (d.equations, "equations are written as their linear text"), + ] { + if n > 0 { + log::warn!(".doc save: {n} × {what}"); + } + } +} + +fn pad_to(v: &mut Vec, align: usize) { + while !v.len().is_multiple_of(align) { + v.push(0); + } +} + +/// The FIB for nFib 0x00C1 ([MS-DOC] §2.5): `ccp` is text, footnotes, headers, endnotes. +fn fib(cb_mac: u32, ccp: [u32; 4], pairs: &HashMap, has_pic: bool) -> Vec { + let mut v = vec![0u8; FIB_LEN]; + let put16 = |v: &mut Vec, at: usize, x: u16| { + if let Some(b) = v.get_mut(at..at + 2) { + b.copy_from_slice(&x.to_le_bytes()); + } + }; + put16(&mut v, 0x00, 0xA5EC); // wIdent + put16(&mut v, 0x02, 0x00C1); // nFib + put16(&mut v, 0x06, 0x0409); // lid + // fHasPic, fWhichTblStm (1Table), fExtChar. + put16(&mut v, 0x0A, 0x0200 | 0x1000 | if has_pic { 0x0008 } else { 0 }); + put16(&mut v, 0x0C, 0x00BF); // nFibBack + put16(&mut v, 0x20, 0x000E); // csw + put16(&mut v, 0x22 + 13 * 2, 0x0409); // FibRgW97.lidFE + put16(&mut v, 0x3E, 0x0016); // cslw + let put32 = |v: &mut Vec, at: usize, x: u32| { + if let Some(b) = v.get_mut(at..at + 4) { + b.copy_from_slice(&x.to_le_bytes()); + } + }; + put32(&mut v, 0x40, cb_mac); + put32(&mut v, 0x40 + 3 * 4, ccp[0]); + put32(&mut v, 0x40 + 4 * 4, ccp[1]); + put32(&mut v, 0x40 + 5 * 4, ccp[2]); + put32(&mut v, 0x40 + 8 * 4, ccp[3]); + put16(&mut v, 0x98, 0x005D); // cbRgFcLcb + for (&i, &(fc, lcb)) in pairs { + if i < 0x5D { + put32(&mut v, 0x9A + i * 8, fc); + put32(&mut v, 0x9A + i * 8 + 4, lcb); + } + } + // cswNew = 0: the last two bytes stay zero. + v +} + +/// A Dop97 ([MS-DOC] §2.7.4): footnotes at the bottom of the page, endnotes at the end of the +/// document, both numbered from 1; the default tab stop, hyphenation zone and the settings the +/// document carries; 100 % zoom. +fn dop(doc: &Document) -> Vec { + let s = &doc.settings; + let mut v = vec![0u8; DOP97_LEN]; + // fFacingPages (different odd and even headers), fpc = 1 (bottom of page). + v[0] = u8::from(s.even_odd_headers) | (1 << 5); + v[2..4].copy_from_slice(&(1u16 << 2).to_le_bytes()); // rncFtn 0, nFtn 1 + let mut flags: u32 = 0; + if s.auto_hyphenation { + flags |= 1 << 12; // fAutoHyphen + } + if s.hyphenate_caps { + flags |= 1 << 11; // fHyphCapitals + } + if s.track_changes { + flags |= 1 << 15; // fRevMarking + } + if s.mirror_margins { + flags |= 1 << 21; // fMirrorMargins + } + v[4..8].copy_from_slice(&flags.to_le_bytes()); + let tab = if s.default_tab > 0.0 { grpprl::twips(s.default_tab) } else { 720 }; + v[10..12].copy_from_slice(&tab.to_le_bytes()); // dxaTab + let hot = if s.hyphenation_zone > 0.0 { grpprl::twips(s.hyphenation_zone) } else { 360 }; + v[14..16].copy_from_slice(&hot.to_le_bytes()); // dxaHotZ + v[20..24].copy_from_slice(&dttm(&doc.core.created).to_le_bytes()); + v[24..28].copy_from_slice(&dttm(&doc.core.modified).to_le_bytes()); + v[32..34].copy_from_slice(&(doc.core.revision.clamp(1, u16::MAX as u32) as u16).to_le_bytes()); + v[52..54].copy_from_slice(&(1u16 << 2).to_le_bytes()); // rncEdn 0, nEdn 1 + v[54..56].copy_from_slice(&3u16.to_le_bytes()); // epc: end of document + v[82..84].copy_from_slice(&((100u16 << 3) | (1 << 12)).to_le_bytes()); // pctWwdSaved, zkSaved + v +} + +/// A `DTTM` ([MS-DOC] §2.9.75) from an ISO 8601 date; 0 when there is none. +pub(crate) fn dttm(iso: &str) -> u32 { + use chrono::{Datelike, Timelike}; + let Some(t) = parse_time(iso) else { return 0 }; + let year = t.year(); + if !(1900..=2411).contains(&year) { + return 0; + } + (t.minute() & 0x3F) + | ((t.hour() & 0x1F) << 6) + | ((t.day() & 0x1F) << 11) + | ((t.month() & 0xF) << 16) + | ((((year - 1900) as u32) & 0x1FF) << 20) + | ((t.weekday().num_days_from_sunday() & 7) << 29) +} + +/// An ISO 8601 date or date-time (UTC when it doesn't say). +pub(crate) fn parse_time(iso: &str) -> Option { + let s = iso.trim(); + if s.is_empty() { + return None; + } + if let Ok(t) = chrono::DateTime::parse_from_rfc3339(s) { + return Some(t.naive_utc()); + } + for f in ["%Y-%m-%dT%H:%M:%S", "%Y-%m-%dT%H:%M:%S%.f", "%Y-%m-%d %H:%M:%S"] { + if let Ok(t) = chrono::NaiveDateTime::parse_from_str(s.trim_end_matches('Z'), f) { + return Some(t); + } + } + chrono::NaiveDate::parse_from_str(s, "%Y-%m-%d").ok().and_then(|d| d.and_hms_opt(0, 0, 0)) +} + +/// The compound file holding `streams` at its root. Version 3 (512-byte sectors), the version +/// Word 97-2003 writes; readers of that era expect it. +fn compound(streams: &[(&str, Vec)]) -> Result, DocbinError> { + let refs: Vec<(&str, &[u8])> = streams.iter().map(|(name, data)| (*name, data.as_slice())).collect(); + craft_cfb::write_streams(craft_cfb::Version::V3, &refs).map_err(|e| DocbinError::Container(e.to_string())) +} + +#[cfg(test)] +mod tests; diff --git a/crates/doc-binary/src/write/picture.rs b/crates/doc-binary/src/write/picture.rs new file mode 100644 index 000000000..07eb19fa4 --- /dev/null +++ b/crates/doc-binary/src/write/picture.rs @@ -0,0 +1,211 @@ +//! Inline pictures in the Data stream: a `PICF` header ([MS-DOC] §2.9.193) followed by an +//! `OfficeArtInlineSpContainer` ([MS-ODRAW]): the picture-frame shape, its properties (the +//! picture's place in the BLIP store, crop, alt text) and the `OfficeArtFBSE` with the BLIP +//! embedded in it. The character 0x01 in the text points here through `sprmCPicLocation`. + +use sha1::Digest; + +/// `PICF.cbHeader`. +const CB_HEADER: u16 = 0x44; +/// `MM_SHAPE`: the picture is the OfficeArt shape that follows the header. +const MM_SHAPE: u16 = 0x0064; +/// Largest picture written (bytes of its BLIP): Word's own limit for one picture is far above +/// what the Data stream's 32-bit offsets allow many of. +const MAX_PICTURE: usize = 64 << 20; +/// All pictures together: `sprmCPicLocation` offsets are 32-bit, keep well inside them. +const MAX_DATA: usize = 1 << 30; + +/// OfficeArt record types and BLIP instances ([MS-ODRAW] §2.2). +const SP_CONTAINER: u16 = 0xF004; +const FSP: u16 = 0xF00A; +const FOPT: u16 = 0xF00B; +const FBSE: u16 = 0xF007; +const BLIP_EMF: (u16, u16) = (0xF01A, 0x3D4); +const BLIP_WMF: (u16, u16) = (0xF01B, 0x216); +const BLIP_JPEG: (u16, u16) = (0xF01D, 0x46A); +const BLIP_PNG: (u16, u16) = (0xF01E, 0x6E0); +/// `msosptPictureFrame`. +const SPT_PICTURE_FRAME: u16 = 75; + +/// The Data stream being built. +#[derive(Default)] +pub(crate) struct Pictures { + pub(crate) data: Vec, +} + +/// A picture in a form the BLIP store holds, with its `btWin32` type. +enum Blip { + Png(Vec), + Jpeg(Vec), + /// EMF (true) or WMF metafile bytes. + Metafile(Vec, bool), +} + +impl Blip { + /// Sniff `bytes`: PNG and JPEG go in as they are, metafiles compressed, other raster + /// formats (GIF, BMP, TIFF, WebP) re-encoded as PNG. + fn of(bytes: &[u8]) -> Option { + if bytes.starts_with(b"\x89PNG") { + return Some(Blip::Png(bytes.to_vec())); + } + if bytes.starts_with(&[0xFF, 0xD8, 0xFF]) { + return Some(Blip::Jpeg(bytes.to_vec())); + } + // EMF: an EMR_HEADER record (type 1) with " EMF" at offset 40. + if bytes.get(0..4) == Some(&[1, 0, 0, 0]) && bytes.get(40..44) == Some(b" EMF") { + return Some(Blip::Metafile(bytes.to_vec(), true)); + } + // WMF: the placeable header's key, or a plain header (type 1 or 2, header size 9). + if bytes.starts_with(&[0xD7, 0xCD, 0xC6, 0x9A]) || (matches!(bytes.get(0..4), Some([1 | 2, 0, 9, 0]))) { + // The BLIP holds the metafile without the placeable header. + let body = if bytes.starts_with(&[0xD7, 0xCD, 0xC6, 0x9A]) { bytes.get(22..)? } else { bytes }; + return Some(Blip::Metafile(body.to_vec(), false)); + } + let img = image::load_from_memory(bytes).ok()?; + let mut png = Vec::new(); + img.write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png).ok()?; + Some(Blip::Png(png)) + } + + /// `btWin32` ([MS-ODRAW] §2.4.1 MSOBLIPTYPE). + fn bt(&self) -> u8 { + match self { + Blip::Png(_) => 6, + Blip::Jpeg(_) => 5, + Blip::Metafile(_, true) => 2, + Blip::Metafile(_, false) => 3, + } + } + + /// The `OfficeArtBlip*` record. + fn record(&self, w_emu: i32, h_emu: i32) -> Vec { + let (raw, (typ, inst)) = match self { + Blip::Png(b) => (b, BLIP_PNG), + Blip::Jpeg(b) => (b, BLIP_JPEG), + Blip::Metafile(b, emf) => (b, if *emf { BLIP_EMF } else { BLIP_WMF }), + }; + let mut body = uid(raw).to_vec(); + match self { + Blip::Png(b) | Blip::Jpeg(b) => { + body.push(0xFF); // tag + body.extend_from_slice(b); + } + Blip::Metafile(b, _) => { + let packed = miniz_oxide::deflate::compress_to_vec_zlib(b, 6); + // OfficeArtMetafileHeader: cbSize, rcBounds, ptSize (EMUs), cbSave, compression + // (0 = deflate), filter (0xFE = none). + body.extend_from_slice(&(b.len() as u32).to_le_bytes()); + for v in [0i32, 0, w_emu / 12_700, h_emu / 12_700] { + body.extend_from_slice(&v.to_le_bytes()); + } + body.extend_from_slice(&w_emu.to_le_bytes()); + body.extend_from_slice(&h_emu.to_le_bytes()); + body.extend_from_slice(&(packed.len() as u32).to_le_bytes()); + body.push(0); + body.push(0xFE); + body.extend_from_slice(&packed); + } + } + rec(0, inst, typ, &body) + } +} + +/// A 16-byte id for a BLIP (the format wants an MD4; any digest identifies it). +fn uid(bytes: &[u8]) -> [u8; 16] { + let d = sha1::Sha1::digest(bytes); + let mut u = [0u8; 16]; + u.copy_from_slice(d.get(..16).unwrap_or(&[0; 16])); + u +} + +/// An OfficeArt record: header (version, instance, type, length) then the body. +fn rec(ver: u16, inst: u16, typ: u16, body: &[u8]) -> Vec { + let mut v = Vec::with_capacity(8 + body.len()); + v.extend_from_slice(&((ver & 0xF) | (inst << 4)).to_le_bytes()); + v.extend_from_slice(&typ.to_le_bytes()); + v.extend_from_slice(&(body.len() as u32).to_le_bytes()); + v.extend_from_slice(body); + v +} + +/// A 16.16 fixed-point fraction. +fn fixed(f: f32) -> u32 { + ((f.clamp(0.0, 0.99) * 65_536.0).round() as i32) as u32 +} + +impl Pictures { + /// Add a picture shown `w` × `h` points with `crop` (left, top, right, bottom fractions): + /// the offset of its `PICF` in the Data stream, `None` when the picture can't be stored. + pub(crate) fn add(&mut self, bytes: &[u8], w: f32, h: f32, crop: [f32; 4], alt: &str) -> Option { + if bytes.len() > MAX_PICTURE { + return None; + } + let blip = Blip::of(bytes)?; + let [cl, ct, cr, cb] = crop.map(|c| if c.is_finite() { c.clamp(0.0, 0.99) } else { 0.0 }); + // The goal size is the uncropped picture's: the crop takes its share off it. + let gw = (w.max(1.0) / (1.0 - cl - cr).max(0.01)).min(1584.0); + let gh = (h.max(1.0) / (1.0 - ct - cb).max(0.01)).min(1584.0); + let emu = |pt: f32| (pt * 12_700.0).round() as i32; + + let blip_rec = blip.record(emu(gw), emu(gh)); + let mut fbse = vec![blip.bt(), blip.bt()]; + fbse.extend_from_slice(&uid(bytes)); + fbse.extend_from_slice(&0x00FFu16.to_le_bytes()); // tag + fbse.extend_from_slice(&(blip_rec.len() as u32).to_le_bytes()); + fbse.extend_from_slice(&1u32.to_le_bytes()); // cRef + fbse.extend_from_slice(&0u32.to_le_bytes()); // foDelay: embedded + fbse.extend_from_slice(&[0, 0, 0, 0]); // unused1, cbName, unused2, unused3 + fbse.extend_from_slice(&blip_rec); + let fbse = rec(2, u16::from(blip.bt()), FBSE, &fbse); + + // The shape: an FSP (spid, fHaveAnchor | fHaveSpt) and its properties. + let mut fsp = 1025u32.to_le_bytes().to_vec(); + fsp.extend_from_slice(&0x0A00u32.to_le_bytes()); + let fsp = rec(2, SPT_PICTURE_FRAME, FSP, &fsp); + let mut props: Vec<(u16, u32)> = Vec::new(); + for (pid, f) in [(0x0100u16, ct), (0x0101, cb), (0x0102, cl), (0x0103, cr)] { + if f > 0.0 { + props.push((pid, fixed(f))); + } + } + props.push((0x4104, 1)); // pib, fBid: the first (only) store entry + let alt_units: Vec = alt.encode_utf16().take(4095).chain(std::iter::once(0)).collect(); + let has_alt = alt_units.len() > 1; + if has_alt { + props.push((0x8381, (alt_units.len() * 2) as u32)); // wzDescription, complex + } + let mut fopt = Vec::new(); + for (pid, v) in &props { + fopt.extend_from_slice(&pid.to_le_bytes()); + fopt.extend_from_slice(&v.to_le_bytes()); + } + if has_alt { + for u in &alt_units { + fopt.extend_from_slice(&u.to_le_bytes()); + } + } + let fopt = rec(3, props.len() as u16, FOPT, &fopt); + let mut sp = fsp; + sp.extend_from_slice(&fopt); + let sp = rec(0xF, 0, SP_CONTAINER, &sp); + + let lcb = usize::from(CB_HEADER) + sp.len() + fbse.len(); + let at = self.data.len(); + if at.checked_add(lcb)? > MAX_DATA { + return None; + } + let mut picf = vec![0u8; usize::from(CB_HEADER)]; + picf[0..4].copy_from_slice(&(lcb as u32).to_le_bytes()); + picf[4..6].copy_from_slice(&CB_HEADER.to_le_bytes()); + picf[6..8].copy_from_slice(&MM_SHAPE.to_le_bytes()); + // PICMID: dxaGoal, dyaGoal, mx, my (1000 = 100 %). + picf[28..30].copy_from_slice(&super::grpprl::twips(gw).to_le_bytes()); + picf[30..32].copy_from_slice(&super::grpprl::twips(gh).to_le_bytes()); + picf[32..34].copy_from_slice(&1000u16.to_le_bytes()); + picf[34..36].copy_from_slice(&1000u16.to_le_bytes()); + self.data.extend_from_slice(&picf); + self.data.extend_from_slice(&sp); + self.data.extend_from_slice(&fbse); + u32::try_from(at).ok() + } +} diff --git a/crates/doc-binary/src/write/story.rs b/crates/doc-binary/src/write/story.rs new file mode 100644 index 000000000..b74720c76 --- /dev/null +++ b/crates/doc-binary/src/write/story.rs @@ -0,0 +1,735 @@ +//! The text of every story, as Word's character stream: paragraphs and table cells end with +//! their marks, fields become begin/separator/end characters, pictures and note references +//! special characters, each character carrying its CHPX and each paragraph its PAPX +//! ([MS-DOC] §2.4.1 Retrieving Text, §2.4.3 Table Text). + +use std::collections::HashMap; +use std::sync::Arc; + +use craft_wordmodel::para::{InlineObject, NoteKind, Paragraph}; +use craft_wordmodel::props::{CharProps, ParaProps}; +use craft_wordmodel::section::SectionProps; +use craft_wordmodel::table::Table; +use craft_wordmodel::{Block, Document}; + +use super::grpprl::{self, CharCtx, Grpprl, ParaCtx}; +use super::picture::Pictures; +use super::tables; + +/// Paragraph mark, cell or row end, section mark and the other characters Word gives meaning. +pub(crate) const PARA: u16 = 0x0D; +pub(crate) const CELL: u16 = 0x07; +pub(crate) const SECTION: u16 = 0x0C; +const FIELD_BEGIN: u16 = 0x13; +const FIELD_SEP: u16 = 0x14; +const FIELD_END: u16 = 0x15; +const NOTE_REF: u16 = 0x02; +const PICTURE: u16 = 0x01; + +/// Deepest field nesting written; deeper fields keep their result text only. +const MAX_FIELD_DEPTH: usize = 20; + +/// One paragraph's mark: the CP after it, the paragraph's style and PAPX grpprl. +pub(crate) struct ParaEnd { + pub(crate) end_cp: u32, + pub(crate) istd: u16, + pub(crate) grpprl: Arc>, +} + +/// One field character ([MS-DOC] §2.9.84 Fld): its CP (absolute) and its two bytes. +pub(crate) struct FieldChar { + pub(crate) cp: u32, + pub(crate) fld: [u8; 2], +} + +/// A note reference in the main text: its CP, kind, story (part id) and whether it is numbered +/// automatically. +pub(crate) struct NoteRefAt { + pub(crate) cp: u32, + pub(crate) kind: NoteKind, + pub(crate) part: u32, + pub(crate) auto: bool, +} + +/// What the writer needs to look up while building the text. +pub(crate) struct Lookup<'d> { + pub(crate) doc: &'d Document, + /// Style id → istd. + pub(crate) styles: HashMap, + /// The istd of `Normal`. + pub(crate) normal: u16, + /// Model num id → 1-based LFO index. + pub(crate) lfos: HashMap, + /// Font names in table order and their indexes. + pub(crate) fonts: Vec, + font_index: HashMap, + /// Revision authors (`SttbfRMark`, index 0 = "Unknown") and their indexes. + pub(crate) authors: Vec, +} + +impl<'d> Lookup<'d> { + pub(crate) fn new(doc: &'d Document, styles: HashMap, normal: u16, lfos: HashMap) -> Self { + Lookup { doc, styles, normal, lfos, fonts: Vec::new(), font_index: HashMap::new(), authors: vec!["Unknown".to_string()] } + } +} + +impl CharCtx for Lookup<'_> { + fn font(&mut self, name: &str) -> u16 { + let name = name.trim(); + if let Some(&i) = self.font_index.get(name) { + return i; + } + // The font table keeps names Word can store (it counts them in 16-bit units). + let i = u16::try_from(self.fonts.len()).unwrap_or(0).min(0x7FFF); + if self.fonts.len() < 0x7FFF { + self.fonts.push(name.chars().take(31).collect()); + self.font_index.insert(name.to_string(), i); + } + i + } + + fn char_style(&self, id: &str) -> Option { + let st = self.doc.styles.get(id)?; + (st.kind == craft_wordmodel::styles::StyleKind::Character).then(|| self.styles.get(id).copied()).flatten() + } + + fn revision(&mut self, rev: u32) -> Option<(u16, u32)> { + let r = self.doc.revisions.get(rev as usize)?; + let author = if r.author.trim().is_empty() { "Unknown" } else { r.author.trim() }; + let ibst = match self.authors.iter().position(|a| a == author) { + Some(i) => i, + None => { + self.authors.push(author.to_string()); + self.authors.len() - 1 + } + }; + Some((u16::try_from(ibst).unwrap_or(0), super::dttm(&r.date))) + } +} + +impl ParaCtx for Lookup<'_> { + fn lfo(&self, num: u32) -> u16 { + self.lfos.get(&num).copied().unwrap_or(0) + } +} + +/// Grpprls are shared: a run or paragraph names one by its index. +#[derive(Default)] +struct Interned { + all: Vec>>, + index: HashMap>, usize>, +} + +impl Interned { + fn get(&mut self, g: Vec) -> usize { + if let Some(&i) = self.index.get(&g) { + return i; + } + let g = Arc::new(g); + self.all.push(g.clone()); + self.index.insert(g, self.all.len() - 1); + self.all.len() - 1 + } +} + +/// Counts of content the binary format (as written here) leaves out, logged once per save. +#[derive(Default, Debug)] +pub(crate) struct Dropped { + pub(crate) shapes: usize, + pub(crate) comments: usize, + pub(crate) nested_tables: usize, + pub(crate) floating_pictures: usize, + pub(crate) pictures: usize, + pub(crate) equations: usize, +} + +/// The character stream of every story, with what each character and paragraph carries. +pub(crate) struct Text<'d> { + pub(crate) look: Lookup<'d>, + pub(crate) units: Vec, + /// Run starts: (CP, interned CHPX), each run up to the next start. + runs: Vec<(u32, usize)>, + chpx: Interned, + /// CHPX → the same with `sprmCFSpec`, for field characters. + spec: HashMap, + pub(crate) paras: Vec, + /// Field characters of the subdocument being written, then of each finished one. + pub(crate) fields: Vec, + /// Bookmarks: name, start CP, end CP (absolute), in the order they start. + pub(crate) bookmarks: Vec<(String, u32, Option)>, + pub(crate) notes: Vec, + /// Section ends in the main text: the CP after each section mark, and its properties. + pub(crate) sections: Vec<(u32, SectionProps)>, + pub(crate) pictures: Pictures, + pub(crate) dropped: Dropped, + /// Fields begun with a `FieldStart` and not yet ended (their nesting depth counts here). + open_fields: usize, + /// The note story being written: its own reference mark is its leading 0x02. + note: Option<(NoteKind, u32)>, + /// Inside a table cell: section marks can't end a cell's paragraph. + in_cell: bool, +} + +impl<'d> Text<'d> { + pub(crate) fn new(look: Lookup<'d>) -> Self { + Text { + look, + units: Vec::new(), + runs: Vec::new(), + chpx: Interned::default(), + spec: HashMap::new(), + paras: Vec::new(), + fields: Vec::new(), + bookmarks: Vec::new(), + notes: Vec::new(), + sections: Vec::new(), + pictures: Pictures::default(), + dropped: Dropped::default(), + open_fields: 0, + note: None, + in_cell: false, + } + } + + /// The CP the next character gets. + pub(crate) fn cp(&self) -> u32 { + u32::try_from(self.units.len()).unwrap_or(u32::MAX) + } + + /// The character runs: (start CP, end CP, CHPX grpprl). + pub(crate) fn char_runs(&self) -> Vec<(u32, u32, &[u8])> { + let end = self.cp(); + self.runs + .iter() + .enumerate() + .map(|(i, &(cp, g))| { + let next = self.runs.get(i + 1).map_or(end, |r| r.0); + (cp, next, self.chpx.all.get(g).map_or(&[][..], |v| v.as_slice())) + }) + .collect() + } + + fn emit(&mut self, unit: u16, chpx: usize) { + let cp = self.cp(); + if self.runs.last().is_none_or(|&(_, g)| g != chpx) { + self.runs.push((cp, chpx)); + } + self.units.push(unit); + } + + /// The interned CHPX of `props`, plus `extra` sprms. + fn chpx_of(&mut self, props: &CharProps, extra: Option<&Grpprl>) -> usize { + let mut g = grpprl::chpx(props, &mut self.look); + if let Some(e) = extra { + g.extend(e); + } + g.truncate_to(255); + self.chpx.get(g.0) + } + + fn text(&mut self, s: &str, chpx: usize) { + for c in s.chars() { + self.char(c, chpx); + } + } + + /// One character of text, mapped to what Word stores for it. + fn char(&mut self, c: char, chpx: usize) { + let unit = match c { + '\n' => 0x0B, + '\t' => 0x09, + '\u{C}' => 0x0C, + '\u{E}' => 0x0E, + '\u{2011}' => 0x1E, + '\u{AD}' => 0x1F, + '\r' | '\u{FFFC}' => return, + c if (c as u32) < 0x20 => return, + c => { + let mut buf = [0u16; 2]; + for u in c.encode_utf16(&mut buf).iter() { + self.emit(*u, chpx); + } + return; + } + }; + self.emit(unit, chpx); + } + + /// A field character: the text's formatting with `sprmCFSpec` on, as every field character + /// MUST have ([MS-DOC] §2.8.25). + fn field_char(&mut self, ch: u16, second: u8, chpx: usize) { + let spec = match self.spec.get(&chpx) { + Some(&s) => s, + None => { + let mut g = Grpprl(self.chpx.all.get(chpx).map_or_else(Vec::new, |g| g.as_ref().clone())); + g.truncate_to(252); + g.u8(grpprl::C_SPEC, 1); + let s = self.chpx.get(g.0); + self.spec.insert(chpx, s); + s + } + }; + self.fields.push(FieldChar { cp: self.cp(), fld: [ch as u8, second] }); + self.emit(ch, spec); + } + + /// A whole field: begin, its code, separator and result, end. + fn field(&mut self, instr: &str, result: Option<&str>, locked: bool, dirty: bool, chpx: usize) { + if self.open_fields >= MAX_FIELD_DEPTH { + if let Some(r) = result { + self.text(r, chpx); + } + return; + } + self.field_char(FIELD_BEGIN, flt(instr), chpx); + self.text(&format!(" {} ", instr.trim()), chpx); + if let Some(r) = result { + self.field_char(FIELD_SEP, 0, chpx); + self.text(r, chpx); + } + self.field_char(FIELD_END, end_flags(result.is_some(), locked, dirty, self.open_fields > 0), chpx); + } + + /// Write `blocks` as a story's paragraphs and tables. + pub(crate) fn blocks(&mut self, blocks: &[Arc], top: bool) { + for b in blocks { + match &**b { + Block::Para(p) => self.paragraph(p, top, None), + Block::Table(t) => self.table(t), + } + } + } + + /// Write a note's story, its reference mark first. + pub(crate) fn note_story(&mut self, kind: NoteKind, part: u32, blocks: &[Arc]) { + let own_mark = blocks + .first() + .and_then(|b| b.as_para()) + .is_some_and(|p| p.objects.iter().any(|o| matches!(o, InlineObject::NoteRef { kind: k, id, .. } if *k == kind && *id == part))); + self.note = Some((kind, part)); + if !own_mark { + let style = self.note_ref_style(kind); + let chpx = self.special(&style); + self.emit(NOTE_REF, chpx); + } + if blocks.is_empty() { + self.mark(&Paragraph::new(), PARA, &Grpprl::default()); + } + self.blocks(blocks, false); + self.note = None; + } + + /// A character style for note references ("footnote reference"), when the document has it. + fn note_ref_style(&self, kind: NoteKind) -> CharProps { + let id = match kind { + NoteKind::Footnote => "FootnoteReference", + NoteKind::Endnote => "EndnoteReference", + }; + let style = self.look.styles.contains_key(id).then(|| id.to_string()); + CharProps { style, ..Default::default() } + } + + /// The CHPX of a special character (a note reference, a picture): `sprmCFSpec` on. + fn special(&mut self, props: &CharProps) -> usize { + let mut extra = Grpprl::default(); + extra.u8(grpprl::C_SPEC, 1); + self.chpx_of(props, Some(&extra)) + } + + /// One paragraph: its text, then its mark (`mark` overrides the paragraph mark, for cells; + /// a paragraph ending a main-text section takes a section mark). + pub(crate) fn paragraph(&mut self, p: &Paragraph, top: bool, cell: Option<(u16, &Grpprl)>) { + let mut objects = p.objects.iter(); + let mut link: Option<(String, usize)> = None; + let mut at = 0usize; + for run in &p.runs { + let end = at.saturating_add(run.len).min(p.text.len()); + let Some(s) = p.text.get(at..end) else { break }; + at = end; + if s.is_empty() { + continue; + } + // A run's link becomes a HYPERLINK field around the runs that share it. + let mut props = run.props.clone(); + let target = props.link.take(); + if link.as_ref().map(|l| &l.0) != target.as_ref() { + if let Some((_, chpx)) = link.take() { + self.field_char(FIELD_END, end_flags(true, false, false, self.open_fields > 0), chpx); + } + if let Some(t) = &target { + let chpx = self.chpx_of(&props, None); + self.field_char(FIELD_BEGIN, FLT_HYPERLINK, chpx); + self.text(&format!(" {} ", hyperlink_instr(t)), chpx); + self.field_char(FIELD_SEP, 0, chpx); + link = Some((t.clone(), chpx)); + } + } + let chpx = self.chpx_of(&props, None); + for c in s.chars() { + if c == '\u{FFFC}' { + if let Some(o) = objects.next() { + self.object(o, &props, chpx); + } + } else { + self.char(c, chpx); + } + } + } + if let Some((_, chpx)) = link.take() { + self.field_char(FIELD_END, end_flags(true, false, false, self.open_fields > 0), chpx); + } + match cell { + Some((mark, extra)) => self.mark(p, mark, extra), + None => { + let section = top && !self.in_cell && p.section.is_some(); + self.mark(p, if section { SECTION } else { PARA }, &Grpprl::default()); + if section && let Some(s) = &p.section { + self.sections.push((self.cp(), (**s).clone())); + } + } + } + } + + /// The paragraph mark: its character formatting is the paragraph's mark formatting; the + /// PAPX carries the style and paragraph properties (plus `extra`, for table cells). + pub(crate) fn mark(&mut self, p: &Paragraph, mark: u16, extra: &Grpprl) { + let chpx = self.chpx_of(&p.mark, None); + self.emit(mark, chpx); + let (istd, g) = self.papx_of(&p.props, extra); + self.paras.push(ParaEnd { end_cp: self.cp(), istd, grpprl: g }); + } + + pub(crate) fn papx_of(&mut self, props: &ParaProps, extra: &Grpprl) -> (u16, Arc>) { + let istd = props.style.as_deref().and_then(|s| self.look.styles.get(s).copied()).unwrap_or(self.look.normal); + let mut g = grpprl::papx(props, &self.look); + g.extend(extra); + g.truncate_to(super::fkp::MAX_PAPX_GRPPRL); + (istd, Arc::new(g.0)) + } + + fn object(&mut self, o: &InlineObject, props: &CharProps, chpx: usize) { + match o { + InlineObject::Field { instr, result, locked, dirty, .. } => self.field(instr, Some(result), *locked, *dirty, chpx), + InlineObject::FieldStart { instr, locked, dirty } => { + if self.open_fields >= MAX_FIELD_DEPTH { + self.open_fields += 1; + return; + } + self.field_char(FIELD_BEGIN, flt(instr), chpx); + self.text(&format!(" {} ", instr.trim()), chpx); + self.field_char(FIELD_SEP, 0, chpx); + // The end's flags are decided now: they don't depend on the result. + self.open_fields += 1; + let _ = (locked, dirty); + } + InlineObject::FieldEnd => { + if self.open_fields == 0 { + return; + } + self.open_fields -= 1; + if self.open_fields < MAX_FIELD_DEPTH { + self.field_char(FIELD_END, end_flags(true, false, false, self.open_fields > 0), chpx); + } + } + InlineObject::NoteRef { kind, id, custom } => { + if self.note == Some((*kind, *id)) { + let c = self.special(props); + self.emit(NOTE_REF, c); + } else if self.note.is_none() { + let cp = self.cp(); + let c = self.special(props); + self.emit(NOTE_REF, c); + self.notes.push(NoteRefAt { cp, kind: *kind, part: *id, auto: custom.is_empty() }); + } + } + InlineObject::BookmarkStart { name } => { + if !name.is_empty() && self.bookmarks.iter().all(|(n, _, _)| n != name) { + self.bookmarks.push((name.clone(), self.cp(), None)); + } + } + InlineObject::BookmarkEnd { name } => { + let cp = self.cp(); + if let Some(b) = self.bookmarks.iter_mut().find(|(n, _, e)| n == name && e.is_none()) { + b.2 = Some(cp); + } + } + InlineObject::Image { media, w, h, crop, float, alt, .. } => { + if float.wrap != craft_wordmodel::para::Wrap::Inline { + self.dropped.floating_pictures += 1; + } + let Some(bytes) = self.look.doc.media.get(media).cloned() else { + self.dropped.pictures += 1; + return; + }; + match self.pictures.add(&bytes, *w, *h, *crop, alt) { + Some(fc) => { + let mut extra = Grpprl::default(); + extra.u8(grpprl::C_SPEC, 1); + extra.u32(grpprl::C_PIC_LOCATION, fc); + let c = self.chpx_of(props, Some(&extra)); + self.emit(PICTURE, c); + } + None => self.dropped.pictures += 1, + } + } + InlineObject::Equation { linear, .. } => { + self.dropped.equations += 1; + self.text(linear, chpx); + } + InlineObject::Ruby { base, .. } => self.text(base, chpx), + InlineObject::PositionalTab { .. } => self.emit(0x09, chpx), + InlineObject::Opaque { text, .. } => self.text(text, chpx), + InlineObject::CommentStart { .. } => self.dropped.comments += 1, + InlineObject::Shape { .. } | InlineObject::Group { .. } | InlineObject::Graphic { .. } => self.dropped.shapes += 1, + InlineObject::CommentEnd { .. } + | InlineObject::ControlStart { .. } + | InlineObject::ControlEnd + | InlineObject::PermStart { .. } + | InlineObject::PermEnd { .. } => {} + } + } + + /// End fields left open at the end of a story, so every begin has its end; the ends get a + /// paragraph of their own, as the story must end with a mark. + pub(crate) fn close_fields(&mut self) { + let mut wrote = false; + while self.open_fields > 0 { + self.open_fields -= 1; + if self.open_fields < MAX_FIELD_DEPTH { + let chpx = self.chpx.get(Vec::new()); + self.field_char(FIELD_END, end_flags(true, false, false, self.open_fields > 0), chpx); + wrote = true; + } + } + if wrote { + self.mark(&Paragraph::new(), PARA, &Grpprl::default()); + } + } + + /// A table: each cell's paragraphs end with a cell mark, each row with a row-end mark that + /// carries the row's table properties ([MS-DOC] §2.4.3). + fn table(&mut self, t: &Table) { + let was = self.in_cell; + self.in_cell = true; + let rows = t.rows.len(); + let style_borders = t.props.style.as_deref().and_then(|s| self.look.doc.styles.get(s)).and_then(|s| s.table.as_ref()).and_then(|p| p.borders); + for (ri, row) in t.rows.iter().enumerate() { + // A row has at most 63 cells: the text of any past them goes in the last one. + let last = row.cells.len().min(tables::MAX_CELLS).saturating_sub(1); + let mut in_table = Grpprl::default(); + grpprl::in_table(&mut in_table, false); + for (ci, cell) in row.cells.iter().enumerate() { + let mut paras: Vec<&Paragraph> = Vec::new(); + let mut owned: Vec = Vec::new(); + flatten(&cell.blocks, &mut paras, &mut owned, &mut self.dropped.nested_tables); + let all: Vec<&Paragraph> = if owned.is_empty() { paras } else { owned.iter().collect() }; + // Whether this cell's last paragraph ends the (possibly merged) cell. + let ends_cell = ci < last || ci + 1 == row.cells.len(); + if all.is_empty() { + let mark = if ends_cell { CELL } else { PARA }; + self.paragraph(&Paragraph::new(), false, Some((mark, &in_table))); + continue; + } + for (i, p) in all.iter().enumerate() { + let mark = if ends_cell && i + 1 == all.len() { CELL } else { PARA }; + self.paragraph(p, false, Some((mark, &in_table))); + } + } + let tapx = tables::row_end(t, ri, rows, style_borders); + let mut extra = Grpprl::default(); + grpprl::in_table(&mut extra, true); + extra.extend(&tapx); + self.mark(&Paragraph::new(), CELL, &extra); + } + self.in_cell = was; + } +} + +/// A cell's paragraphs, nested tables flattened into their own paragraphs (the writer keeps one +/// level of tables). When there is nothing to flatten `paras` borrows; else `owned` holds all. +fn flatten<'a>(blocks: &'a [Arc], paras: &mut Vec<&'a Paragraph>, owned: &mut Vec, nested: &mut usize) { + if blocks.iter().all(|b| b.as_para().is_some()) { + paras.extend(blocks.iter().filter_map(|b| b.as_para())); + return; + } + *nested += 1; + fn walk(blocks: &[Arc], out: &mut Vec, depth: usize) { + for b in blocks { + match &**b { + Block::Para(p) => out.push(p.clone()), + Block::Table(t) if depth < 16 => { + for row in &t.rows { + for c in &row.cells { + walk(&c.blocks, out, depth + 1); + } + } + } + Block::Table(_) => {} + } + } + } + walk(blocks, owned, 0); +} + +/// `flt` of a HYPERLINK field. +const FLT_HYPERLINK: u8 = 88; + +/// The field type (`flt`, [MS-DOC] §2.9.87) of a field code, from its first word; 0x01 (an +/// unknown keyword) for anything not in the table, which Word reparses from the code anyway. +fn flt(instr: &str) -> u8 { + let word = instr.split_whitespace().next().unwrap_or("").trim_start_matches('=').to_ascii_uppercase(); + if instr.trim_start().starts_with('=') { + return 34; + } + match word.as_str() { + "REF" => 3, + "FTNREF" => 5, + "SET" => 6, + "IF" => 7, + "INDEX" => 8, + "TC" => 9, + "STYLEREF" => 10, + "SEQ" => 12, + "TOC" => 13, + "INFO" => 14, + "TITLE" => 15, + "SUBJECT" => 16, + "AUTHOR" => 17, + "KEYWORDS" => 18, + "COMMENTS" => 19, + "LASTSAVEDBY" => 20, + "CREATEDATE" => 21, + "SAVEDATE" => 22, + "PRINTDATE" => 23, + "REVNUM" => 24, + "EDITTIME" => 25, + "NUMPAGES" => 26, + "NUMWORDS" => 27, + "NUMCHARS" => 28, + "FILENAME" => 29, + "TEMPLATE" => 30, + "DATE" => 31, + "TIME" => 32, + "PAGE" => 33, + "QUOTE" => 35, + "INCLUDE" => 36, + "PAGEREF" => 37, + "ASK" => 38, + "FILLIN" => 39, + "DATA" => 40, + "NEXT" => 41, + "NEXTIF" => 42, + "SKIPIF" => 43, + "MERGEREC" => 44, + "DDE" => 45, + "DDEAUTO" => 46, + "GLOSSARY" => 47, + "PRINT" => 48, + "EQ" => 49, + "GOTOBUTTON" => 50, + "MACROBUTTON" => 51, + "AUTONUMOUT" => 52, + "AUTONUMLGL" => 53, + "AUTONUM" => 54, + "IMPORT" => 55, + "LINK" => 56, + "SYMBOL" => 57, + "EMBED" => 58, + "MERGEFIELD" => 59, + "USERNAME" => 60, + "USERINITIALS" => 61, + "USERADDRESS" => 62, + "BARCODE" => 63, + "DOCVARIABLE" => 64, + "SECTION" => 65, + "SECTIONPAGES" => 66, + "INCLUDEPICTURE" => 67, + "INCLUDETEXT" => 68, + "FILESIZE" => 69, + "FORMTEXT" => 70, + "FORMCHECKBOX" => 71, + "NOTEREF" => 72, + "TOA" => 73, + "TA" => 74, + "MERGESEQ" => 75, + "AUTOTEXT" => 79, + "COMPARE" => 80, + "ADDIN" => 81, + "FORMDROPDOWN" => 83, + "ADVANCE" => 84, + "DOCPROPERTY" => 85, + "CONTROL" => 87, + "HYPERLINK" => 88, + "AUTOTEXTLIST" => 89, + "LISTNUM" => 90, + "HTMLCONTROL" => 91, + "BIDIOUTLINE" => 92, + "ADDRESSBLOCK" => 93, + "GREETINGLINE" => 94, + "SHAPE" => 95, + "CITATION" => 96, + "BIBLIOGRAPHY" => 97, + _ => 1, + } +} + +/// The second byte of a field end ([MS-DOC] §2.9.84 grffldEnd): `fHasSep` when there is a +/// result, `fLocked`, `fResultsDirty` and `fNested`. +fn end_flags(has_sep: bool, locked: bool, dirty: bool, nested: bool) -> u8 { + let mut f = 0u8; + if dirty { + f |= 0x04; + } + if locked { + f |= 0x10; + } + if nested { + f |= 0x40; + } + if has_sep { + f |= 0x80; + } + f +} + +/// The field code of a link: `HYPERLINK "url"`, `HYPERLINK \l "bookmark"` for an internal +/// one, or both for a link into another document's bookmark. A quote or backslash in an +/// argument is escaped with a backslash, as field codes do. +fn hyperlink_instr(target: &str) -> String { + let q = |s: &str| s.replace('\\', "\\\\").replace('"', "\\\""); + match target.split_once('#') { + Some(("", frag)) => format!("HYPERLINK \\l \"{}\"", q(frag)), + Some((url, frag)) if !frag.is_empty() && !url.contains("://") => format!("HYPERLINK \"{}\" \\l \"{}\"", q(url), q(frag)), + _ => format!("HYPERLINK \"{}\"", q(target)), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn field_types() { + assert_eq!(flt("PAGE"), 33); + assert_eq!(flt(" hyperlink \"x\""), 88); + assert_eq!(flt("= 2 + 2"), 34); + assert_eq!(flt("NOSUCHFIELD"), 1); + } + + #[test] + fn hyperlink_codes() { + assert_eq!(hyperlink_instr("https://example.org/a#b"), "HYPERLINK \"https://example.org/a#b\""); + assert_eq!(hyperlink_instr("#Intro"), "HYPERLINK \\l \"Intro\""); + assert_eq!(hyperlink_instr("other.doc#Part"), "HYPERLINK \"other.doc\" \\l \"Part\""); + assert_eq!(craft_wordmodel::link::hyperlink_target(&hyperlink_instr("#Intro")).as_deref(), Some("#Intro")); + assert_eq!( + craft_wordmodel::link::hyperlink_target(&hyperlink_instr("https://example.org/?q=\"x\"")).as_deref(), + Some("https://example.org/?q=\"x\"") + ); + assert_eq!( + craft_wordmodel::link::hyperlink_target(&hyperlink_instr(r"file:///C:\docs\report.doc")).as_deref(), + Some(r"file:///C:\docs\report.doc") + ); + assert_eq!(craft_wordmodel::link::hyperlink_target(&hyperlink_instr("#a\"b")).as_deref(), Some("#a\"b")); + } +} diff --git a/crates/doc-binary/src/write/styles.rs b/crates/doc-binary/src/write/styles.rs new file mode 100644 index 000000000..d1d6a6649 --- /dev/null +++ b/crates/doc-binary/src/write/styles.rs @@ -0,0 +1,400 @@ +//! The stylesheet (`STSH`, [MS-DOC] §2.9.271) and the font table (`SttbfFfn`, §2.9.286). +//! +//! Istds 0–14 are fixed: 0 Normal, 1–9 heading 1–9, 10 Default Paragraph Font, 11 Normal +//! Table, 12 No List, 13–14 unused. Every other style follows from istd 15 in stylesheet +//! order. A style Word has built in keeps its `sti` and the name Word gives it, so Word treats +//! it as its own; the rest are user styles. + +use std::collections::HashMap; + +use craft_wordmodel::props::CharProps; +use craft_wordmodel::styles::{Style, StyleKind, StyleSheet}; + +use super::grpprl::{self, CharCtx, Grpprl, ParaCtx}; + +/// Istds reserved for built-in styles. +const FIXED: u16 = 15; +/// `sti` of a user-defined style. +const STI_USER: u16 = 0x0FFE; +/// `istdBase` / `istdNext` meaning "none". +const ISTD_NIL: u16 = 0x0FFF; +/// Most styles written (the format allows 0x0FFE). +const MAX_STYLES: usize = 4000; + +/// Built-in styles: the name Word stores (lower-case where Word's is), and the `sti`. +const BUILTIN: &[(&str, u16)] = &[ + ("Normal", 0), + ("heading 1", 1), + ("heading 2", 2), + ("heading 3", 3), + ("heading 4", 4), + ("heading 5", 5), + ("heading 6", 6), + ("heading 7", 7), + ("heading 8", 8), + ("heading 9", 9), + ("toc 1", 19), + ("toc 2", 20), + ("toc 3", 21), + ("toc 4", 22), + ("toc 5", 23), + ("toc 6", 24), + ("toc 7", 25), + ("toc 8", 26), + ("toc 9", 27), + ("Normal Indent", 28), + ("footnote text", 29), + ("annotation text", 30), + ("header", 31), + ("footer", 32), + ("index heading", 33), + ("caption", 34), + ("table of figures", 35), + ("footnote reference", 38), + ("annotation reference", 39), + ("line number", 40), + ("page number", 41), + ("endnote reference", 42), + ("endnote text", 43), + ("List", 47), + ("List Bullet", 48), + ("List Number", 49), + ("Title", 62), + ("Signature", 64), + ("Default Paragraph Font", 65), + ("Body Text", 66), + ("Body Text Indent", 67), + ("List Continue", 68), + ("Subtitle", 74), + ("Salutation", 75), + ("Date", 76), + ("Hyperlink", 85), + ("FollowedHyperlink", 86), + ("Strong", 87), + ("Emphasis", 88), + ("Plain Text", 91), + ("Normal (Web)", 94), + ("Normal Table", 105), + ("No List", 107), + ("Balloon Text", 153), + ("Table Grid", 154), + ("Placeholder Text", 156), + ("No Spacing", 157), + ("List Paragraph", 179), + ("Quote", 180), + ("Intense Quote", 181), + ("Subtle Emphasis", 260), + ("Intense Emphasis", 261), + ("Subtle Reference", 262), + ("Intense Reference", 263), + ("Book Title", 264), + ("Bibliography", 265), + ("TOC Heading", 266), +]; + +/// The built-in style a model style is, by its name or id (`Heading 1`, `Heading1` and +/// `heading 1` are the same), with the name Word stores. +fn builtin(st: &Style) -> Option<(&'static str, u16)> { + let norm = |s: &str| s.chars().filter(|c| !c.is_whitespace()).collect::().to_ascii_lowercase(); + let (name, id) = (norm(&st.name), norm(&st.id)); + // The docx reader's ids for a few styles differ from their names. + let alias = |s: &str| match s { + "tablenormal" => "normaltable".to_string(), + "commenttext" => "annotationtext".to_string(), + "commentreference" => "annotationreference".to_string(), + other => other.to_string(), + }; + BUILTIN + .iter() + .find(|(n, _)| { + let n = norm(n); + n == alias(&name) || n == alias(&id) + }) + .copied() +} + +/// The stylesheet as written: each model style's istd. +pub(crate) struct Plan { + /// Model style id → istd. + pub(crate) istd: HashMap, + /// Istd → model style (index into the stylesheet), `None` for an empty slot. + slots: Vec>, + /// Istd → the name and sti it is written with. + names: Vec<(String, u16)>, +} + +/// Assign istds: the fixed built-ins to their slots, everything else after them. +pub(crate) fn plan(sheet: &StyleSheet) -> Plan { + let mut slots: Vec> = vec![None; FIXED as usize]; + let mut names: Vec<(String, u16)> = vec![(String::new(), 0); FIXED as usize]; + let mut istd = HashMap::new(); + let mut taken = std::collections::HashSet::new(); + for (i, st) in sheet.styles.iter().enumerate().take(MAX_STYLES) { + if st.id.is_empty() || istd.contains_key(&st.id) { + continue; + } + let bi = builtin(st); + // The fixed slot a built-in style takes, when its kind is the one Word gives it. + let fixed = bi.and_then(|(_, sti)| match (sti, st.kind) { + (0..=9, StyleKind::Paragraph) => Some(sti), + (65, StyleKind::Character) => Some(10), + (105, StyleKind::Table) => Some(11), + (107, StyleKind::Numbering) => Some(12), + _ => None, + }); + let slot = match fixed { + Some(s) if !taken.contains(&s) => s, + _ => { + slots.push(None); + names.push((String::new(), 0)); + (slots.len() - 1) as u16 + } + }; + taken.insert(slot); + if let Some(s) = slots.get_mut(slot as usize) { + *s = Some(i); + } + // A built-in name is Word's own spelling; its sti only where the kind matches. + let (name, sti) = match bi { + Some((n, sti)) if builtin_kind(sti) == st.kind => (n.to_string(), sti), + _ => (st.name.clone(), STI_USER), + }; + if let Some(n) = names.get_mut(slot as usize) { + *n = (name, sti); + } + istd.insert(st.id.clone(), slot); + } + // Normal and Default Paragraph Font are always there. + if slots.first().is_some_and(Option::is_none) + && let Some(n) = names.get_mut(0) + { + *n = ("Normal".into(), 0); + } + for (i, name, sti) in [(10usize, "Default Paragraph Font", 65u16), (11, "Normal Table", 105), (12, "No List", 107)] { + if slots.get(i).is_some_and(Option::is_none) + && let Some(n) = names.get_mut(i) + { + *n = (name.into(), sti); + } + } + Plan { istd, slots, names } +} + +/// The kind of style Word's built-in `sti` is. +fn builtin_kind(sti: u16) -> StyleKind { + match sti { + 38 | 39 | 40 | 41 | 42 | 65 | 85 | 86 | 87 | 88 | 156 | 260..=264 => StyleKind::Character, + 105 | 154 => StyleKind::Table, + 107 => StyleKind::Numbering, + _ => StyleKind::Paragraph, + } +} + +/// The STSH bytes. `default_font` is the font-table index of the document's default font +/// (the standard font of the stylesheet header). +pub(crate) fn stsh(sheet: &StyleSheet, plan: &Plan, ctx: &mut (impl CharCtx + ParaCtx), default_fonts: [u16; 3]) -> Vec { + // LPStshi: cbStshi, then Stshi: Stshif (18 bytes), ftcBi, and the latent style data (an + // empty LSD for every sti below stiMaxWhenSaved). + let cstd = plan.slots.len().min(0x0FFE) as u16; + let sti_max = plan.names.iter().map(|(_, sti)| *sti).filter(|&s| s != STI_USER).max().map_or(0x5B, |m| (m + 1).max(0x5B)); + let cb_stshi = 18 + 2 + 2 + 4 * usize::from(sti_max); + let mut v = Vec::new(); + v.extend_from_slice(&(cb_stshi as u16).to_le_bytes()); + v.extend_from_slice(&cstd.to_le_bytes()); + v.extend_from_slice(&0x000Au16.to_le_bytes()); // cbSTDBaseInFile + v.extend_from_slice(&1u16.to_le_bytes()); // fStdStylenamesWritten + v.extend_from_slice(&sti_max.to_le_bytes()); // stiMaxWhenSaved + v.extend_from_slice(&FIXED.to_le_bytes()); // istdMaxFixedWhenSaved + v.extend_from_slice(&0u16.to_le_bytes()); // nVerBuiltInNamesWhenSaved + for f in default_fonts { + v.extend_from_slice(&f.to_le_bytes()); // rgftcStandardChpStsh + } + v.extend_from_slice(&default_fonts[2].to_le_bytes()); // ftcBi + v.extend_from_slice(&4u16.to_le_bytes()); // StshiLsd.cbLSD + v.extend(std::iter::repeat_n(0u8, 4 * usize::from(sti_max))); + for (istd, slot) in plan.slots.iter().enumerate().take(cstd as usize) { + let (name, sti) = plan.names.get(istd).cloned().unwrap_or_default(); + let std = match slot.and_then(|i| sheet.styles.get(i)) { + Some(st) => std_bytes(st, &name, sti, sheet, plan, ctx, istd == 0), + None if !name.is_empty() => empty_builtin(&name, sti, istd as u16), + None => Vec::new(), + }; + v.extend_from_slice(&(std.len() as u16).to_le_bytes()); + v.extend_from_slice(&std); + } + v +} + +/// A built-in style the document doesn't define (Normal, Default Paragraph Font). +fn empty_builtin(name: &str, sti: u16, istd: u16) -> Vec { + let own = istd.to_le_bytes().to_vec(); + let (stk, upx): (u16, Vec>) = match sti { + 65 => (2, vec![Vec::new()]), + 105 => (3, vec![Vec::new(), own, Vec::new()]), + 107 => (4, vec![own]), + _ => (1, vec![own, Vec::new()]), + }; + let next = if stk == 1 { istd } else { ISTD_NIL }; + assemble(sti, stk, ISTD_NIL, next, upx.len() as u16, 0, name, &upx) +} + +/// One STD: `StdfBase`, the name, then the UPXs for its kind. +#[allow(clippy::too_many_arguments)] +fn std_bytes(st: &Style, name: &str, sti: u16, sheet: &StyleSheet, plan: &Plan, ctx: &mut (impl CharCtx + ParaCtx), normal: bool) -> Vec { + let base = st.based_on.as_deref().and_then(|b| plan.istd.get(b).copied()).unwrap_or(ISTD_NIL); + let istd_self = plan.istd.get(&st.id).copied().unwrap_or(0); + let next = st.next.as_deref().and_then(|b| plan.istd.get(b).copied()).unwrap_or(istd_self); + // Document defaults have nowhere else to go in this format: Normal (and any other root + // paragraph or character style) starts from them. + let root = base == ISTD_NIL; + let mut chr = st.chr.clone(); + let mut para = st.para.clone(); + if root && matches!(st.kind, StyleKind::Paragraph) { + chr = overlay(&sheet.default_chr, &chr); + para = craft_wordmodel::props::ParaProps { style: None, ..overlay_para(&sheet.default_para, ¶) }; + } + if normal { + chr.style = None; + } + para.style = None; + para.numbering = para.numbering.filter(|n| n.num != 0); + chr.style = None; + let mut grfstd: u16 = 0; + if st.hidden { + grfstd |= 0x0002 | 0x0100; // fHidden, fSemiHidden + } + if st.locked { + grfstd |= 0x0200; + } + if st.quick { + grfstd |= 0x1000; // fQFormat + } + let (stk, cupx, upx): (u16, u16, Vec>) = match st.kind { + StyleKind::Paragraph => { + let mut papx = istd_self.to_le_bytes().to_vec(); + let mut g = grpprl::papx(¶, ctx); + g.truncate_to(super::fkp::MAX_PAPX_GRPPRL); + papx.extend_from_slice(&g.0); + let mut c = grpprl::chpx(&chr, ctx); + c.truncate_to(255); + (1, 2, vec![papx, c.0]) + } + StyleKind::Character => { + let mut c = grpprl::chpx(&chr, ctx); + c.truncate_to(255); + (2, 1, vec![c.0]) + } + // Table styles: their paragraph and character formatting; the conditional formats stay + // with the model (tables carry their own borders and shading when written). + StyleKind::Table => { + let mut papx = istd_self.to_le_bytes().to_vec(); + papx.extend_from_slice(&grpprl::papx(¶, ctx).0); + (3, 3, vec![Vec::new(), papx, grpprl::chpx(&chr, ctx).0]) + } + StyleKind::Numbering => { + let mut papx = istd_self.to_le_bytes().to_vec(); + papx.extend_from_slice(&Grpprl::default().0); + (4, 1, vec![papx]) + } + }; + assemble(sti, stk, base, next, cupx, grfstd, name, &upx) +} + +/// `StdfBase` + `xstzName` + `GrLPUpxSw` (each UPX padded to an even size). +#[allow(clippy::too_many_arguments)] +fn assemble(sti: u16, stk: u16, base: u16, next: u16, cupx: u16, grfstd: u16, name: &str, upx: &[Vec]) -> Vec { + let mut v = Vec::new(); + v.extend_from_slice(&(sti & 0x0FFF).to_le_bytes()); + v.extend_from_slice(&((stk & 0xF) | ((base & 0x0FFF) << 4)).to_le_bytes()); + v.extend_from_slice(&((cupx & 0xF) | ((next & 0x0FFF) << 4)).to_le_bytes()); + let bch_at = v.len(); + v.extend_from_slice(&0u16.to_le_bytes()); // bchUpe, filled below + v.extend_from_slice(&grfstd.to_le_bytes()); + let units: Vec = name.encode_utf16().take(253).collect(); + v.extend_from_slice(&(units.len() as u16).to_le_bytes()); + for u in &units { + v.extend_from_slice(&u.to_le_bytes()); + } + v.extend_from_slice(&0u16.to_le_bytes()); + for u in upx { + v.extend_from_slice(&(u.len() as u16).to_le_bytes()); + v.extend_from_slice(u); + if u.len() % 2 == 1 { + v.push(0); + } + } + let len = v.len() as u16; + if let Some(b) = v.get_mut(bch_at..bch_at + 2) { + b.copy_from_slice(&len.to_le_bytes()); + } + v +} + +/// `over`'s character properties over `under`'s. +fn overlay(under: &CharProps, over: &CharProps) -> CharProps { + let mut out = under.clone(); + out.overlay(over); + out +} + +fn overlay_para(under: &craft_wordmodel::props::ParaProps, over: &craft_wordmodel::props::ParaProps) -> craft_wordmodel::props::ParaProps { + let mut out = under.clone(); + out.overlay(over); + out +} + +/// The `SttbfFfn`: a non-extended STTB whose entries are `FFN`s (a byte count, then the FFN). +pub(crate) fn font_table(names: &[String]) -> Vec { + let mut v = Vec::new(); + v.extend_from_slice(&(names.len().min(0x7FFF) as u16).to_le_bytes()); + v.extend_from_slice(&0u16.to_le_bytes()); // cbExtra + for name in names.iter().take(0x7FFF) { + let ffn = ffn(name); + v.push(ffn.len() as u8); + v.extend_from_slice(&ffn); + } + v +} + +/// One `FFN` ([MS-DOC] §2.9.82): pitch/TrueType/family bits, `wWeight`, `chs`, +/// `ixchSzAlt`, `panose`, `fs`, then the name, NUL-terminated UTF-16. +fn ffn(name: &str) -> Vec { + let units: Vec = name.encode_utf16().take(31).collect(); + let mut v = Vec::with_capacity(40 + units.len() * 2 + 2); + let symbol = matches!(name.to_ascii_lowercase().as_str(), "symbol" | "wingdings" | "wingdings 2" | "wingdings 3" | "webdings"); + let family: u8 = if symbol { + 5 // FF_DECORATIVE + } else if name.to_ascii_lowercase().contains("mono") || name.eq_ignore_ascii_case("courier new") { + 3 // FF_MODERN + } else if name.to_ascii_lowercase().contains("sans") + || ["arial", "calibri", "aptos", "verdana", "tahoma", "segoe ui"].contains(&name.to_ascii_lowercase().as_str()) + { + 2 // FF_SWISS + } else { + 1 // FF_ROMAN + }; + // prq (2 = variable pitch), fTrueType, ff. + v.push(2 | 0x04 | (family << 4)); + v.extend_from_slice(&400u16.to_le_bytes()); // wWeight + v.push(if symbol { 2 } else { 0 }); // chs: SYMBOL_CHARSET or ANSI_CHARSET + v.push(0); // ixchSzAlt: no alternate name + v.extend_from_slice(&[0u8; 10]); // panose + v.extend_from_slice(&[0u8; 24]); // fs + for u in &units { + v.extend_from_slice(&u.to_le_bytes()); + } + v.extend_from_slice(&0u16.to_le_bytes()); + v +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn font_table_reads_back() { + let names = vec!["Times New Roman".to_string(), "Symbol".to_string(), "Noto Sans Ünï".to_string()]; + let t = font_table(&names); + assert_eq!(crate::stsh::fonts(&t, 0, t.len() as u32), names); + } +} diff --git a/crates/doc-binary/src/write/summary.rs b/crates/doc-binary/src/write/summary.rs new file mode 100644 index 000000000..f67dc8cc1 --- /dev/null +++ b/crates/doc-binary/src/write/summary.rs @@ -0,0 +1,112 @@ +//! The `\u{5}SummaryInformation` stream ([MS-OLEPS] §2.21): title, subject, author, keywords, +//! comments, last author, revision and the creation and save times. + +use craft_wordmodel::CoreProps; + +/// `FMTID_SummaryInformation` as stored (little-endian GUID fields). +const SUMMARY_FMTID: [u8; 16] = [0xe0, 0x85, 0x9f, 0xf2, 0xf9, 0x4f, 0x68, 0x10, 0xab, 0x91, 0x08, 0x00, 0x2b, 0x27, 0xb3, 0xd9]; +const VT_I2: u32 = 2; +const VT_LPSTR: u32 = 30; +const VT_FILETIME: u32 = 64; +/// Longest string property written (characters). +const MAX_CHARS: usize = 32 << 10; + +/// The text of `s` in code page 1252, when every character has a byte there. +fn cp1252(s: &str) -> Option> { + s.chars().map(|c| (0u8..=255).find(|&b| craft_codepage::cp1252(b) == c && (b >= 0x20 || c == '\t' || c == '\n' || c == '\r'))).collect() +} + +/// The stream's bytes. Strings are Windows-1252 when they all fit it, else UTF-16 (code page +/// 1200). +pub(crate) fn stream(core: &CoreProps) -> Vec { + let strings: Vec<(u32, String)> = + [(2u32, &core.title), (3, &core.subject), (4, &core.creator), (5, &core.keywords), (6, &core.description), (8, &core.last_modified_by)] + .into_iter() + .filter(|(_, s)| !s.is_empty()) + .map(|(id, s)| (id, s.chars().take(MAX_CHARS).collect())) + .chain((core.revision > 0).then(|| (9u32, core.revision.to_string()))) + .collect(); + let ansi = strings.iter().all(|(_, s)| cp1252(s).is_some()); + let codepage: u16 = if ansi { 1252 } else { 1200 }; + + let mut props: Vec<(u32, Vec)> = Vec::new(); + let mut cp = VT_I2.to_le_bytes().to_vec(); + cp.extend_from_slice(&codepage.to_le_bytes()); + cp.extend_from_slice(&[0, 0]); + props.push((1, cp)); + for (id, s) in &strings { + let mut bytes = if ansi { cp1252(s).unwrap_or_default() } else { s.encode_utf16().flat_map(u16::to_le_bytes).collect() }; + bytes.extend_from_slice(if ansi { &[0][..] } else { &[0, 0][..] }); + let mut v = VT_LPSTR.to_le_bytes().to_vec(); + v.extend_from_slice(&(bytes.len() as u32).to_le_bytes()); + v.extend_from_slice(&bytes); + while !v.len().is_multiple_of(4) { + v.push(0); + } + props.push((*id, v)); + } + for (id, iso) in [(12u32, &core.created), (13, &core.modified)] { + if let Some(ft) = filetime(iso) { + let mut v = VT_FILETIME.to_le_bytes().to_vec(); + v.extend_from_slice(&(ft as u32).to_le_bytes()); + v.extend_from_slice(&((ft >> 32) as u32).to_le_bytes()); + props.push((id, v)); + } + } + + // PropertySet: size, count, (id, offset) pairs, then the values. + let table = 8 + props.len() * 8; + let mut set = Vec::new(); + let mut values = Vec::new(); + let mut index = Vec::new(); + for (id, v) in &props { + index.extend_from_slice(&id.to_le_bytes()); + index.extend_from_slice(&((table + values.len()) as u32).to_le_bytes()); + values.extend_from_slice(v); + } + set.extend_from_slice(&((table + values.len()) as u32).to_le_bytes()); + set.extend_from_slice(&(props.len() as u32).to_le_bytes()); + set.extend_from_slice(&index); + set.extend_from_slice(&values); + + // PropertySetStream header: byte order, version, system id, CLSID, one set, its FMTID and + // offset. + let mut out = vec![0xFE, 0xFF, 0, 0]; + out.extend_from_slice(&0x0002_0006u32.to_le_bytes()); + out.extend_from_slice(&[0u8; 16]); + out.extend_from_slice(&1u32.to_le_bytes()); + out.extend_from_slice(&SUMMARY_FMTID); + out.extend_from_slice(&48u32.to_le_bytes()); + out.extend_from_slice(&set); + out +} + +/// A FILETIME (100 ns since 1601) from an ISO 8601 date. +fn filetime(iso: &str) -> Option { + let t = super::parse_time(iso)?.and_utc().timestamp(); + let ft = (t.checked_add(11_644_473_600)?).checked_mul(10_000_000)?; + u64::try_from(ft).ok() +} + +#[cfg(test)] +mod tests { + #[test] + fn summary_reads_back() { + let core = craft_wordmodel::CoreProps { + title: "Annual Report".into(), + creator: "Zoë Writer".into(), + keywords: "a, b".into(), + revision: 3, + created: "2024-05-06T07:08:09Z".into(), + ..Default::default() + }; + let read = crate::metadata::parse_for_tests(&super::stream(&core)).unwrap(); + assert_eq!(read.title, "Annual Report"); + assert_eq!(read.creator, "Zoë Writer"); + assert_eq!(read.keywords, "a, b"); + assert_eq!(read.revision, 3); + assert_eq!(read.created, "2024-05-06T07:08:09Z"); + let unicode = craft_wordmodel::CoreProps { title: "Отчёт 报告".into(), ..Default::default() }; + assert_eq!(crate::metadata::parse_for_tests(&super::stream(&unicode)).unwrap().title, "Отчёт 报告"); + } +} diff --git a/crates/doc-binary/src/write/tables.rs b/crates/doc-binary/src/write/tables.rs new file mode 100644 index 000000000..43476b17a --- /dev/null +++ b/crates/doc-binary/src/write/tables.rs @@ -0,0 +1,224 @@ +//! A table row's properties, carried by its row-end mark ([MS-DOC] §2.4.3, §2.6.3): the cell +//! edges and per-cell borders (`sprmTDefTable`), the table's borders, alignment and indent, row +//! height and flags, and the cells' shading, widths, vertical merges and alignment. + +use craft_wordmodel::props::{Align, Border, Borders, HeightRule, VAlign, VMerge}; +use craft_wordmodel::table::Table; + +use super::grpprl::{Grpprl, brc, brc80, shd, twips}; + +const T_JC90: u16 = 0x5400; +const T_JC: u16 = 0x548A; +const T_DXA_LEFT: u16 = 0x9601; +const T_DXA_GAP_HALF: u16 = 0x9602; +const T_CANT_SPLIT90: u16 = 0x3403; +const T_TABLE_HEADER: u16 = 0x3404; +const T_CANT_SPLIT: u16 = 0x3466; +const T_TABLE_BORDERS80: u16 = 0xD605; +const T_ROW_HEIGHT: u16 = 0x9407; +const T_DEF_TABLE: u16 = 0xD608; +const T_DEF_TABLE_SHD: [u16; 3] = [0xD612, 0xD616, 0xD60C]; +const T_TABLE_BORDERS: u16 = 0xD613; +const T_TABLE_WIDTH: u16 = 0xF614; +const T_VERT_MERGE: u16 = 0xD62B; +const T_VERT_ALIGN: u16 = 0xD62C; +const T_CELL_PADDING_DEFAULT: u16 = 0xD634; +const T_CELL_WIDTH: u16 = 0xD635; + +/// Most cells a row holds (`itcMac` MUST be at most 63). +pub(crate) const MAX_CELLS: usize = 63; +/// Word's default space left of a cell's text (5.4 pt), when the table doesn't say. +const DEFAULT_GAP: f32 = 5.4; + +/// The TAPX sprms of row `ri` of `t` (of `rows`), for its row-end mark; `style_borders` are +/// the borders of the table's style, for a table without its own. +pub(crate) fn row_end(t: &Table, ri: usize, rows: usize, style_borders: Option) -> Grpprl { + let mut g = Grpprl::default(); + let Some(row) = t.rows.get(ri) else { return g }; + let cells = &row.cells.get(..row.cells.len().min(MAX_CELLS)).unwrap_or(&[]); + let n = cells.len(); + let tp = &t.props; + + // Alignment, indent and the cell gap. + let jc: u16 = match tp.align { + Some(Align::Center) => 1, + Some(Align::Right) => 2, + _ => 0, + }; + if jc != 0 { + g.u16(T_JC90, jc); + g.u16(T_JC, jc); + } + let gap = tp.cell_margins.map_or(DEFAULT_GAP, |m| m[1]).clamp(0.0, 100.0); + g.i16(T_DXA_GAP_HALF, twips(gap)); + let indent = tp.indent.unwrap_or(0.0); + g.i16(T_DXA_LEFT, twips(indent + gap)); + if let Some(m) = tp.cell_margins { + // CSSAOperand: itcFirst, itcLim, grfbrc (top 1, left 2, bottom 4, right 8), ftsWidth + // (3 = twips), wWidth. + for (side, v) in [(1u8, m[0]), (2, m[1]), (4, m[2]), (8, m[3])] { + let w = twips(v.max(0.0)) as u16; + let mut op = vec![0, n.max(1) as u8, side, 3]; + op.extend_from_slice(&w.to_le_bytes()); + g.var(T_CELL_PADDING_DEFAULT, &op); + } + } + if let Some(pct) = tp.width_pct { + // ftsWidth 2: fiftieths of a percent. + let mut op = vec![2u8]; + op.extend_from_slice(&((pct.clamp(0.0, 600.0) * 50.0).round() as u16).to_le_bytes()); + g.raw(T_TABLE_WIDTH, &op); + } else if let Some(w) = tp.width { + let mut op = vec![3u8]; + op.extend_from_slice(&(twips(w.max(0.0)) as u16).to_le_bytes()); + g.raw(T_TABLE_WIDTH, &op); + } + + // Row height and flags. + if let Some(h) = row.props.height { + let tw = twips(h.max(0.0)); + g.i16(T_ROW_HEIGHT, if row.props.height_rule == HeightRule::Exact { tw.saturating_neg() } else { tw }); + } + if row.props.header { + g.u8(T_TABLE_HEADER, 1); + } + if row.props.cant_split { + g.u8(T_CANT_SPLIT90, 1); + g.u8(T_CANT_SPLIT, 1); + } + + // The table's borders: its own, else its style's. + let borders = tp.borders.or(style_borders).unwrap_or_default(); + let six = [borders.top, borders.left, borders.bottom, borders.right, borders.between, borders.inside_v]; + let mut b80 = Vec::with_capacity(24); + let mut b = Vec::with_capacity(48); + for side in &six { + b80.extend_from_slice(&side.as_ref().map_or([0; 4], brc80)); + b.extend_from_slice(&side.as_ref().map_or([0; 8], brc)); + } + g.var(T_TABLE_BORDERS80, &b80); + g.var(T_TABLE_BORDERS, &b); + + // Cell edges: each cell spans its grid columns (from the row's `grid_before`), else its own + // preferred width; the edges start at the table's indent. + let widths = cell_widths(t, ri); + let mut edges: Vec = Vec::with_capacity(n + 1); + let mut x = twips(indent); + edges.push(x); + for w in &widths { + x = x.saturating_add(twips(*w).max(1)); + edges.push(x); + } + // TDefTableOperand: cb, itcMac, rgdxaCenter, rgTc80. + let mut body = vec![n as u8]; + for e in &edges { + body.extend_from_slice(&e.to_le_bytes()); + } + for (ci, cell) in cells.iter().enumerate() { + let mut grf: u16 = 0; + match cell.props.vmerge { + VMerge::Restart => grf |= 0x20 | 0x40, + VMerge::Continue => grf |= 0x20, + VMerge::None => {} + } + grf |= valign_bits(cell.props.valign) << 7; + grf |= 3 << 9; // ftsWidth: twips + if cell.props.no_wrap { + grf |= 1 << 13; + } + body.extend_from_slice(&grf.to_le_bytes()); + body.extend_from_slice(&(twips(widths.get(ci).copied().unwrap_or(0.0)) as u16).to_le_bytes()); + let cb = cell_borders(&borders, cell.props.borders.as_ref(), ri, rows, ci, n); + for side in [cb.top, cb.left, cb.bottom, cb.right] { + body.extend_from_slice(&side.as_ref().map_or([0; 4], brc80)); + } + } + let cb = u16::try_from(body.len() + 1).unwrap_or(u16::MAX); + let mut op = cb.to_le_bytes().to_vec(); + op.extend_from_slice(&body); + g.raw(T_DEF_TABLE, &op); + + // Cell shading, in three arrays of up to 22 cells each. + if cells.iter().any(|c| c.props.shading.is_some()) || tp.shading.is_some() { + for (k, op) in T_DEF_TABLE_SHD.iter().enumerate() { + let chunk = cells.get(k * 22..((k + 1) * 22).min(n)).unwrap_or(&[]); + if chunk.is_empty() { + break; + } + let mut v = Vec::with_capacity(chunk.len() * 10); + for c in chunk { + v.extend_from_slice(&shd(c.props.shading.or(tp.shading))); + } + g.var(*op, &v); + } + } + // Per-cell preferred widths, vertical merges and alignment, for the readers that take them + // from sprms rather than from the TC80s. + for (ci, cell) in cells.iter().enumerate() { + let i = ci as u8; + let mut op = vec![i, i + 1]; + if let Some(pct) = cell.props.width_pct { + op.push(2); + op.extend_from_slice(&((pct.clamp(0.0, 100.0) * 50.0).round() as u16).to_le_bytes()); + } else { + op.push(3); + op.extend_from_slice(&(twips(widths.get(ci).copied().unwrap_or(0.0)) as u16).to_le_bytes()); + } + g.var(T_CELL_WIDTH, &op); + match cell.props.vmerge { + VMerge::Restart => g.var(T_VERT_MERGE, &[i, 3]), + VMerge::Continue => g.var(T_VERT_MERGE, &[i, 1]), + VMerge::None => {} + } + if let Some(v) = cell.props.valign + && v != VAlign::Top + { + g.var(T_VERT_ALIGN, &[i, i + 1, valign_bits(Some(v)) as u8]); + } + } + g +} + +fn valign_bits(v: Option) -> u16 { + match v { + Some(VAlign::Center) => 1, + Some(VAlign::Bottom) => 2, + _ => 0, + } +} + +/// Each cell's width in points: the grid columns it spans, else its preferred width, else an +/// equal share of a 6-inch row. +fn cell_widths(t: &Table, ri: usize) -> Vec { + let Some(row) = t.rows.get(ri) else { return Vec::new() }; + let n = row.cells.len().min(MAX_CELLS); + let mut col = row.props.grid_before as usize; + let mut out = Vec::with_capacity(n); + for cell in row.cells.iter().take(n) { + let span = (cell.props.span.max(1) as usize).min(MAX_CELLS); + let from_grid: f32 = t.grid.get(col..col.saturating_add(span).min(t.grid.len())).map_or(0.0, |g| g.iter().sum()); + col = col.saturating_add(span); + let w = if from_grid > 0.0 && from_grid.is_finite() { + from_grid + } else { + cell.props.width.filter(|w| *w > 0.0 && w.is_finite()).unwrap_or(432.0 / n.max(1) as f32) + }; + out.push(w.clamp(1.0, 1584.0)); + } + out +} + +/// The borders cell `ci` of `n` in row `ri` of `rows` shows: the table's outer borders on the +/// table's edges, its inside ones between cells, the cell's own over both. +fn cell_borders(table: &Borders, own: Option<&Borders>, ri: usize, rows: usize, ci: usize, n: usize) -> Borders { + let pick = |own: Option, edge: bool, outer: Option, inner: Option| own.or(if edge { outer } else { inner }); + let own = own.copied().unwrap_or_default(); + Borders { + top: pick(own.top, ri == 0, table.top, table.between), + bottom: pick(own.bottom, ri + 1 == rows, table.bottom, table.between), + left: pick(own.left, ci == 0, table.left, table.inside_v), + right: pick(own.right, ci + 1 == n, table.right, table.inside_v), + between: None, + inside_v: None, + } +} diff --git a/crates/doc-binary/src/write/tests.rs b/crates/doc-binary/src/write/tests.rs new file mode 100644 index 000000000..b649a4c9f --- /dev/null +++ b/crates/doc-binary/src/write/tests.rs @@ -0,0 +1,707 @@ +//! Round trips: documents written as `.doc` and read back with the reader, which follows the +//! same specification independently of the writer. + +use std::sync::Arc; + +use craft_wordmodel::para::{InlineObject, NoteKind, Paragraph}; +use craft_wordmodel::props::*; +use craft_wordmodel::section::{Columns, SectionProps, SectionStart}; +use craft_wordmodel::table::{Cell, Row, Table}; +use craft_wordmodel::{Block, Document, PartKind, para_block}; + +use crate::{read, write}; + +fn doc_of(paras: Vec) -> Document { + let mut d = Document::new(); + d.body = paras.into_iter().map(para_block).collect(); + d +} + +fn round(d: &Document) -> Document { + let bytes = write(d).expect("write"); + read(&bytes).expect("read back") +} + +fn texts(d: &Document) -> Vec { + d.body.iter().filter_map(|b| b.as_para().map(|p| p.plain_text())).collect() +} + +fn para(text: &str) -> Paragraph { + Paragraph::with_text(text, CharProps::default()) +} + +#[test] +fn plain_text_round_trips() { + let d = doc_of(vec![ + para("Hello, world."), + para(""), + para("Ünïcødé — “quotes” 😀 𝄞 中文"), + para("tab\there, line\nbreak, nb\u{2011}hyphen, soft\u{AD}hyphen"), + ]); + let r = round(&d); + assert_eq!(texts(&r), texts(&d)); +} + +#[test] +fn an_empty_document_is_one_paragraph() { + let r = round(&Document::new()); + assert_eq!(texts(&r), vec![String::new()]); +} + +#[test] +fn character_formatting_round_trips() { + let mut p = para("bold italic under red big font high sup"); + let fmt = |p: &mut Paragraph, a: usize, b: usize, f: &dyn Fn(&mut CharProps)| p.format(a, b, f).unwrap(); + fmt(&mut p, 0, 4, &|c| c.bold = Some(true)); + fmt(&mut p, 5, 11, &|c| c.italic = Some(true)); + fmt(&mut p, 12, 17, &|c| c.underline = Some(Underline::Double)); + fmt(&mut p, 18, 21, &|c| c.color = Some(TextColor::Rgb(craft_wordmodel::Rgb(0xC0, 0x10, 0x20)))); + fmt(&mut p, 22, 25, &|c| c.size = Some(18.5)); + fmt(&mut p, 26, 30, &|c| c.font = Some("Georgia".into())); + fmt(&mut p, 31, 35, &|c| c.highlight = Some(Highlight::Yellow)); + fmt(&mut p, 36, 39, &|c| { + c.strike = Some(true); + c.small_caps = Some(true); + }); + let r = round(&doc_of(vec![p.clone()])); + let q = r.body[0].as_para().unwrap(); + assert_eq!(q.plain_text(), p.plain_text()); + let at = |i: usize| q.props_at(i + 1).clone(); + assert_eq!(at(0).bold, Some(true)); + assert_eq!(at(5).italic, Some(true)); + assert_eq!(at(12).underline, Some(Underline::Double)); + assert_eq!(at(18).color, Some(TextColor::Rgb(craft_wordmodel::Rgb(0xC0, 0x10, 0x20)))); + assert_eq!(at(22).size, Some(18.5)); + assert_eq!(at(26).font.as_deref(), Some("Georgia")); + assert_eq!(at(36).strike, Some(true)); + assert_eq!(at(36).small_caps, Some(true)); + assert_ne!(at(5).bold, Some(true)); +} + +#[test] +fn paragraph_formatting_round_trips() { + let mut p = para("Centred and indented"); + p.props.align = Some(Align::Center); + p.props.indent_left = Some(36.0); + p.props.indent_right = Some(18.0); + p.props.indent_first = Some(-9.0); + p.props.space_before = Some(12.0); + p.props.space_after = Some(6.0); + p.props.line_spacing = Some(LineSpacing::Multiple(1.5)); + p.props.keep_next = Some(true); + p.props.page_break_before = Some(true); + p.props.tabs = Some(vec![TabStop { pos: 72.0, align: TabAlign::Right, leader: TabLeader::Dot }]); + p.props.borders = Some(Borders { + bottom: Some(Border { style: BorderStyle::Double, width: 1.5, color: Some(craft_wordmodel::Rgb(0, 0, 255)), space: 1.0 }), + ..Default::default() + }); + let mut exact = para("Exactly 14 pt"); + exact.props.line_spacing = Some(LineSpacing::Exactly(14.0)); + let r = round(&doc_of(vec![p.clone(), exact])); + let q = &r.body[0].as_para().unwrap().props; + assert_eq!(q.align, Some(Align::Center)); + assert_eq!(q.indent_left, Some(36.0)); + assert_eq!(q.indent_right, Some(18.0)); + assert_eq!(q.indent_first, Some(-9.0)); + assert_eq!(q.space_before, Some(12.0)); + assert_eq!(q.space_after, Some(6.0)); + assert_eq!(q.line_spacing, Some(LineSpacing::Multiple(1.5))); + assert_eq!(q.keep_next, Some(true)); + assert_eq!(q.page_break_before, Some(true)); + assert_eq!(q.tabs, p.props.tabs); + assert_eq!(q.borders.and_then(|b| b.bottom), p.props.borders.and_then(|b| b.bottom)); + assert_eq!(r.body[1].as_para().unwrap().props.line_spacing, Some(LineSpacing::Exactly(14.0))); +} + +#[test] +fn styles_round_trip() { + let mut d = Document::new(); + let h1 = d.styles.styles.iter().find(|s| s.name == "Heading 1").map(|s| s.id.clone()).expect("a Heading 1 style"); + Arc::make_mut(&mut d.styles).styles.push(craft_wordmodel::styles::Style { + id: "MyQuote".into(), + name: "My Quote".into(), + kind: craft_wordmodel::styles::StyleKind::Paragraph, + based_on: Some("Normal".into()), + chr: CharProps { italic: Some(true), ..Default::default() }, + para: ParaProps { indent_left: Some(24.0), ..Default::default() }, + ..Default::default() + }); + d.body = vec![para_block(para("Title text").styled(&h1)), para_block(para("Quoted").styled("MyQuote")), para_block(para("Body"))]; + let r = round(&d); + assert_eq!(texts(&r), vec!["Title text", "Quoted", "Body"]); + let style_of = |i: usize| r.body[i].as_para().unwrap().props.style.clone().and_then(|id| r.styles.get(&id).map(|s| s.name.clone())); + assert_eq!(style_of(0).as_deref(), Some("Heading 1")); + assert_eq!(style_of(1).as_deref(), Some("My Quote")); + let q = r.styles.styles.iter().find(|s| s.name == "My Quote").unwrap(); + assert_eq!(q.chr.italic, Some(true)); + assert_eq!(q.para.indent_left, Some(24.0)); + // The heading keeps its outline level, the stylesheet its default font. + let h = r.styles.styles.iter().find(|s| s.name == "Heading 1").unwrap(); + assert_eq!(h.para.outline_level, Some(0)); +} + +#[test] +fn many_paragraphs_page_their_formatting() { + let paras: Vec = (0..2000) + .map(|i| { + let mut p = para(&format!("Paragraph {i} with some text")); + if i % 3 == 0 { + p.format(0, 9, &|c| c.bold = Some(true)).unwrap(); + } + if i % 5 == 0 { + p.props.indent_left = Some(i as f32 % 100.0); + } + p + }) + .collect(); + let d = doc_of(paras); + let r = round(&d); + assert_eq!(texts(&r), texts(&d)); + for i in [0usize, 3, 999, 1998] { + let q = r.body[i].as_para().unwrap(); + assert_eq!(q.props_at(1).bold, if i % 3 == 0 { Some(true) } else { q.props_at(1).bold.filter(|_| false) }, "paragraph {i}"); + if i % 5 == 0 { + assert_eq!(q.props.indent_left, Some(i as f32 % 100.0)); + } + } +} + +fn cell(text: &str) -> Cell { + Cell { props: CellProps { span: 1, ..Default::default() }, blocks: vec![para_block(para(text))], controls: Default::default() } +} + +#[test] +fn tables_round_trip() { + let mut a = cell("A1"); + a.props.shading = Some(craft_wordmodel::Rgb(0xEE, 0xDD, 0x00)); + a.props.vmerge = VMerge::Restart; + let mut b = cell(""); + b.props.vmerge = VMerge::Continue; + let mut multi = cell("B1 first"); + multi.blocks.push(para_block(para("B1 second"))); + let t = Table { + props: TableProps { + borders: Some(Borders { top: Some(Border::single(0.5)), bottom: Some(Border::single(0.5)), ..Default::default() }), + ..Default::default() + }, + grid: vec![100.0, 150.0, 80.0], + rows: vec![ + Row { props: RowProps { header: true, ..Default::default() }, cells: vec![a, multi, cell("C1")], controls: Default::default() }, + Row { + props: RowProps { height: Some(30.0), height_rule: HeightRule::Exact, ..Default::default() }, + cells: vec![b, cell("B2"), cell("C2")], + controls: Default::default(), + }, + ], + controls: Default::default(), + }; + let mut d = Document::new(); + d.body = vec![para_block(para("Before")), Arc::new(Block::Table(t)), para_block(para("After"))]; + let r = round(&d); + assert_eq!(r.body.len(), 3, "{:?}", r.body.iter().map(|b| b.as_para().map(|p| p.plain_text())).collect::>()); + let t = r.body[1].as_table().expect("a table"); + assert_eq!(t.rows.len(), 2); + assert_eq!(t.grid, vec![100.0, 150.0, 80.0]); + let cell_text = |r: usize, c: usize| t.rows[r].cells[c].blocks.iter().filter_map(|b| b.as_para().map(|p| p.plain_text())).collect::>(); + assert_eq!(cell_text(0, 0), vec!["A1"]); + assert_eq!(cell_text(0, 1), vec!["B1 first", "B1 second"]); + assert_eq!(cell_text(1, 2), vec!["C2"]); + assert_eq!(t.rows[0].cells[0].props.shading, Some(craft_wordmodel::Rgb(0xEE, 0xDD, 0x00))); + assert_eq!(t.rows[0].cells[0].props.vmerge, VMerge::Restart); + assert_eq!(t.rows[1].cells[0].props.vmerge, VMerge::Continue); + assert!(t.rows[0].props.header); + assert_eq!(t.rows[1].props.height, Some(30.0)); + assert_eq!(t.rows[1].props.height_rule, HeightRule::Exact); + assert_eq!(texts(&r), vec!["Before", "After"]); +} + +#[test] +fn sections_headers_and_footers_round_trip() { + let mut d = Document::new(); + let h1 = d.add_part(PartKind::Header, vec![para_block(para("First header"))]); + let f1 = d.add_part(PartKind::Footer, vec![para_block(para("First footer"))]); + let h2 = d.add_part(PartKind::Header, vec![para_block(para("Landscape header"))]); + let mut first = para("Portrait section"); + let mut s1 = SectionProps::default(); + s1.headers.default = Some(h1); + s1.footers.default = Some(f1); + s1.margin_left = 54.0; + first.section = Some(Box::new(s1)); + let mut last = + SectionProps { landscape: true, start: SectionStart::NextPage, columns: Columns { count: 2, ..Default::default() }, ..Default::default() }; + (last.page_w, last.page_h) = (792.0, 612.0); + last.headers.default = Some(h2); + d.body = vec![para_block(first), para_block(para("Landscape section"))]; + d.last_section = last; + let r = round(&d); + assert_eq!(texts(&r), vec!["Portrait section", "Landscape section"]); + let s = r.body[0].as_para().unwrap().section.as_ref().expect("the first section ends here"); + assert_eq!(s.margin_left, 54.0); + assert!(!s.landscape); + let part_text = + |id: Option| id.and_then(|i| r.parts.get(&i)).and_then(|p| p.blocks.first()).and_then(|b| b.as_para()).map(|p| p.plain_text()); + assert_eq!(part_text(s.headers.default).as_deref(), Some("First header")); + assert_eq!(part_text(s.footers.default).as_deref(), Some("First footer")); + assert!(r.last_section.landscape); + assert_eq!((r.last_section.page_w, r.last_section.page_h), (792.0, 612.0)); + assert_eq!(r.last_section.columns.count, 2); + assert_eq!(part_text(r.last_section.headers.default).as_deref(), Some("Landscape header")); +} + +#[test] +fn notes_round_trip() { + let mut d = Document::new(); + let f = d.add_part(PartKind::Footnote, vec![para_block(para("The footnote."))]); + let e = d.add_part(PartKind::Endnote, vec![para_block(para("The endnote."))]); + let mut p = para("Text."); + p.insert_object(5, InlineObject::NoteRef { kind: NoteKind::Footnote, id: f, custom: String::new() }, &CharProps::default()).unwrap(); + let end = p.text.len(); + p.insert_object(end, InlineObject::NoteRef { kind: NoteKind::Endnote, id: e, custom: String::new() }, &CharProps::default()).unwrap(); + d.body = vec![para_block(p), para_block(para("After."))]; + let r = round(&d); + assert_eq!(texts(&r)[1], "After."); + let q = r.body[0].as_para().unwrap(); + let notes: Vec<(NoteKind, String)> = q + .objects + .iter() + .filter_map(|o| match o { + InlineObject::NoteRef { kind, id, .. } => { + Some((*kind, r.parts.get(id).and_then(|p| p.blocks.first()).and_then(|b| b.as_para()).map(|p| p.plain_text()).unwrap_or_default())) + } + _ => None, + }) + .collect(); + assert_eq!(notes, vec![(NoteKind::Footnote, "The footnote.".to_string()), (NoteKind::Endnote, "The endnote.".to_string())]); +} + +#[test] +fn fields_links_and_bookmarks_round_trip() { + let mut p = para("Page , see Example and here."); + p.insert_object( + 5, + InlineObject::Field { instr: "PAGE".into(), result: "7".into(), locked: false, dirty: false, code: false, form: String::new() }, + &CharProps::default(), + ) + .unwrap(); + let at = p.text.find("Example").unwrap(); + p.format(at, at + 7, &|c| c.link = Some("https://example.org/a?b=1".into())).unwrap(); + let here = p.text.find("here").unwrap(); + p.insert_object(here + 4, InlineObject::BookmarkEnd { name: "Spot".into() }, &CharProps::default()).unwrap(); + p.insert_object(here, InlineObject::BookmarkStart { name: "Spot".into() }, &CharProps::default()).unwrap(); + let r = round(&doc_of(vec![p])); + let q = r.body[0].as_para().unwrap(); + assert!(q.objects.iter().any(|o| matches!(o, InlineObject::Field { instr, result, .. } if instr == "PAGE" && result == "7")), "{:?}", q.objects); + let link_at = q.text.find("Example").unwrap(); + assert_eq!(q.props_at(link_at + 1).link.as_deref(), Some("https://example.org/a?b=1")); + assert!(q.objects.iter().any(|o| matches!(o, InlineObject::BookmarkStart { name } if name == "Spot"))); + assert!(q.objects.iter().any(|o| matches!(o, InlineObject::BookmarkEnd { name } if name == "Spot"))); +} + +/// A 2×1 PNG. +fn png() -> Vec { + let img = image::RgbaImage::from_pixel(2, 1, image::Rgba([10, 200, 30, 255])); + let mut out = Vec::new(); + image::DynamicImage::ImageRgba8(img).write_to(&mut std::io::Cursor::new(&mut out), image::ImageFormat::Png).unwrap(); + out +} + +#[test] +fn inline_pictures_round_trip() { + let mut d = Document::new(); + let bytes = png(); + d.media.insert("pic.png".into(), Arc::new(bytes.clone())); + let mut p = para("Picture: ."); + p.insert_object( + 9, + InlineObject::Image { + media: "pic.png".into(), + w: 144.0, + h: 72.0, + alt: "A green bar".into(), + float: Default::default(), + crop: [0.0; 4], + ole: None, + fx: Default::default(), + }, + &CharProps::default(), + ) + .unwrap(); + d.body = vec![para_block(p)]; + let r = round(&d); + let q = r.body[0].as_para().unwrap(); + let Some(InlineObject::Image { media, w, h, alt, .. }) = q.objects.first() else { panic!("no picture: {:?}", q.objects) }; + assert!((w - 144.0).abs() < 0.1 && (h - 72.0).abs() < 0.1, "{w}×{h}"); + assert_eq!(alt, "A green bar"); + assert_eq!(r.media.get(media).map(|m| m.as_slice()), Some(bytes.as_slice())); +} + +#[test] +fn document_properties_round_trip() { + let mut d = Document::new(); + d.core.title = "Quarterly".into(); + d.core.creator = "A. Writer".into(); + let r = round(&d); + assert_eq!(r.core.title, "Quarterly"); + assert_eq!(r.core.creator, "A. Writer"); +} + +#[test] +fn lists_round_trip() { + use craft_wordmodel::numbering::{AbstractNum, Level, Num}; + use craft_wordmodel::section::NumFormat; + let mut d = Document::new(); + let levels = vec![ + Level { start: 1, format: NumFormat::Decimal, text: "%1.".into(), indent: 36.0, hanging: 18.0, ..Level::default() }, + Level { start: 1, format: NumFormat::LowerLetter, text: "%1.%2)".into(), indent: 72.0, hanging: 18.0, ..Level::default() }, + Level { start: 1, format: NumFormat::Bullet, text: "\u{2022}".into(), indent: 108.0, hanging: 18.0, ..Level::default() }, + ]; + let numbering = Arc::make_mut(&mut d.numbering); + numbering.abstracts = vec![AbstractNum { id: 7, levels, ..Default::default() }]; + numbering.nums = vec![Num { id: 3, abstract_id: 7, start_overrides: vec![(0, 4)], ..Default::default() }]; + let item = |text: &str, level: u8| { + let mut p = para(text); + p.props.numbering = Some(NumRef { num: 3, level }); + para_block(p) + }; + d.body = vec![item("One", 0), item("One a", 1), item("Dot", 2)]; + let r = round(&d); + let num = |i: usize| r.body[i].as_para().unwrap().props.numbering.expect("numbered"); + assert_eq!((num(0).level, num(1).level, num(2).level), (0, 1, 2)); + let n = r.numbering.nums.iter().find(|n| n.id == num(0).num).expect("the list"); + assert_eq!(n.start_overrides, vec![(0, 4)]); + let a = r.numbering.abstracts.iter().find(|a| a.id == n.abstract_id).expect("its levels"); + assert_eq!(a.levels[0].text, "%1."); + assert_eq!(a.levels[1].text, "%1.%2)"); + assert_eq!(a.levels[1].format, NumFormat::LowerLetter); + assert_eq!(a.levels[2].text, "\u{2022}"); + assert_eq!(a.levels[2].format, NumFormat::Bullet); + assert_eq!((a.levels[1].indent, a.levels[1].hanging), (72.0, 18.0)); +} + +#[test] +fn tracked_changes_round_trip() { + use craft_wordmodel::{Revision, RevisionKind}; + let mut d = Document::new(); + d.revisions = vec![ + Revision::new(RevisionKind::Insert, "Ada", "2025-03-04T05:06:00Z"), + Revision::new(RevisionKind::Delete, "Grace", "2025-03-05T10:20:00Z"), + ]; + let mut p = para("kept added removed"); + p.format(5, 10, &|c| c.ins = Some(0)).unwrap(); + p.format(11, 18, &|c| c.del = Some(1)).unwrap(); + d.body = vec![para_block(p)]; + let r = round(&d); + let q = r.body[0].as_para().unwrap(); + assert_eq!(q.plain_text(), "kept added removed"); + let ins = q.props_at(6).ins.and_then(|i| r.revisions.get(i as usize)).expect("an insertion"); + assert_eq!((ins.kind, ins.author.as_str(), ins.date.as_str()), (RevisionKind::Insert, "Ada", "2025-03-04T05:06:00Z")); + let del = q.props_at(12).del.and_then(|i| r.revisions.get(i as usize)).expect("a deletion"); + assert_eq!((del.kind, del.author.as_str(), del.date.as_str()), (RevisionKind::Delete, "Grace", "2025-03-05T10:20:00Z")); + assert_eq!(q.props_at(1).ins, None); + assert_eq!(q.mark.ins, None); +} + +/// An inserted or deleted paragraph break (the paragraph mark's revision) round-trips too. +#[test] +fn tracked_paragraph_marks_round_trip() { + use craft_wordmodel::{Revision, RevisionKind}; + let mut d = Document::new(); + d.revisions = vec![ + Revision::new(RevisionKind::Insert, "Ada", "2025-03-04T05:06:00Z"), + Revision::new(RevisionKind::Delete, "Grace", "2025-03-05T10:20:00Z"), + ]; + let (mut inserted, mut deleted) = (para("inserted break"), para("deleted break")); + inserted.mark.ins = Some(0); + deleted.mark.del = Some(1); + d.body = vec![para_block(inserted), para_block(deleted), para_block(para("last"))]; + let r = round(&d); + let mark = |i: usize| r.body[i].as_para().unwrap().mark.clone(); + let ins = mark(0).ins.and_then(|i| r.revisions.get(i as usize)).expect("an inserted mark"); + assert_eq!((ins.kind, ins.author.as_str()), (RevisionKind::Insert, "Ada")); + let del = mark(1).del.and_then(|i| r.revisions.get(i as usize)).expect("a deleted mark"); + assert_eq!((del.kind, del.author.as_str()), (RevisionKind::Delete, "Grace")); + assert_eq!((mark(2).ins, mark(2).del), (None, None)); + assert_eq!(r.body[0].as_para().unwrap().props_at(1).ins, None, "the text itself isn't marked"); +} + +/// A tracked insertion or deletion of a picture, a note reference or a field round-trips: the +/// reader takes each anchor's revision marks from its CHPX. +#[test] +fn tracked_object_anchors_round_trip() { + use craft_wordmodel::{Revision, RevisionKind}; + let mut d = Document::new(); + d.revisions = vec![ + Revision::new(RevisionKind::Insert, "Ada", "2025-03-04T05:06:00Z"), + Revision::new(RevisionKind::Delete, "Grace", "2025-03-05T10:20:00Z"), + ]; + d.media.insert("pic.png".into(), Arc::new(png())); + let f = d.add_part(PartKind::Footnote, vec![para_block(para("The footnote."))]); + let inserted = CharProps { ins: Some(0), ..Default::default() }; + let deleted = CharProps { del: Some(1), ..Default::default() }; + let mut p = para("a b c d"); + let picture = InlineObject::Image { + media: "pic.png".into(), + w: 20.0, + h: 10.0, + alt: String::new(), + float: Default::default(), + crop: [0.0; 4], + ole: None, + fx: Default::default(), + }; + let page = InlineObject::Field { instr: "PAGE".into(), result: "1".into(), locked: false, dirty: false, code: false, form: String::new() }; + let note = InlineObject::NoteRef { kind: NoteKind::Footnote, id: f, custom: String::new() }; + // Inserted back to front so the offsets stay put: picture after "a", note after "b", + // field after "c" and an untracked field after "d". + p.insert_object(7, page.clone(), &CharProps::default()).unwrap(); + p.insert_object(5, page, &inserted).unwrap(); + p.insert_object(3, note, &deleted).unwrap(); + p.insert_object(1, picture, &inserted).unwrap(); + d.body = vec![para_block(p)]; + let r = round(&d); + let q = r.body[0].as_para().unwrap(); + let anchors: Vec<(&str, Option, Option)> = q + .text + .match_indices('\u{FFFC}') + .zip(&q.objects) + .map(|((at, _), o)| { + let props = q.props_of_char(at); + let kind = |rev: Option| rev.and_then(|i| r.revisions.get(i as usize)).map(|rev| rev.kind); + let name = match o { + InlineObject::Image { .. } => "picture", + InlineObject::NoteRef { .. } => "note", + InlineObject::Field { .. } => "field", + _ => "other", + }; + (name, kind(props.ins), kind(props.del)) + }) + .collect(); + assert_eq!( + anchors, + vec![ + ("picture", Some(RevisionKind::Insert), None), + ("note", None, Some(RevisionKind::Delete)), + ("field", Some(RevisionKind::Insert), None), + ("field", None, None), + ] + ); +} + +#[test] +#[ignore = "the reader pairs bookmark ends through FBKF.ibkl once craft-libs#1817 is in"] +fn overlapping_bookmarks_keep_their_ends() { + // Outer starts first and ends last; inner ends before it: the ends sort apart from the starts. + let mut p = para("abcdef"); + p.insert_object(6, InlineObject::BookmarkEnd { name: "Outer".into() }, &CharProps::default()).unwrap(); + p.insert_object(4, InlineObject::BookmarkEnd { name: "Inner".into() }, &CharProps::default()).unwrap(); + p.insert_object(2, InlineObject::BookmarkStart { name: "Inner".into() }, &CharProps::default()).unwrap(); + p.insert_object(0, InlineObject::BookmarkStart { name: "Outer".into() }, &CharProps::default()).unwrap(); + let r = round(&doc_of(vec![p.clone()])); + let q = r.body[0].as_para().unwrap(); + let marks = |p: &Paragraph| -> Vec { + p.objects + .iter() + .filter_map(|o| match o { + InlineObject::BookmarkStart { name } => Some(format!("+{name}")), + InlineObject::BookmarkEnd { name } => Some(format!("-{name}")), + _ => None, + }) + .collect() + }; + assert_eq!(marks(q), marks(&p)); + assert_eq!(q.text, p.text); +} + +/// What the writer writes for a character's vertical position: superscript and subscript as +/// `sprmCIss`, a raised or lowered position as `sprmCHpsPos`, character spacing as +/// `sprmCDxaSpace`. The reader reads them once craft-libs#1799 is in. +#[test] +#[ignore = "the reader reads sprmCIss, sprmCHpsPos and sprmCDxaSpace once craft-libs#1799 is in"] +fn position_and_spacing_round_trip() { + let mut p = para("sup sub up sp"); + p.format(0, 3, &|c| c.vert_align = Some(VertAlign::Superscript)).unwrap(); + p.format(4, 7, &|c| c.vert_align = Some(VertAlign::Subscript)).unwrap(); + p.format(8, 10, &|c| c.position = Some(3.0)).unwrap(); + p.format(11, 13, &|c| c.spacing = Some(1.5)).unwrap(); + let r = round(&doc_of(vec![p])); + let q = r.body[0].as_para().unwrap(); + assert_eq!(q.props_at(1).vert_align, Some(VertAlign::Superscript)); + assert_eq!(q.props_at(5).vert_align, Some(VertAlign::Subscript)); + assert_eq!(q.props_at(9).position, Some(3.0)); + assert_ne!(q.props_at(9).vert_align, Some(VertAlign::Superscript)); + assert_eq!(q.props_at(12).spacing, Some(1.5)); +} + +/// Double strikethrough, emboss and the double-wave underline. The reader reads them once +/// craft-libs#1969 is fixed. +#[test] +#[ignore = "the reader reads sprmCFDStrike, sprmCFEmboss and Kul 0x2B once craft-libs#1969 is fixed"] +fn character_effects_round_trip() { + let mut p = para("dbl emb"); + p.format(0, 3, &|c| c.double_strike = Some(true)).unwrap(); + p.format(4, 7, &|c| { + c.emboss = Some(true); + c.underline = Some(Underline::DoubleWave); + }) + .unwrap(); + let r = round(&doc_of(vec![p])); + let q = r.body[0].as_para().unwrap(); + assert_eq!(q.props_at(1).double_strike, Some(true)); + assert_eq!(q.props_at(5).emboss, Some(true)); + assert_eq!(q.props_at(5).underline, Some(Underline::DoubleWave)); +} + +#[test] +#[ignore = "the reader reads sprmCHighlight as an Ico once craft-libs#1854 is in"] +fn every_highlight_colour_round_trips() { + for h in Highlight::ALL { + let mut p = para("x"); + p.format(0, 1, &|c| c.highlight = Some(h)).unwrap(); + let r = round(&doc_of(vec![p])); + assert_eq!(r.body[0].as_para().unwrap().props_at(0).highlight, Some(h), "{h:?}"); + } +} + +/// A section's column count survives a save. +#[test] +fn section_columns_round_trip() { + let mut d = Document::new(); + d.last_section.columns = Columns { count: 3, space: 18.0, ..Default::default() }; + d.body = vec![para_block(para("Three columns"))]; + let r = round(&d); + assert_eq!(r.last_section.columns.count, 3); +} + +/// The page-number start and format, the column spacing, and the paragraph's shading, widow +/// control and contextual spacing, as the writer writes them. Each needs a reader change that is +/// still open: page numbers craft-libs#1354, column spacing and widow control craft-libs#1799, +/// shading craft-libs#1808, contextual spacing craft-libs#1969. +#[test] +#[ignore = "needs the reader changes in craft-libs#1354, #1799 and #1808, and craft-libs#1969"] +fn page_numbering_and_paragraph_shading_round_trip() { + let mut d = Document::new(); + d.last_section.page_num_start = Some(5); + d.last_section.page_num_format = craft_wordmodel::section::NumFormat::LowerRoman; + d.last_section.columns = Columns { count: 3, space: 18.0, ..Default::default() }; + let mut p = para("Shaded"); + p.props.shading = Some(craft_wordmodel::Rgb(0xDD, 0xEE, 0xFF)); + p.props.widow_control = Some(false); + p.props.contextual_spacing = Some(true); + d.body = vec![para_block(p)]; + let r = round(&d); + assert_eq!(r.last_section.page_num_start, Some(5)); + assert_eq!(r.last_section.page_num_format, craft_wordmodel::section::NumFormat::LowerRoman); + assert_eq!((r.last_section.columns.count, r.last_section.columns.space), (3, 18.0)); + let q = &r.body[0].as_para().unwrap().props; + assert_eq!(q.shading, Some(craft_wordmodel::Rgb(0xDD, 0xEE, 0xFF))); + assert_eq!(q.widow_control, Some(false)); + assert_eq!(q.contextual_spacing, Some(true)); +} + +fn table_of(grid: Vec, rows: Vec>) -> Table { + Table { + props: TableProps::default(), + grid, + rows: rows.into_iter().map(|cells| Row { props: RowProps::default(), cells, controls: Default::default() }).collect(), + controls: Default::default(), + } +} + +#[test] +fn nested_tables_become_paragraphs_of_their_cell() { + let inner = table_of(vec![50.0, 50.0], vec![vec![cell("i1"), cell("i2")]]); + let mut outer_cell = cell("before"); + outer_cell.blocks.push(Arc::new(Block::Table(inner))); + let mut d = Document::new(); + d.body = vec![Arc::new(Block::Table(table_of(vec![200.0], vec![vec![outer_cell]]))), para_block(para("end"))]; + let r = round(&d); + let t = r.body[0].as_table().expect("the outer table"); + let texts: Vec = t.rows[0].cells[0].blocks.iter().filter_map(|b| b.as_para().map(|p| p.plain_text())).collect(); + assert_eq!(texts, vec!["before", "i1", "i2"]); +} + +#[test] +fn a_table_ending_the_document_gets_a_paragraph_after_it() { + let mut d = Document::new(); + d.body = vec![Arc::new(Block::Table(table_of(vec![100.0], vec![vec![cell("only")]])))]; + let r = round(&d); + assert!(r.body[0].as_table().is_some()); + assert_eq!(texts(&r), vec![String::new()]); +} + +#[test] +fn rows_wider_than_the_format_keep_their_first_cells() { + let cells: Vec = (0..80).map(|i| cell(&format!("c{i}"))).collect(); + let mut d = Document::new(); + d.body = vec![Arc::new(Block::Table(table_of(vec![10.0; 80], vec![cells]))), para_block(para("after"))]; + // Never a panic; the first 63 cells (the format's most) keep their text. + let r = round(&d); + let all: Vec = r + .body + .iter() + .flat_map(|b| match &**b { + Block::Para(p) => vec![p.plain_text()], + Block::Table(t) => { + t.rows.iter().flat_map(|r| r.cells.iter()).flat_map(|c| c.blocks.iter()).filter_map(|b| b.as_para().map(|p| p.plain_text())).collect() + } + }) + .collect(); + for i in [0, 30, 62, 79] { + assert!(all.iter().any(|t| t == &format!("c{i}")), "c{i} missing: {all:?}"); + } + assert_eq!(texts(&r).last().map(String::as_str), Some("after")); +} + +proptest::proptest! { + #![proptest_config(proptest::prelude::ProptestConfig::with_cases(64))] + /// Any text, with any run boundaries and formatting, writes without panicking and reads back + /// as the same text. + #[test] + fn any_text_round_trips(lines in proptest::collection::vec("\\PC{0,40}", 1..8), bold in proptest::collection::vec(proptest::prelude::any::(), 8)) { + let paras: Vec = lines + .iter() + .enumerate() + .map(|(i, l)| { + let clean: String = l.chars().filter(|c| !c.is_control() && *c != '\u{FFFC}').collect(); + let mut p = para(&clean); + if bold.get(i).copied().unwrap_or(false) && !clean.is_empty() { + let end = clean.char_indices().nth(clean.chars().count() / 2).map_or(clean.len(), |(i, _)| i); + p.format(0, end, &|c| c.bold = Some(true)).unwrap(); + } + p + }) + .collect(); + let d = doc_of(paras); + let r = round(&d); + proptest::prop_assert_eq!(texts(&r), texts(&d)); + } +} + +/// The thin/thick compound border lines (`brcType` 0x0B-0x13) keep their style through a save, +/// rather than coming back as single lines. +#[test] +fn compound_border_lines_round_trip() { + let styles = [ + BorderStyle::ThinThickSmallGap, + BorderStyle::ThickThinSmallGap, + BorderStyle::ThinThickThinSmallGap, + BorderStyle::ThinThickMediumGap, + BorderStyle::ThickThinMediumGap, + BorderStyle::ThinThickThinMediumGap, + BorderStyle::ThinThickLargeGap, + BorderStyle::ThickThinLargeGap, + BorderStyle::ThinThickThinLargeGap, + ]; + let mut d = Document::new(); + d.body = styles + .iter() + .map(|&style| { + let mut p = para("Bordered"); + p.props.borders = Some(Borders { bottom: Some(Border { style, width: 3.0, color: None, space: 1.0 }), ..Default::default() }); + para_block(p) + }) + .collect(); + let r = round(&d); + let got: Vec<_> = r.body.iter().filter_map(|b| b.as_para()).filter_map(|p| p.props.borders.as_ref()?.bottom.map(|b| b.style)).collect(); + assert_eq!(got, styles); +} From 1bb51887fd16fa6116305a0828883da58831b2d2 Mon Sep 17 00:00:00 2001 From: Piohrun Date: Tue, 17 Nov 2026 03:29:22 +0100 Subject: [PATCH 05/64] craft-pdf: content reads a lone minus between operands as the number 0 (#1958) --- crates/pdf/README.md | 6 +++- crates/pdf/src/cos/content.rs | 38 +++++++++++++++++++++++- crates/pdf/src/cos/content/tests.rs | 46 ++++++++++++++++++++++++++++- 3 files changed, 87 insertions(+), 3 deletions(-) diff --git a/crates/pdf/README.md b/crates/pdf/README.md index b9e0129d3..a1332ce4f 100644 --- a/crates/pdf/README.md +++ b/crates/pdf/README.md @@ -136,7 +136,11 @@ let bytes = write_full(&doc, &SaveOptions::default())?; // rewrite what t With `content`, `cos::content` reads and writes page content streams. `parse` keeps each operator's byte span and skips (and counts) what it cannot read instead of failing; inline images -stay whole, so `parse` → `serialize_ops` round-trips them. `Matrix` holds the arithmetic content +stay whole, so `parse` → `serialize_ops` round-trips them. Between operands, a token of one or two +signs with a minus among them (`-`, `--`, `-+`, `+-`), followed by whitespace, a delimiter or the +end, is read as the number 0, as hayro-syntax reads it. Inside an array or dictionary, or among an +inline image's parameters, such a token still makes the whole operand unreadable (such an image is +left out of `ops` and counted in `ambiguous_images`). `Matrix` holds the arithmetic content interpretation needs. - Reads every cross-reference form (tables, streams, hybrid `/XRefStm`) and object streams. A diff --git a/crates/pdf/src/cos/content.rs b/crates/pdf/src/cos/content.rs index a3087972d..d91552553 100644 --- a/crates/pdf/src/cos/content.rs +++ b/crates/pdf/src/cos/content.rs @@ -137,6 +137,10 @@ pub struct Ops<'a> { ends: &'a [usize], boundary: usize, comment_edges: Vec<(bool, bool)>, + /// Arrays, dictionaries and hex strings whose read failed, until as many `]` or `>` (of either + /// kind) have passed: what follows the opener is re-read token by token, and a sign there is + /// left to the lexer, not read as 0. + broken: usize, } impl<'a> Ops<'a> { @@ -151,6 +155,7 @@ impl<'a> Ops<'a> { ends, boundary: 0, comment_edges: vec![(false, false); ends.len()], + broken: 0, } } @@ -170,7 +175,7 @@ impl Iterator for Ops<'_> { type Item = Op; fn next(&mut self) -> Option { - let Ops { data, lx, operands, start, skipped, ambiguous_images, ends, boundary, comment_edges: edges } = self; + let Ops { data, lx, operands, start, skipped, ambiguous_images, ends, boundary, comment_edges: edges, broken } = self; let (data, ends): (&[u8], &[usize]) = (data, ends); loop { let trivia = lx.pos; @@ -187,6 +192,14 @@ impl Iterator for Ops<'_> { return None; }; let at = lx.pos; + if *broken == 0 + && let Some(run) = lone_minus(data, at) + { + lx.pos = at + run; + start.get_or_insert(at); + operands.push(Object::Int(0)); + continue; + } let operand_start = matches!(b, b'/' | b'(' | b'<' | b'[' | b'+' | b'-' | b'.') || b.is_ascii_digit(); if operand_start { match lx.object() { @@ -200,6 +213,9 @@ impl Iterator for Ops<'_> { lx.pos = data.len(); } Err(_) => { + if matches!(b, b'[' | b'<') { + *broken += 1; + } let read = lx.pos.saturating_sub(at); #[cfg(test)] tests::RESCANNED.with(|c| c.set(c.get() + read)); @@ -219,6 +235,9 @@ impl Iterator for Ops<'_> { } if is_delim(b) { // A stray `)`, `>`, `]`, `{`, `}`. + if matches!(b, b']' | b'>') { + *broken = broken.saturating_sub(1); + } lx.pos += 1; *skipped += 1; continue; @@ -272,6 +291,23 @@ impl Iterator for Ops<'_> { } } +/// The length of the token at `at` when it is one or two signs with a minus among them, followed by +/// whitespace, a delimiter or the end (`-`, `--`, `-+`, `+-`). That is no number to the lexer, but +/// the number 0 to hayro-syntax, both the copy vendored here and PdfCraft's. A lone `-` occurs in +/// real files: PDF.js bug 1753983 has one among the operands of `c`. The two copies disagree on `+` +/// and `++` and on runs such as `---`, both read `+++` as an unknown operator, and signs after a +/// digit belong to that number, so the lexer's reading of those stands. No more than four bytes +/// are looked at: the one before `at` and three from it. +fn lone_minus(data: &[u8], at: usize) -> Option { + if !at.checked_sub(1).and_then(|i| data.get(i)).is_none_or(|c| is_ws(*c) || is_delim(*c)) { + return None; + } + let token = data.get(at..)?; + let run = token.iter().take(2).take_while(|c| matches!(c, b'+' | b'-')).count(); + let ends = token.get(run).is_none_or(|c| is_ws(*c) || is_delim(*c)); + (run > 0 && ends && token.get(..run)?.contains(&b'-')).then_some(run) +} + /// Record the piece boundaries crossed by the comments in `trivia` (skipped whitespace and /// comments). `boundary` is the first boundary not yet passed; boundaries only move forward. fn comment_edges(data: &[u8], trivia: std::ops::Range, ends: &[usize], boundary: &mut usize, edges: &mut [(bool, bool)]) { diff --git a/crates/pdf/src/cos/content/tests.rs b/crates/pdf/src/cos/content/tests.rs index 6a44d51b1..1a6a14851 100644 --- a/crates/pdf/src/cos/content/tests.rs +++ b/crates/pdf/src/cos/content/tests.rs @@ -42,13 +42,14 @@ fn splicing_visits_each_piece_a_few_times() { #[test] fn a_long_unreadable_number_is_read_once() { - for junk in ["+", "5"] { + for junk in ["+", "5", "-", "-+", "+-"] { let n = 20_000; let src = format!("{}{} 1 0 0 1 0 0 cm", junk.repeat(n), if junk == "5" { "x" } else { "" }); RESCANNED.with(|c| c.set(0)); let p = parse(src.as_bytes()); let rescanned = RESCANNED.with(|c| c.get()); assert!(rescanned <= 2 * n, "{rescanned} bytes read for a {n}-byte token"); + assert!(junk == "5" || junk == "+" || rescanned > 0, "the run of {junk:?} is counted"); assert_eq!(p.ops.last().and_then(|o| o.nums::<6>()), Some([1.0, 0.0, 0.0, 1.0, 0.0, 0.0])); } // A short damaged number still recovers byte by byte. @@ -57,6 +58,49 @@ fn a_long_unreadable_number_is_read_once() { assert_eq!(p.ops[0].nums::<2>(), Some([5.0, 0.0])); } +/// A lone `-`, or two signs with a minus among them, between operands, is the number 0 to +/// hayro-syntax, as a lone `-` is in real files (PDF.js bug 1753983, among the operands of `c`): +/// the second `Tr` of `3 Tr - Tr` gets 0, and `0 - (a) "` three operands. The token takes no +/// bytes from what follows and starts the operator's span. Other sign tokens are read as before: a +/// `+` alone, three signs, signs before a letter or after a digit, and signs inside an array or +/// dictionary the lexer can't read. +#[test] +fn a_lone_minus_is_read_as_zero() { + let ops = |data: &[u8]| -> Vec<(Vec, Vec)> { parse(data).ops.into_iter().map(|o| (o.op, o.operands)).collect() }; + let zero = || Object::Int(0); + assert_eq!(ops(b"3 Tr - Tr"), [(b"Tr".to_vec(), vec![Object::Int(3)]), (b"Tr".to_vec(), vec![zero()])]); + assert_eq!(ops(b"0 - (a) \""), [(b"\"".to_vec(), vec![zero(), zero(), Object::String(PdfString::literal(b"a".to_vec()))])]); + for data in [&b"- w"[..], b"-- w", b"+- w", b"-+ w", b"-"] { + let want: &[(Vec, Vec)] = if data == b"-" { &[] } else { &[(b"w".to_vec(), vec![zero()])] }; + assert_eq!(ops(data), want, "{}", String::from_utf8_lossy(data)); + } + assert_eq!(ops(b"(a)-/N gs"), [(b"gs".to_vec(), vec![Object::String(PdfString::literal(b"a".to_vec())), zero(), Object::name("N")])]); + for data in [&b"- w"[..], b"-- w", b"-+ w", b"+- w"] { + let parsed = parse(data); + assert_eq!((parsed.skipped, parsed.ops.first().map(|o| o.span.clone())), (0, Some(0..data.len())), "{}", String::from_utf8_lossy(data)); + } + // As before. + assert_eq!(ops(b"5 + Tc"), [(b"Tc".to_vec(), vec![Object::Int(5)])]); + assert_eq!(ops(b"/Span << /A - >> BDC"), [(b"BDC".to_vec(), vec![Object::name("Span"), Object::name("A")])]); + assert_eq!(ops(b"[(a) - ] TJ"), [(b"TJ".to_vec(), vec![Object::String(PdfString::literal(b"a".to_vec()))])]); + assert_eq!(ops(b"[1 - 2] 0 d"), [(b"d".to_vec(), vec![Object::Int(1), Object::Int(2), Object::Int(0)])]); + assert_eq!(ops(b"<- w"), [(b"w".to_vec(), vec![])]); + // Past a broken array's or dictionary's end, a lone minus is 0 again; not before the outer one's. + assert_eq!(ops(b"[(a) - ] TJ - Tc")[1], (b"Tc".to_vec(), vec![zero()])); + assert_eq!(ops(b"/Span << /A - >> BDC - w")[1], (b"w".to_vec(), vec![zero()])); + assert_eq!( + ops(b"/P << /A << /B - >> /C - >> BDC - w"), + [(b"BDC".to_vec(), vec![Object::name("P"), Object::name("A"), Object::name("B"), Object::name("C")]), (b"w".to_vec(), vec![zero()])] + ); + assert_eq!(ops(b"5 ++ Tc"), [(b"Tc".to_vec(), vec![Object::Int(5)])]); + assert_eq!(ops(b"--- w"), [(b"w".to_vec(), vec![])]); + assert_eq!(ops(b"-x w"), [(b"x".to_vec(), vec![]), (b"w".to_vec(), vec![])]); + assert_eq!(ops(b"5-- Tc"), [(b"Tc".to_vec(), vec![])]); + for (data, n) in [(&b"-5 w"[..], -5.0), (b"+5 w", 5.0), (b"-.5 w", -0.5), (b"--5 w", -5.0)] { + assert_eq!(parse(data).ops.first().and_then(|o| o.num_back(0)), Some(n), "{}", String::from_utf8_lossy(data)); + } +} + #[test] fn operators_keep_operands_and_spans() { let src = b"q 1 0 0 1 72 720 cm BT /F1 12 Tf (Hello \\(world\\)) Tj [(A) -120 (B)] TJ ET Q"; From e7b247c09f7f3b446743762cf1dcdfa98e6c5d60 Mon Sep 17 00:00:00 2001 From: Valentin Klein Date: Tue, 17 Nov 2026 03:29:27 +0100 Subject: [PATCH 06/64] EXR: show the main picture the way compositing apps do (#1954) --- crates/exr/src/channels.rs | 89 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/crates/exr/src/channels.rs b/crates/exr/src/channels.rs index 32e460e46..32287f5f8 100644 --- a/crates/exr/src/channels.rs +++ b/crates/exr/src/channels.rs @@ -146,6 +146,53 @@ pub fn color_channels<'a>(names: impl IntoIterator) -> Option<(C best.or_else(|| (count == 1).then(|| (ColorLayout::Y, vec![0]))) } +/// The main picture of a file by the OpenEXR convention, the one compositing applications show +/// when a file is imported: the channels without a layer prefix, `R`, `G`, `B` (and `A` when +/// present), of the first part that has all three; else the first part's unprefixed `Y` (and +/// `A`). Named layers never stand in for it: a file of named layers only (Blender's +/// `ViewLayer.Combined.R`, a part that stores `beauty.R`) has no main picture, and its layers +/// are reached by name, as in After Effects (EXtractoR) and Nuke (the `rgba` layer stays empty). +/// +/// `parts` gives each part's channel names as stored, in file order. Returns the part's index +/// and the channels' indices in that part, in layout order (R, G, B, A or Y, A). The names are +/// matched exactly, as the specification spells them; the first of duplicate names counts. +pub fn main_picture<'a, P, C>(parts: P) -> Option<(usize, ColorLayout, Vec)> +where + P: IntoIterator, + C: IntoIterator, +{ + let mut luminance: Option<(usize, ColorLayout, Vec)> = None; + for (part, names) in parts.into_iter().enumerate() { + let (mut r, mut g, mut b, mut a, mut y) = (None, None, None, None, None); + for (index, name) in names.into_iter().enumerate() { + let slot = match name { + "R" => &mut r, + "G" => &mut g, + "B" => &mut b, + "A" => &mut a, + "Y" => &mut y, + _ => continue, + }; + slot.get_or_insert(index); + } + if let (Some(r), Some(g), Some(b)) = (r, g, b) { + return Some(match a { + Some(a) => (part, ColorLayout::Rgba, vec![r, g, b, a]), + None => (part, ColorLayout::Rgb, vec![r, g, b]), + }); + } + if luminance.is_none() + && let Some(y) = y + { + luminance = Some(match a { + Some(a) => (part, ColorLayout::YA, vec![y, a]), + None => (part, ColorLayout::Y, vec![y]), + }); + } + } + luminance +} + #[cfg(test)] mod tests { #![allow(clippy::unwrap_used)] @@ -235,4 +282,46 @@ mod tests { assert_eq!(pick(&[]), None); assert_eq!(pick(&["r", "g", "b"]), None); } + + #[test] + fn the_main_picture_is_the_unprefixed_colour_of_the_first_part_that_has_it() { + let main = |parts: &[&[&str]]| main_picture(parts.iter().map(|p| p.iter().copied())); + // One part: the bare channels, whatever else is there, also before them alphabetically. + assert_eq!( + main(&[&["A", "B", "CryptoMaterial00.A", "CryptoMaterial00.B", "CryptoMaterial00.G", "CryptoMaterial00.R", "G", "R", "Z"]]), + Some((0, ColorLayout::Rgba, vec![7, 6, 1, 0])) + ); + assert_eq!(main(&[&["B", "G", "R", "diffuse.A", "diffuse.B", "diffuse.G", "diffuse.R"]]), Some((0, ColorLayout::Rgb, vec![2, 1, 0]))); + // Named layers only (Blender multilayer): no main picture, however good a layer looks. + assert_eq!( + main(&[&[ + "ViewLayer.AO.B", + "ViewLayer.AO.G", + "ViewLayer.AO.R", + "ViewLayer.Combined.A", + "ViewLayer.Combined.B", + "ViewLayer.Combined.G", + "ViewLayer.Combined.R" + ]]), + None + ); + assert_eq!( + main(&[&["ViewLayer.Combined.A", "ViewLayer.Combined.B", "ViewLayer.Combined.G", "ViewLayer.Combined.R"], &["ViewLayer.Depth.Z"]]), + None + ); + // Multi-part: the first part with bare R, G and B, not the first part. + assert_eq!(main(&[&["Z"], &["A", "B", "G", "R"], &["B", "G", "R"]]), Some((1, ColorLayout::Rgba, vec![3, 2, 1, 0]))); + assert_eq!(main(&[&["B", "G", "R"], &["A", "B", "G", "R"]]), Some((0, ColorLayout::Rgb, vec![2, 1, 0]))); + // Colour wins over an earlier luminance part; luminance when there is no colour. + assert_eq!(main(&[&["Y"], &["B", "G", "R"]]), Some((1, ColorLayout::Rgb, vec![2, 1, 0]))); + assert_eq!(main(&[&["Z"], &["A", "Y"], &["Y"]]), Some((1, ColorLayout::YA, vec![1, 0]))); + // Incomplete colour, other spellings and lone data channels are no picture. + assert_eq!(main(&[&["G", "R"]]), None); + assert_eq!(main(&[&["b", "g", "r"]]), None); + assert_eq!(main(&[&["Z"]]), None); + assert_eq!(main(&[&["A"]]), None); + assert_eq!(main(&[]), None); + // The first of duplicate names counts. + assert_eq!(main(&[&["R", "G", "B", "R"]]), Some((0, ColorLayout::Rgb, vec![0, 1, 2]))); + } } From 5fd8db24b1c952a480f90dbda4544660cbee1af8 Mon Sep 17 00:00:00 2001 From: Valentin Klein Date: Tue, 17 Nov 2026 03:29:31 +0100 Subject: [PATCH 07/64] EXR: read only the channels and rows a frame needs, and a crafted DWA file no longer crashes (#1953) --- crates/exr/src/decode.rs | 19 +- crates/exr/src/decode_tests.rs | 4 +- crates/exr/src/dwa_guard.rs | 161 ++++ crates/exr/src/lib.rs | 8 + crates/exr/src/seek.rs | 1551 ++++++++++++++++++++++++++++++++ crates/exr/src/seek_tests.rs | 1525 +++++++++++++++++++++++++++++++ crates/exr/src/stream.rs | 3 + 7 files changed, 3266 insertions(+), 5 deletions(-) create mode 100644 crates/exr/src/dwa_guard.rs create mode 100644 crates/exr/src/seek.rs create mode 100644 crates/exr/src/seek_tests.rs diff --git a/crates/exr/src/decode.rs b/crates/exr/src/decode.rs index 2797e3641..04d135e27 100644 --- a/crates/exr/src/decode.rs +++ b/crates/exr/src/decode.rs @@ -281,8 +281,9 @@ pub(super) fn read_meta(bytes: &[u8], limits: &Limits) -> Result { return Err(Error::LimitExceeded(format!("{total} bytes across {} parts exceed {}", meta.headers.len(), limits.max_bytes))); } // A flat part's samples are allocated before its chunks are read, so the file must be able - // to hold the flat parts' samples. DWA's run-length channels are zlib-packed on top and reach - // about 132000:1, so DWA parts are counted at a quarter. Deep parts size their samples from + // to hold the flat parts' samples. DWA's run-length channels are zlib-packed on top (RLE up to + // 64:1, zlib up to about 1032:1, about 66000:1 together), so DWA parts are counted at a quarter + // (with room to spare). Deep parts size their samples from // the file's own counts and are not counted here. let declared = flat.saturating_sub(dwa).saturating_add(dwa / 4); let capacity = (bytes.len() as u64).saturating_mul(limits.max_ratio).saturating_add(1 << 20); @@ -308,7 +309,7 @@ fn text_attributes(header: &Header) -> Vec<(String, String)> { out } -fn part_info(index: usize, header: &Header) -> PartInfo { +pub(crate) fn part_info(index: usize, header: &Header) -> PartInfo { let (w, h) = window_size(header.layer_size); let display = &header.shared_attributes.display_window; let (dw, dh) = window_size(display.size); @@ -449,6 +450,7 @@ pub fn decode_display_part( header_limits.max_pixels = u64::MAX; header_limits.max_bytes = u64::MAX; let meta = read_meta(bytes, &header_limits)?; + check_dwa_chunks(bytes, &meta)?; let info = meta.headers.get(index).map(|header| part_info(index, header)).ok_or_else(|| malformed(format!("part {index}")))?; if info.deep { return Err(Error::Unsupported("deep data (use the deep reader)".into())); @@ -756,6 +758,16 @@ fn tables_start(bytes: &[u8]) -> Result { Ok(cursor.position()) } +/// Checks the chunks of the file's DWAA/DWAB parts before the `exr` crate decompresses them (see +/// [`crate::dwa_guard`]: a few bytes of counters can make it allocate terabytes and abort). +fn check_dwa_chunks(bytes: &[u8], meta: &MetaData) -> Result<()> { + if !meta.headers.iter().any(|h| crate::dwa_guard::is_dwa(h.compression)) { + return Ok(()); + } + let tables = usize::try_from(tables_start(bytes)?).map_err(|_| malformed("header size"))?; + crate::dwa_guard::check_file(bytes, meta, tables).map_err(malformed) +} + /// Stable dense ordinal without materializing every tile. The library's block iterator /// internally allocates a Vec of all coordinates, which is unsuitable for cropped reads. pub(super) fn flat_block_ordinal(header: &Header, tile: TileCoordinates) -> Result { @@ -944,6 +956,7 @@ fn read_flat_part_chunks(bytes: &[u8], meta: &MetaData, index: usize, reader: &m /// [`Error::Unsupported`]; the file's other parts may be deep. pub fn decode_part(bytes: &[u8], index: usize, keep: &dyn Fn(&str) -> bool, limits: &Limits) -> Result { let meta = read_meta(bytes, limits)?; + check_dwa_chunks(bytes, &meta)?; let header = meta.headers.get(index).ok_or_else(|| malformed(format!("part {index} of {}", meta.headers.len())))?; if header.deep { return Err(Error::Unsupported("deep data (use the deep reader)".into())); diff --git a/crates/exr/src/decode_tests.rs b/crates/exr/src/decode_tests.rs index 89f44d506..0f63d8108 100644 --- a/crates/exr/src/decode_tests.rs +++ b/crates/exr/src/decode_tests.rs @@ -354,13 +354,13 @@ fn mixed_headers_with_deep_size( } /// Sample `i` of a flat channel: `R` is 1, 2, 3, …, `G` 10 more and `B` 100 more, top row first. -fn mixed_flat(channel: f32, i: usize) -> f32 { +pub(super) fn mixed_flat(channel: f32, i: usize) -> f32 { channel + 1.0 + i as f32 } /// A mixed file with a 3 × 2 flat part, and its chunk offsets as `offsets[part][chunk]`. The /// tiled flat part's chunks hold the tiles at (0, 0) and (1, 0). -fn mixed_file(deep_first: bool, tiled: bool) -> (Vec, [[usize; 2]; 2]) { +pub(super) fn mixed_file(deep_first: bool, tiled: bool) -> (Vec, [[usize; 2]; 2]) { let (w, h) = (3usize, 2usize); let mut out = mixed_headers(deep_first, tiled, (w, h)); let chunks: Vec>> = (0..2i32) diff --git a/crates/exr/src/dwa_guard.rs b/crates/exr/src/dwa_guard.rs new file mode 100644 index 000000000..a0b9c7546 --- /dev/null +++ b/crates/exr/src/dwa_guard.rs @@ -0,0 +1,161 @@ +//! A check of DWAA/DWAB chunks before the `exr` crate decompresses them. +//! +//! A DWA payload starts with eleven little-endian `u64` counters, which the `exr` crate (1.74.3, +//! `src/compression/dwa/chunk_header.rs`, `DwaHeader::parse`) reads in this order: version, +//! unknown uncompressed size, unknown compressed size, AC compressed size, DC compressed size, +//! RLE compressed size, RLE uncompressed size, RLE raw size, AC count, DC count, AC compression. +//! The crate checks them only against `i64::MAX`, then inflates sections with these sizes as the +//! size hint (`src/compression/dwa/section_stream.rs`: `inflate(section, expected)` with the +//! unknown uncompressed size, `ac_count * 2` for deflated AC, `dc_count * 2`, and the RLE +//! uncompressed size), and its inflater allocates the hint up front. A 100-byte chunk declaring +//! 2^44 DC values makes it allocate 32 TiB: the process aborts, which `catch_unwind` can't stop. +//! +//! What a valid chunk declares is bounded by its block (`width × height` pixels of all the +//! part's channels, `raw` bytes uncompressed): +//! - the unknown (losslessly zipped) channels and the RLE channels are some of the block's +//! channels stored planar, so their uncompressed sizes are at most `raw`; +//! - the RLE token stream adds at most one count byte per 127 literal bytes (runs of three or +//! more shrink), so it stays within `2 × raw`, a bound that leaves room for any encoder; +//! - the lossy channels are cut into 8 × 8 DCT blocks over the block padded to multiples of 8: +//! one DC value and at most 63 AC values per DCT block and channel. + +use exr::block::chunk::{CompressedBlock, CompressedScanLineBlock, CompressedTileBlock, TileCoordinates}; +use exr::math::Vec2; +use exr::meta::header::Header; +use exr::prelude::Compression; + +/// The counters' bytes at the start of a DWA payload. +const COUNTERS: usize = 11 * 8; + +/// Whether chunks of `compression` go through this check. +pub(crate) fn is_dwa(compression: Compression) -> bool { + matches!(compression, Compression::DWAA(_) | Compression::DWAB(_)) +} + +/// What the check needs of a DWA part: the bytes of one pixel of all its channels, and how many +/// channels it has. `None` when the pixel's bytes overflow. +fn shape(header: &Header) -> Option<(usize, usize)> { + let pixel_bytes = header.channels.list.iter().map(|c| c.sample_type.bytes_per_sample()).try_fold(0usize, usize::checked_add)?; + Some((pixel_bytes, header.channels.list.len())) +} + +/// Checks the DWA payload `payload` of a block of `width × height` pixels of the part `header` +/// describes: an error message when a counter declares more than a valid chunk of that block +/// can hold. A payload as long as the block's raw bytes is stored uncompressed (the crate doesn't +/// read counters then); one shorter than the counters is left to the crate, which refuses it. +pub(crate) fn check_payload(header: &Header, size: (usize, usize), payload: &[u8]) -> Result<(), String> { + if !is_dwa(header.compression) { + return Ok(()); + } + check_shaped(shape(header).ok_or("a DWA pixel size overflows")?, size, payload) +} + +/// [`check_payload`] with the part's [`shape`] worked out already. +fn check_shaped((pixel_bytes, channels): (usize, usize), (width, height): (usize, usize), payload: &[u8]) -> Result<(), String> { + let raw = pixel_bytes.checked_mul(width).and_then(|b| b.checked_mul(height)).ok_or("a DWA block size overflows")?; + if payload.len() == raw { + return Ok(()); + } + let Some(counters) = payload.get(..COUNTERS) else { return Ok(()) }; + let counter = |i: usize| counters.get(i * 8..i * 8 + 8).and_then(|b| <[u8; 8]>::try_from(b).ok()).map_or(u64::MAX, u64::from_le_bytes); + let dct_blocks = width.div_ceil(8).checked_mul(height.div_ceil(8)).and_then(|n| n.checked_mul(channels)).ok_or("a DWA block size overflows")?; + let raw = raw as u64; + let bounds: [(usize, &str, u64); 5] = [ + (1, "unknown uncompressed size", raw), + (6, "RLE uncompressed size", raw.saturating_mul(2)), + (7, "RLE raw size", raw), + (8, "AC count", (dct_blocks as u64).saturating_mul(63)), + (9, "DC count", dct_blocks as u64), + ]; + for (i, name, most) in bounds { + let value = counter(i); + // (also keeps `count * 2` within a 32-bit usize: the bounds are block sizes, which fit) + if value > most || usize::try_from(value.saturating_mul(2)).is_err() { + return Err(format!("a DWA chunk declares a {name} of {value}, more than its {width} × {height} block can hold ({most})")); + } + } + Ok(()) +} + +/// The pixel size of the block the `exr` crate decompresses a chunk of the part `header` +/// describes into, from the chunk's coordinates: the crate's own placement +/// (`Header::get_block_data_indices`, then `get_absolute_block_pixel_coordinates`), so a scan-line +/// `y` the crate rounds into a block (it divides toward zero: rows just above the data window land +/// in block 0) is sized as that block. An error where the crate can't place the chunk. +fn block_size(header: &Header, block: &CompressedBlock) -> Result<(usize, usize), String> { + if let CompressedBlock::Tile(tile) = block { + // (the crate's level size asserts on levels of 64 and more; no valid file has 32) + if tile.coordinates.level_index.0 >= 32 || tile.coordinates.level_index.1 >= 32 { + return Err("a DWA tile of an impossible level".into()); + } + } + let tile = header.get_block_data_indices(block).map_err(|e| format!("a DWA chunk the decoder can't place: {e}"))?; + let bounds = header.get_absolute_block_pixel_coordinates(tile).map_err(|e| format!("a DWA chunk the decoder can't place: {e}"))?; + Ok((bounds.size.0, bounds.size.1)) +} + +/// Checks every chunk the offset tables point at that is, or names, a flat DWA part (`tables` is +/// where the offset tables start), before the `exr` crate's whole-image reader, which offers no +/// hook between reading a chunk and decompressing it, gets the bytes. It fails closed: a chunk of +/// a DWA part whose part number, coordinates, size or payload can't be read, or whose block can't +/// be placed, is an error, not left to the crate. +pub(crate) fn check_file(bytes: &[u8], meta: &exr::meta::MetaData, tables: usize) -> Result<(), String> { + if !meta.headers.iter().any(|h| !h.deep && is_dwa(h.compression)) { + return Ok(()); + } + let multipart = meta.requirements.is_multilayer(); + let word = |at: usize| bytes.get(at..at.checked_add(4)?).and_then(|b| <[u8; 4]>::try_from(b).ok()).map(i32::from_le_bytes); + let cut = || "a DWA chunk cut off by the end of the file".to_string(); + // Per part: its shape when it is a flat DWA part (worked out once, not per chunk). + let shapes: Vec> = meta + .headers + .iter() + .map(|h| if !h.deep && is_dwa(h.compression) { shape(h).ok_or("a DWA pixel size overflows").map(Some) } else { Ok(None) }) + .collect::>()?; + let mut table = tables; + for (table_part, header) in meta.headers.iter().enumerate() { + let entries = + bytes.get(table..table.saturating_add(header.chunk_count.saturating_mul(8))).ok_or("the offset tables run past the end of the file")?; + table = table.saturating_add(header.chunk_count.saturating_mul(8)); + for entry in entries.as_chunks::<8>().0 { + let offset = usize::try_from(u64::from_le_bytes(*entry)).ok(); + // The part the crate decodes the chunk as: the one it names (multi-part files). + let (part, mut at) = match (multipart, offset) { + (false, Some(at)) => (Some(table_part), at), + (true, Some(at)) => (word(at).and_then(|p| usize::try_from(p).ok()), at.saturating_add(4)), + (_, None) => (None, 0), + }; + let named = part.and_then(|p| shapes.get(p).copied().flatten().map(|s| (p, s))); + let Some((part, shape)) = named else { + // (not a DWA chunk, unless it sits in a DWA part's table and can't be read) + if shapes.get(table_part).copied().flatten().is_some() && part.is_none_or(|p| p >= meta.headers.len()) { + return Err(cut()); + } + continue; + }; + let header = meta.headers.get(part).ok_or_else(cut)?; + let block = match header.blocks { + exr::meta::BlockDescription::ScanLines => { + let y = word(at).ok_or_else(cut)?; + at = at.saturating_add(4); + CompressedBlock::ScanLine(CompressedScanLineBlock { y_coordinate: y, compressed_pixels_le: Vec::new() }) + } + exr::meta::BlockDescription::Tiles(_) => { + let tile = [word(at), word(at.saturating_add(4)), word(at.saturating_add(8)), word(at.saturating_add(12))]; + at = at.saturating_add(16); + let [Some(x), Some(y), Some(lx), Some(ly)] = tile else { return Err(cut()) }; + let index = |v: i32| usize::try_from(v).map_err(|_| "a DWA tile at a negative position".to_string()); + let coordinates = TileCoordinates { tile_index: Vec2(index(x)?, index(y)?), level_index: Vec2(index(lx)?, index(ly)?) }; + CompressedBlock::Tile(CompressedTileBlock { coordinates, compressed_pixels_le: Vec::new() }) + } + }; + let size = block_size(header, &block)?; + let len = word(at).ok_or_else(cut)?; + let len = usize::try_from(len).map_err(|_| "a DWA chunk declaring a negative size".to_string())?; + let start = at.saturating_add(4); + let payload = bytes.get(start..start.saturating_add(len)).ok_or_else(cut)?; + check_shaped(shape, size, payload)?; + } + } + Ok(()) +} diff --git a/crates/exr/src/lib.rs b/crates/exr/src/lib.rs index 78afd427e..9ff66f95d 100644 --- a/crates/exr/src/lib.rs +++ b/crates/exr/src/lib.rs @@ -15,6 +15,8 @@ //! - [`decode`]: bounded part listing, flat decoding (scan lines and tiles, every compression the //! `exr` crate reads) and writing, on top of the `exr` crate. //! - [`deep`]: deep scan lines and tiles (NONE, RLE, ZIPS) and their flattening. +//! - [`seek`]: any channels, display rows and reduced resolution of a file's flat parts, read from +//! a seekable source and delivered band by band (or collected into planes). //! - [`stream`]: one flat scan-line part read block by block, for pictures larger than memory. //! - [`cryptomatte_samples`]: a file's Cryptomatte layers and their per-pixel (ID, coverage) ranks. @@ -36,4 +38,10 @@ pub mod deep; #[cfg(all(test, feature = "decode"))] mod deep_tests; #[cfg(feature = "decode")] +mod dwa_guard; +#[cfg(feature = "decode")] +pub mod seek; +#[cfg(all(test, feature = "decode"))] +mod seek_tests; +#[cfg(feature = "decode")] pub mod stream; diff --git a/crates/exr/src/seek.rs b/crates/exr/src/seek.rs new file mode 100644 index 000000000..03f0fa506 --- /dev/null +++ b/crates/exr/src/seek.rs @@ -0,0 +1,1551 @@ +//! Selective reading of flat OpenEXR parts from a seekable source (feature `decode`): the headers +//! are indexed once, then any channels, any display rows and a reduced resolution are read from +//! the file without loading the rest of it. +//! +//! - [`Index::build`] reads the headers and the offset tables only, through `Read + Seek`, after +//! checking what they declare against [`Limits`] and the source's length. It allocates nothing +//! sized by pixels, and the index holds no pixel data, so it can be kept per file. +//! - [`read_bands`] reads what a [`Request`] asks for and delivers it incrementally: each +//! compression block becomes [`Band`]s (one per requested channel: a rectangle of rows) handed +//! to a callback on the calling thread, in file order. Blocks are decoded on worker threads; the +//! calling thread hands over what has been decoded each time it has read a piece of the file +//! and while it waits, so the first bands arrive long before the request has been read. A +//! caller that writes into tiles or shows lines while the rest is still being read never holds +//! a whole plane. +//! - [`read_planes`] is a collector over [`read_bands`]: the same request delivered as one +//! display-window plane per channel once everything is read. +//! +//! A request names channels as `(part, channel)` pairs (positions in [`Index::parts`]), a range of +//! display-window rows, and a level: level `n` keeps every `2^n`-th row and column of the display +//! window, so a reduced picture is made without allocating the full-resolution one. Rows and band +//! positions count from the display window's top-left corner (0, 0), not in the file's absolute +//! coordinates (which [`PartInfo`]'s windows use). Only the chunks that hold a requested channel +//! and a requested row are fetched, chunks that follow each other in the file in one read, and +//! they are decompressed on several threads while the next ones are being read. Samples are +//! converted to `f32` (integer samples above 2^24 lose precision); outside a part's data window +//! (and in rows no chunk holds) a plane has the channel's fill value. +//! +//! A tile writer (an image editor storing a picture in tiles at its own depth) uses it like this: +//! [`Index::build`], then [`Index::estimate`] to reserve the working memory and size a progress +//! bar (one step per chunk), then [`read_bands_try`] with the colour channels as one group +//! ([`Request::groups`]), so each block arrives as one band of interleaved pixels to write into +//! the tiles it covers. Its sink checks the tile budget or scratch disk before each band and +//! returns its own error to stop the read; the read winds down and hands that error back. +//! +//! Deep parts are not read here (see [`crate::deep`]); a flat part beside them is. Tiled parts +//! are read from their largest resolution level. Every size a header declares is checked before +//! it is used and every allocation is bounded by a limit or reserved fallibly. +//! +//! Panics: the `exr` crate's header parser and decompressors can panic on some damaged input. +//! Where panics unwind (native targets), those calls are wrapped in `catch_unwind` and a panic +//! becomes [`Error::Malformed`]. Where panics abort (`wasm32-unknown-unknown`), `catch_unwind` +//! does nothing, so this module checks beforehand what it knows the crate would panic on: the +//! chunk layout is computed here with checked arithmetic instead of the crate's (which panics on +//! some sizes), the crate's block-size formula is checked for overflow, and a chunk's part, +//! coordinates, level and declared size are checked before the crate reads it. A panic inside +//! the crate's header +//! parsing or a decompressor on damaged data is not ruled out there. + +use std::io::{Cursor, Read, Seek, SeekFrom}; +use std::ops::Range; +use std::panic::{AssertUnwindSafe, catch_unwind}; +use std::sync::mpsc::{self, Receiver, RecvTimeoutError, Sender}; +use std::sync::{Arc, Mutex}; +use std::time::Duration; + +use exr::block::UncompressedBlock; +use exr::block::chunk::Chunk; +use exr::math::Vec2; +use exr::meta::MetaData; +use exr::meta::attribute::SampleType as ExrSample; +use exr::meta::header::Header; + +use crate::decode::{Limits, PartInfo, Window, check_previews, part_info}; + +/// Why a read failed. More kinds may be added: a `match` needs a catch-all arm. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +#[non_exhaustive] +pub enum Error { + /// The file is damaged, or a chunk can't be decompressed. + #[error("OpenEXR: {0}")] + Malformed(String), + /// A valid file this reader does not cover (subsampled channels, channels of deep parts). + #[error("unsupported OpenEXR: {0}")] + Unsupported(String), + /// A valid file whose compression this reader does not decode (HTJ2K): the name of the + /// compression. An app may hand such a file to another decoder. + #[error("unsupported OpenEXR compression: {0}")] + UnsupportedCompression(String), + /// The file declares more than [`Limits`] (or this module's own bounds) allow, or the request + /// needs more than [`Request::max_bytes`]: a lasting refusal of this file or request. + #[error("OpenEXR exceeds a limit: {0}")] + LimitExceeded(String), + /// The system could not give memory the read needed (within its limits) just now: another + /// attempt, with more memory free, may succeed. + #[error("OpenEXR: out of memory: {0}")] + OutOfMemory(String), + /// The source failed just now (a seek or read error other than the file ending early): + /// another attempt may succeed. + #[error("OpenEXR: cannot read: {0}")] + Io(String), + /// The `cancel` callback asked to stop. + #[error("OpenEXR: cancelled")] + Cancelled, +} + +/// Result of this module's functions. +pub type Result = std::result::Result; + +fn malformed(e: impl std::fmt::Display) -> Error { + Error::Malformed(e.to_string()) +} + +fn io(e: impl std::fmt::Display) -> Error { + Error::Io(e.to_string()) +} + +/// A failed `read_exact` of the headers or tables: the file ending early is a damaged file, any +/// other error is the source failing. +fn read_failed(e: std::io::Error) -> Error { + if e.kind() == std::io::ErrorKind::UnexpectedEof { malformed(e) } else { io(e) } +} + +fn exr_error(e: exr::error::Error) -> Error { + match e { + exr::error::Error::NotSupported(message) => Error::Unsupported(message.to_string()), + exr::error::Error::Io(e) => io(e), + e => malformed(e), + } +} + +const MAGIC: [u8; 4] = [0x76, 0x2f, 0x31, 0x01]; +/// Headers of all parts together: at most this many bytes, parts, and attributes per part. +const META_BYTES: usize = 8 << 20; +const MAX_PARTS: usize = 1024; +const MAX_ATTRIBUTES: usize = 4096; +/// The most chunks all parts of a file may have together. The offset tables and the index hold +/// a few bytes per chunk, so a header declaring billions of tiny tiles (whose tables a short file +/// can't hold anyway) is refused before anything is sized by it. 16 million chunks is a 64K × +/// 64K picture in 16 × 16 tiles. +const MAX_CHUNKS: usize = 1 << 24; +/// The most bytes one decompressed block may take in a read that sets no +/// [`Request::max_block_bytes`] and whose [`Request::max_bytes`] is smaller: the decompressor +/// allocates a block's bytes before it looks at the data, so a hostile header (a data window a +/// billion pixels wide over one tiny chunk) would otherwise ask for gigabytes. Such a read allows +/// blocks up to `max(this, max_bytes)`: a caller that budgets more memory can read files with +/// larger blocks (wide DWAB parts with many channels hold 512 MiB a block). +const MAX_BLOCK_BYTES: usize = 256 << 20; +/// Chunks are read in pieces: a run of chunks that follow each other in the file, read with one +/// request (one round trip to a network share, not one per chunk). The first piece is small so +/// the first bands arrive early; each later one may be twice as large, up to [`PIECE_BYTES`], so +/// a long read makes few requests. A piece holds at most [`PIECE_CHUNKS`] chunks, and a single +/// chunk larger than the limit is read alone. +const FIRST_PIECE_BYTES: u64 = 256 << 10; +const PIECE_BYTES: u64 = 4 << 20; +const PIECE_CHUNKS: usize = 256; +/// The most decoded bytes a read keeps in flight: the decompressed blocks and the bands of the +/// chunks read but not yet handed to the sink. Compressed bytes say little about this (a flat +/// colour compresses a thousandfold), so the reader estimates each chunk's decoded size from its +/// header and waits for the sink to catch up before reading more. +const IN_FLIGHT_BYTES: u64 = 64 << 20; +/// How often a wait for the workers polls `cancel`. +const CANCEL_POLL: Duration = Duration::from_millis(50); + +/// One chunk of a part's full-resolution level, as [`Index::chunks`] lists it. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct ChunkInfo { + /// Where the chunk starts in the file. + pub offset: u64, + /// The bytes read for it: up to the next chunk in the file (or the file's end), at most a + /// block's bytes plus its header; 0 when its offset lies outside the chunk area (past the + /// file's end, or in the headers or offset tables): a read that needs it fails. + pub len: u64, + /// The column of its top-left pixel in the part's data window, counted from the data + /// window's left edge (0). + pub x: usize, + /// The row of its top-left pixel, counted from the data window's top edge (0). + pub y: usize, + /// Its width in pixels (a tile at the right edge, or a scan-line block, may be narrower than + /// the tile size; a scan-line block is as wide as the data window). + pub width: usize, + /// Its height in pixels (the last scan-line block or the bottom tiles may hold fewer rows). + pub height: usize, +} + +/// One chunk of the full-resolution level of a part, in offset-table order. +#[derive(Debug, Clone, Copy)] +struct ChunkRef { + /// Where it starts in the file, and how many bytes to read for it (0: its offset is not valid, + /// it is never read). + offset: u64, + len: u64, + /// Its top-left pixel in the part's data window (0-based) and its size. + x: usize, + y: usize, + cols: usize, + rows: usize, + /// Its tile column and row (scan-line blocks: column 0, row = block number). + tile: (usize, usize), +} + +/// Where one part's samples go in the display window, and its chunks. +#[derive(Debug, Clone)] +struct PartLayout { + /// The part's data window position in the display window. + offset: (i64, i64), + /// The data window's size. + size: (usize, usize), + /// The bytes of one pixel of all its channels, uncompressed. + pixel_bytes: usize, + /// The chunks of the full-resolution level (smaller levels of tiled parts are never read). + chunks: Vec, +} + +/// What an OpenEXR file holds, from its headers and offset tables: the facts [`read_bands`] needs +/// to fetch only the chunks a request touches. Holds no pixel data. +#[derive(Debug, Clone)] +pub struct Index { + meta: MetaData, + parts: Vec, + layout: Vec, + display: Window, + len: u64, + /// [`Limits::max_ratio`] at build: how many bytes one byte of a chunk may decompress to. + max_ratio: u64, +} + +impl Index { + /// Reads the headers and offset tables of the file in `source` and checks them against + /// `limits`: the window and pixel limits. `max_bytes` bounds what the whole file may decode + /// to in [`crate::decode`] and plays no part here (a read is bounded by + /// [`Request::max_bytes`]); `max_ratio` is kept in the index, and a read refuses a chunk whose + /// block is more than its bytes can decompress to (see [`Index::check_blocks`]). Nothing is + /// sized by pixels. + /// `cancel` is polled while reading. + /// The display window and every data window are held to `limits.max_pixels`; see + /// [`Index::build_with_display_limit`] to hold the display window to its own bound. + pub fn build(source: &mut R, limits: &Limits, cancel: &dyn Fn() -> bool) -> Result { + Index::build_with_display_limit(source, limits, limits.max_pixels, cancel) + } + + /// [`Index::build`] with the display window held to `max_display_pixels` instead of + /// `limits.max_pixels`, which then bounds the data windows only: an app may allow parts larger + /// than the picture it shows (overscan) while keeping the planes it allocates smaller. + pub fn build_with_display_limit( + source: &mut R, + limits: &Limits, + max_display_pixels: u64, + cancel: &dyn Fn() -> bool, + ) -> Result { + let len = source.seek(SeekFrom::End(0)).map_err(io)?; + source.seek(SeekFrom::Start(0)).map_err(io)?; + let prefix = read_headers(source, cancel)?; + check_previews(&prefix).map_err(malformed)?; + // (the crate's own parsing panics on some malformed headers: reported, never raised, + // where panics unwind) + let meta = catch_unwind(AssertUnwindSafe(|| MetaData::read_from_buffered(Cursor::new(&prefix), false))) + .map_err(|_| malformed("invalid OpenEXR headers"))? + .map_err(exr_error)?; + if meta.headers.is_empty() || meta.headers.len() > MAX_PARTS { + return Err(malformed("part count")); + } + for (i, h) in meta.headers.iter().enumerate() { + if matches!(h.compression, exr::prelude::Compression::HTJ2K32 | exr::prelude::Compression::HTJ2K256) { + return Err(Error::UnsupportedCompression("HTJ2K".into())); + } + check_part(i, h, limits)?; + } + let first = meta.headers.first().ok_or_else(|| malformed("missing header"))?; + let display = first.shared_attributes.display_window; + let (dw, dh) = (display.size.0, display.size.1); + let display_pixels = (dw as u64).saturating_mul(dh as u64); + if dw == 0 || dh == 0 || dw > limits.max_width as usize || dh > limits.max_height as usize || display_pixels > max_display_pixels { + return Err(Error::LimitExceeded(format!("display window of {dw}x{dh}"))); + } + let tables = read_tables(source, &meta, prefix.len() as u64, len, cancel)?; + let chunks_start = prefix.len() as u64 + tables.iter().map(|t| t.len() as u64 * 8).sum::(); + let layout = layout_of(&meta, &tables, chunks_start, len)?; + let mut parts: Vec = meta.headers.iter().enumerate().map(|(i, h)| part_info(i, h)).collect(); + // (an index stays small however much a renderer writes into the headers: the text + // attributes are kept in the part infos, the crate's own copies are dropped) + let mut meta = meta; + for h in &mut meta.headers { + h.shared_attributes.other.clear(); + h.own_attributes.other.clear(); + h.own_attributes.preview = None; + } + for (info, h) in parts.iter_mut().zip(&meta.headers) { + info.deep = h.deep; + } + let display = parts.first().map_or(Window { x: 0, y: 0, width: 0, height: 0 }, |p| p.display_window); + Ok(Index { meta, parts, layout, display, len, max_ratio: limits.max_ratio }) + } + + /// Every part's header facts: channels (in the order a request's `(part, channel)` pairs + /// count them), windows (in the file's absolute coordinates), compression and text attributes. + pub fn parts(&self) -> &[PartInfo] { + &self.parts + } + + /// The display window of the file (the first part's, in absolute coordinates): every plane + /// covers it, and a request's rows and a band's position count from its top-left corner. + pub fn display(&self) -> Window { + self.display + } + + /// The chunks of part `part`'s full-resolution level, in offset-table order (none for a deep + /// part or a part that doesn't exist): where each lies in the file and which pixels of the + /// part's data window it holds. For diagnostics and tests; [`read_bands`] picks the chunks a + /// request needs by itself. + pub fn chunks(&self, part: usize) -> impl Iterator + '_ { + self.layout.get(part).map_or(&[][..], |p| p.chunks.as_slice()).iter().map(|c| ChunkInfo { + offset: c.offset, + len: c.len, + x: c.x, + y: c.y, + width: c.cols, + height: c.rows, + }) + } + + /// Checks every chunk of the full-resolution level of every flat part against what its bytes + /// can decompress to (see [`Index::build`]'s `max_ratio`), from the index alone: an app can + /// refuse a file before another decoder allocates by its headers. A chunk's bytes are counted + /// here as the gap to the next chunk in the file (the index holds no payload sizes); a read + /// makes the same check for the chunks it needs, and again, once a chunk is read, against the + /// payload size the chunk declares, and also holds each block to its own byte limit. + pub fn check_blocks(&self) -> Result<()> { + for (pi, part) in self.layout.iter().enumerate() { + let Some(header) = self.meta.headers.get(pi).filter(|h| !h.deep) else { continue }; + for c in &part.chunks { + self.check_ratio(pi, header, part, c, c.len)?; + } + } + Ok(()) + } + + /// Refuses chunk `c` of part `pi` when its decompressed block is more than `len` bytes can + /// hold: at most `max_ratio` bytes per byte (four times that for DWA, whose RLE stage, up to + /// 64 : 1, and zlib, up to about 1032 : 1, together reach about 66 000 : 1), plus 1 MiB. A + /// hostile header can declare a block of gigabytes over a chunk of a few bytes, and the + /// decompressors allocate the whole block first. + fn check_ratio(&self, pi: usize, header: &Header, part: &PartLayout, c: &ChunkRef, len: u64) -> Result<()> { + let block = (c.cols as u64).saturating_mul(c.rows as u64).saturating_mul(part.pixel_bytes as u64); + let ratio = if crate::dwa_guard::is_dwa(header.compression) { self.max_ratio.saturating_mul(4) } else { self.max_ratio }; + let most = len.checked_mul(ratio).and_then(|b| b.checked_add(1 << 20)).unwrap_or(u64::MAX); + if block > most { + return Err(Error::LimitExceeded(format!( + "a block of part {pi} decompresses to {block} bytes, more than its {len}-byte chunk can hold ({most})" + ))); + } + Ok(()) + } + + /// The file's length when it was indexed. + pub fn file_len(&self) -> u64 { + self.len + } + + /// About the bytes the index holds in memory. + pub fn bytes(&self) -> usize { + let chunks: usize = self.layout.iter().map(|p| p.chunks.len()).sum(); + let infos: usize = self + .parts + .iter() + .map(|p| { + let channels: usize = p.channels.iter().map(|c| c.name.len() + 48).sum(); + let text: usize = p.text_attributes.iter().map(|(k, v)| k.len() + v.len() + 48).sum(); + channels + text + p.compression.len() + 256 + }) + .sum(); + chunks.saturating_mul(std::mem::size_of::()).saturating_add(infos).saturating_add(self.meta.headers.len().saturating_mul(1024)) + } +} + +/// The headers of the file in `r` (up to and including the empty name that ends them), as raw +/// bytes: bounded in size, parts and attributes before anything parses them. +fn read_headers(r: &mut R, cancel: &dyn Fn() -> bool) -> Result> { + let mut start = [0u8; 8]; + r.read_exact(&mut start).map_err(read_failed)?; + if start.get(..4) != Some(&MAGIC[..]) { + return Err(malformed("OpenEXR signature")); + } + let version = start.get(4..8).and_then(|v| <[u8; 4]>::try_from(v).ok()).map(u32::from_le_bytes).ok_or_else(|| malformed("version"))?; + let multipart = version & 0x1000 != 0; + let mut prefix = start.to_vec(); + let mut headers = 0usize; + let mut pending: Option = None; + loop { + let mut attributes = 0usize; + // One header: attributes (name, type, size, value) up to an empty name. + loop { + if cancel() { + return Err(Error::Cancelled); + } + if !read_name(r, &mut prefix, pending.take())? { + break; + } + attributes += 1; + if attributes > MAX_ATTRIBUTES { + return Err(Error::LimitExceeded("more than 4096 attributes in a header".into())); + } + read_name(r, &mut prefix, None)?; + let mut size = [0u8; 4]; + r.read_exact(&mut size).map_err(read_failed)?; + prefix.extend_from_slice(&size); + let n = usize::try_from(i32::from_le_bytes(size)).map_err(malformed)?; + let end = + prefix.len().checked_add(n).filter(|end| *end <= META_BYTES).ok_or_else(|| Error::LimitExceeded("headers over 8 MiB".into()))?; + let begin = prefix.len(); + prefix.try_reserve_exact(n).map_err(|_| Error::OutOfMemory("header allocation".into()))?; + prefix.resize(end, 0); + for bytes in prefix.get_mut(begin..).ok_or_else(|| malformed("attribute size"))?.chunks_mut(64 << 10) { + if cancel() { + return Err(Error::Cancelled); + } + r.read_exact(bytes).map_err(read_failed)?; + } + } + headers += 1; + if headers > MAX_PARTS { + return Err(Error::LimitExceeded("more than 1024 parts".into())); + } + if !multipart { + return Ok(prefix); + } + // A multi-part header list ends with one more empty name. + let mut next = [0u8; 1]; + r.read_exact(&mut next).map_err(read_failed)?; + match next.first().copied() { + Some(0) | None => { + prefix.push(0); + return Ok(prefix); + } + Some(b) => pending = Some(b), + } + } +} + +/// One NUL-terminated name (at most 255 bytes) appended to `prefix`, `first` already read; `false` +/// for the empty name that ends a header. +fn read_name(r: &mut R, prefix: &mut Vec, first: Option) -> Result { + let mut i = 0usize; + let mut next = first; + loop { + let b = match next.take() { + Some(b) => b, + None => { + let mut one = [0u8; 1]; + r.read_exact(&mut one).map_err(read_failed)?; + one.first().copied().unwrap_or(0) + } + }; + prefix.push(b); + if b == 0 { + return Ok(i != 0); + } + i += 1; + if i > 255 { + return Err(Error::LimitExceeded("an attribute name over 255 bytes".into())); + } + } +} + +/// What a header may declare before any chunk of the part is sized by it. +fn check_part(index: usize, h: &Header, limits: &Limits) -> Result<()> { + if h.deep { + // (flat parts beside it are read; a request for a channel of this one is refused) + return Ok(()); + } + let (w, ht) = (h.layer_size.0, h.layer_size.1); + if w == 0 || ht == 0 { + return Err(malformed(format!("empty data window of part {index}"))); + } + if w > limits.max_width as usize || ht > limits.max_height as usize || (w as u64).saturating_mul(ht as u64) > limits.max_pixels { + return Err(Error::LimitExceeded(format!("part {index} of {w}x{ht}"))); + } + if h.channels.list.is_empty() || h.channels.list.len() > 4096 { + return Err(malformed(format!("channel count of part {index}"))); + } + // (the decompressor's actual block is no larger than the crate's bound, so it fits too; how + // large a block may be depends on the read: see `read_bands`) + if !crate_bound_fits(h) { + return Err(malformed(format!("the block size of part {index} overflows"))); + } + Ok(()) +} + +/// The bytes of all channels of one pixel of `h`, checked. +fn pixel_bytes(h: &Header) -> Option { + h.channels.list.iter().map(|c| c.sample_type.bytes_per_sample()).try_fold(0usize, usize::checked_add) +} + +/// The bytes of the largest block the decompressor allocates for a chunk of `h`: a pixel's bytes +/// times a tile's area, or times the width and the rows of a scan-line block (no more than the +/// part has). `None` when it overflows. +fn block_bytes(h: &Header) -> Option { + let pixels = match h.blocks { + exr::meta::BlockDescription::Tiles(t) => t.tile_size.0.checked_mul(t.tile_size.1)?, + exr::meta::BlockDescription::ScanLines => h.compression.scan_lines_per_block().min(h.layer_size.1).checked_mul(h.layer_size.0)?, + }; + pixel_bytes(h)?.checked_mul(pixels) +} + +/// Whether the `exr` crate's own bound on a chunk of `h` (`Header::max_block_byte_size`: like +/// [`block_bytes`] but with every scan line a block may hold, even past the part's last row) can +/// be computed: the crate computes it without overflow checks. It is not a limit here: before +/// the crate reads a chunk, [`check_chunk_header`] has made sure the size the chunk declares is +/// no more than the bytes it holds, so the crate never allocates by that bound. +fn crate_bound_fits(h: &Header) -> bool { + let pixels = match h.blocks { + exr::meta::BlockDescription::Tiles(t) => t.tile_size.0.checked_mul(t.tile_size.1), + exr::meta::BlockDescription::ScanLines => h.compression.scan_lines_per_block().checked_mul(h.layer_size.0), + }; + pixels.zip(pixel_bytes(h)).and_then(|(pixels, bytes)| pixels.checked_mul(bytes)).is_some() +} + +/// The offset tables, one per part, read from where the headers end. +fn read_tables(r: &mut R, meta: &MetaData, headers_end: u64, len: u64, cancel: &dyn Fn() -> bool) -> Result>> { + let chunks: usize = meta.headers.iter().map(|h| h.chunk_count).fold(0, usize::saturating_add); + if chunks > MAX_CHUNKS { + return Err(Error::LimitExceeded(format!("{chunks} chunks, more than {MAX_CHUNKS}"))); + } + // Eight bytes of table per chunk: a header can't claim more chunks than the file holds. + if (chunks as u64).saturating_mul(8) > len.saturating_sub(headers_end) { + return Err(malformed("offset tables longer than the file")); + } + r.seek(SeekFrom::Start(headers_end)).map_err(io)?; + let mut tables = Vec::new(); + tables.try_reserve_exact(meta.headers.len()).map_err(|_| Error::OutOfMemory("offset table allocation".into()))?; + let mut buf = vec![0u8; 8 * 8192]; + for h in &meta.headers { + let mut table: Vec = Vec::new(); + table.try_reserve_exact(h.chunk_count).map_err(|_| Error::OutOfMemory("offset table allocation".into()))?; + let mut left = h.chunk_count; + while left > 0 { + if cancel() { + return Err(Error::Cancelled); + } + let take = left.min(8192); + let bytes = buf.get_mut(..take * 8).ok_or_else(|| malformed("table buffer"))?; + r.read_exact(bytes).map_err(read_failed)?; + table.extend(bytes.as_chunks::<8>().0.iter().map(|c| u64::from_le_bytes(*c))); + left -= take; + } + tables.push(table); + } + Ok(tables) +} + +/// Each part's chunks of the full-resolution level: where they are and which pixels they hold. A +/// chunk ends where the next one in the file starts (or at the end of the file); an offset +/// outside the chunk area is kept as a chunk that is never read. +/// +/// The layout is computed here rather than with the `exr` crate's block iterator, which allocates +/// for every level and panics on some sizes. The full-resolution level comes first in the offset +/// table of every level mode (scan lines, single-level tiles, mip and rip maps), its blocks row by +/// row and left to right. +fn layout_of(meta: &MetaData, tables: &[Vec], chunks_start: u64, len: u64) -> Result> { + let allocation = |_| Error::OutOfMemory("chunk layout allocation".into()); + let first = meta.headers.first().ok_or_else(|| malformed("missing header"))?; + let display = first.shared_attributes.display_window; + let mut starts: Vec = Vec::new(); + starts.try_reserve_exact(tables.iter().map(Vec::len).fold(0, usize::saturating_add)).map_err(allocation)?; + starts.extend(tables.iter().flatten().copied().filter(|o| *o >= chunks_start && *o < len)); + starts.sort_unstable(); + starts.dedup(); + let end_of = |offset: u64| match starts.binary_search(&offset) { + Ok(i) => starts.get(i + 1).copied().unwrap_or(len), + Err(_) => offset, + }; + let mut out = Vec::new(); + out.try_reserve_exact(meta.headers.len()).map_err(allocation)?; + for (pi, h) in meta.headers.iter().enumerate() { + let pos = h.own_attributes.layer_position; + let offset = (i64::from(pos.0) - i64::from(display.position.0), i64::from(pos.1) - i64::from(display.position.1)); + if h.deep { + out.push(PartLayout { offset, size: (0, 0), pixel_bytes: 0, chunks: Vec::new() }); + continue; + } + let table = tables.get(pi).ok_or_else(|| malformed("offset table"))?; + // A chunk is at most its block's bytes plus its own small header (part number, position + // and sizes): never read more for one. + let most = (block_bytes(h).ok_or_else(|| malformed("block size"))? as u64).saturating_add(64); + let (w, ht) = (h.layer_size.0, h.layer_size.1); + let (bw, bh) = match h.blocks { + exr::meta::BlockDescription::Tiles(t) => (t.tile_size.0, t.tile_size.1), + exr::meta::BlockDescription::ScanLines => (w, h.compression.scan_lines_per_block()), + }; + if bw == 0 || bh == 0 { + return Err(malformed(format!("block size of part {pi}"))); + } + let across = w.div_ceil(bw); + let count = + across.checked_mul(ht.div_ceil(bh)).filter(|n| *n <= table.len()).ok_or_else(|| malformed(format!("chunk count of part {pi}")))?; + let mut chunks = Vec::new(); + chunks.try_reserve_exact(count).map_err(allocation)?; + for (i, at) in table.iter().copied().enumerate().take(count) { + let tile = (i % across, i / across); + // (inside the data window: a tile index is below the count of blocks across or down) + let (x, y) = (tile.0.saturating_mul(bw), tile.1.saturating_mul(bh)); + let valid = at >= chunks_start && at < len; + let bytes = if valid { end_of(at).saturating_sub(at).min(most) } else { 0 }; + chunks.push(ChunkRef { offset: at, len: bytes, x, y, cols: bw.min(w.saturating_sub(x)), rows: bh.min(ht.saturating_sub(y)), tile }); + } + let pixel_bytes = pixel_bytes(h).ok_or_else(|| malformed("pixel size"))?; + out.push(PartLayout { offset, size: (w, ht), pixel_bytes, chunks }); + } + Ok(out) +} + +/// What to read. +#[derive(Debug, Clone)] +pub struct Request<'a> { + /// The channels wanted as `(part, channel)` (positions in [`Index::parts`] and in the part's + /// [`PartInfo::channels`]), in the order [`Band::slot`] and the planes of [`read_planes`] count + /// them. A channel may be named more than once (each slot gets its own bands). A channel of a + /// deep part is refused. + pub channels: &'a [(usize, usize)], + /// The value of each requested channel (same order) where the file has no samples; missing + /// entries count as 0. Only [`read_planes`] uses it ([`read_bands`] delivers samples only). + pub fill: &'a [f32], + /// The rows to read, counted from the display window's top row (0, whatever the display + /// window's absolute position), at full resolution; `None`: all. + pub rows: Option>, + /// Every `2^level`-th row and column of the display window (0: full resolution, at most 16). + pub level: u32, + /// The most bytes of samples the read may produce: [`read_bands`] checks the requested rows + /// at the level, [`read_planes`] the whole display-window planes it allocates. Without + /// [`Request::max_block_bytes`], it also raises the most one decompressed block may take + /// above the 256 MiB default. + pub max_bytes: usize, + /// The most threads that decompress (`None`: as many as the machine runs at once; `Some(0)`: + /// none, everything is decoded on the calling thread). Never more than the chunks need. + pub workers: Option, + /// The most bytes one decompressed block may take (`None`: `max(256 MiB, max_bytes)`). A + /// needed chunk whose block is larger is refused before anything is read. + /// + /// It is a limit of its own because the `exr` crate's decompressors allocate a whole block at + /// once and can't report that the memory isn't there: the process aborts. A block must stay + /// below what the caller is sure the system can give, even when the read's total budget + /// (`max_bytes`, which allocations this module makes fallibly count against) is far larger. A + /// block is one strip of the file (at most 256 scan lines, for DWAB): 8 GiB is a 16K-wide + /// strip of 256 lines of 512 f32 channels. + pub max_block_bytes: Option, + /// Runs of request slots delivered together, as one band per block whose pixels hold the + /// slots' values in slot order (`0..4` over R, G, B, A of a part: one RGBA band): for a caller + /// that stores pixels interleaved. Every slot of a group must name a channel of the same part + /// (they then share every block), and no slot may be in two groups; slots in no group come one + /// band each, as without groups. Empty: no groups. [`read_planes`] ignores it. + pub groups: &'a [Range], +} + +impl<'a> Request<'a> { + /// Every row of `channels` at full resolution, fill 0, up to `max_bytes` of samples, with as + /// many decoding threads as the machine runs at once. + pub fn new(channels: &'a [(usize, usize)], max_bytes: usize) -> Request<'a> { + Request { channels, fill: &[], rows: None, level: 0, max_bytes, workers: None, max_block_bytes: None, groups: &[] } + } +} + +/// The size of the planes of a read at `level` of a `width` × `height` display window. +pub fn level_size((width, height): (usize, usize), level: u32) -> (usize, usize) { + let stride = 1usize << level.min(16); + (width.div_ceil(stride), height.div_ceil(stride)) +} + +/// A rectangle of rows of one requested channel, or of a group of them ([`Request::groups`]), +/// decoded: `samples` holds `height` rows of `width` pixels, row by row, each pixel +/// `values_per_pixel` values in slot order. `x` and `y` are in the output grid, counted from the +/// display window's top-left corner (0, 0, not its absolute position): display-window pixels at +/// level 0, every `2^level`-th pixel above. +#[derive(Debug, Clone, PartialEq)] +pub struct Band { + /// The position of the channel in [`Request::channels`]; for a group, its first slot. + pub slot: usize, + pub x: usize, + pub y: usize, + pub width: usize, + pub height: usize, + /// The values per pixel: 1, or the size of the group the band is of. + pub values_per_pixel: usize, + /// The chunk the band was decoded from: its number in the read, from 0 in file order, counting + /// the chunks [`Index::estimate`] counts. A chunk may give no band (none of its rows on the + /// level's grid, say) or several; the bands of a chunk come together, so progress is the + /// highest `chunk` seen plus one, out of [`Estimate::chunks`]. + pub chunk: usize, + pub samples: Vec, +} + +/// What a read did, for measurements and tests. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Stats { + /// Chunks fetched, per part. + pub chunks: Vec, + /// Bytes of chunks read from the source. + pub bytes: u64, + /// Scan lines (or tile rows) decompressed. + pub lines: usize, + /// The most decoded bytes the read had in flight at once, as estimated from the headers: the + /// decompressed blocks and the bands of the chunks read but not yet handed to the sink. + pub in_flight: u64, +} + +/// What a read will take, from [`Index::estimate`], before anything is read. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct Estimate { + /// The chunks it fetches: one unit of progress each (a read hands every chunk's bands over + /// together). + pub chunks: usize, + /// The bytes of those chunks it reads from the source. + pub compressed_bytes: u64, + /// An upper estimate of the most memory the read holds at once besides what the sink keeps: + /// the decoded bytes in flight (as [`Stats::in_flight`] counts them: each chunk's + /// decompressed block and its bands, exactly as large as they are made, grouped or not), as + /// much again for the decompressors' scratch, two pieces of compressed bytes, and each + /// worker's copy of the chunk it decodes. + pub working_bytes: u64, + /// The bytes of the planes [`read_planes`] would allocate for the request (whole display + /// window planes, one per slot: it ignores [`Request::groups`]). Not part of `working_bytes`, + /// and not checked here: [`read_planes`] checks it against [`Request::max_bytes`] when it + /// runs, a caller that collects bands itself checks what it allocates. + pub planes_bytes: u64, +} + +/// The planes of [`read_planes`]: one per requested channel, `width` × `height` (the display +/// window at the request's level). +#[derive(Debug, Clone, PartialEq)] +pub struct Planes { + pub width: usize, + pub height: usize, + pub planes: Vec>, + pub stats: Stats, +} + +/// How a read with a fallible sink ([`read_bands_try`]) ended early. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Stop { + /// The read failed. + Read(Error), + /// The sink returned this error; nothing was handed to it after. + Sink(E), +} + +impl From for Stop { + fn from(e: Error) -> Self { + Stop::Read(e) + } +} + +impl std::fmt::Display for Stop { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Stop::Read(e) => e.fmt(f), + Stop::Sink(e) => e.fmt(f), + } + } +} + +impl std::error::Error for Stop { + fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { + match self { + Stop::Read(e) => Some(e), + Stop::Sink(_) => None, + } + } +} + +/// The planes' geometry for [`chunk_bands`]. +struct Geometry<'a> { + /// The display window's size and the output's (at the level). + size: (usize, usize), + out: (usize, usize), + stride: i64, + /// The display rows read. + rows: Range, + /// Each part's channel → the request slots that name it. + slots: &'a [Vec>], + /// Per request slot: the band it goes into (the first slot of its group, or itself), that + /// band's values per pixel, and the slot's place among them. + units: &'a [(usize, usize, usize)], +} + +impl Geometry<'_> { + /// A display row is read: in the rows, on the level's grid. + fn wanted(&self, row: i64) -> bool { + row >= self.rows.start && row < self.rows.end && row.rem_euclid(self.stride) == 0 + } + + /// A chunk holding display rows `a..b` has a row read. + fn any_wanted(&self, a: i64, b: i64) -> bool { + let first = a.max(self.rows.start); + // (saturating: the rows are clamped to the display window, but the chunk's top may not be) + let first = first.saturating_add((self.stride - first.rem_euclid(self.stride)) % self.stride); + first < b.min(self.rows.end) + } + + /// How many rows are read (in the rows, on the level's grid). + fn rows_read(&self) -> usize { + let (a, b) = (self.rows.start.max(0), self.rows.end.max(0)); + let count = |n: i64| n.saturating_add(self.stride - 1) / self.stride; + usize::try_from(count(b).saturating_sub(count(a))).unwrap_or(0) + } +} + +/// A chunk the request needs, in the order the jobs are numbered (file order). +struct Planned { + part: usize, + offset: u64, + len: u64, + chunk: ChunkRef, + /// Its estimated decoded bytes: the decompressed block and the bands of the requested slots. + cost: u64, +} + +/// What a request needs, worked out from the index alone: the shared first step of a read and of +/// [`Index::estimate`]. +struct Plan { + /// Per part and channel: the request slots that name it. + slots: Vec>>, + size: (usize, usize), + out: (usize, usize), + stride: i64, + rows: Range, + /// The chunks to read, in file order. + jobs: Vec, + /// The decoding threads to start. + workers: usize, + /// Per request slot: see [`Geometry::units`]. + units: Vec<(usize, usize, usize)>, +} + +impl Plan { + fn geometry(&self) -> Geometry<'_> { + Geometry { size: self.size, out: self.out, stride: self.stride, rows: self.rows.clone(), slots: &self.slots, units: &self.units } + } +} + +/// Checks `request` against `index` and lists the chunks it needs (see [`read_bands`] for the +/// checks): nothing is read. +fn plan(index: &Index, request: &Request) -> Result { + let level = request.level.min(16); + let stride = 1i64 << level; + let (w, h) = (index.display.width as usize, index.display.height as usize); + let out = level_size((w, h), level); + // Per part and channel: the request slots that name it. + let mut slots: Vec>> = index.parts.iter().map(|p| vec![Vec::new(); p.channels.len()]).collect(); + for (slot, (part, channel)) in request.channels.iter().enumerate() { + let info = index.parts.get(*part).ok_or_else(|| malformed("no such part"))?; + if info.deep { + return Err(Error::Unsupported("a channel of a deep part".into())); + } + let c = info.channels.get(*channel).ok_or_else(|| malformed("no such channel"))?; + if c.sampling != (1, 1) { + return Err(Error::Unsupported("a subsampled channel".into())); + } + if let Some(s) = slots.get_mut(*part).and_then(|p| p.get_mut(*channel)) { + s.push(slot); + } + } + // Groups: slots of one part (so they share every block), none in two groups. + let mut units: Vec<(usize, usize, usize)> = (0..request.channels.len()).map(|slot| (slot, 1, 0)).collect(); + let mut grouped = vec![false; request.channels.len()]; + for group in request.groups { + let members = request + .channels + .get(group.clone()) + .filter(|m| !m.is_empty()) + .ok_or_else(|| malformed(format!("channel group {group:?} is empty or past the requested channels")))?; + if members.iter().any(|(part, _)| Some(*part) != members.first().map(|m| m.0)) { + return Err(Error::Unsupported(format!("channel group {group:?} spans parts"))); + } + for taken in grouped.get_mut(group.clone()).unwrap_or_default() { + if std::mem::replace(taken, true) { + return Err(malformed(format!("channel group {group:?} overlaps another"))); + } + } + for (k, unit) in units.get_mut(group.clone()).unwrap_or_default().iter_mut().enumerate() { + *unit = (group.start, group.len(), k); + } + } + let rows = request.rows.clone().unwrap_or(0..h as i64); + // (both ends inside the display window, so an empty or reversed range at either end of i64 + // stays empty instead of overflowing when aligned to the level's grid) + let rows = rows.start.clamp(0, h as i64)..rows.end.clamp(0, h as i64); + let geometry = Geometry { size: (w, h), out, stride, rows: rows.clone(), slots: &slots, units: &units }; + // What the request delivers: the rows read, at the level, of every requested channel. + let need = plane_bytes((out.0, geometry.rows_read()), request.channels.len()); + if need > request.max_bytes { + return Err(Error::LimitExceeded(format!("the requested rows need {need} bytes, more than the {} the read may use", request.max_bytes))); + } + // The chunks to read, in file order. The decompressor allocates each one's whole block, so a + // block may take no more than the read allows (see `Request::max_block_bytes`). + let most_block = request.max_block_bytes.unwrap_or(MAX_BLOCK_BYTES.max(request.max_bytes)) as u64; + let mut jobs: Vec = Vec::new(); + for (pi, part) in index.layout.iter().enumerate() { + let requested = slots.get(pi).map_or(0, |s| s.iter().map(Vec::len).sum::()); + if requested == 0 { + continue; + } + for c in &part.chunks { + let top = (c.y as i64).saturating_add(part.offset.1); + if !geometry.any_wanted(top, top.saturating_add(c.rows as i64)) { + continue; + } + if c.len == 0 { + return Err(malformed("a chunk offset outside the chunk area of the file")); + } + if let Some(header) = index.meta.headers.get(pi) { + index.check_ratio(pi, header, part, c, c.len)?; + } + let pixels = (c.cols as u64).saturating_mul(c.rows as u64); + let block = pixels.saturating_mul(part.pixel_bytes as u64); + if block > most_block { + return Err(Error::LimitExceeded(format!( + "a block of part {pi} decompresses to {block} bytes, more than the {most_block} one block of this read may use" + ))); + } + let cost = block.saturating_add(pixels.saturating_mul(requested as u64).saturating_mul(4)); + jobs.try_reserve(1).map_err(|_| Error::OutOfMemory("chunk list allocation".into()))?; + jobs.push(Planned { part: pi, offset: c.offset, len: c.len, chunk: *c, cost }); + } + } + jobs.sort_by_key(|j| j.offset); + // (no more threads than chunks can be in flight: two pieces) + let workers = + request.workers.unwrap_or_else(|| std::thread::available_parallelism().map_or(1, usize::from)).min(jobs.len()).min(2 * PIECE_CHUNKS); + Ok(Plan { slots, size: (w, h), out, stride, rows, jobs, workers, units }) +} + +impl Index { + /// What reading `request` will take, before anything is read: the chunks (one unit of + /// progress each), their bytes, the most memory the read holds at once, and the planes + /// [`read_planes`] allocates. Fails as the read would on the same request (limits, unknown or + /// deep channels), so an app can reserve memory and size a progress bar first. + pub fn estimate(&self, request: &Request) -> Result { + estimate_within(self, request, IN_FLIGHT_BYTES) + } +} + +/// [`Index::estimate`] for a read keeping at most `budget` decoded bytes in flight. +pub(crate) fn estimate_within(index: &Index, request: &Request, budget: u64) -> Result { + let plan = plan(index, request)?; + let sum = |f: fn(&Planned) -> u64| plan.jobs.iter().map(f).fold(0u64, u64::saturating_add); + let most = |f: fn(&Planned) -> u64| plan.jobs.iter().map(f).max().unwrap_or(0); + let (compressed, longest) = (sum(|j| j.len), most(|j| j.len)); + // As the read bounds them: decoded bytes within the budget or one chunk, two pieces. + let decoded = sum(|j| j.cost).min(budget.max(most(|j| j.cost))); + let pieces = compressed.min(PIECE_BYTES.max(longest).saturating_mul(2)); + let copies = (plan.workers.max(1) as u64).saturating_mul(longest).min(compressed); + let (w, h) = level_size(plan.size, request.level.min(16)); + Ok(Estimate { + chunks: plan.jobs.len(), + compressed_bytes: compressed, + working_bytes: decoded.saturating_mul(2).saturating_add(pieces).saturating_add(copies), + planes_bytes: plane_bytes((w, h), request.channels.len()) as u64, + }) +} + +/// The bands of what `request` asks for, handed to `sink` one decoded block at a time, in file +/// order: by offset in the file, so a part written bottom-up (`LineOrder::Decreasing`) arrives +/// bottom-up, and the chunks of several parts arrive interleaved as the file stores them. Within +/// a block, the bands come by request slot (a group at its first slot). +/// +/// The chunks are read on the calling thread, in pieces of chunks that follow each other in the +/// file, and decompressed on worker threads ([`Request::workers`]) while the next piece is read. +/// Each time a piece has been read, and while waiting, the calling thread hands every band that +/// is next in file order to `sink`, so the first bands arrive after the first few hundred +/// kilobytes have been read, not after the whole request, and `sink` needs to be neither `Send` +/// nor `Sync`. +/// +/// Memory is bounded. At most one piece is read ahead of what has been delivered, so at most two +/// pieces of compressed bytes (8 MiB, or one larger chunk) are held. Each chunk's decoded bytes +/// are estimated from the headers as its decompressed block plus 4 bytes per pixel for each +/// requested slot of its part (see [`Stats::in_flight`]); the chunks in flight stay within +/// 64 MiB of that, and a chunk whose estimate alone is over 64 MiB is decoded alone, once +/// everything before it has been delivered, so however many workers run, at most one such chunk +/// is held at a time. A block may take no more than [`Request::max_block_bytes`] (by default +/// 256 MiB, or [`Request::max_bytes`] if that is more); a needed chunk over it is refused +/// ([`Error::LimitExceeded`]) before anything is read. +/// For one big chunk the real peak is several times its block: its compressed bytes in the +/// piece, the `exr` crate's copy of its payload (a chunk's declared size is checked against the +/// bytes it holds first, so that copy is no larger than the chunk), the decompressed block, the +/// decompressor's scratch buffers, and the `f32` bands; roughly 3 to 4 times +/// `max(256 MiB, max_bytes)` at worst ([`Index::estimate`] gives the bound for a request). Where +/// threads can't be started (WebAssembly) the chunks are decoded on the calling thread instead. +/// `cancel` is polled before each piece, before each chunk is handed to `sink`, and at least +/// every 50 ms while waiting for the workers. +/// +/// A band lies inside the planes the request describes ([`level_size`] of the display window); +/// rows or columns no chunk or data window covers are not delivered. A chunk the request needs +/// whose offset lies outside the file fails the read before anything is read or delivered +/// ([`Error::Malformed`]). A chunk that can't be decoded or isn't the block its offset-table +/// entry stands for fails the read when its turn comes: the bands before it have been delivered +/// by then. +pub fn read_bands( + source: &mut R, + index: &Index, + request: &Request, + cancel: &dyn Fn() -> bool, + sink: &mut dyn FnMut(Band), +) -> Result { + read_bands_within(source, index, request, cancel, sink, IN_FLIGHT_BYTES) +} + +/// [`read_bands`] that keeps what it did in `stats` as it goes, so the counts are there also when +/// the read fails or is cancelled (they then say how far it got). `stats` is reset first. +pub fn read_bands_with_stats( + source: &mut R, + index: &Index, + request: &Request, + cancel: &dyn Fn() -> bool, + sink: &mut dyn FnMut(Band), + stats: &mut Stats, +) -> Result<()> { + read_infallible(source, index, request, cancel, sink, IN_FLIGHT_BYTES, stats) +} + +/// [`read_bands_with_stats`] with a sink that can stop the read with an error of its own (a tile +/// store out of room, a full scratch disk): nothing more is read or handed to the sink after it +/// fails, the decoding threads wind down as on a cancel, and the sink's error comes back as +/// [`Stop::Sink`], unchanged. `stats` says how far the read got either way; after a sink error +/// its `lines` include the chunk whose band the sink refused (the chunk was decoded whole). +/// +/// This is also the way to pull: a caller that wants to decide band by band whether to go on (and +/// check a budget before each one) does that in the sink. A pulling iterator would have to run the +/// read on a thread of its own, because the read hands bands over from the middle of its loop. +pub fn read_bands_try( + source: &mut R, + index: &Index, + request: &Request, + cancel: &dyn Fn() -> bool, + sink: &mut dyn FnMut(Band) -> std::result::Result<(), E>, + stats: &mut Stats, +) -> std::result::Result<(), Stop> { + read_into(source, index, request, cancel, sink, IN_FLIGHT_BYTES, stats) +} + +/// [`read_bands`] keeping at most `budget` decoded bytes in flight (the tests use a small one). +pub(crate) fn read_bands_within( + source: &mut R, + index: &Index, + request: &Request, + cancel: &dyn Fn() -> bool, + sink: &mut dyn FnMut(Band), + budget: u64, +) -> Result { + let mut stats = Stats::default(); + read_infallible(source, index, request, cancel, sink, budget, &mut stats)?; + Ok(stats) +} + +/// [`read_into`] with a sink that can't fail. +fn read_infallible( + source: &mut R, + index: &Index, + request: &Request, + cancel: &dyn Fn() -> bool, + sink: &mut dyn FnMut(Band), + budget: u64, + stats: &mut Stats, +) -> Result<()> { + let mut sink = |band: Band| -> std::result::Result<(), std::convert::Infallible> { + sink(band); + Ok(()) + }; + read_into(source, index, request, cancel, &mut sink, budget, stats).map_err(|stop| match stop { + Stop::Read(e) => e, + Stop::Sink(never) => match never {}, + }) +} + +/// The read behind [`read_bands`], counting into `stats`. +fn read_into( + source: &mut R, + index: &Index, + request: &Request, + cancel: &dyn Fn() -> bool, + sink: &mut dyn FnMut(Band) -> std::result::Result<(), E>, + budget: u64, + stats: &mut Stats, +) -> std::result::Result<(), Stop> { + *stats = Stats { chunks: vec![0; index.layout.len()], ..Default::default() }; + let plan = plan(index, request)?; + let geometry = plan.geometry(); + let jobs = &plan.jobs; + if jobs.is_empty() { + return Ok(()); + } + // (declared outside the scope because the workers borrow the receiving end) + let (to_workers, queue) = mpsc::channel::(); + let queue = Mutex::new(queue); + std::thread::scope(|scope| { + // Owned by this closure so that every way out of it (an error, a cancel, the sink's + // error) drops the sending end, which ends the workers' loops before the scope waits. + let to_workers = to_workers; + let (done, results) = mpsc::channel(); + let mut started = 0usize; + for _ in 0..plan.workers { + let (queue, done, geometry) = (&queue, done.clone(), &geometry); + let worker = + std::thread::Builder::new().name("exr-decode".into()).spawn_scoped(scope, move || decode_worker(index, geometry, queue, &done)); + started += usize::from(worker.is_ok()); + } + // (only the workers hold senders now: if they all stop, waiting for a result fails + // instead of blocking forever) + drop(done); + let mut order = InOrder::default(); + let mut pos: Option = None; + let mut most = FIRST_PIECE_BYTES; + let mut submitted = 0usize; + // The decoded bytes of the chunks submitted and not yet delivered. + let mut in_flight = 0u64; + // The sequence number of the first chunk of the piece read last. + let mut last_piece = 0usize; + // Hands over what is next in order and takes it off the bytes in flight. + let mut deliver = |order: &mut InOrder, in_flight: &mut u64, stats: &mut Stats| -> std::result::Result<(), Stop> { + let before = order.next; + let delivered = order.deliver(sink, stats, cancel); + let done: u64 = jobs.get(before..order.next).unwrap_or_default().iter().map(|j| j.cost).fold(0, u64::saturating_add); + *in_flight = in_flight.saturating_sub(done); + delivered + }; + while submitted < jobs.len() { + if cancel() { + return Err(Error::Cancelled.into()); + } + let rest = jobs.get(submitted..).unwrap_or_default(); + let take = piece_len(rest, most, budget); + let piece = rest.get(..take).unwrap_or_default(); + let cost = piece.iter().map(|j| j.cost).fold(0, u64::saturating_add); + // Read ahead by one piece at most, and keep the decoded bytes in flight within the + // budget (a piece over it alone is read once everything before it is delivered). + // (`order.next` is a chunk not received yet whenever this waits, so a result is on + // its way: everything decoded on this thread is delivered at once.) + while order.next < last_piece || (order.next < submitted && in_flight.saturating_add(cost) > budget) { + let (seq, result) = next_result(&results, cancel)?; + order.accept(seq, result); + deliver(&mut order, &mut in_flight, stats)?; + if cancel() { + return Err(Error::Cancelled.into()); + } + } + most = most.saturating_mul(2).min(PIECE_BYTES); + let Piece { data, chunks } = read_piece(source, piece, &mut pos, stats)?; + let data = Arc::new(data); + last_piece = submitted; + in_flight = in_flight.saturating_add(cost); + stats.in_flight = stats.in_flight.max(in_flight); + for (planned, range) in piece.iter().zip(chunks) { + let job = Job { seq: submitted, part: planned.part, chunk: planned.chunk, data: Arc::clone(&data), range }; + submitted += 1; + if started == 0 { + order.accept(job.seq, decode_job(index, &geometry, &job)); + } else if let Err(mpsc::SendError(job)) = to_workers.send(job) { + // (the queue outlives this loop, so a send doesn't fail; if it ever did, the + // chunk is decoded here rather than lost) + order.accept(job.seq, decode_job(index, &geometry, &job)); + } + } + while let Ok((seq, result)) = results.try_recv() { + order.accept(seq, result); + } + deliver(&mut order, &mut in_flight, stats)?; + } + // Everything is read: the rest as it is decoded. + while order.next < submitted { + if cancel() { + return Err(Error::Cancelled.into()); + } + let (seq, result) = next_result(&results, cancel)?; + order.accept(seq, result); + deliver(&mut order, &mut in_flight, stats)?; + } + Ok(()) + }) +} + +/// The next decoded chunk from the workers, polling `cancel` while waiting. (Only called while a +/// worker holds a chunk: on the calling thread everything is decoded before it would wait.) +fn next_result(results: &Receiver<(usize, Decoded)>, cancel: &dyn Fn() -> bool) -> Result<(usize, Decoded)> { + loop { + match results.recv_timeout(CANCEL_POLL) { + Ok(result) => return Ok(result), + Err(RecvTimeoutError::Timeout) => { + if cancel() { + return Err(Error::Cancelled); + } + } + Err(RecvTimeoutError::Disconnected) => return Err(malformed("a decoding thread stopped")), + } + } +} + +/// [`read_bands`] collected: one plane per requested channel covering the whole display window +/// at the request's level (also when [`Request::rows`] selects only some rows: the other rows +/// keep the fill value), filled with [`Request::fill`] where nothing was read. The planes are +/// reserved up front and count against [`Request::max_bytes`] (an allocation the system refuses +/// is [`Error::OutOfMemory`], not an abort), so the cost is known before the first chunk is +/// read. +pub fn read_planes(source: &mut R, index: &Index, request: &Request, cancel: &dyn Fn() -> bool) -> Result { + let (w, h) = (index.display.width as usize, index.display.height as usize); + let (ow, oh) = level_size((w, h), request.level.min(16)); + let n = ow.checked_mul(oh).ok_or_else(|| Error::LimitExceeded("display window".into()))?; + let need = plane_bytes((ow, oh), request.channels.len()); + if need > request.max_bytes { + return Err(Error::LimitExceeded(format!("{w}×{h} channels need {need} bytes, more than the {} the read may use", request.max_bytes))); + } + let mut planes: Vec> = Vec::new(); + planes.try_reserve_exact(request.channels.len()).map_err(|_| Error::OutOfMemory("plane list allocation".into()))?; + for slot in 0..request.channels.len() { + let mut plane: Vec = Vec::new(); + plane.try_reserve_exact(n).map_err(|_| Error::OutOfMemory(format!("{need} bytes of planes: the system can't give that memory now")))?; + plane.resize(n, request.fill.get(slot).copied().unwrap_or(0.0)); + planes.push(plane); + } + // (one plane per slot: groups would interleave) + let request = Request { groups: &[], ..request.clone() }; + let stats = read_bands(source, index, &request, cancel, &mut |band: Band| { + let Some(plane) = planes.get_mut(band.slot) else { return }; + for r in 0..band.height { + let start = (band.y + r).checked_mul(ow).and_then(|row| row.checked_add(band.x)); + let (Some(start), Some(from)) = (start, r.checked_mul(band.width)) else { continue }; + if let (Some(dst), Some(src)) = + (plane.get_mut(start..start.saturating_add(band.width)), band.samples.get(from..from.saturating_add(band.width))) + { + dst.copy_from_slice(src); + } + } + })?; + Ok(Planes { width: ow, height: oh, planes, stats }) +} + +/// The bytes of `count` planes of `size`, saturating. +fn plane_bytes((w, h): (usize, usize), count: usize) -> usize { + w.saturating_mul(h).saturating_mul(count).saturating_mul(std::mem::size_of::()) +} + +/// One chunk to decode: its sequence number in file order, its part, where it belongs, and where +/// its bytes lie in the piece it was read with (shared by all the chunks of that piece). +struct Job { + seq: usize, + part: usize, + chunk: ChunkRef, + data: Arc>, + range: Range, +} + +/// What decoding one chunk gives: its bands and the scan lines decompressed. +type Decoded = Result<(Vec, usize)>; + +/// A decoding thread: takes chunks from `queue` until it is closed, and sends each one's bands +/// back through `done` (until nobody listens any more: the read has ended early). +fn decode_worker(index: &Index, g: &Geometry, queue: &Mutex>, done: &Sender<(usize, Decoded)>) { + loop { + // (the lock is held while waiting for the next chunk, so the workers take turns waiting; + // a poisoned lock can't happen, no worker panics while holding it, and would end this one) + let next = match queue.lock() { + Ok(queue) => queue.recv(), + Err(_) => return, + }; + let Ok(job) = next else { return }; + let seq = job.seq; + let mut report = Report { seq, done, sent: false }; + let decoded = decode_job(index, g, &job); + // (its share of the piece's bytes goes now, not after the result is taken: the two-pieces + // bound counts on it) + drop(job); + report.sent = true; + if done.send((seq, decoded)).is_err() { + return; + } + } +} + +/// Reports a chunk as failed if the worker decoding it unwinds before sending its result, so the +/// calling thread, which waits for every chunk in order, never waits for one that won't come. +struct Report<'a> { + seq: usize, + done: &'a Sender<(usize, Decoded)>, + sent: bool, +} + +impl Drop for Report<'_> { + fn drop(&mut self) { + if !self.sent { + let _ = self.done.send((self.seq, Err(malformed("a decoding thread stopped")))); + } + } +} + +/// The bands of one chunk. A panic in the `exr` crate's decompressors is reported as a damaged +/// chunk, never raised (where panics unwind). +fn decode_job(index: &Index, g: &Geometry, job: &Job) -> Decoded { + let buf = job.data.get(job.range.clone()).unwrap_or_default(); + let decoded = catch_unwind(AssertUnwindSafe(|| chunk_bands(index, job.part, &job.chunk, buf, g))) + .unwrap_or_else(|_| Err(malformed("a chunk could not be decompressed"))); + decoded.map(|(mut bands, lines)| { + for band in &mut bands { + band.chunk = job.seq; + } + (bands, lines) + }) +} + +/// Puts decoded chunks back into file order: the workers finish them in any order, the sink gets +/// them by sequence number. +#[derive(Default)] +struct InOrder { + /// The sequence number of the next chunk to deliver. + next: usize, + /// Chunks decoded ahead of it. + waiting: std::collections::BTreeMap, +} + +impl InOrder { + fn accept(&mut self, seq: usize, decoded: Decoded) { + self.waiting.insert(seq, decoded); + } + + /// Hands every chunk that is next in order to `sink`, polling `cancel` before each one; the + /// first chunk that failed to decode ends the read with its error (after the chunks before it + /// were delivered). + /// The sink's error stops the delivery at once (no band after it). + fn deliver( + &mut self, + sink: &mut dyn FnMut(Band) -> std::result::Result<(), E>, + stats: &mut Stats, + cancel: &dyn Fn() -> bool, + ) -> std::result::Result<(), Stop> { + while self.waiting.contains_key(&self.next) { + if cancel() { + return Err(Error::Cancelled.into()); + } + let Some(decoded) = self.waiting.remove(&self.next) else { break }; + self.next += 1; + let (bands, lines) = decoded?; + stats.lines = stats.lines.saturating_add(lines); + for band in bands { + sink(band).map_err(Stop::Sink)?; + } + } + Ok(()) + } +} + +/// The bytes of a piece, and each of its chunks' range in them (in the piece's order). +struct Piece { + data: Vec, + chunks: Vec>, +} + +/// How many of `jobs` (chunks in file order) the next piece takes: chunks that each start where +/// the one before ends, up to [`PIECE_CHUNKS`] of them, `most` bytes or `budget` decoded bytes, +/// at least one. +fn piece_len(jobs: &[Planned], most: u64, budget: u64) -> usize { + let mut take = 0; + let (mut bytes, mut cost) = (0u64, 0u64); + let mut end = None; + while let Some(job) = jobs.get(take) { + if take > 0 + && (take >= PIECE_CHUNKS || end != Some(job.offset) || bytes.saturating_add(job.len) > most || cost.saturating_add(job.cost) > budget) + { + break; + } + bytes = bytes.saturating_add(job.len); + cost = cost.saturating_add(job.cost); + end = Some(job.offset.saturating_add(job.len)); + take += 1; + } + take +} + +/// The raw bytes of the chunks `piece` (in file order, each starting where the one before ends), +/// read with one request after a seek when the source stands elsewhere (`pos`), and each chunk's +/// range in them. A chunk the file ends in keeps the bytes there are. +fn read_piece(source: &mut R, piece: &[Planned], pos: &mut Option, stats: &mut Stats) -> Result { + let Some(start) = piece.first().map(|j| j.offset) else { return Ok(Piece { data: Vec::new(), chunks: Vec::new() }) }; + let total = piece.iter().map(|j| j.len).fold(0u64, u64::saturating_add); + let mut data = Vec::new(); + data.try_reserve_exact(usize::try_from(total).map_err(|_| malformed("chunk size"))?) + .map_err(|_| Error::OutOfMemory("chunk allocation".into()))?; + if *pos != Some(start) { + source.seek(SeekFrom::Start(start)).map_err(io)?; + } + (&mut *source).take(total).read_to_end(&mut data).map_err(io)?; + *pos = Some(start.saturating_add(data.len() as u64)); + stats.bytes = stats.bytes.saturating_add(data.len() as u64); + let mut chunks = Vec::new(); + chunks.try_reserve_exact(piece.len()).map_err(|_| Error::OutOfMemory("chunk allocation".into()))?; + for job in piece { + let a = usize::try_from(job.offset.saturating_sub(start)).unwrap_or(usize::MAX).min(data.len()); + let b = usize::try_from(job.len).map_or(data.len(), |l| a.saturating_add(l)).min(data.len()); + chunks.push(a..b); + if let Some(c) = stats.chunks.get_mut(job.part) { + *c += 1; + } + } + Ok(Piece { data, chunks }) +} + +/// Checks the header of the chunk `buf` of flat part `pi` (`header`), which its offset table +/// says is `expected`, before the `exr` crate reads it: the crate allocates and zero-fills the +/// payload size a chunk declares (up to its own bound per block, which can be hundreds of +/// megabytes) before reading it, and computes a tile's position from the level it declares +/// (panicking on some). The header is the part number (in multi-part files), then the first +/// scan line's y or the tile's column, row and level (x, y), then the payload size, all `i32`. +fn check_chunk_header(meta: &MetaData, header: &Header, pi: usize, expected: &ChunkRef, buf: &[u8]) -> Result> { + let word = |i: usize| buf.get(i * 4..i * 4 + 4).and_then(|b| <[u8; 4]>::try_from(b).ok()).map(i32::from_le_bytes); + let short = || malformed("a chunk shorter than its header"); + let mut at = 0usize; + if meta.requirements.is_multilayer() { + if usize::try_from(word(0).ok_or_else(short)?).ok() != Some(pi) { + return Err(malformed("a chunk of another part where its offset table points")); + } + at = 1; + } + let in_place = match header.blocks { + exr::meta::BlockDescription::ScanLines => { + let y = word(at).ok_or_else(short)?; + at += 1; + i64::from(y) == i64::from(header.own_attributes.layer_position.1).saturating_add(expected.y as i64) + } + exr::meta::BlockDescription::Tiles(_) => { + let tile = [word(at), word(at + 1), word(at + 2), word(at + 3)]; + at += 4; + let [Some(x), Some(y), Some(lx), Some(ly)] = tile else { return Err(short()) }; + (usize::try_from(x).ok(), usize::try_from(y).ok()) == (Some(expected.tile.0), Some(expected.tile.1)) && (lx, ly) == (0, 0) + } + }; + if !in_place { + return Err(malformed("a chunk is not the block its offset table entry stands for")); + } + let size = usize::try_from(word(at).ok_or_else(short)?).map_err(|_| malformed("a chunk declaring a negative size"))?; + if size > buf.len().saturating_sub((at + 1) * 4) { + return Err(malformed("a chunk declaring more bytes than it holds")); + } + let start = (at + 1) * 4; + Ok(start..start + size) +} + +/// Decompress the chunk `buf` of part `pi`, which its offset table says is `expected`, and convert +/// the lines of the requested channels to bands (`g.slots`: each channel's request slots): the +/// bands, and the scan lines decompressed. A chunk that names another part, level or position +/// than its offset-table entry, or declares more bytes than it holds, is refused before the +/// `exr` crate reads it. +fn chunk_bands(index: &Index, pi: usize, expected: &ChunkRef, buf: &[u8], g: &Geometry) -> Result<(Vec, usize)> { + let meta = &index.meta; + let (Some(header), Some(part)) = (meta.headers.get(pi), index.layout.get(pi)) else { return Err(malformed("no such part")) }; + let payload = check_chunk_header(meta, header, pi, expected, buf)?; + // (a DWA chunk's counters can make the crate allocate terabytes: see `crate::dwa_guard`) + let payload = buf.get(payload).unwrap_or_default(); + // (planned against the gap to the next chunk; the payload the chunk declares may be smaller) + index.check_ratio(pi, header, part, expected, payload.len() as u64)?; + crate::dwa_guard::check_payload(header, (expected.cols, expected.rows), payload).map_err(malformed)?; + let mut read = buf; + let chunk = Chunk::read(&mut read, meta).map_err(exr_error)?; + let block = UncompressedBlock::decompress_chunk(chunk, meta, false).map_err(exr_error)?; + if block.index.level != Vec2(0, 0) || block.index.pixel_position != Vec2(expected.x, expected.y) { + return Err(malformed("a chunk is not the block its offset table entry stands for")); + } + let slots = g.slots.get(pi).map_or(&[][..], Vec::as_slice); + let lines = block.index.pixel_size.1; + let ((lw, lh), (w, h)) = (part.size, g.size); + let (ow, _) = g.out; + // The output rows of the block: its data-window rows that land in the display window on a + // wanted row. They are consecutive in the output grid (wanted rows are every stride-th). + let (by, bh) = (block.index.pixel_position.1, block.index.pixel_size.1); + let out_rows: Vec = (by..by.saturating_add(bh)) + .filter_map(|y| usize::try_from(y as i64 + part.offset.1).ok()) + .filter(|ty| *ty < h && g.wanted(*ty as i64)) + .map(|ty| ty / g.stride as usize) + .collect(); + let (Some(&top), Some(&bottom)) = (out_rows.first(), out_rows.last()) else { return Ok((Vec::new(), lines)) }; + let height = bottom.saturating_sub(top).saturating_add(1); + // One band per output unit (a group, or a slot of its own), each row written straight into it + // at its place: no band is copied or regrown. + let mut bands: std::collections::BTreeMap = std::collections::BTreeMap::new(); + // (typed: the line reader is generic over the sample type, and an untyped `0` would make the + // integer buffer `i32`, turning ids from 2^31 up negative) + let (mut f16s, mut f32s, mut u32s): (Vec, Vec, Vec) = (Vec::new(), Vec::new(), Vec::new()); + for line in block.lines(&header.channels) { + let Some(wanted) = slots.get(line.location.channel).filter(|s| !s.is_empty()) else { continue }; + let Some(kind) = header.channels.list.get(line.location.channel).map(|c| c.sample_type) else { continue }; + let (x0, y, count) = (line.location.position.0, line.location.position.1, line.location.sample_count); + // The samples of data-window row `y`, columns `x0..x0 + count`, at display row `ty` from + // display column `tx0`; clipped to the display window. + if y >= lh || x0.checked_add(count).is_none_or(|end| end > lw) { + continue; + } + let Some(ty) = usize::try_from(y as i64 + part.offset.1).ok().filter(|ty| *ty < h) else { continue }; + if !g.wanted(ty as i64) { + continue; + } + let tx0 = x0 as i64 + part.offset.0; + let skip = usize::try_from(-tx0).unwrap_or(0).min(count); + let tx = usize::try_from(tx0.max(0)).unwrap_or(usize::MAX); + let take = (count - skip).min(w.saturating_sub(tx)); + if take == 0 { + continue; + } + let samples: Vec = match kind { + ExrSample::F16 => { + f16s.resize(count, exr::prelude::f16::ZERO); + line.read_samples_into_slice(&mut f16s).map_err(exr_error)?; + let mut out = vec![0.0; take]; + if let Some(src) = f16s.get(skip..skip + take) { + half::slice::HalfFloatSliceExt::convert_to_f32_slice(src, &mut out); + } + out + } + ExrSample::F32 => { + f32s.resize(count, 0.0); + line.read_samples_into_slice(&mut f32s).map_err(exr_error)?; + f32s.iter().skip(skip).take(take).copied().collect() + } + ExrSample::U32 => { + u32s.resize(count, 0); + line.read_samples_into_slice(&mut u32s).map_err(exr_error)?; + u32s.iter().skip(skip).take(take).map(|s| *s as f32).collect() + } + }; + let (row, col, values) = if g.stride == 1 { + (ty, tx, samples) + } else { + // A reduced level: every stride-th column of the row, on the level's grid. + let stride = g.stride as usize; + let first = tx.div_ceil(stride) * stride; + let values: Vec = samples.iter().enumerate().filter(|(j, _)| (tx + j) % stride == 0).map(|(_, v)| *v).collect(); + (ty / stride, first / stride, values) + }; + if values.is_empty() || col.saturating_add(values.len()) > ow { + continue; + } + // (a channel requested more than once goes into each of its slots) + for slot in wanted { + let Some(&(unit, n, k)) = g.units.get(*slot) else { continue }; + let band = match bands.entry(unit) { + std::collections::btree_map::Entry::Occupied(band) => band.into_mut(), + std::collections::btree_map::Entry::Vacant(place) => { + let len = height.saturating_mul(values.len()).saturating_mul(n); + let mut samples = Vec::new(); + samples.try_reserve_exact(len).map_err(|_| Error::OutOfMemory("band allocation".into()))?; + samples.resize(len, 0.0); + place.insert(Band { slot: unit, x: col, y: top, width: values.len(), height, values_per_pixel: n, chunk: 0, samples }) + } + }; + // (every line of a block covers the same columns; a block whose lines don't is damaged) + if band.x != col || band.width != values.len() || row < top || row > bottom { + return Err(malformed("the lines of a block disagree on where they lie")); + } + let base = (row - top).saturating_mul(band.width).saturating_mul(n); + for (i, v) in values.iter().enumerate() { + if let Some(slot) = band.samples.get_mut(base + i * n + k) { + *slot = *v; + } + } + } + } + drop(block); + Ok((bands.into_values().collect(), lines)) +} diff --git a/crates/exr/src/seek_tests.rs b/crates/exr/src/seek_tests.rs new file mode 100644 index 000000000..010492235 --- /dev/null +++ b/crates/exr/src/seek_tests.rs @@ -0,0 +1,1525 @@ +//! Tests of [`crate::seek`]: files are built with the `exr` crate and read back through the +//! seekable reader; the whole-part decoder ([`crate::decode`]) is the oracle for what a channel +//! should hold. +#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)] +// (lists of channel groups with one group are arrays of one range on purpose) +#![allow(clippy::single_range_in_vec_init)] + +use std::cell::Cell; +use std::io::{Cursor, Read, Seek, SeekFrom}; + +use exr::math::Vec2; +use exr::prelude::{ + AnyChannel, AnyChannels, Blocks, Compression, Encoding, FlatSamples, ImageAttributes, IntegerBounds, Layer, LayerAttributes, LineOrder, + WritableImage, +}; + +use super::decode::{Limits, decode_display_part}; +use super::seek::*; + +fn value(i: usize, k: usize) -> f32 { + (i * 7 + k * 1000) as f32 / 4.0 +} + +/// A layer of `w × h` at `at` in the display window, with these channels (f32 ramps, each its own). +fn layer( + name: Option<&str>, + at: (i32, i32), + (w, h): (usize, usize), + channels: &[&str], + tiles: bool, + compression: Compression, +) -> Layer> { + let mut attrs = name.map_or_else(LayerAttributes::default, LayerAttributes::named); + attrs.layer_position = Vec2(at.0, at.1); + let list = channels.iter().enumerate().map(|(k, n)| AnyChannel::new(*n, FlatSamples::F32((0..w * h).map(|i| value(i, k)).collect()))).collect(); + let blocks = if tiles { Blocks::Tiles(Vec2(4, 4)) } else { Blocks::ScanLines }; + Layer::new((w, h), attrs, Encoding { compression, blocks, line_order: LineOrder::Increasing }, AnyChannels::sort(list)) +} + +fn file(layers: Vec>>, display: (usize, usize)) -> Vec { + let image = exr::image::Image::from_layers(ImageAttributes::new(IntegerBounds::new((0, 0), display)), layers); + let mut out = Cursor::new(Vec::new()); + image.write().to_buffered(&mut out).unwrap(); + out.into_inner() +} + +fn never() -> bool { + false +} + +fn indexed(bytes: &[u8]) -> Index { + Index::build(&mut Cursor::new(bytes), &Limits::default(), &never).unwrap() +} + +/// What the whole-part decoder places in the display window for each channel of part `part`. +fn oracle(bytes: &[u8], part: usize, fill: f32) -> Vec> { + decode_display_part(bytes, part, &|_| true, &|_| fill, &Limits::default()).unwrap().channels.into_iter().map(|c| c.samples).collect() +} + +fn channels_of(index: &Index, part: usize) -> Vec<(usize, usize)> { + (0..index.parts()[part].channels.len()).map(|c| (part, c)).collect() +} + +#[test] +fn every_compression_scan_lines_and_tiles_read_like_the_whole_part_decoder() { + for compression in + [Compression::Uncompressed, Compression::RLE, Compression::ZIP1, Compression::ZIP16, Compression::PIZ, Compression::PXR24, Compression::B44] + { + for tiles in [false, true] { + let bytes = file(vec![layer(None, (0, 0), (9, 7), &["R", "G", "B", "A"], tiles, compression)], (9, 7)); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&channels, usize::MAX), &never).unwrap(); + assert_eq!((read.width, read.height), (9, 7)); + assert_eq!(read.planes, oracle(&bytes, 0, 0.0), "{compression:?} tiles {tiles}"); + } + } +} + +#[test] +fn only_the_requested_channels_are_returned_in_the_requested_order() { + let bytes = file(vec![layer(None, (0, 0), (8, 4), &["R", "G", "B", "A"], false, Compression::ZIP1)], (8, 4)); + let index = indexed(&bytes); + let names: Vec<&str> = index.parts()[0].channels.iter().map(|c| c.name.as_str()).collect(); + assert_eq!(names, ["A", "B", "G", "R"]); + let whole = oracle(&bytes, 0, 0.0); + // R, then A (stored first), the others not read. + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 3), (0, 0)], usize::MAX), &never).unwrap(); + assert_eq!(read.planes, [whole[3].clone(), whole[0].clone()]); +} + +#[test] +fn a_part_with_no_requested_channel_is_not_read() { + let bytes = file( + vec![ + layer(Some("depth"), (0, 0), (16, 16), &["Z"], false, Compression::ZIP1), + layer(Some("beauty"), (0, 0), (16, 16), &["R", "G", "B", "A"], true, Compression::PIZ), + ], + (16, 16), + ); + let index = indexed(&bytes); + assert_eq!(index.parts().len(), 2); + let depth = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], usize::MAX), &never).unwrap(); + assert_eq!(depth.planes, oracle(&bytes, 0, 0.0)); + assert!(depth.stats.chunks[0] > 0); + assert_eq!(depth.stats.chunks[1], 0, "the beauty part was never touched"); + // Channels of both parts in one read, in request order. + let both = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(1, 3), (0, 0)], usize::MAX), &never).unwrap(); + assert_eq!(both.planes, [oracle(&bytes, 1, 0.0)[3].clone(), oracle(&bytes, 0, 0.0)[0].clone()]); +} + +#[test] +fn only_the_chunks_holding_the_requested_rows_are_read() { + // One line per chunk (ZIPS-like layout through ZIP1): rows 4..8 are four chunks. + let bytes = file(vec![layer(None, (0, 0), (8, 16), &["Y"], false, Compression::ZIP1)], (8, 16)); + let index = indexed(&bytes); + let whole = oracle(&bytes, 0, 0.0)[0].clone(); + let request = Request { rows: Some(4..8), fill: &[-1.0], ..Request::new(&[(0, 0)], usize::MAX) }; + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &request, &never).unwrap(); + assert_eq!(read.stats.chunks[0], 4); + for row in 0..16 { + let got = &read.planes[0][row * 8..row * 8 + 8]; + if (4..8).contains(&row) { + assert_eq!(got, &whole[row * 8..row * 8 + 8], "row {row}"); + } else { + assert_eq!(got, [-1.0; 8], "row {row} keeps the fill value"); + } + } + // Tiles: rows 5..6 touch the one tile row (4..8) only. + let tiled = file(vec![layer(None, (0, 0), (8, 16), &["Y"], true, Compression::ZIP1)], (8, 16)); + let tiled_index = indexed(&tiled); + let request = Request { rows: Some(5..6), ..Request::new(&[(0, 0)], usize::MAX) }; + let read = read_planes(&mut Cursor::new(&tiled[..]), &tiled_index, &request, &never).unwrap(); + assert_eq!(read.stats.chunks[0], 2, "two 4-wide tiles of the one tile row"); + assert_eq!(&read.planes[0][5 * 8..6 * 8], &oracle(&tiled, 0, 0.0)[0][5 * 8..6 * 8]); +} + +#[test] +fn a_reduced_level_keeps_every_nth_row_and_column() { + // 9 × 7: level 1 is 5 × 4, level 2 is 3 × 2. + for tiles in [false, true] { + let bytes = file(vec![layer(None, (0, 0), (9, 7), &["Y"], tiles, Compression::ZIP1)], (9, 7)); + let index = indexed(&bytes); + let whole = oracle(&bytes, 0, 0.0)[0].clone(); + for level in 0..=3u32 { + let stride = 1usize << level; + let request = Request { level, ..Request::new(&[(0, 0)], usize::MAX) }; + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &request, &never).unwrap(); + assert_eq!((read.width, read.height), level_size((9, 7), level)); + let expected: Vec = + (0..7).step_by(stride).flat_map(|y| (0..9).step_by(stride).map(move |x| (y, x))).map(|(y, x)| whole[y * 9 + x]).collect(); + assert_eq!(read.planes[0], expected, "level {level} tiles {tiles}"); + } + } +} + +#[test] +fn a_reduced_level_reads_only_the_chunks_with_a_row_on_its_grid() { + // One line per chunk: level 2 needs every 4th row of 16. + let bytes = file(vec![layer(None, (0, 0), (8, 16), &["Y"], false, Compression::ZIP1)], (8, 16)); + let index = indexed(&bytes); + let request = Request { level: 2, ..Request::new(&[(0, 0)], usize::MAX) }; + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &request, &never).unwrap(); + assert_eq!(read.stats.chunks[0], 4); +} + +#[test] +fn a_part_inside_a_larger_display_window_is_placed_and_clipped_like_the_whole_part_decoder() { + // Data window 3 × 2 at (2, 1) in a 6 × 4 display window; another at (-1, -1) cut by the edge. + for (at, size) in [((2, 1), (3, 2)), ((-1, -1), (4, 3)), ((5, 3), (4, 4)), ((-9, 0), (2, 2))] { + let bytes = file(vec![layer(None, at, size, &["R", "G"], false, Compression::ZIP1)], (6, 4)); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let request = Request { fill: &[9.0, 9.0], ..Request::new(&channels, usize::MAX) }; + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &request, &never).unwrap(); + assert_eq!(read.planes, oracle(&bytes, 0, 9.0), "data window {size:?} at {at:?}"); + } +} + +#[test] +fn bands_cover_the_planes_exactly_and_arrive_in_row_order() { + for tiles in [false, true] { + let bytes = file(vec![layer(None, (0, 0), (12, 10), &["R", "G"], tiles, Compression::ZIP16)], (12, 10)); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let mut planes = [vec![f32::NAN; 120], vec![f32::NAN; 120]]; + let mut seen = 0usize; + // Per slot, the (row, column) of the last band: file order is block row by block row, + // and left to right within one (tiles), so it only grows. + let mut last: [Option<(usize, usize)>; 2] = [None, None]; + let stats = read_bands(&mut Cursor::new(&bytes[..]), &index, &Request::new(&channels, usize::MAX), &never, &mut |band: Band| { + assert!(last[band.slot] < Some((band.y, band.x)), "slot {}: {:?} after {:?}", band.slot, (band.y, band.x), last[band.slot]); + last[band.slot] = Some((band.y, band.x)); + assert_eq!(band.samples.len(), band.width * band.height); + assert!(band.x + band.width <= 12 && band.y + band.height <= 10); + for r in 0..band.height { + for c in 0..band.width { + planes[band.slot][(band.y + r) * 12 + band.x + c] = band.samples[r * band.width + c]; + seen += 1; + } + } + }) + .unwrap(); + assert_eq!(seen, 240, "every sample once"); + assert!(stats.chunks[0] > 0 && stats.lines > 0); + assert_eq!(planes.to_vec(), oracle(&bytes, 0, 0.0), "tiles {tiles}"); + } +} + +/// A source that counts the bytes read from it. +struct Counting<'a> { + inner: Cursor<&'a [u8]>, + read: &'a Cell, +} + +impl Read for Counting<'_> { + fn read(&mut self, buf: &mut [u8]) -> std::io::Result { + let n = self.inner.read(buf)?; + self.read.set(self.read.get() + n as u64); + Ok(n) + } +} + +impl Seek for Counting<'_> { + fn seek(&mut self, pos: SeekFrom) -> std::io::Result { + self.inner.seek(pos) + } +} + +#[test] +fn the_first_bands_arrive_before_the_whole_request_has_been_read() { + // Uncompressed lines of 1024 f32 (one chunk each): about 5 MiB in all, more than the first + // two batches. + let bytes = file(vec![layer(None, (0, 0), (1024, 600), &["R", "G"], false, Compression::Uncompressed)], (1024, 600)); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let read = Cell::new(0u64); + let mut at_first_band = None; + let mut source = Counting { inner: Cursor::new(&bytes[..]), read: &read }; + let before = read.get(); + // The rows each channel's bands have reached: they must keep growing (file order). + let mut reached = [0usize; 2]; + let mut bands = 0usize; + read_bands(&mut source, &index, &Request::new(&channels, usize::MAX), &never, &mut |band: Band| { + at_first_band.get_or_insert(read.get() - before); + assert_eq!(band.y, reached[band.slot], "slot {} out of order", band.slot); + reached[band.slot] = band.y + band.height; + bands += 1; + }) + .unwrap(); + let total = read.get() - before; + let first = at_first_band.unwrap(); + assert!(first < total / 2, "first band after {first} of {total} bytes"); + assert_eq!((reached, bands), ([600, 600], 1200), "every row of both channels, one band per chunk and channel"); +} + +#[test] +fn without_threads_the_chunks_are_decoded_on_the_calling_thread_with_the_same_result() { + // (where threads can't be started, as in WebAssembly, no worker runs) + let bytes = file(vec![layer(None, (0, 0), (1024, 300), &["R", "G"], false, Compression::Uncompressed)], (1024, 300)); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let whole = oracle(&bytes, 0, 0.0); + let read = Cell::new(0u64); + let mut source = Counting { inner: Cursor::new(&bytes[..]), read: &read }; + let mut planes = vec![vec![f32::NAN; 1024 * 300]; 2]; + let mut reached = [0usize; 2]; + let mut at_first_band = None; + let request = Request { workers: Some(0), ..Request::new(&channels, usize::MAX) }; + let stats = read_bands(&mut source, &index, &request, &never, &mut |band: Band| { + at_first_band.get_or_insert(read.get()); + assert_eq!(band.y, reached[band.slot], "file order"); + reached[band.slot] = band.y + band.height; + let plane = &mut planes[band.slot]; + plane[band.y * 1024..(band.y + band.height) * 1024].copy_from_slice(&band.samples); + }) + .unwrap(); + assert_eq!(planes, whole); + assert_eq!(stats.chunks[0], 300); + assert!(at_first_band.unwrap() < stats.bytes / 2, "delivered piece by piece"); +} + +#[test] +fn a_read_can_be_called_off() { + let bytes = file(vec![layer(None, (0, 0), (16, 16), &["R"], false, Compression::ZIP1)], (16, 16)); + let index = indexed(&bytes); + let count = Cell::new(0usize); + let cancel = || { + count.set(count.get() + 1); + count.get() > 1 + }; + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], usize::MAX), &cancel); + assert_eq!(got.err(), Some(Error::Cancelled)); + let building = Index::build(&mut Cursor::new(&bytes[..]), &Limits::default(), &|| true); + assert_eq!(building.err(), Some(Error::Cancelled)); +} + +#[test] +fn a_request_over_the_byte_limit_is_refused_before_anything_is_read() { + let bytes = file(vec![layer(None, (0, 0), (16, 16), &["R", "G"], false, Compression::ZIP1)], (16, 16)); + let index = indexed(&bytes); + let read = Cell::new(0u64); + let mut source = Counting { inner: Cursor::new(&bytes[..]), read: &read }; + // Two planes of 16 × 16 f32 are 2048 bytes. + let got = read_planes(&mut source, &index, &Request::new(&[(0, 0), (0, 1)], 2047), &never); + assert!(matches!(got, Err(Error::LimitExceeded(_))), "{got:?}"); + assert_eq!(read.get(), 0, "no chunk was fetched"); + let got = read_planes(&mut source, &index, &Request::new(&[(0, 0), (0, 1)], 2048), &never).unwrap(); + assert_eq!(got.planes.len(), 2); + // A reduced level counts its smaller planes. + let request = Request { level: 1, ..Request::new(&[(0, 0), (0, 1)], 512) }; + assert_eq!(read_planes(&mut source, &index, &request, &never).unwrap().width, 8); +} + +#[test] +fn requests_for_channels_that_do_not_exist_are_refused() { + let bytes = file(vec![layer(None, (0, 0), (4, 4), &["R"], false, Compression::ZIP1)], (4, 4)); + let index = indexed(&bytes); + for channels in [[(1, 0)], [(0, 1)]] { + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&channels, usize::MAX), &never); + assert!(matches!(got, Err(Error::Malformed(_))), "{channels:?}: {got:?}"); + } + // Nothing requested is an empty read. + let none = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[], usize::MAX), &never).unwrap(); + assert!(none.planes.is_empty() && none.stats.bytes == 0); +} + +#[test] +fn headers_declaring_more_than_the_limits_are_refused_before_any_allocation() { + // An 8 × 8 data window, but the limits allow 4 × 4 only. + let bytes = file(vec![layer(None, (0, 0), (8, 8), &["R"], false, Compression::ZIP1)], (8, 8)); + let limits = Limits { max_width: 4, max_height: 4, ..Limits::default() }; + let got = Index::build(&mut Cursor::new(&bytes[..]), &limits, &never); + assert!(matches!(&got, Err(Error::LimitExceeded(m)) if m.contains("part 0")), "{got:?}"); + // A 2 × 2 data window (within the limit) in an 8 × 8 display window over it. + let small = file(vec![layer(None, (0, 0), (2, 2), &["R"], false, Compression::ZIP1)], (8, 8)); + let limits = Limits { max_pixels: 16, ..Limits::default() }; + let got = Index::build(&mut Cursor::new(&small[..]), &limits, &never); + assert!(matches!(&got, Err(Error::LimitExceeded(m)) if m.contains("display window")), "{got:?}"); + assert!(Index::build(&mut Cursor::new(&small[..]), &Limits { max_pixels: 64, ..Limits::default() }, &never).is_ok()); +} + +#[test] +fn hostile_files_are_refused_and_never_panic() { + let bytes = file( + vec![ + layer(Some("a"), (0, 0), (9, 7), &["R", "G"], false, Compression::ZIP1), + layer(Some("b"), (1, 1), (5, 5), &["Z"], true, Compression::PIZ), + ], + (9, 7), + ); + let try_read = |data: &[u8]| { + let Ok(index) = Index::build(&mut Cursor::new(data), &Limits::default(), &never) else { return }; + let channels: Vec<(usize, usize)> = (0..index.parts().len()).flat_map(|p| channels_of(&index, p)).collect(); + let _ = read_planes(&mut Cursor::new(data), &index, &Request::new(&channels, 1 << 24), &never); + }; + // Every truncation. + for n in 0..bytes.len() { + try_read(&bytes[..n]); + } + // A flipped byte at every position (headers, tables and chunks). + for at in 0..bytes.len() { + let mut broken = bytes.clone(); + broken[at] ^= 0xFF; + try_read(&broken); + } + // Garbage and an empty source. + try_read(&[]); + try_read(&[0x76, 0x2f, 0x31, 0x01, 2, 0, 0, 0]); + try_read(&vec![0xAB; 4096]); +} + +#[test] +fn headers_over_the_attribute_and_size_bounds_are_refused() { + let mut bytes = vec![0x76, 0x2f, 0x31, 0x01, 2, 0, 0, 0]; + // An attribute that claims 100 MB. + bytes.extend_from_slice(b"comments\0string\0"); + bytes.extend_from_slice(&100_000_000i32.to_le_bytes()); + bytes.extend_from_slice(&[0; 64]); + assert!(matches!(Index::build(&mut Cursor::new(&bytes[..]), &Limits::default(), &never), Err(Error::LimitExceeded(_)))); + // A name that never ends. + let mut bytes = vec![0x76, 0x2f, 0x31, 0x01, 2, 0, 0, 0]; + bytes.extend_from_slice(&[b'a'; 1000]); + assert!(matches!(Index::build(&mut Cursor::new(&bytes[..]), &Limits::default(), &never), Err(Error::LimitExceeded(_)))); +} + +#[test] +fn a_tiled_file_with_mip_levels_is_read_from_its_largest_level_only() { + use exr::math::RoundingMode; + use exr::prelude::Levels; + // 9 × 7 in 4 × 4 tiles: level 0 is 3 × 2 tiles, then 4 × 3, 2 × 1 and 1 × 1 pixels in one + // tile each. The smaller levels hold a value no full-resolution pixel has, so a wrong level + // would show in the planes. + let (w, h) = (9usize, 7usize); + let sizes: Vec = exr::meta::mip_map_levels(RoundingMode::Down, Vec2(w, h)).map(|(_, size)| size.area()).collect(); + assert!(sizes.len() > 1); + let levels = |k: usize| Levels::Mip { + rounding_mode: RoundingMode::Down, + level_data: sizes + .iter() + .enumerate() + .map(|(level, n)| FlatSamples::F32(if level == 0 { (0..*n).map(|i| value(i, k)).collect() } else { vec![1e9; *n] })) + .collect(), + }; + let channels = AnyChannels::sort(vec![AnyChannel::new("R", levels(0)), AnyChannel::new("G", levels(1))].into()); + let encoding = Encoding { compression: Compression::ZIP1, blocks: Blocks::Tiles(Vec2(4, 4)), line_order: LineOrder::Increasing }; + let image = exr::image::Image::from_layers( + ImageAttributes::new(IntegerBounds::new((0, 0), (w, h))), + vec![Layer::new((w, h), LayerAttributes::default(), encoding, channels)], + ); + let mut out = Cursor::new(Vec::new()); + image.write().to_buffered(&mut out).unwrap(); + let bytes = out.into_inner(); + let index = indexed(&bytes); + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0), (0, 1)], usize::MAX), &never).unwrap(); + // (the part stores G before R) + let expected = |k: usize| (0..w * h).map(|i| value(i, k)).collect::>(); + assert_eq!(read.planes, [expected(1), expected(0)]); + assert_eq!(read.stats.chunks[0], 6, "the six tiles of level 0, none of the smaller levels"); + // A reduced read takes its rows from the largest level too. + let half = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request { level: 1, ..Request::new(&[(0, 1)], usize::MAX) }, &never).unwrap(); + let every_other: Vec = (0..h).step_by(2).flat_map(|y| (0..w).step_by(2).map(move |x| value(y * w + x, 0))).collect(); + assert_eq!(half.planes[0], every_other); +} + +#[test] +fn a_flat_part_beside_a_deep_part_is_read_and_the_deep_part_is_refused() { + use super::decode_tests::{mixed_file, mixed_flat}; + for (deep_first, tiled) in [(false, false), (true, false), (false, true), (true, true)] { + let (bytes, _) = mixed_file(deep_first, tiled); + let (flat, deep) = if deep_first { (1, 0) } else { (0, 1) }; + let index = indexed(&bytes); + assert_eq!((index.parts()[flat].deep, index.parts()[deep].deep), (false, true)); + let names: Vec<&str> = index.parts()[flat].channels.iter().map(|c| c.name.as_str()).collect(); + assert_eq!(names, ["B", "G", "R"]); + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(flat, 2), (flat, 0)], usize::MAX), &never).unwrap(); + let expected = |channel: f32| (0..6).map(|i| mixed_flat(channel, i)).collect::>(); + assert_eq!(read.planes, [expected(0.0), expected(100.0)], "deep first {deep_first} tiled {tiled}"); + assert_eq!((read.stats.chunks[flat], read.stats.chunks[deep]), (2, 0), "the deep part's chunks are never read"); + for channels in [vec![(deep, 0)], vec![(flat, 0), (deep, 0)]] { + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&channels, usize::MAX), &never); + assert!(matches!(got, Err(Error::Unsupported(_))), "{channels:?}: {got:?}"); + } + } +} + +#[test] +fn a_subsampled_channel_is_refused() { + let mut bytes = file(vec![layer(None, (0, 0), (4, 2), &["R"], false, Compression::Uncompressed)], (4, 2)); + // The `exr` crate's writer emits no subsampling: the x sampling of the one channel in the + // channel list is patched to 2 (the 4 × 2 window is a multiple of it). + let tag = b"channels\0chlist\0"; + let attr = bytes.windows(tag.len()).position(|window| window == tag).unwrap(); + let payload = attr + tag.len() + 4; + let name_end = payload + bytes[payload..].iter().position(|byte| *byte == 0).unwrap(); + let x_sampling = name_end + 1 + 4 + 1 + 3; + bytes[x_sampling..x_sampling + 4].copy_from_slice(&2u32.to_le_bytes()); + let index = indexed(&bytes); + assert_eq!(index.parts()[0].channels[0].sampling, (2, 1)); + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], usize::MAX), &never); + assert!(matches!(got, Err(Error::Unsupported(_))), "{got:?}"); +} + +#[test] +fn half_float_and_integer_channels_convert_like_the_whole_part_decoder() { + use exr::prelude::f16; + let (w, h) = (7usize, 5usize); + let halves: Vec = (0..w * h).map(|i| f16::from_f32(i as f32 / 8.0 - 2.0)).collect(); + // Integers beyond f32's exact range too (object ids): they round like the oracle's. + let ids: Vec = (0..w * h).map(|i| (i as u32).wrapping_mul(2_654_435_761)).collect(); + for tiles in [false, true] { + let list = vec![ + AnyChannel::new("Y", FlatSamples::F16(halves.clone())), + AnyChannel::new("id", FlatSamples::U32(ids.clone())), + AnyChannel::new("Z", FlatSamples::F32(vec![0.5; w * h])), + ]; + let blocks = if tiles { Blocks::Tiles(Vec2(4, 4)) } else { Blocks::ScanLines }; + let layer = Layer::new( + (w, h), + LayerAttributes::default(), + Encoding { compression: Compression::ZIP16, blocks, line_order: LineOrder::Increasing }, + AnyChannels::sort(list.into()), + ); + // Placed partly outside the display window, so the conversion and the clipping meet. + let mut layer = layer; + layer.attributes.layer_position = Vec2(-2, 1); + let bytes = file(vec![layer], (6, 5)); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let request = Request { fill: &[7.0, 7.0, 7.0], ..Request::new(&channels, usize::MAX) }; + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &request, &never).unwrap(); + assert_eq!(read.planes, oracle(&bytes, 0, 7.0), "tiles {tiles}"); + assert!(read.planes.iter().all(|p| p.iter().any(|v| *v != 7.0))); + } +} + +#[test] +fn the_index_reports_its_parts_and_a_size() { + let bytes = file(vec![layer(Some("beauty"), (0, 0), (8, 8), &["R", "G", "B"], false, Compression::ZIP16)], (8, 8)); + let index = indexed(&bytes); + assert_eq!(index.parts()[0].name.as_deref(), Some("beauty")); + assert_eq!((index.display().width, index.display().height), (8, 8)); + assert_eq!(index.file_len(), bytes.len() as u64); + assert!(index.bytes() > 0 && index.bytes() < 64 << 10, "{}", index.bytes()); +} + +/// Writes `layers` into a file whose display window is `display` (absolute position and size). +fn file_at(layers: Vec>>, display: ((i32, i32), (usize, usize))) -> Vec { + let image = exr::image::Image::from_layers(ImageAttributes::new(IntegerBounds::new(display.0, display.1)), layers); + let mut out = Cursor::new(Vec::new()); + image.write().to_buffered(&mut out).unwrap(); + out.into_inner() +} + +/// Where the offset table of a single-part file with `count` chunks starts: the position whose +/// smallest entry is where the table ends. +fn table_at(bytes: &[u8], count: usize) -> usize { + let entry = |p: usize| u64::from_le_bytes(bytes[p..p + 8].try_into().unwrap()) as usize; + (8..bytes.len() - count * 8).find(|p| (0..count).map(|i| entry(p + i * 8)).min() == Some(p + count * 8)).unwrap() +} + +/// Sets the box2i attribute `name` (`dataWindow`, `displayWindow`) of a file to `bounds`. +fn patch_box(bytes: &mut [u8], name: &str, bounds: [i32; 4]) { + let tag = format!("{name}\0box2i\0"); + let at = bytes.windows(tag.len()).position(|w| w == tag.as_bytes()).unwrap() + tag.len() + 4; + for (i, v) in bounds.iter().enumerate() { + bytes[at + i * 4..at + i * 4 + 4].copy_from_slice(&v.to_le_bytes()); + } +} + +/// A tiled 9 × 7 file in 4 × 4 tiles with these levels of one channel `R`. +fn tiled_levels(levels: exr::prelude::Levels) -> Vec { + let encoding = Encoding { compression: Compression::ZIP1, blocks: Blocks::Tiles(Vec2(4, 4)), line_order: LineOrder::Increasing }; + let channels = AnyChannels::sort(vec![AnyChannel::new("R", levels)].into()); + let image = exr::image::Image::from_layers( + ImageAttributes::new(IntegerBounds::new((0, 0), (9, 7))), + vec![Layer::new((9, 7), LayerAttributes::default(), encoding, channels)], + ); + let mut out = Cursor::new(Vec::new()); + image.write().to_buffered(&mut out).unwrap(); + out.into_inner() +} + +#[test] +fn a_channel_requested_twice_is_delivered_in_both_slots() { + for tiles in [false, true] { + let bytes = file(vec![layer(None, (0, 0), (9, 7), &["R", "G"], tiles, Compression::ZIP1)], (9, 7)); + let index = indexed(&bytes); + let whole = oracle(&bytes, 0, 0.0); + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 1), (0, 0), (0, 1)], usize::MAX), &never).unwrap(); + assert_eq!(read.planes, [whole[1].clone(), whole[0].clone(), whole[1].clone()], "tiles {tiles}"); + } +} + +#[test] +fn a_block_is_bounded_by_the_bytes_the_decompressor_allocates_for_it() { + // One row 4 Mi pixels wide of one f32 channel: 16 MiB. PIZ holds 32 rows a block, but a + // one-row part's block is that row; 16 such rows of four channels in one ZIP16 block are 1 GiB. + // Both index; a read refuses the 1 GiB block unless its `max_bytes` allows that much. + // (`cancel` stops each read that passes the check before a chunk is fetched.) + let stop = || true; + for (compression, (w, h), channels, big) in + [(Compression::PIZ, (4 << 20, 1), &["R"][..], false), (Compression::ZIP16, (4 << 20, 16), &["R", "G", "B", "A"][..], true)] + { + let mut bytes = file(vec![layer(None, (0, 0), (1, h), channels, false, compression)], (1, h)); + patch_box(&mut bytes, "dataWindow", [0, 0, w - 1, h as i32 - 1]); + let index = Index::build(&mut Cursor::new(&bytes[..]), &Limits::none(), &never).unwrap(); + let read = |max_bytes| read_bands(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], max_bytes), &stop, &mut |_| {}); + let got = read(256 << 20); + if big { + assert!(matches!(&got, Err(Error::LimitExceeded(m)) if m.contains("block")), "{compression:?}: {got:?}"); + assert_eq!(read(1 << 30).err(), Some(Error::Cancelled), "{compression:?}: allowed with max_bytes 1 GiB"); + } else { + assert_eq!(got.err(), Some(Error::Cancelled), "{compression:?}"); + } + } +} + +#[test] +fn a_wide_dwab_part_with_half_a_gigabyte_blocks_reads_only_with_a_budget_that_allows_them() { + // 16K wide, 256 lines (one DWAB block), 64 half channels: 128 bytes a pixel, 512 MiB a block. + let mut bytes = many_channels(1, 1, 64, true, Compression::DWAB(None)); + patch_box(&mut bytes, "dataWindow", [0, 0, 16383, 255]); + patch_box(&mut bytes, "displayWindow", [0, 0, 16383, 255]); + let index = Index::build(&mut Cursor::new(&bytes[..]), &Limits::none(), &never).unwrap(); + assert_eq!(index.chunks(0).map(|c| (c.width, c.height)).collect::>(), [(16384, 256)]); + let stop = || true; + let read = |max_bytes| read_bands(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], max_bytes), &stop, &mut |_| {}); + let got = read(256 << 20); + assert!(matches!(&got, Err(Error::LimitExceeded(m)) if m.contains("block")), "{got:?}"); + assert_eq!(read((512 << 20) - 1).err().map(|e| matches!(e, Error::LimitExceeded(_))), Some(true)); + assert_eq!(read(512 << 20).err(), Some(Error::Cancelled), "a 512 MiB block within max_bytes passes the check"); + assert_eq!(read(1 << 30).err(), Some(Error::Cancelled)); +} + +// (budgets over 4 GiB: a 64-bit usize) +#[cfg(target_pointer_width = "64")] +#[test] +fn a_block_is_held_to_max_block_bytes_whatever_the_total_budget() { + // The same 512 MiB DWAB block, read with a 64 GiB budget: `max_block_bytes` decides. The + // source panics if a chunk is fetched, so a missing check fails at once. + let mut bytes = many_channels(1, 1, 64, true, Compression::DWAB(None)); + patch_box(&mut bytes, "dataWindow", [0, 0, 16383, 255]); + patch_box(&mut bytes, "displayWindow", [0, 0, 16383, 255]); + let index = Index::build(&mut Cursor::new(&bytes[..]), &Limits::none(), &never).unwrap(); + let chunks = index.chunks(0).next().unwrap().offset; + let read = |max_block_bytes, cancel: &dyn Fn() -> bool| { + let request = Request { max_block_bytes, ..Request::new(&[(0, 0)], 64 << 30) }; + read_bands(&mut NoChunks { inner: Cursor::new(&bytes[..]), chunks }, &index, &request, cancel, &mut |_| {}) + }; + let got = read(Some(256 << 20), &never); + assert!(matches!(&got, Err(Error::LimitExceeded(m)) if m.contains("one block")), "{got:?}"); + // (cancelled right after the check, before a chunk is fetched) + assert_eq!(read(Some(1 << 30), &|| true).err(), Some(Error::Cancelled), "a 1 GiB block limit passes the check"); + // `None`: max(256 MiB, max_bytes), here 64 GiB. + assert_eq!(read(None, &|| true).err(), Some(Error::Cancelled)); +} + +#[test] +fn a_chunk_over_the_in_flight_budget_is_decoded_alone() { + // 64 rows of one f32 channel, 16 wide, one row a chunk: each chunk holds a 64-byte block and + // 64 bytes of bands, 128 bytes in flight; with a budget of 100 no two may be in flight at + // once, however many workers there are. + let bytes = file(vec![layer(None, (0, 0), (16, 64), &["R"], false, Compression::ZIP1)], (16, 64)); + let index = indexed(&bytes); + let whole = oracle(&bytes, 0, 0.0); + for _ in 0..20 { + let mut plane = vec![f32::NAN; 16 * 64]; + let request = Request { workers: Some(8), ..Request::new(&[(0, 0)], usize::MAX) }; + let mut sink = |b: Band| plane[b.y * 16..(b.y + b.height) * 16].copy_from_slice(&b.samples); + let stats = super::seek::read_bands_within(&mut Cursor::new(&bytes[..]), &index, &request, &never, &mut sink, 100).unwrap(); + assert_eq!(stats.in_flight, 128, "one chunk at a time"); + assert_eq!(vec![plane], whole); + } +} + +/// A file of `channels` channels named `c0`, `c1`, … of `w × h` pixels, f32 or half. +fn many_channels(w: usize, h: usize, channels: usize, half: bool, compression: Compression) -> Vec { + use exr::prelude::f16; + let list: Vec> = (0..channels) + .map(|k| { + let samples = (0..w * h).map(|i| ((i * 3 + k * 7) % 50) as f32 / 8.0); + let samples = if half { FlatSamples::F16(samples.map(f16::from_f32).collect()) } else { FlatSamples::F32(samples.collect()) }; + AnyChannel::new(format!("c{k:03}").as_str(), samples) + }) + .collect(); + let encoding = Encoding { compression, blocks: Blocks::ScanLines, line_order: LineOrder::Increasing }; + file(vec![Layer::new((w, h), LayerAttributes::default(), encoding, AnyChannels::sort(list.into()))], (w, h)) +} + +#[test] +fn wide_dwab_parts_with_many_channels_are_accepted() { + // DWAB holds 256 scan lines a block, and the `exr` crate's bound on a chunk counts all 256 + // even in a part with fewer rows: over 256 MiB for these, though each block is a few MiB. + let dwab = Compression::DWAB(None); + for (w, h, channels, half) in [(65536, 1, 16, false), (4096, 8, 70, false), (8192, 4, 65, true)] { + let mut bytes = many_channels(1, 1, channels, half, dwab); + patch_box(&mut bytes, "dataWindow", [0, 0, w - 1, h - 1]); + let got = Index::build(&mut Cursor::new(&bytes[..]), &Limits::none(), &never); + assert!(got.is_ok(), "{w} × {h}, {channels} channels: {got:?}"); + } + // A real one: one row 4096 wide of 65 f32 channels (the crate's bound: 256 × 1 MiB). + let bytes = many_channels(4096, 1, 65, false, dwab); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&channels, usize::MAX), &never).unwrap(); + assert_eq!(read.planes, oracle(&bytes, 0, 0.0)); +} + +#[test] +fn a_chunk_declaring_more_bytes_than_it_holds_is_refused_before_the_crate_reads_it() { + // A one-pixel-wide part in 4096 × 16 tiles: each chunk holds 16 pixels, but the `exr` crate + // would allocate whatever size up to a whole tile (256 KiB) a chunk declares. + let part = layer(None, (0, 0), (1, 32), &["R"], false, Compression::ZIP1); + let part = + Layer::new((1, 32), LayerAttributes::default(), Encoding { blocks: Blocks::Tiles(Vec2(4096, 16)), ..part.encoding }, part.channel_data); + let good = file(vec![part], (1, 32)); + let table = table_at(&good, 2); + let chunk = u64::from_le_bytes(good[table..table + 8].try_into().unwrap()) as usize; + assert!(indexed(&good).chunks(0).all(|c| (c.width, c.height) == (1, 16))); + for size in [4096 * 16 * 4 - 1, -1i32] { + let mut bytes = good.clone(); + // (tile column, row, level x and y, then the size) + bytes[chunk + 16..chunk + 20].copy_from_slice(&size.to_le_bytes()); + let index = indexed(&bytes); + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], usize::MAX), &never); + assert!(matches!(&got, Err(Error::Malformed(m)) if m.starts_with("a chunk declaring")), "size {size}: {got:?}"); + } +} + +#[test] +fn a_chunk_naming_another_part_is_refused() { + use super::decode_tests::mixed_file; + // The flat part's first chunk names the deep part. + let (mut bytes, offsets) = mixed_file(false, false); + bytes[offsets[0][0]..offsets[0][0] + 4].copy_from_slice(&1i32.to_le_bytes()); + let index = indexed(&bytes); + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], usize::MAX), &never); + assert!(matches!(&got, Err(Error::Malformed(m)) if m.contains("another part")), "{got:?}"); +} + +#[test] +fn a_failed_or_cancelled_read_still_reports_how_far_it_got() { + // Row 400's chunk of 600 claims another row (see the damaged-chunk test). + let mut bytes = file(vec![layer(None, (0, 0), (1024, 600), &["R", "G"], false, Compression::Uncompressed)], (1024, 600)); + let at = bytes.len() - (600 - 400) * 8200; + bytes[at..at + 4].copy_from_slice(&7i32.to_le_bytes()); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let request = Request { workers: Some(4), ..Request::new(&channels, usize::MAX) }; + let mut stats = Stats::default(); + let got = read_bands_with_stats(&mut Cursor::new(&bytes[..]), &index, &request, &never, &mut |_| {}, &mut stats); + assert!(matches!(got, Err(Error::Malformed(_))), "{got:?}"); + assert_eq!(stats.lines, 400, "the lines delivered before the damaged chunk"); + assert!(stats.chunks[0] > 400 && stats.bytes >= 400 * 8200, "{stats:?}"); + // Called off after the first band. + let stop = Cell::new(false); + let got = read_bands_with_stats(&mut Cursor::new(&bytes[..]), &index, &request, &|| stop.get(), &mut |_| stop.set(true), &mut stats); + assert_eq!(got.err(), Some(Error::Cancelled)); + assert!(stats.lines > 0 && stats.lines < 600 && stats.chunks[0] > 0, "{stats:?}"); +} + +#[test] +fn the_index_lists_the_chunks_of_the_full_resolution_level() { + use super::decode_tests::mixed_file; + use exr::math::RoundingMode; + use exr::prelude::Levels; + let sizes: Vec = exr::meta::mip_map_levels(RoundingMode::Down, Vec2(9, 7)).map(|(_, size)| size.area()).collect(); + let bytes = + tiled_levels(Levels::Mip { rounding_mode: RoundingMode::Down, level_data: sizes.iter().map(|n| FlatSamples::F32(vec![1.0; *n])).collect() }); + let index = indexed(&bytes); + let chunks: Vec = index.chunks(0).collect(); + let tiles: Vec<(usize, usize, usize, usize)> = chunks.iter().map(|c| (c.x, c.y, c.width, c.height)).collect(); + assert_eq!(tiles, [(0, 0, 4, 4), (4, 0, 4, 4), (8, 0, 1, 4), (0, 4, 4, 3), (4, 4, 4, 3), (8, 4, 1, 3)]); + assert!(chunks.iter().all(|c| c.len > 0 && c.offset > 0 && c.offset + c.len <= bytes.len() as u64)); + assert_eq!(index.chunks(1).count(), 0, "no such part"); + let (mixed, offsets) = mixed_file(true, false); + let index = indexed(&mixed); + assert_eq!(index.chunks(0).count(), 0, "a deep part"); + assert_eq!(index.chunks(1).map(|c| (c.offset as usize, c.y, c.height)).collect::>(), [(offsets[1][0], 0, 1), (offsets[1][1], 1, 1)]); +} + +#[test] +fn htj2k_compression_is_its_own_error() { + let mut bytes = file(vec![layer(None, (0, 0), (4, 4), &["R"], false, Compression::ZIP1)], (4, 4)); + let tag = b"compression\0compression\0"; + let at = bytes.windows(tag.len()).position(|w| w == tag).unwrap() + tag.len() + 4; + for code in [10u8, 11] { + bytes[at] = code; + let got = Index::build(&mut Cursor::new(&bytes[..]), &Limits::default(), &never); + assert_eq!(got.err(), Some(Error::UnsupportedCompression("HTJ2K".into())), "code {code}"); + } +} + +#[test] +fn the_display_window_may_have_its_own_pixel_limit() { + // A 16 × 16 data window (overscan) over an 8 × 8 display window. + let bytes = file(vec![layer(None, (-4, -4), (16, 16), &["R"], false, Compression::ZIP1)], (8, 8)); + let limits = Limits { max_pixels: 256, ..Limits::default() }; + let build = |display| Index::build_with_display_limit(&mut Cursor::new(&bytes[..]), &limits, display, &never); + assert!(build(64).is_ok()); + assert!(matches!(&build(63), Err(Error::LimitExceeded(m)) if m.contains("display window")), "{:?}", build(63)); + // The data windows stay bound by `max_pixels`. + let tight = Limits { max_pixels: 255, ..Limits::default() }; + let got = Index::build_with_display_limit(&mut Cursor::new(&bytes[..]), &tight, 1 << 20, &never); + assert!(matches!(&got, Err(Error::LimitExceeded(m)) if m.contains("part 0")), "{got:?}"); + // `build` holds both to `max_pixels`. + assert!(Index::build(&mut Cursor::new(&bytes[..]), &Limits { max_pixels: 63, ..Limits::default() }, &never).is_err()); + assert!(Index::build(&mut Cursor::new(&bytes[..]), &limits, &never).is_ok()); +} + +#[test] +fn rows_and_band_positions_count_from_the_display_window_s_corner() { + // Display window 12 × 9 at (10, 20); the data window 8 × 5 at (11, 22), i.e. (1, 2) inside it. + let bytes = file_at(vec![layer(None, (11, 22), (8, 5), &["Y"], false, Compression::ZIP1)], ((10, 20), (12, 9))); + let index = indexed(&bytes); + assert_eq!((index.display().x, index.display().y), (10, 20)); + let whole = oracle(&bytes, 0, -1.0)[0].clone(); + let request = Request { rows: Some(3..6), fill: &[-1.0], ..Request::new(&[(0, 0)], usize::MAX) }; + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &request, &never).unwrap(); + for row in 0..9 { + let got = &read.planes[0][row * 12..row * 12 + 12]; + if (3..6).contains(&row) { + assert_eq!(got, &whole[row * 12..row * 12 + 12], "row {row}"); + assert!(got.iter().any(|v| *v != -1.0), "row {row} has samples"); + } else { + assert_eq!(got, [-1.0; 12], "row {row}"); + } + } + let mut placed = Vec::new(); + read_bands(&mut Cursor::new(&bytes[..]), &index, &request, &never, &mut |b: Band| placed.push((b.x, b.y, b.width, b.height))).unwrap(); + assert_eq!(placed, [(1, 3, 8, 1), (1, 4, 8, 1), (1, 5, 8, 1)]); +} + +#[test] +fn bands_are_bounded_by_the_rows_they_deliver_and_planes_by_the_display_window() { + let bytes = file(vec![layer(None, (0, 0), (16, 16), &["R", "G"], false, Compression::ZIP1)], (16, 16)); + let index = indexed(&bytes); + // Rows 4..8 of two channels: 4 × 16 × 2 f32, 512 bytes; the whole planes are 2048. + let rows = |max_bytes| Request { rows: Some(4..8), ..Request::new(&[(0, 0), (0, 1)], max_bytes) }; + let mut count = 0; + read_bands(&mut Cursor::new(&bytes[..]), &index, &rows(512), &never, &mut |_| count += 1).unwrap(); + assert_eq!(count, 8); + let got = read_bands(&mut Cursor::new(&bytes[..]), &index, &rows(511), &never, &mut |_| {}); + assert!(matches!(got, Err(Error::LimitExceeded(_))), "{got:?}"); + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &rows(512), &never); + assert!(matches!(got, Err(Error::LimitExceeded(_))), "read_planes allocates the whole planes: {got:?}"); + // At level 2 rows 4..8 hold one row on the grid (row 4): 4 × 2 f32. + let reduced = |max_bytes| Request { level: 2, ..rows(max_bytes) }; + read_bands(&mut Cursor::new(&bytes[..]), &index, &reduced(32), &never, &mut |_| {}).unwrap(); + assert!(read_bands(&mut Cursor::new(&bytes[..]), &index, &reduced(31), &never, &mut |_| {}).is_err()); +} + +#[test] +fn a_header_declaring_more_chunks_than_the_bound_is_refused_before_the_tables_are_read() { + // One column of 2^24 + 1 rows, one row a chunk: the file can't hold its table, but the count + // alone is refused first. + let mut bytes = file(vec![layer(None, (0, 0), (1, 1), &["R"], false, Compression::Uncompressed)], (1, 1)); + patch_box(&mut bytes, "dataWindow", [0, 0, 0, 1 << 24]); + patch_box(&mut bytes, "displayWindow", [0, 0, 0, 1 << 24]); + let got = Index::build(&mut Cursor::new(&bytes[..]), &Limits::none(), &never); + assert!(matches!(&got, Err(Error::LimitExceeded(m)) if m.contains("chunks")), "{got:?}"); +} + +/// A source that fails with `kind` once `after` bytes have been read. +struct Failing<'a> { + inner: Cursor<&'a [u8]>, + after: u64, + kind: std::io::ErrorKind, +} + +impl Read for Failing<'_> { + fn read(&mut self, buf: &mut [u8]) -> std::io::Result { + if self.inner.position() >= self.after { + return Err(std::io::Error::new(self.kind, "the share went away")); + } + let room = (self.after - self.inner.position()) as usize; + let n = buf.len().min(room); + self.inner.read(&mut buf[..n]) + } +} + +impl Seek for Failing<'_> { + fn seek(&mut self, pos: SeekFrom) -> std::io::Result { + self.inner.seek(pos) + } +} + +#[test] +fn a_failing_source_is_an_io_error_and_a_short_file_is_malformed() { + let bytes = file(vec![layer(None, (0, 0), (8, 8), &["R"], false, Compression::ZIP1)], (8, 8)); + for after in [4u64, 40, 200] { + let mut source = Failing { inner: Cursor::new(&bytes[..]), after, kind: std::io::ErrorKind::Other }; + let got = Index::build(&mut source, &Limits::default(), &never); + assert!(matches!(got, Err(Error::Io(_))), "after {after}: {got:?}"); + let got = Index::build(&mut Cursor::new(&bytes[..after as usize]), &Limits::default(), &never); + assert!(matches!(got, Err(Error::Malformed(_))), "cut at {after}: {got:?}"); + } +} + +#[test] +fn a_read_called_off_while_workers_hold_chunks_stops() { + let bytes = file(vec![layer(None, (0, 0), (1024, 600), &["R", "G"], false, Compression::Uncompressed)], (1024, 600)); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let stop = Cell::new(false); + let mut bands = 0usize; + let request = Request { workers: Some(2), ..Request::new(&channels, usize::MAX) }; + let got = read_bands(&mut Cursor::new(&bytes[..]), &index, &request, &|| stop.get(), &mut |_| { + bands += 1; + stop.set(true); + }); + assert_eq!(got.err(), Some(Error::Cancelled)); + assert!(bands > 0 && bands < 1200, "{bands} bands"); +} + +#[test] +fn a_part_written_bottom_up_arrives_bottom_up() { + let mut part = layer(None, (0, 0), (8, 12), &["Y"], false, Compression::ZIP1); + part.encoding.line_order = LineOrder::Decreasing; + let bytes = file(vec![part], (8, 12)); + let index = indexed(&bytes); + let mut rows = Vec::new(); + let mut plane = vec![f32::NAN; 96]; + read_bands(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], usize::MAX), &never, &mut |b: Band| { + rows.push(b.y); + plane[b.y * 8..(b.y + b.height) * 8].copy_from_slice(&b.samples); + }) + .unwrap(); + assert_eq!(rows, (0..12).rev().collect::>(), "file order"); + assert_eq!(vec![plane], oracle(&bytes, 0, 0.0)); +} + +#[test] +fn a_tiled_file_with_rip_levels_is_read_from_its_largest_level_only() { + use exr::image::RipMaps; + use exr::math::RoundingMode; + use exr::prelude::Levels; + let (w, h) = (9usize, 7usize); + let sizes: Vec = exr::meta::rip_map_levels(RoundingMode::Down, Vec2(w, h)).map(|(_, size)| size.area()).collect(); + let level_count = Vec2(exr::meta::compute_level_count(RoundingMode::Down, w), exr::meta::compute_level_count(RoundingMode::Down, h)); + assert!(sizes.len() > 1); + let map_data = sizes + .iter() + .enumerate() + .map(|(level, n)| FlatSamples::F32(if level == 0 { (0..*n).map(|i| value(i, 0)).collect() } else { vec![1e9; *n] })) + .collect(); + let bytes = tiled_levels(Levels::Rip { rounding_mode: RoundingMode::Down, level_data: RipMaps { map_data, level_count } }); + let index = indexed(&bytes); + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], usize::MAX), &never).unwrap(); + assert_eq!(read.planes[0], (0..w * h).map(|i| value(i, 0)).collect::>()); + assert_eq!(read.stats.chunks[0], 6); +} + +#[test] +fn rows_an_odd_data_window_and_a_level_together_on_several_threads() { + // A 37 × 29 data window at (3, 5) in a 50 × 40 display window, one row a chunk. + let bytes = file(vec![layer(None, (3, 5), (37, 29), &["R", "G"], false, Compression::ZIP1)], (50, 40)); + let index = indexed(&bytes); + let whole = oracle(&bytes, 0, 9.0); + for level in [0u32, 1, 2] { + let stride = 1usize << level; + let request = Request { rows: Some(7..33), level, fill: &[9.0, 9.0], workers: Some(4), ..Request::new(&[(0, 1), (0, 0)], usize::MAX) }; + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &request, &never).unwrap(); + for (slot, channel) in [(0, 1), (1, 0)] { + let expected: Vec = (0..40) + .step_by(stride) + .flat_map(|y| (0..50).step_by(stride).map(move |x| (y, x))) + .map(|(y, x)| if (7..33).contains(&y) { whole[channel][y * 50 + x] } else { 9.0 }) + .collect(); + assert_eq!(read.planes[slot], expected, "level {level} slot {slot}"); + } + } +} + +#[test] +fn a_damaged_chunk_in_the_middle_ends_the_read_after_the_bands_before_it() { + // 600 uncompressed chunks of 8200 bytes (y, size, 2 × 1024 f32), the last at the file's end: + // row 400's chunk claims another row. The read spans several pieces and threads. + let mut bytes = file(vec![layer(None, (0, 0), (1024, 600), &["R", "G"], false, Compression::Uncompressed)], (1024, 600)); + let at = bytes.len() - (600 - 400) * 8200; + assert_eq!(&bytes[at..at + 4], &400i32.to_le_bytes()); + bytes[at..at + 4].copy_from_slice(&7i32.to_le_bytes()); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let mut reached = [0usize; 2]; + let request = Request { workers: Some(4), ..Request::new(&channels, usize::MAX) }; + let got = read_bands(&mut Cursor::new(&bytes[..]), &index, &request, &never, &mut |b: Band| { + assert_eq!(b.y, reached[b.slot]); + reached[b.slot] = b.y + b.height; + }); + assert!(matches!(got, Err(Error::Malformed(_))), "{got:?}"); + assert_eq!(reached, [400, 400], "every row before the damaged chunk, nothing after it"); +} + +#[test] +fn a_chunk_that_is_not_the_block_its_table_entry_stands_for_is_refused() { + // Scan lines: the entries of rows 0 and 1 swapped; reading row 0 fetches row 1's chunk. + let mut bytes = file(vec![layer(None, (0, 0), (8, 16), &["Y"], false, Compression::ZIP1)], (8, 16)); + let table = table_at(&bytes, 16); + let (a, b) = (bytes[table..table + 8].to_vec(), bytes[table + 8..table + 16].to_vec()); + bytes[table..table + 8].copy_from_slice(&b); + bytes[table + 8..table + 16].copy_from_slice(&a); + let index = indexed(&bytes); + let request = Request { rows: Some(0..1), ..Request::new(&[(0, 0)], usize::MAX) }; + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &request, &never); + assert!(matches!(got, Err(Error::Malformed(_))), "{got:?}"); + // Mip-mapped tiles: the first full-resolution tile's entry points at a smaller level's tile. + use exr::math::RoundingMode; + use exr::prelude::Levels; + let sizes: Vec = exr::meta::mip_map_levels(RoundingMode::Down, Vec2(9, 7)).map(|(_, size)| size.area()).collect(); + let mut mip = + tiled_levels(Levels::Mip { rounding_mode: RoundingMode::Down, level_data: sizes.iter().map(|n| FlatSamples::F32(vec![1.0; *n])).collect() }); + let table = table_at(&mip, 6 + sizes.len() - 1); + let smaller = mip[table + 6 * 8..table + 7 * 8].to_vec(); + mip[table..table + 8].copy_from_slice(&smaller); + let index = indexed(&mip); + let got = read_planes(&mut Cursor::new(&mip[..]), &index, &Request::new(&[(0, 0)], usize::MAX), &never); + assert!(matches!(got, Err(Error::Malformed(_))), "{got:?}"); +} + +#[test] +fn the_decoded_bytes_in_flight_stay_within_the_budget_however_well_the_file_compresses() { + // A flat colour in ZIP1 lines: each 1024-pixel line of two f32 channels compresses to a few + // dozen bytes but decodes to 8 KiB (and 8 KiB of bands), so a 256 KiB piece would hold + // thousands of them. + let (w, h) = (1024usize, 600usize); + let list = vec![AnyChannel::new("R", FlatSamples::F32(vec![0.25; w * h])), AnyChannel::new("G", FlatSamples::F32(vec![0.5; w * h]))]; + let encoding = Encoding { compression: Compression::ZIP1, blocks: Blocks::ScanLines, line_order: LineOrder::Increasing }; + let bytes = file(vec![Layer::new((w, h), LayerAttributes::default(), encoding, AnyChannels::sort(list.into()))], (w, h)); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let budget = 64 << 10; + let mut rows = 0usize; + let request = Request { workers: Some(4), ..Request::new(&channels, usize::MAX) }; + let mut sink = |b: Band| { + assert!(b.samples.iter().all(|v| *v == 0.25 || *v == 0.5)); + rows += b.height; + }; + let stats = super::seek::read_bands_within(&mut Cursor::new(&bytes[..]), &index, &request, &never, &mut sink, budget).unwrap(); + assert_eq!(rows, 2 * h); + assert!(stats.bytes < 64 << 10, "{} bytes: well compressed", stats.bytes); + assert!(stats.in_flight > 0 && stats.in_flight <= budget, "{} decoded bytes in flight", stats.in_flight); +} + +#[test] +fn cancel_is_polled_before_each_chunk_reaches_the_sink() { + // Decoded on the calling thread, the first piece's ~30 chunks are ready at once; a cancel + // the sink raises after the first chunk's two bands stops the rest. + let bytes = file(vec![layer(None, (0, 0), (1024, 600), &["R", "G"], false, Compression::Uncompressed)], (1024, 600)); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let stop = Cell::new(false); + let mut bands = 0usize; + let request = Request { workers: Some(0), ..Request::new(&channels, usize::MAX) }; + let got = read_bands(&mut Cursor::new(&bytes[..]), &index, &request, &|| stop.get(), &mut |_| { + bands += 1; + stop.set(true); + }); + assert_eq!(got.err(), Some(Error::Cancelled)); + assert_eq!(bands, 2, "one chunk (both channels), nothing after the cancel"); +} + +#[test] +fn a_chunk_offset_into_the_headers_is_outside_the_chunk_area() { + let mut bytes = file(vec![layer(None, (0, 0), (8, 16), &["Y"], false, Compression::ZIP1)], (8, 16)); + let table = table_at(&bytes, 16); + bytes[table..table + 8].copy_from_slice(&8u64.to_le_bytes()); + let index = indexed(&bytes); + assert_eq!(index.chunks(0).next().map(|c| c.len), Some(0)); + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], usize::MAX), &never); + assert!(matches!(&got, Err(Error::Malformed(m)) if m.contains("outside the chunk area")), "{got:?}"); +} + +/// A single-part scan-line DWA file of `w × h` with these half channels (a ramp each). +fn dwa_file(compression: Compression, (w, h): (usize, usize), names: &[&str], tiles: bool) -> Vec { + use exr::prelude::f16; + let list: Vec> = names + .iter() + .enumerate() + .map(|(k, n)| AnyChannel::new(*n, FlatSamples::F16((0..w * h).map(|i| f16::from_f32(((i % w) + k) as f32 / 64.0)).collect()))) + .collect(); + let blocks = if tiles { Blocks::Tiles(Vec2(16, 16)) } else { Blocks::ScanLines }; + let encoding = Encoding { compression, blocks, line_order: LineOrder::Increasing }; + file(vec![Layer::new((w, h), LayerAttributes::default(), encoding, AnyChannels::sort(list.into()))], (w, h)) +} + +/// `bytes` with DWA counter `field` (0: version … 9: DC count) of the first chunk set to `value`. +fn with_dwa_counter(bytes: &[u8], field: usize, value: u64) -> Vec { + let index = indexed(bytes); + let chunk = index.chunks(0).next().unwrap(); + let at = chunk.offset as usize; + // (y, then the payload size: compressed, so it's no raw copy of the 64 × 32 half block) + assert_ne!(i32::from_le_bytes(bytes[at + 4..at + 8].try_into().unwrap()), 64 * 32 * 2); + let mut out = bytes.to_vec(); + out[at + 8 + 8 * field..at + 16 + 8 * field].copy_from_slice(&value.to_le_bytes()); + out +} + +/// Every reader of the crate refuses `bytes` as damaged, and none aborts. +fn refused_by_every_reader(bytes: &[u8], what: &str) { + use crate::decode::{Error as DecodeError, decode_display_part, decode_part}; + let index = indexed(bytes); + let got = read_planes(&mut Cursor::new(bytes), &index, &Request::new(&[(0, 0)], usize::MAX), &never); + assert!(matches!(&got, Err(Error::Malformed(m)) if m.contains("DWA")), "seek, {what}: {got:?}"); + let got = decode_display_part(bytes, 0, &|_| true, &|_| 0.0, &Limits::default()).map(|_| ()); + assert!(matches!(&got, Err(DecodeError::Malformed(m)) if m.contains("DWA")), "decode_display_part, {what}: {got:?}"); + let got = decode_part(bytes, 0, &|_| true, &Limits::default()).map(|_| ()); + assert!(matches!(&got, Err(DecodeError::Malformed(m)) if m.contains("DWA")), "decode_part, {what}: {got:?}"); + let got = crate::stream::Decoder::new(Cursor::new(bytes), &never).and_then(|mut d| { + while d.next_band(&never)?.is_some() {} + Ok(()) + }); + assert!(matches!(&got, Err(DecodeError::Malformed(m)) if m.contains("DWA")), "stream, {what}: {got:?}"); +} + +#[test] +fn a_dwa_chunk_declaring_2_to_the_44_dc_values_is_refused_not_an_abort() { + // The case that aborted the process: DWAA 64 × 32, one half channel R, DC count 2^44. + let bytes = with_dwa_counter(&dwa_file(Compression::DWAA(None), (64, 32), &["R"], false), 9, 1 << 44); + refused_by_every_reader(&bytes, "DC count 2^44"); +} + +#[test] +fn a_dwa_chunk_just_above_the_data_window_is_checked_as_the_block_the_decoder_rounds_it_into() { + // The `exr` crate divides a scan line's offset from the data window toward zero, so a chunk + // at y = -1 (DWAA, 32 lines) or -255 (DWAB, 256 lines) becomes block 0 and is decompressed. + use crate::decode::{Error as DecodeError, decode_display_part, decode_part}; + for (compression, y) in [(Compression::DWAA(None), -1i32), (Compression::DWAA(None), -31), (Compression::DWAB(None), -255)] { + let mut bytes = with_dwa_counter(&dwa_file(compression, (64, 32), &["R"], false), 9, 1 << 40); + let at = indexed(&bytes).chunks(0).next().unwrap().offset as usize; + bytes[at..at + 4].copy_from_slice(&y.to_le_bytes()); + let got = decode_part(&bytes, 0, &|_| true, &Limits::default()).map(|_| ()); + assert!(matches!(&got, Err(DecodeError::Malformed(m)) if m.contains("DWA")), "decode_part, {compression:?} y {y}: {got:?}"); + let got = decode_display_part(&bytes, 0, &|_| true, &|_| 0.0, &Limits::default()).map(|_| ()); + assert!(matches!(&got, Err(DecodeError::Malformed(m)) if m.contains("DWA")), "decode_display_part, {compression:?} y {y}: {got:?}"); + } +} + +#[test] +fn a_dwa_chunk_the_scan_cannot_read_is_refused_not_left_to_the_decoder() { + use crate::decode::{Error as DecodeError, decode_part}; + let good = dwa_file(Compression::DWAA(None), (64, 32), &["R"], false); + let table = table_at(&good, 1); + // The entry points past the end of the file, and into the last bytes of it. + for offset in [good.len() as u64 + 100, good.len() as u64 - 6] { + let mut bytes = good.clone(); + bytes[table..table + 8].copy_from_slice(&offset.to_le_bytes()); + let got = decode_part(&bytes, 0, &|_| true, &Limits::default()).map(|_| ()); + assert!(matches!(&got, Err(DecodeError::Malformed(m)) if m.contains("DWA")), "offset {offset}: {got:?}"); + } +} + +#[test] +fn a_chunk_declaring_a_small_payload_before_padding_is_held_to_what_the_payload_can_hold() { + // A 1 × 1 PIZ file patched to 16 Mi pixels wide (a 64 MiB block) with 100 KiB of padding + // after its one chunk: the gap to the file's end could hold the block at 1024 : 1, the few + // dozen bytes the chunk declares can't. + let mut bytes = file(vec![layer(None, (0, 0), (1, 1), &["R"], false, Compression::PIZ)], (1, 1)); + patch_box(&mut bytes, "dataWindow", [0, 0, (16 << 20) - 1, 0]); + bytes.extend(std::iter::repeat_n(0u8, 100 << 10)); + let limits = Limits { max_ratio: 1024, ..Limits::none() }; + let index = Index::build(&mut Cursor::new(&bytes[..]), &limits, &never).unwrap(); + assert_eq!(index.check_blocks(), Ok(()), "the gap is enough"); + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], 1 << 30), &never); + assert!(matches!(&got, Err(Error::LimitExceeded(m)) if m.contains("can hold")), "{got:?}"); +} + +#[test] +fn every_dwa_counter_the_inflater_sizes_by_is_bounded_by_the_block() { + for compression in [Compression::DWAA(None), Compression::DWAB(None)] { + // (fields: 1 unknown uncompressed size, 6 RLE uncompressed size, 7 RLE raw size, 8 AC + // count, 9 DC count; a value just over each bound, and a huge one) + let good = dwa_file(compression, (64, 32), &["R"], false); + // The block: 64 × 32 half, 4096 bytes; 8 × 4 DCT blocks of one channel. + for (field, over) in [(1, 4097u64), (6, 8193), (7, 4097), (8, 32 * 63 + 1), (9, 33)] { + for value in [over, 1 << 44, i64::MAX as u64] { + refused_by_every_reader(&with_dwa_counter(&good, field, value), &format!("{compression:?} counter {field} = {value}")); + } + } + } +} + +#[test] +fn valid_dwa_files_pass_the_guard() { + // Odd sizes (blocks padded to 8 × 8 for the DCT), lossy and lossless channels, one-row and + // one-column parts, scan lines and tiles. + for compression in [Compression::DWAA(None), Compression::DWAB(None)] { + for (size, names, tiles) in [ + ((1, 1), &["R"][..], false), + ((9, 7), &["B", "G", "R"][..], false), + ((1, 300), &["Y", "A"][..], false), + ((300, 1), &["R", "G", "B", "A", "Z"][..], false), + ((64, 32), &["R"][..], false), + ((37, 41), &["R", "G", "B", "A"][..], true), + ] { + let bytes = dwa_file(compression, size, names, tiles); + let index = indexed(&bytes); + assert_eq!(index.check_blocks(), Ok(())); + let channels = channels_of(&index, 0); + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&channels, usize::MAX), &never); + assert_eq!(read.map(|r| r.planes).ok(), Some(oracle(&bytes, 0, 0.0)), "{compression:?} {size:?} {names:?} tiles {tiles}"); + assert!(crate::decode::decode_part(&bytes, 0, &|_| true, &Limits::default()).is_ok()); + if !tiles { + let mut stream = crate::stream::Decoder::new(Cursor::new(&bytes[..]), &never); + if let Ok(d) = stream.as_mut() { + while d.next_band(&never).unwrap().is_some() {} + } + } + } + } +} + +/// A source that panics when anything at or past `chunks` (where the chunks start) is read: a +/// read that a check should have refused fails fast instead of allocating. +#[cfg(target_pointer_width = "64")] +struct NoChunks<'a> { + inner: Cursor<&'a [u8]>, + chunks: u64, +} + +#[cfg(target_pointer_width = "64")] +impl Read for NoChunks<'_> { + fn read(&mut self, buf: &mut [u8]) -> std::io::Result { + assert!(self.inner.position() < self.chunks, "a chunk was read"); + self.inner.read(buf) + } +} + +#[cfg(target_pointer_width = "64")] +impl Seek for NoChunks<'_> { + fn seek(&mut self, pos: SeekFrom) -> std::io::Result { + self.inner.seek(pos) + } +} + +// (budgets over 4 GiB: a 64-bit usize) +#[cfg(target_pointer_width = "64")] +#[test] +fn a_tiny_chunk_declaring_a_gigabyte_block_is_refused_before_it_is_read() { + // A 1 × 1 file whose data window is patched to 2^30 - 2 pixels wide: one row of one f32 + // channel is a 4 GiB block over a chunk of a few dozen bytes. Within an app's 8 GiB budget + // the block cap allows it; the bytes can't hold it. + let limits = Limits { max_ratio: Limits::default().max_ratio, ..Limits::none() }; + for compression in [Compression::PIZ, Compression::DWAB(None), Compression::ZIP16] { + let mut bytes = file(vec![layer(None, (0, 0), (1, 1), &["R"], false, compression)], (1, 1)); + patch_box(&mut bytes, "dataWindow", [0, 0, (1 << 30) - 3, 0]); + let index = Index::build(&mut Cursor::new(&bytes[..]), &limits, &never).unwrap(); + let chunk = index.chunks(0).next().unwrap(); + assert!(chunk.len < 200 && chunk.width == (1 << 30) - 2, "{chunk:?}"); + let got = index.check_blocks(); + assert!(matches!(&got, Err(Error::LimitExceeded(m)) if m.contains("can hold")), "{compression:?}: {got:?}"); + let mut source = NoChunks { inner: Cursor::new(&bytes[..]), chunks: chunk.offset }; + let got = read_planes(&mut source, &index, &Request::new(&[(0, 0)], 8 << 30), &never); + assert!(matches!(&got, Err(Error::LimitExceeded(m)) if m.contains("can hold")), "{compression:?}: {got:?}"); + } +} + +#[test] +fn black_frames_that_compress_extremely_well_still_read() { + // 4096 × 256 × 4 half channels of zero in DWAB (one 8 MiB block) and of f32 in ZIP16. + use exr::prelude::f16; + let (w, h) = (4096usize, 256usize); + for (compression, half) in [(Compression::DWAB(None), true), (Compression::ZIP16, false)] { + let list: Vec> = ["R", "G", "B", "A"] + .iter() + .map(|n| AnyChannel::new(*n, if half { FlatSamples::F16(vec![f16::ZERO; w * h]) } else { FlatSamples::F32(vec![0.0; w * h]) })) + .collect(); + let encoding = Encoding { compression, blocks: Blocks::ScanLines, line_order: LineOrder::Increasing }; + let bytes = file(vec![Layer::new((w, h), LayerAttributes::default(), encoding, AnyChannels::sort(list.into()))], (w, h)); + let index = indexed(&bytes); + let smallest = index.chunks(0).map(|c| c.len).min().unwrap(); + assert_eq!(index.check_blocks(), Ok(()), "{compression:?}, chunks from {smallest} bytes"); + let channels = channels_of(&index, 0); + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&channels, usize::MAX), &never).unwrap(); + assert!(read.planes.iter().all(|p| p.len() == w * h && p.iter().all(|v| *v == 0.0)), "{compression:?}"); + } +} + +#[test] +fn the_ratio_bound_allows_a_mebibyte_more_and_four_times_as_much_for_dwa() { + use exr::prelude::f16; + let build = |bytes: &[u8], max_ratio| Index::build(&mut Cursor::new(bytes), &Limits { max_ratio, ..Limits::default() }, &never).unwrap(); + // A black ZIP16 block of 512 × 16 f32 RGBA is 128 KiB over a few hundred bytes: refused at + // one byte per byte but for the 1 MiB every chunk is allowed besides. + let zip = file(vec![layer(None, (0, 0), (512, 16), &["R", "G", "B", "A"], false, Compression::ZIP16)], (512, 16)); + let list: Vec> = + ["R", "G", "B", "A"].iter().map(|n| AnyChannel::new(*n, FlatSamples::F32(vec![0.0; 512 * 16]))).collect(); + let encoding = Encoding { compression: Compression::ZIP16, blocks: Blocks::ScanLines, line_order: LineOrder::Increasing }; + let black = file(vec![Layer::new((512, 16), LayerAttributes::default(), encoding, AnyChannels::sort(list.into()))], (512, 16)); + for bytes in [&zip, &black] { + let index = build(bytes, 1); + assert!(index.chunks(0).all(|c| c.len < 128 << 10)); + assert_eq!(index.check_blocks(), Ok(())); + } + // A black DWAB block of 4096 × 256 half RGBA (8 MiB): with a ratio that lets its bytes hold + // between a quarter of the block and the block (less the 1 MiB), only the fourfold DWA + // allowance admits it. + let list: Vec> = + ["R", "G", "B", "A"].iter().map(|n| AnyChannel::new(*n, FlatSamples::F16(vec![f16::ZERO; 4096 * 256]))).collect(); + let encoding = Encoding { compression: Compression::DWAB(None), blocks: Blocks::ScanLines, line_order: LineOrder::Increasing }; + let dwab = file(vec![Layer::new((4096, 256), LayerAttributes::default(), encoding, AnyChannels::sort(list.into()))], (4096, 256)); + let len = indexed(&dwab).chunks(0).next().unwrap().len; + let ratio = (5u64 << 20) / len; // len × ratio ≈ 5 MiB: 8 MiB > that + 1 MiB, but ≤ 4 × that + 1 MiB + let index = build(&dwab, ratio); + assert_eq!(index.check_blocks(), Ok(()), "{len}-byte chunk, ratio {ratio}"); + assert!(matches!(build(&dwab, ratio / 8).check_blocks(), Err(Error::LimitExceeded(_)))); +} + +#[cfg(target_pointer_width = "64")] +#[test] +fn memory_the_system_cannot_give_is_out_of_memory_not_a_limit() { + // A display window of (2^30 - 2)^2 pixels: one f32 plane is 4 EiB, which no system maps, so + // the reservation fails at once (nothing is touched). + let mut bytes = file(vec![layer(None, (0, 0), (1, 1), &["R"], false, Compression::ZIP1)], (1, 1)); + patch_box(&mut bytes, "displayWindow", [0, 0, (1 << 30) - 3, (1 << 30) - 3]); + let index = Index::build(&mut Cursor::new(&bytes[..]), &Limits::none(), &never).unwrap(); + let got = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request::new(&[(0, 0)], usize::MAX), &never); + assert!(matches!(got, Err(Error::OutOfMemory(_))), "{got:?}"); +} + +#[test] +#[allow(clippy::reversed_empty_ranges)] // (reversed ranges are what is tested) +fn empty_reversed_and_extreme_row_ranges_read_without_overflow() { + // (alignment to a level's grid near the ends of i64 overflowed before the rows were clamped) + let bytes = file(vec![layer(None, (0, 0), (9, 7), &["R"], false, Compression::ZIP1)], (9, 7)); + let index = indexed(&bytes); + let whole = oracle(&bytes, 0, 0.0)[0].clone(); + for level in 0..=16u32 { + for rows in [i64::MAX..i64::MAX, i64::MIN..i64::MIN, i64::MAX - 1..i64::MAX, 5..2, i64::MAX..i64::MIN, -3..-1, 7..9] { + let request = Request { rows: Some(rows.clone()), level, ..Request::new(&[(0, 0)], usize::MAX) }; + let mut bands = 0; + read_bands(&mut Cursor::new(&bytes[..]), &index, &request, &never, &mut |_| bands += 1).unwrap(); + assert_eq!(bands, 0, "{rows:?} at level {level} holds no row"); + assert_eq!(index.estimate(&request).unwrap().chunks, 0); + } + // Everything, from one end of i64 to the other. + let request = Request { rows: Some(i64::MIN..i64::MAX), level, ..Request::new(&[(0, 0)], usize::MAX) }; + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &request, &never).unwrap(); + let stride = 1usize << level; + let expected: Vec = + (0..7).step_by(stride).flat_map(|y| (0..9).step_by(stride).map(move |x| (y, x))).map(|(y, x)| whole[y * 9 + x]).collect(); + assert_eq!(read.planes[0], expected, "level {level}"); + } +} + +#[test] +fn a_sink_can_stop_the_read_with_its_own_error() { + // 600 chunks on 4 threads: the sink refuses its third band. Nothing reaches it after that, the + // read returns (no hang) with the sink's error unchanged, and the counts say how far it got. + let bytes = file(vec![layer(None, (0, 0), (1024, 600), &["R", "G"], false, Compression::Uncompressed)], (1024, 600)); + let index = indexed(&bytes); + let channels = channels_of(&index, 0); + let request = Request { workers: Some(4), ..Request::new(&channels, usize::MAX) }; + let mut calls = 0usize; + let mut stats = Stats::default(); + let got = read_bands_try( + &mut Cursor::new(&bytes[..]), + &index, + &request, + &never, + &mut |_: Band| { + calls += 1; + if calls >= 3 { Err("the tile store is full") } else { Ok(()) } + }, + &mut stats, + ); + assert_eq!(got, Err(Stop::Sink("the tile store is full"))); + assert_eq!(calls, 3, "no band after the sink's error"); + assert!(stats.lines >= 1 && stats.lines < 600 && stats.bytes > 0, "{stats:?}"); + // A sink that never fails reads everything, as `read_bands` does. + let mut bands = 0usize; + let mut sink = |_: Band| -> std::result::Result<(), ()> { + bands += 1; + Ok(()) + }; + read_bands_try(&mut Cursor::new(&bytes[..]), &index, &request, &never, &mut sink, &mut stats).unwrap(); + assert_eq!((bands, stats.lines), (1200, 600)); + // The read's own errors come back as such. + let mut damaged = bytes.clone(); + let at = damaged.len() - 200 * 8200; + damaged[at..at + 4].copy_from_slice(&7i32.to_le_bytes()); + let index = indexed(&damaged); + let got = read_bands_try(&mut Cursor::new(&damaged[..]), &index, &request, &never, &mut |_| Ok::<(), ()>(()), &mut stats); + assert!(matches!(got, Err(Stop::Read(Error::Malformed(_)))), "{got:?}"); +} + +/// The planes of `bands` (grouped or not) for `slots` slots of `w × h`, de-interleaved. +fn planes_of(bands: &[Band], slots: usize, (w, h): (usize, usize)) -> Vec> { + let mut planes = vec![vec![-1e30; w * h]; slots]; + for b in bands { + assert_eq!(b.samples.len(), b.width * b.height * b.values_per_pixel); + for r in 0..b.height { + for c in 0..b.width { + for k in 0..b.values_per_pixel { + planes[b.slot + k][(b.y + r) * w + b.x + c] = b.samples[(r * b.width + c) * b.values_per_pixel + k]; + } + } + } + } + planes +} + +#[test] +fn grouped_slots_arrive_interleaved_as_one_band_per_block() { + for tiles in [false, true] { + let bytes = file(vec![layer(None, (0, 0), (13, 11), &["R", "G", "B", "A", "Z"], tiles, Compression::ZIP1)], (13, 11)); + let index = indexed(&bytes); + // Stored A B G R Z: ask for R G B A as a group, Z alone, and G again in a group of one. + let names: Vec<&str> = index.parts()[0].channels.iter().map(|c| c.name.as_str()).collect(); + let at = |n: &str| (0, names.iter().position(|m| *m == n).unwrap()); + let channels = [at("R"), at("G"), at("B"), at("A"), at("Z"), at("G")]; + for (rows, level) in [(None, 0u32), (Some(3..9), 0), (None, 1)] { + let base = Request { rows: rows.clone(), level, ..Request::new(&channels, usize::MAX) }; + let mut single = Vec::new(); + read_bands(&mut Cursor::new(&bytes[..]), &index, &base, &never, &mut |b| single.push(b)).unwrap(); + let groups = [0..4, 5..6]; + let mut grouped = Vec::new(); + read_bands(&mut Cursor::new(&bytes[..]), &index, &Request { groups: &groups, ..base.clone() }, &never, &mut |b| grouped.push(b)).unwrap(); + assert!(single.iter().all(|b| b.values_per_pixel == 1)); + assert!(grouped.iter().all(|b| b.values_per_pixel == if b.slot == 0 { 4 } else { 1 }), "{tiles} {rows:?} {level}"); + assert_eq!(grouped.iter().filter(|b| b.slot == 0).count(), single.iter().filter(|b| b.slot == 0).count(), "one band per block"); + let size = level_size((13, 11), level); + assert_eq!(planes_of(&grouped, 6, size), planes_of(&single, 6, size), "tiles {tiles} rows {rows:?} level {level}"); + // `read_planes` ignores groups. + let with = read_planes(&mut Cursor::new(&bytes[..]), &index, &Request { groups: &groups, ..base.clone() }, &never).unwrap(); + assert_eq!(with, read_planes(&mut Cursor::new(&bytes[..]), &index, &base, &never).unwrap()); + } + } +} + +#[test] +fn groups_must_be_slots_of_one_part_each_in_one_group() { + let bytes = file( + vec![ + layer(Some("a"), (0, 0), (8, 8), &["R", "G"], false, Compression::ZIP1), + layer(Some("b"), (0, 0), (8, 8), &["Z"], false, Compression::ZIP1), + ], + (8, 8), + ); + let index = indexed(&bytes); + let channels = [(0, 0), (0, 1), (1, 0)]; + let read = |groups: &[std::ops::Range]| { + read_bands(&mut Cursor::new(&bytes[..]), &index, &Request { groups, ..Request::new(&channels, usize::MAX) }, &never, &mut |_| {}) + }; + assert!(matches!(read(&[1..3]), Err(Error::Unsupported(m)) if m.contains("spans parts"))); + for bad in [&[0..2, 1..2][..], &[2..4], &[1..1]] { + assert!(matches!(read(bad), Err(Error::Malformed(_))), "{bad:?}"); + } + assert!(read(&[0..2]).is_ok()); +} + +#[test] +fn the_estimate_covers_what_the_read_does() { + // A flat colour in ZIP16 (decodes to far more than it reads), lines of a ramp, and tiles. + let (w, h) = (1024usize, 600usize); + let list = vec![AnyChannel::new("R", FlatSamples::F32(vec![0.25; w * h])), AnyChannel::new("G", FlatSamples::F32(vec![0.5; w * h]))]; + let encoding = Encoding { compression: Compression::ZIP16, blocks: Blocks::ScanLines, line_order: LineOrder::Increasing }; + let flat = file(vec![Layer::new((w, h), LayerAttributes::default(), encoding, AnyChannels::sort(list.into()))], (w, h)); + let ramp = file(vec![layer(None, (0, 0), (1024, 600), &["R", "G"], false, Compression::Uncompressed)], (1024, 600)); + let tiled = file(vec![layer(None, (0, 0), (300, 200), &["R", "G", "B"], true, Compression::PIZ)], (300, 200)); + for bytes in [&flat, &ramp, &tiled] { + let index = indexed(bytes); + let channels = channels_of(&index, 0); + for (rows, level, workers) in [(None, 0u32, None), (Some(50..120), 0, Some(4)), (None, 1, Some(0))] { + let request = Request { rows: rows.clone(), level, workers, ..Request::new(&channels, usize::MAX) }; + let estimate = index.estimate(&request).unwrap(); + let read = read_planes(&mut Cursor::new(&bytes[..]), &index, &request, &never).unwrap(); + let what = format!("{rows:?} level {level}: {estimate:?} {:?}", read.stats); + assert_eq!(estimate.chunks, read.stats.chunks.iter().sum::(), "{what}"); + assert_eq!(estimate.compressed_bytes, read.stats.bytes, "{what}"); + assert!(estimate.working_bytes >= read.stats.in_flight, "{what}"); + let (ow, oh) = level_size((index.display().width as usize, index.display().height as usize), level); + assert_eq!(estimate.planes_bytes, (ow * oh * 4 * channels.len()) as u64, "{what}"); + // Measured from what is decoded: the largest chunk's block and bands (decoded, and + // as much again for scratch) fit in the working bytes. + let largest = decoded_per_chunk(bytes, &index, &request).into_iter().max().unwrap_or(0); + assert!(estimate.working_bytes >= 2 * largest, "{what}, largest chunk {largest}"); + } + } + // It refuses what the read refuses. + let index = indexed(&ramp); + assert!(matches!(index.estimate(&Request::new(&[(0, 0)], 1024)), Err(Error::LimitExceeded(_)))); + assert!(matches!(index.estimate(&Request::new(&[(0, 9)], usize::MAX)), Err(Error::Malformed(_)))); +} + +/// Per chunk of a read of part 0 of `bytes`: its decompressed block's bytes (all of the part's +/// channels over the chunk's pixels) plus the bytes of the bands it gave, as decoded. +fn decoded_per_chunk(bytes: &[u8], index: &Index, request: &Request) -> Vec { + let pixel_bytes: u64 = index.parts()[0].channels.iter().map(|c| if c.sample == crate::decode::SampleType::F16 { 2 } else { 4 }).sum(); + let mut bands_of: std::collections::BTreeMap = std::collections::BTreeMap::new(); + read_bands(&mut Cursor::new(bytes), index, request, &never, &mut |b: Band| { + assert_eq!(b.samples.len(), b.width * b.height * b.values_per_pixel, "exactly sized"); + assert_eq!(b.samples.capacity(), b.samples.len(), "no slack"); + *bands_of.entry(b.chunk).or_default() += 4 * b.samples.len() as u64; + }) + .unwrap(); + // The chunks a read fetches, in file order, as the bands number them. + let mut chunks: Vec = index.chunks(0).collect(); + chunks.sort_by_key(|c| c.offset); + let estimate = index.estimate(request).unwrap(); + let needed: Vec = chunks + .into_iter() + .filter(|c| { + let rows = request.rows.clone().unwrap_or(0..i64::MAX); + let stride = 1i64 << request.level; + (c.y as i64..(c.y + c.height) as i64).any(|r| rows.contains(&r) && r % stride == 0) + }) + .collect(); + assert_eq!(needed.len(), estimate.chunks); + needed.iter().enumerate().map(|(i, c)| (c.width * c.height) as u64 * pixel_bytes + bands_of.get(&i).copied().unwrap_or(0)).collect() +} + +#[test] +fn a_grouped_read_with_duplicates_keeps_one_chunk_in_flight_at_its_decoded_size() { + // 1024 × 64 RGBA f32 in ZIP16: 16-row blocks of 256 KiB. R, G, B, A and R again as one group: + // each block's band is 16 × 1024 × 5 values (320 KiB), so a chunk is 576 KiB decoded, over + // a 64 KiB budget: one at a time. + let bytes = file(vec![layer(None, (0, 0), (1024, 64), &["R", "G", "B", "A"], false, Compression::ZIP16)], (1024, 64)); + let index = indexed(&bytes); + let names: Vec<&str> = index.parts()[0].channels.iter().map(|c| c.name.as_str()).collect(); + let at = |n: &str| (0, names.iter().position(|m| *m == n).unwrap()); + let channels = [at("R"), at("G"), at("B"), at("A"), at("R")]; + let groups = [0..5]; + let request = Request { groups: &groups, workers: Some(4), ..Request::new(&channels, usize::MAX) }; + let decoded = decoded_per_chunk(&bytes, &index, &request); + assert_eq!(decoded, vec![(256 + 320) << 10; 4], "block and band of each chunk, as decoded"); + let budget = 64 << 10; + let mut bands = Vec::new(); + let stats = super::seek::read_bands_within(&mut Cursor::new(&bytes[..]), &index, &request, &never, &mut |b| bands.push(b), budget).unwrap(); + assert_eq!(stats.in_flight, (256 + 320) << 10, "one chunk at a time, counted at its decoded size"); + let estimate = super::seek::estimate_within(&index, &request, budget).unwrap(); + assert!(estimate.working_bytes >= 2 * ((256 + 320) << 10), "{estimate:?}"); + // The interleaved values, duplicates included, are those of per-channel reads. + let mut single = Vec::new(); + read_bands(&mut Cursor::new(&bytes[..]), &index, &Request::new(&channels, usize::MAX), &never, &mut |b| single.push(b)).unwrap(); + assert_eq!(planes_of(&bands, 5, (1024, 64)), planes_of(&single, 5, (1024, 64))); +} + +#[test] +fn bands_say_which_chunk_they_came_from_for_progress() { + // Tiles of 4 × 4 over 9 × 7 (six chunks), and one-row chunks read at level 2 over some rows. + let tiled = file(vec![layer(None, (0, 0), (9, 7), &["R", "G"], true, Compression::ZIP1)], (9, 7)); + let lines = file(vec![layer(None, (0, 0), (8, 16), &["Y"], false, Compression::ZIP1)], (8, 16)); + for (bytes, request) in [ + (&tiled, Request::new(&[(0, 0), (0, 1)], usize::MAX)), + (&lines, Request { rows: Some(3..14), level: 2, workers: Some(2), ..Request::new(&[(0, 0)], usize::MAX) }), + ] { + let index = indexed(bytes); + let estimate = index.estimate(&request).unwrap(); + let mut seen = Vec::new(); + read_bands(&mut Cursor::new(&bytes[..]), &index, &request, &never, &mut |b| seen.push(b.chunk)).unwrap(); + assert!(seen.windows(2).all(|w| w[0] <= w[1]), "in order: {seen:?}"); + seen.dedup(); + assert_eq!(seen, (0..estimate.chunks).collect::>(), "every chunk, numbered as the estimate counts"); + } +} + +#[test] +fn a_stop_s_source_is_the_read_error() { + use std::error::Error as _; + let read: Stop = Stop::Read(Error::Cancelled); + assert_eq!(read.source().map(|e| e.to_string()), Some(Error::Cancelled.to_string())); + assert!(Stop::Sink("full".to_string()).source().is_none()); +} diff --git a/crates/exr/src/stream.rs b/crates/exr/src/stream.rs index 8e69e534e..c3d942e94 100644 --- a/crates/exr/src/stream.rs +++ b/crates/exr/src/stream.rs @@ -262,6 +262,9 @@ impl Decoder { } self.source.read_exact(bytes).map_err(invalid)?; } + // (a DWA chunk's counters can make the crate allocate terabytes: see `crate::dwa_guard`) + let lines = self.rows.min((self.info.height as usize).saturating_sub(row as usize)); + crate::dwa_guard::check_payload(header, (self.info.width as usize, lines), &packed).map_err(invalid)?; let chunk = Chunk { layer_index: 0, compressed_block: CompressedBlock::ScanLine(CompressedScanLineBlock { y_coordinate: y, compressed_pixels_le: packed }), From 8c3cd06633782a08bc019b76b396370a157c06e5 Mon Sep 17 00:00:00 2001 From: mtlcl410 <2368091+mtlcl410@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:29:35 +0800 Subject: [PATCH 08/64] craft-pdf: an object nested past the depth limit is refused where it passes it (cos, content) (#1952) --- crates/pdf/src/cos/content.rs | 7 +++--- crates/pdf/src/cos/content/tests.rs | 23 +++++++++++++++++ crates/pdf/src/cos/parser.rs | 38 ++++++++++++++++++++++++++--- 3 files changed, 62 insertions(+), 6 deletions(-) diff --git a/crates/pdf/src/cos/content.rs b/crates/pdf/src/cos/content.rs index d91552553..f31c27359 100644 --- a/crates/pdf/src/cos/content.rs +++ b/crates/pdf/src/cos/content.rs @@ -220,9 +220,10 @@ impl Iterator for Ops<'_> { #[cfg(test)] tests::RESCANNED.with(|c| c.set(c.get() + read)); let number = matches!(b, b'+' | b'-' | b'.') || b.is_ascii_digit(); - if number && read > MAX_RETRIED_TOKEN { - // A long unreadable number is skipped whole: retrying from each of its - // bytes would read the rest of it again every time. + if (number && read > MAX_RETRIED_TOKEN) || (lx.too_deep() && read > 0) { + // A long unreadable number, or an operand nested deeper than the + // parser follows, is skipped whole: retrying from each of its bytes + // would read the rest of it again every time. *skipped += read; } else { // Skip the offending byte and carry on. diff --git a/crates/pdf/src/cos/content/tests.rs b/crates/pdf/src/cos/content/tests.rs index 1a6a14851..4076370cd 100644 --- a/crates/pdf/src/cos/content/tests.rs +++ b/crates/pdf/src/cos/content/tests.rs @@ -101,6 +101,29 @@ fn a_lone_minus_is_read_as_zero() { } } +#[test] +fn a_long_run_of_unclosed_brackets_is_read_once() { + // Every `[` opens an array nested inside the one before, so none of them parses: each is + // refused once it passes the depth limit, not after reading to the end of the stream. + for open in ["[", "<<"] { + let n = 100_000; + let src = format!("{} 1 0 0 1 0 0 cm", open.repeat(n)); + RESCANNED.with(|c| c.set(0)); + let p = parse(src.as_bytes()); + let rescanned = RESCANNED.with(|c| c.get()); + assert!(rescanned <= 2 * src.len(), "{rescanned} bytes read again for {open} x {n}"); + assert!(p.skipped >= n, "{} skipped", p.skipped); + assert_eq!(p.ops.last().map(|o| o.op.as_slice()), Some(&b"cm"[..]), "{open}"); + } + // A stray `[` before a whole stream of operators still loses only itself. + let p = parse(b"[ 1 0 0 1 0 0 cm 0 0 m"); + assert_eq!(p.ops.last().map(|o| o.op.as_slice()), Some(&b"m"[..])); + // An array nested within the limit is still one operand. + let deep = format!("{}{} TJ", "[".repeat(100), "]".repeat(100)); + let p = parse(deep.as_bytes()); + assert_eq!((p.ops.len(), p.skipped), (1, 0)); +} + #[test] fn operators_keep_operands_and_spans() { let src = b"q 1 0 0 1 72 720 cm BT /F1 12 Tf (Hello \\(world\\)) Tj [(A) -120 (B)] TJ ET Q"; diff --git a/crates/pdf/src/cos/parser.rs b/crates/pdf/src/cos/parser.rs index 763a5e514..94e7f5b0b 100644 --- a/crates/pdf/src/cos/parser.rs +++ b/crates/pdf/src/cos/parser.rs @@ -33,11 +33,13 @@ pub struct Lexer<'a> { pub pos: usize, /// Objects built by the current top-level [`Lexer::object`] call. nodes: usize, + /// Whether the current top-level [`Lexer::object`] call reached [`MAX_DEPTH`]. + too_deep: bool, } impl<'a> Lexer<'a> { pub fn new(data: &'a [u8], pos: usize) -> Self { - Self { data, pos: pos.min(data.len()), nodes: 0 } + Self { data, pos: pos.min(data.len()), nodes: 0, too_deep: false } } fn peek(&self) -> Option { @@ -90,6 +92,7 @@ impl<'a> Lexer<'a> { /// Parse one direct object. References `N G R` are recognised. pub fn object(&mut self) -> Result { self.nodes = 0; + self.too_deep = false; self.object_depth(0) } @@ -97,8 +100,16 @@ impl<'a> Lexer<'a> { self.nodes > MAX_NODES } + /// Whether the last [`Lexer::object`] call failed because the object nests deeper than the + /// parser follows. Such an object is refused as soon as it passes the limit, not skipped byte + /// by byte as junk, so reading it costs at most the limit's worth of bytes. + pub fn too_deep(&self) -> bool { + self.too_deep + } + fn object_depth(&mut self, depth: usize) -> Result { if depth > MAX_DEPTH { + self.too_deep = true; return Err(self.err("nesting too deep")); } self.nodes = self.nodes.saturating_add(1); @@ -139,7 +150,7 @@ impl<'a> Lexer<'a> { let before = self.pos; match self.object_depth(depth + 1) { Ok(o) => items.push(o), - Err(e) if self.over_budget() => return Err(e), + Err(e) if self.over_budget() || self.too_deep => return Err(e), // Tolerate junk inside arrays by skipping one byte. Err(_) if self.pos == before => self.pos += 1, Err(e) => return Err(e), @@ -297,10 +308,15 @@ impl<'a> Lexer<'a> { Some(_) => { // Tolerate garbage between entries (seen in damaged files): skip a token. let before = self.pos; - let _ = self.object_depth(depth + 1); + let skipped = self.object_depth(depth + 1); if self.over_budget() { return Err(self.err("object too large")); } + if let Err(e) = skipped + && self.too_deep + { + return Err(e); + } if self.pos == before { self.pos += 1; } @@ -859,6 +875,22 @@ mod tests { assert!(Lexer::new(deep.as_bytes(), 0).object().is_err()); } + #[test] + fn an_object_nested_past_the_limit_is_refused_where_it_passes_it() { + // Not skipped byte by byte as junk to the end of the data: the bytes after it are unread. + for (open, width) in [("[", 1), ("<<", 2), ("<< /A [", 7)] { + let deep = open.repeat(10_000); + let mut lx = Lexer::new(deep.as_bytes(), 0); + assert!(lx.object().is_err()); + assert!(lx.too_deep(), "{open}"); + assert!(lx.pos <= (MAX_DEPTH + 2) * width, "{open}: read to {}", lx.pos); + } + // A new object starts with the flag clear. + let mut lx = Lexer::new(b"[[1]]", 0); + assert!(lx.object().is_ok()); + assert!(!lx.too_deep()); + } + #[test] fn one_object_has_a_node_budget() { // A wide array (from a tiny compressed object stream) must not grow without bound. From 81092ab15a8f7f634a8e8c9d261b3e261d8e3701 Mon Sep 17 00:00:00 2001 From: keithcsqueensu <92232107+keithcsqueensu@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:29:39 -0500 Subject: [PATCH 09/64] rtf: name the writing application in the full writer's generator group (#1950) --- crates/rtf/src/doc.rs | 2 +- crates/rtf/src/doc/export.rs | 26 ++++++++++++++++++++++---- crates/rtf/src/doc/tests.rs | 20 ++++++++++++++++++++ 3 files changed, 43 insertions(+), 5 deletions(-) diff --git a/crates/rtf/src/doc.rs b/crates/rtf/src/doc.rs index f87e13d76..77254151f 100644 --- a/crates/rtf/src/doc.rs +++ b/crates/rtf/src/doc.rs @@ -46,9 +46,9 @@ mod text; mod word; pub use date::{dttm_to_iso, iso_to_dttm}; +pub use export::{GENERATOR, esc, export, export_with_generator}; #[cfg(test)] use export::{Tables, Writer}; -pub use export::{esc, export}; pub use parse::{import, parse}; use reader::Reader; #[cfg(test)] diff --git a/crates/rtf/src/doc/export.rs b/crates/rtf/src/doc/export.rs index 0cd34498c..b66779c2b 100644 --- a/crates/rtf/src/doc/export.rs +++ b/crates/rtf/src/doc/export.rs @@ -848,8 +848,21 @@ fn level_def(ordered: bool, l: usize) -> String { } } -/// RTF text of a document. +/// The application [`export`] names in the `\generator` group. +pub const GENERATOR: &str = "WordCraft"; + +/// Longest application name [`export_with_generator`] writes, characters. +const MAX_GENERATOR: usize = 255; + +/// RTF text of a document, naming [`GENERATOR`] as the application that wrote it. pub fn export(doc: &Document) -> String { + export_with_generator(doc, GENERATOR) +} + +/// [`export`], naming `generator` as the application that wrote it (`{\*\generator …;}`), for an +/// app that embeds the writer under its own name. Control characters are dropped and the name is +/// cut at [`MAX_GENERATOR`] characters; a blank name leaves the group out. +pub fn export_with_generator(doc: &Document, generator: &str) -> String { let (marked, marks) = match mark_doc(doc) { Some((d, m)) => (Some(d), m), None => (None, Vec::new()), @@ -868,10 +881,10 @@ pub fn export(doc: &Document) -> String { w.sections = secs; } w.blocks(&flow.blocks, false, "\\par", &mut body, 0); - export_with(&flow.meta, &w, &body, &doc.last_section) + export_with(&flow.meta, &w, &body, &doc.last_section, generator) } -fn export_with(m: &Meta, w: &Writer, body: &str, sec: &craft_wordmodel::SectionProps) -> String { +fn export_with(m: &Meta, w: &Writer, body: &str, sec: &craft_wordmodel::SectionProps, generator: &str) -> String { let mut out = String::from("{\\rtf1\\ansi\\ansicpg1252\\deff0\\deflang1033\\uc1\n{\\fonttbl"); for (i, f) in w.t.fonts.items.iter().enumerate() { let fam = if model::is_mono(f) { "\\fmodern" } else { "\\fswiss" }; @@ -881,7 +894,12 @@ fn export_with(m: &Meta, w: &Writer, body: &str, sec: &craft_wordmodel::SectionP for c in &w.t.colors.items { out.push_str(&format!("\\red{}\\green{}\\blue{};", c.0, c.1, c.2)); } - out.push_str("}\n{\\*\\generator WordCraft;}\n{\\stylesheet{\\s0\\snext0 Normal;}"); + out.push('}'); + let name: String = generator.chars().filter(|c| !c.is_control()).take(MAX_GENERATOR).collect(); + if !name.trim().is_empty() { + out.push_str(&format!("\n{{\\*\\generator {};}}", esc_font(name.trim()))); + } + out.push_str("\n{\\stylesheet{\\s0\\snext0 Normal;}"); for n in 1..=6u32 { let sz = HEAD_SIZES.get(n as usize - 1).copied().unwrap_or(12.0); out.push_str(&format!("{{\\s{n}\\sbasedon0\\snext0\\outlinelevel{}\\keepn\\b\\fs{} heading {n};}}", n - 1, (sz * 2.0) as i32)); diff --git a/crates/rtf/src/doc/tests.rs b/crates/rtf/src/doc/tests.rs index fddd198da..e92f18c77 100644 --- a/crates/rtf/src/doc/tests.rs +++ b/crates/rtf/src/doc/tests.rs @@ -2141,3 +2141,23 @@ fn alignment_survives_an_export_import_round_trip() { // The export writes the alignment before the direction, which Word reads as logical start/end. assert!(out.contains("\\qr\\rtlpar"), "{out}"); } + +/// `export` names WordCraft as the writer; an app embedding the writer names itself, escaped as +/// a font name is (a `;` would end the group's text early), and a blank name leaves the group out. +#[test] +fn the_generator_names_the_writing_application() { + let doc = craft_wordmodel::Document::from_text("Hello"); + assert!(export(&doc).contains(r"{\*\generator WordCraft;}")); + let pdf = export_with_generator(&doc, "PdfCraft 1.2"); + assert!(pdf.contains(r"{\*\generator PdfCraft 1.2;}") && !pdf.contains("WordCraft"), "{pdf}"); + let odd = export_with_generator(&doc, "A;B}\u{1}C\\"); + assert!(odd.contains(r"{\*\generator A\'3bB\}C\\;}"), "{odd}"); + for blank in ["", " ", "\u{1}"] { + assert!(!export_with_generator(&doc, blank).contains("generator"), "{blank:?}"); + } + let long = export_with_generator(&doc, &"x".repeat(1000)); + assert!(long.contains(&format!(r"{{\*\generator {};}}", "x".repeat(255))), "cut at 255 characters"); + // Whatever the name, the text reads back. + let back = parse(odd.as_bytes()).expect("parses"); + assert_eq!(texts(&back), ["Normal:Hello"]); +} From 738bf6fafe4804f77b607d5e64d0f4cb8b6f9cb0 Mon Sep 17 00:00:00 2001 From: keithcsqueensu <92232107+keithcsqueensu@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:29:43 -0500 Subject: [PATCH 10/64] docx: write a font table naming the fonts a document uses (#1948) --- crates/docx/src/write.rs | 1 + crates/docx/src/write/embed.rs | 11 +- crates/docx/src/write/font_table.rs | 98 ++++++++++++++++ crates/docx/src/write/parts.rs | 9 +- .../tests/it/content_control_save_cost.rs | 2 + crates/docx/tests/it/font_table.rs | 106 ++++++++++++++++++ crates/docx/tests/it/main.rs | 1 + crates/docx/tests/it/roundtrip.rs | 17 ++- crates/flow/src/from_doc.rs | 6 +- crates/odf/src/text/package.rs | 28 +---- crates/wordmodel/src/font_kind.rs | 91 +++++++++++++++ crates/wordmodel/src/lib.rs | 1 + 12 files changed, 332 insertions(+), 39 deletions(-) create mode 100644 crates/docx/src/write/font_table.rs create mode 100644 crates/docx/tests/it/font_table.rs create mode 100644 crates/wordmodel/src/font_kind.rs diff --git a/crates/docx/src/write.rs b/crates/docx/src/write.rs index 4ba486a6c..3153534f7 100644 --- a/crates/docx/src/write.rs +++ b/crates/docx/src/write.rs @@ -2,6 +2,7 @@ mod bidi; mod embed; +mod font_table; mod glossary; mod settings_merge; pub(crate) use settings_merge::has_unowned as settings_has_unowned; diff --git a/crates/docx/src/write/embed.rs b/crates/docx/src/write/embed.rs index 7673a6f26..939d2a2d7 100644 --- a/crates/docx/src/write/embed.rs +++ b/crates/docx/src/write/embed.rs @@ -102,12 +102,13 @@ impl<'d> EmbedWriter<'d> { } /// Write the font table kept from a file, with the fonts it embeds, relating it from `rels`. - pub fn font_table(&mut self, rels: &mut PartRels) { + /// Whether there was one to write. + pub fn font_table(&mut self, rels: &mut PartRels) -> bool { let mut written = Vec::new(); - let Some(root) = crate::package::font_table_key(self.passthrough).map(str::to_string) else { return }; - if let Some(name) = self.copy_tree(&root, &mut HashMap::new(), &mut written) { - rels.add(rt::FONT_TABLE, &relative(STORY_PART, &name), false); - } + let Some(root) = crate::package::font_table_key(self.passthrough).map(str::to_string) else { return false }; + let Some(name) = self.copy_tree(&root, &mut HashMap::new(), &mut written) else { return false }; + rels.add(rt::FONT_TABLE, &relative(STORY_PART, &name), false); + true } /// Reserve the names of the media files this writer writes. diff --git a/crates/docx/src/write/font_table.rs b/crates/docx/src/write/font_table.rs new file mode 100644 index 000000000..6ffe759e8 --- /dev/null +++ b/crates/docx/src/write/font_table.rs @@ -0,0 +1,98 @@ +//! A font table (`word/fontTable.xml`, ECMA-376 Part 1 §17.8) for a document that brings none of +//! its own: one built in code, or read from another format. It names each font the document +//! uses with its generic family and pitch, so a reader without the font draws a like one (a sans +//! for Arial, not its own serif default). A table read from a file is written back as it was +//! instead ([`super::embed::EmbedWriter::font_table`]). + +use std::collections::BTreeSet; + +use craft_wordmodel::font_kind::GenericFamily; +use craft_wordmodel::props::CharProps; +use craft_wordmodel::symbol_fonts::is_symbol_font; +use craft_wordmodel::walk::each_para; +use craft_wordmodel::{Document, Paragraph}; + +use crate::xml::W; + +/// Most fonts the table names (hostile input: a font per run). +const MAX_FONTS: usize = 1000; +/// Longest font name it keeps, bytes (as the reader, `MAX_FONT_NAME`). +const MAX_NAME: usize = 256; + +/// Add the fonts `c` names to `out`, up to [`MAX_FONTS`]. +fn take<'a>(c: &'a CharProps, out: &mut BTreeSet<&'a str>) { + for f in [&c.font, &c.font_ea, &c.font_cs, &c.sym_font].into_iter().flatten() { + let f = f.trim(); + if out.len() < MAX_FONTS && !f.is_empty() && f.len() <= MAX_NAME { + out.insert(f); + } + } +} + +/// The fonts `doc` names, sorted: the document defaults', its styles' and list levels', and +/// every run's and paragraph mark's in every story. +fn used_fonts(doc: &Document) -> BTreeSet<&str> { + let mut out = BTreeSet::new(); + take(&doc.styles.default_chr, &mut out); + for s in &doc.styles.styles { + take(&s.chr, &mut out); + } + for a in &doc.numbering.abstracts { + for l in &a.levels { + take(&l.chr, &mut out); + } + } + for n in &doc.numbering.nums { + for (_, l) in &n.level_overrides { + take(&l.chr, &mut out); + } + } + let stories = std::iter::once(&doc.body).chain(doc.parts.values().map(|p| &p.blocks)); + for b in stories.flat_map(|blocks| blocks.iter()) { + if out.len() >= MAX_FONTS { + break; + } + each_para(b, 0, &mut |p: &Paragraph| { + take(&p.mark, &mut out); + for r in &p.runs { + take(&r.props, &mut out); + } + }); + } + out +} + +/// `word/fontTable.xml` for `doc`, or `None` when it names no font. +pub(super) fn font_table_xml(doc: &Document) -> Option> { + let fonts = used_fonts(doc); + if fonts.is_empty() { + return None; + } + let mut w = W::new(); + w.open( + "w:fonts", + &[ + ("xmlns:w", "http://schemas.openxmlformats.org/wordprocessingml/2006/main"), + ("xmlns:r", "http://schemas.openxmlformats.org/officeDocument/2006/relationships"), + ], + ); + for name in fonts { + w.open("w:font", &[("w:name", name)]); + if is_symbol_font(name) { + // Symbol, Wingdings…: the symbol character set, so a reader maps their codes as the + // font's own and doesn't substitute a text face. + w.val("w:charset", "02"); + w.val("w:family", "auto"); + w.val("w:pitch", "variable"); + } else { + // A family the file's own table named roman stays roman (Word draws it in a serif). + let family = + if doc.settings.roman_fonts.iter().any(|r| r.eq_ignore_ascii_case(name)) { GenericFamily::Roman } else { GenericFamily::of(name) }; + w.val("w:family", family.name()); + w.val("w:pitch", if family.fixed_pitch() { "fixed" } else { "variable" }); + } + w.close("w:font"); + } + w.close("w:fonts"); + Some(w.into_bytes()) +} diff --git a/crates/docx/src/write/parts.rs b/crates/docx/src/write/parts.rs index 4cb847276..942da56c2 100644 --- a/crates/docx/src/write/parts.rs +++ b/crates/docx/src/write/parts.rs @@ -7,6 +7,7 @@ use super::{ BTreeMap, Blocks, CT_WML, Document, DocxError, Flavor, HashMap, MAX_VBA_RELATED, PartRels, VBA_PROJECT_PART, VBA_RELATED, W, Writer, embed, glossary, rt, settings_merge, watermark, xml, }; +use crate::package::FONT_TABLE_PART; /// The parts of the package [`write_as`] zips, in order, `[Content_Types].xml` first: (part name /// without the leading `/`, bytes). @@ -160,7 +161,13 @@ pub(crate) fn write_parts(doc: &Document, flavor: Flavor) -> Result = BTreeMap::new(); diff --git a/crates/docx/tests/it/content_control_save_cost.rs b/crates/docx/tests/it/content_control_save_cost.rs index dec621510..9b96aeb7b 100644 --- a/crates/docx/tests/it/content_control_save_cost.rs +++ b/crates/docx/tests/it/content_control_save_cost.rs @@ -221,6 +221,8 @@ const PINNED_PARTS: &[&str] = &[ "word/styles.xml", "word/settings.xml", "word/theme/theme1.xml", + // The fonts the document uses, with their families: it brings no font table of its own. + "word/fontTable.xml", "docProps/core.xml", "docProps/app.xml", ]; diff --git a/crates/docx/tests/it/font_table.rs b/crates/docx/tests/it/font_table.rs new file mode 100644 index 000000000..e4a8b03a1 --- /dev/null +++ b/crates/docx/tests/it/font_table.rs @@ -0,0 +1,106 @@ +//! A document that brings no font table of its own (one built in code, or read from another +//! format) gets one naming the fonts it uses, with their generic family and pitch: a reader +//! without Arial then draws a sans, not its own serif default. +use std::collections::BTreeMap; +use std::io::Read; +use std::sync::Arc; + +use craft_wordmodel::props::CharProps; +use craft_wordmodel::table::Table; +use craft_wordmodel::{Block, Document, Paragraph}; + +fn unzip(bytes: &[u8]) -> BTreeMap { + let mut z = zip::ZipArchive::new(std::io::Cursor::new(bytes)).unwrap(); + let mut out = BTreeMap::new(); + for i in 0..z.len() { + let mut f = z.by_index(i).unwrap(); + let mut s = String::new(); + if f.read_to_string(&mut s).is_ok() { + out.insert(f.name().unwrap().to_string(), s); + } + } + out +} + +/// The `w:font` element for `name` in `table`. +fn font<'a>(table: &'a str, name: &str) -> &'a str { + let open = format!(""); + let at = table.find(&open).unwrap_or_else(|| panic!("no {name} in {table}")); + let rest = &table[at..]; + &rest[..rest.find("").unwrap()] +} + +fn append(p: &mut Paragraph, s: &str, props: &CharProps) { + let at = p.len(); + p.insert_text(at, s, props).unwrap(); +} + +fn run(text: &str, font: &str) -> Paragraph { + Paragraph::with_text(text, CharProps { font: Some(font.into()), ..Default::default() }) +} + +#[test] +fn a_built_document_names_its_fonts_with_their_family_and_pitch() { + let mut d = Document::new(); + let mut table = Table::new(1, 1, 200.0); + if let Some(c) = table.rows.first_mut().and_then(|r| r.cells.first_mut()) { + c.blocks = vec![Arc::new(Block::Para(run("cell", "Courier New")))]; + } + let mut symbol = Paragraph::new(); + append(&mut symbol, "\u{F0B7}", &CharProps { sym_font: Some("Symbol".into()), ..Default::default() }); + let mut serif = run("serif", "Times New Roman"); + append(&mut serif, " east", &CharProps { font_ea: Some("MS Mincho".into()), ..Default::default() }); + d.body = + vec![Arc::new(Block::Para(run("sans", "Arial"))), Arc::new(Block::Table(table)), Arc::new(Block::Para(serif)), Arc::new(Block::Para(symbol))]; + let files = unzip(&craft_docx::write(&d).unwrap()); + let t = files.get("word/fontTable.xml").unwrap_or_else(|| panic!("no font table in {:?}", files.keys())); + assert!(font(t, "Arial").contains(r#""#), "{t}"); + assert!(font(t, "Times New Roman").contains(r#""#), "{t}"); + assert!(font(t, "Courier New").contains(r#""#), "a table cell's font: {t}"); + assert!(font(t, "MS Mincho").contains(""#), "a symbol font has the symbol set: {t}"); + // The built-in styles' fonts are there too. + let body = d.styles.default_chr.font.clone().unwrap(); + font(t, &body); + assert_eq!(t.matches(r#""#).count(), 1, "each font once"); + // Related from the document and typed. + assert!( + files["word/_rels/document.xml.rels"].contains(r#"relationships/fontTable" Target="fontTable.xml""#), + "{}", + files["word/_rels/document.xml.rels"] + ); + assert!(files["[Content_Types].xml"].contains("wordprocessingml.fontTable+xml")); + // The reader takes the families back: Times New Roman is a serif. + let back = craft_docx::read(&craft_docx::write(&d).unwrap()).unwrap(); + assert!(back.settings.roman_fonts.iter().any(|f| f == "Times New Roman"), "{:?}", back.settings.roman_fonts); + assert!(!back.settings.roman_fonts.iter().any(|f| f == "Arial")); + // Saved again, the table read back is written as it was. + let again = unzip(&craft_docx::write(&back).unwrap()); + assert_eq!(again.get("word/fontTable.xml"), Some(t)); +} + +#[test] +fn a_file_font_table_family_wins_over_the_name() { + // A file's table classes "Fancy Face" as roman: the generated table, written when that one is + // gone, keeps it a serif. + let mut d = Document::new(); + d.body = vec![Arc::new(Block::Para(run("x", "Fancy Face")))]; + d.settings.roman_fonts = vec!["Fancy Face".into()]; + let files = unzip(&craft_docx::write(&d).unwrap()); + assert!(font(&files["word/fontTable.xml"], "Fancy Face").contains(r#""#)); +} + +#[test] +fn hostile_font_counts_and_names_are_bounded() { + let mut d = Document::new(); + let mut p = Paragraph::new(); + for i in 0..5000 { + append(&mut p, "x", &CharProps { font: Some(format!("Face {i}")), ..Default::default() }); + } + append(&mut p, "y", &CharProps { font: Some("N".repeat(10_000)), ..Default::default() }); + d.body = vec![Arc::new(Block::Para(p))]; + let files = unzip(&craft_docx::write(&d).unwrap()); + let t = &files["word/fontTable.xml"]; + assert!(t.matches("")); assert!(text.contains("pkg:name=\"/word/document.xml\"") && text.contains("")); assert_eq!(craft_docx::sniff_xml(&xml), craft_docx::XmlKind::FlatOpc); - let back = craft_docx::read_xml(&xml).expect("read flat"); - assert_eq!(back, rt(&d)); + let mut back = craft_docx::read_xml(&xml).expect("read flat"); + // `pkg:xmlData` inlines a part without its XML declaration, so a kept XML part (the font + // table) comes back without one; the markup is the same. + let mut want = rt(&d); + for doc in [&mut back, &mut want] { + for v in doc.passthrough.values_mut() { + if let Some(rest) = + v.strip_prefix(b"').map(|e| r[e + 1..].trim_ascii_start().to_vec())) + { + *v = std::sync::Arc::new(rest); + } + } + } + assert!(back.passthrough.contains_key("word/fontTable.xml")); + assert_eq!(back, want); assert_eq!(back.media.len(), 1); } diff --git a/crates/flow/src/from_doc.rs b/crates/flow/src/from_doc.rs index d85953a0a..11d71dd05 100644 --- a/crates/flow/src/from_doc.rs +++ b/crates/flow/src/from_doc.rs @@ -18,11 +18,7 @@ pub(super) fn uses_kind(blocks: &[FBlock], k: Kind, depth: usize) -> bool { // --------------------------------------------------------------------------------------------- // Document → Flow -/// Is this a monospace family name? -pub fn is_mono(font: &str) -> bool { - let f = font.to_ascii_lowercase(); - f.contains("courier") || f.contains("mono") || f.contains("consolas") || f.contains("menlo") || f.contains("code") || f == "monaco" -} +pub use craft_wordmodel::font_kind::is_mono; fn is_code_style(doc: &Document, id: &str) -> bool { let names = |s: &str| { diff --git a/crates/odf/src/text/package.rs b/crates/odf/src/text/package.rs index f43692be9..e7744a4e8 100644 --- a/crates/odf/src/text/package.rs +++ b/crates/odf/src/text/package.rs @@ -1583,32 +1583,8 @@ fn with_font_faces(xml: &str) -> String { /// A font family's generic family and pitch (§20.270, §20.271), from its name: monospaced /// families are `modern` and fixed, serif ones `roman`, the rest `swiss`. fn font_kind(family: &str) -> (&'static str, &'static str) { - let f = family.to_ascii_lowercase(); - if model::is_mono(family) { - return ("modern", "fixed"); - } - const SERIF: [&str; 16] = [ - "serif", - "times", - "georgia", - "cambria", - "caladea", - "garamond", - "palatino", - "book", - "roman", - "libertine", - "minion", - "baskerville", - "bodoni", - "didot", - "charter", - "constantia", - ]; - if SERIF.iter().any(|s| f.contains(s)) && !f.contains("sans") { - return ("roman", "variable"); - } - ("swiss", "variable") + let generic = craft_wordmodel::font_kind::GenericFamily::of(family); + (generic.name(), if generic.fixed_pitch() { "fixed" } else { "variable" }) } #[cfg(test)] diff --git a/crates/wordmodel/src/font_kind.rs b/crates/wordmodel/src/font_kind.rs new file mode 100644 index 000000000..7f8692783 --- /dev/null +++ b/crates/wordmodel/src/font_kind.rs @@ -0,0 +1,91 @@ +//! The generic family of a font, guessed from its name: what a reader without the font should draw +//! instead. The writers that declare one share it: OOXML's font table (`w:family`, `w:pitch`), +//! ODF's font faces (`style:font-family-generic`, `style:font-pitch`) and RTF's (`\fmodern`). + +/// A font's generic family. The names are the values OOXML (`ST_FontFamily`) and ODF give them. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum GenericFamily { + /// Serif faces (Times New Roman, Georgia, Cambria…). + Roman, + /// Sans-serif faces (Arial, Calibri, Liberation Sans…), and any name not known to be another. + Swiss, + /// Monospace faces (Courier New, Consolas…). + Modern, +} + +/// Words in the names of serif faces. +const SERIF: [&str; 16] = [ + "serif", + "times", + "georgia", + "cambria", + "caladea", + "garamond", + "palatino", + "book", + "roman", + "libertine", + "minion", + "baskerville", + "bodoni", + "didot", + "charter", + "constantia", +]; + +impl GenericFamily { + /// The family of the font named `name`. + pub fn of(name: &str) -> GenericFamily { + if is_mono(name) { + return GenericFamily::Modern; + } + let f = name.to_ascii_lowercase(); + if SERIF.iter().any(|s| f.contains(s)) && !f.contains("sans") { + return GenericFamily::Roman; + } + GenericFamily::Swiss + } + + /// `roman`, `swiss` or `modern`. + pub fn name(self) -> &'static str { + match self { + GenericFamily::Roman => "roman", + GenericFamily::Swiss => "swiss", + GenericFamily::Modern => "modern", + } + } + + /// Whether its faces are fixed pitch (monospace). + pub fn fixed_pitch(self) -> bool { + self == GenericFamily::Modern + } +} + +/// Is this a monospace family name? +pub fn is_mono(font: &str) -> bool { + let f = font.to_ascii_lowercase(); + f.contains("courier") || f.contains("mono") || f.contains("consolas") || f.contains("menlo") || f.contains("code") || f == "monaco" +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn families_from_names() { + for (name, want) in [ + ("Arial", GenericFamily::Swiss), + ("Liberation Sans", GenericFamily::Swiss), + ("Unknown Face", GenericFamily::Swiss), + ("Times New Roman", GenericFamily::Roman), + ("Liberation Serif", GenericFamily::Roman), + ("Caladea", GenericFamily::Roman), + ("Noto Sans Serif", GenericFamily::Swiss), + ("Courier New", GenericFamily::Modern), + ("Liberation Mono", GenericFamily::Modern), + ] { + assert_eq!(GenericFamily::of(name), want, "{name}"); + } + assert!(GenericFamily::Modern.fixed_pitch() && !GenericFamily::Roman.fixed_pitch()); + } +} diff --git a/crates/wordmodel/src/lib.rs b/crates/wordmodel/src/lib.rs index 5fb2d14d8..2b3fb2626 100644 --- a/crates/wordmodel/src/lib.rs +++ b/crates/wordmodel/src/lib.rs @@ -29,6 +29,7 @@ pub mod effects; pub mod eq; pub mod fields; pub mod fill; +pub mod font_kind; pub mod freeform; pub mod geom; pub mod graphic; From 03181405cd85afddb7781c00a2025332f5c8f475 Mon Sep 17 00:00:00 2001 From: Ken Mantle Date: Mon, 16 Nov 2026 21:29:47 -0500 Subject: [PATCH 11/64] craft-mesh: read and write KHR_texture_transform (#1935) --- crates/mesh/README.md | 6 ++-- crates/mesh/src/gltf.rs | 56 +++++++++++++++++++++++++----- crates/mesh/src/lib.rs | 46 +++++++++++++++++++++++++ crates/mesh/src/tests/gltf.rs | 64 ++++++++++++++++++++++++++++++++--- crates/mesh/src/threemf.rs | 2 +- 5 files changed, 156 insertions(+), 18 deletions(-) diff --git a/crates/mesh/README.md b/crates/mesh/README.md index 3b57208fa..d58dd9072 100644 --- a/crates/mesh/README.md +++ b/crates/mesh/README.md @@ -77,13 +77,13 @@ point cloud (positions, no parts). `TRIANGLE_FAN`, indexed or not; POSITION, NORMAL, every TEXCOORD_n (up to 8), COLOR_0, JOINTS_0, WEIGHTS_0 in any component type the specification or `KHR_mesh_quantization` allows; strided buffer views; accessors without a buffer view (zeros); sparse accessors; materials with their -texture slots, UV set and sampler wrap modes, `KHR_materials_emissive_strength`, +texture slots, UV set, sampler wrap modes and `KHR_texture_transform`, `KHR_materials_emissive_strength`, `KHR_materials_unlit`, `KHR_materials_pbrSpecularGlossiness` (diffuse colour and texture, no metal, roughness from the glossiness); textures whose image is in `EXT_texture_webp`; images embedded in a buffer view or a `data:` URI, or named; skins; translation, rotation and scale animations; cameras; `KHR_lights_punctual`. Primitives of a mesh that name the same accessors share their -vertices. `write_glb` writes nodes, meshes (positions, normals, UV sets, colours), materials and -images. +vertices. `write_glb` writes nodes, meshes (positions, normals, UV sets, colours), materials with +their texture transforms, and images. The other formats' writers do not write texture transforms. **3MF.** The package is opened with `craft-opc` and the model part found through its `3dmodel` relationship; `threemf::read_model_part` reads a model part's XML on its own. Mesh objects, diff --git a/crates/mesh/src/gltf.rs b/crates/mesh/src/gltf.rs index 13e53aca1..c92051b84 100644 --- a/crates/mesh/src/gltf.rs +++ b/crates/mesh/src/gltf.rs @@ -5,8 +5,8 @@ //! primitives (`TRIANGLES`, `TRIANGLE_STRIP`, `TRIANGLE_FAN`, indexed or not) with POSITION, //! NORMAL, TANGENT, every TEXCOORD_n, COLOR_0, JOINTS_0 and WEIGHTS_0 of any component type the //! specification or `KHR_mesh_quantization` allows, strided buffer views, sparse accessors, -//! metallic-roughness materials (factors, the five texture slots with their UV set and wrap -//! modes, alpha modes, double-sided, `KHR_materials_emissive_strength`, `KHR_materials_unlit`; +//! metallic-roughness materials (factors, the five texture slots with their UV set, wrap +//! modes and `KHR_texture_transform`, alpha modes, double-sided, `KHR_materials_emissive_strength`, `KHR_materials_unlit`; //! `KHR_materials_pbrSpecularGlossiness` as its diffuse colour and texture with roughness from //! the glossiness), textures whose image is only in `EXT_texture_webp`, images (embedded //! in a buffer view or a `data:` URI, or named), skins, animations of translation, rotation @@ -36,10 +36,11 @@ use serde_json::{Map, Value, json}; use crate::{ AlphaMode, Animation, Camera, Channel, ChannelPath, Corner, Error, IDENTITY, Image, Interpolation, Light, LightKind, Limits, Material, Mesh, - NONE, Node, Part, Projection, Resolver, Result, Scene, Skin, TextureRef, Trs, Wrap, count_warning, malformed, too_large, + NONE, Node, Part, Projection, Resolver, Result, Scene, Skin, TextureRef, Trs, UvTransform, Wrap, count_warning, malformed, too_large, }; const KIND: &str = "glTF"; +const TEXTURE_TRANSFORM: &str = "KHR_texture_transform"; const CHUNK_JSON: u32 = 0x4E4F_534A; const CHUNK_BIN: u32 = 0x004E_4942; /// Most UV sets read from one primitive. @@ -583,7 +584,7 @@ fn materials(j: &Value, limits: &Limits, scene: &mut Scene) -> Result<()> { let sampler = idx(texture, "sampler").and_then(|s| arr(j, "samplers").get(s)); let webp = || texture.get("extensions").and_then(|e| e.get("EXT_texture_webp")).and_then(|e| idx(e, "source")); let image = idx(texture, "source").or_else(webp).filter(|i| *i < images)?; - Some(TextureRef { image, uv_set: 0, wrap: [wrap(sampler, "wrapS"), wrap(sampler, "wrapT")] }) + Some(TextureRef { image, wrap: [wrap(sampler, "wrapS"), wrap(sampler, "wrapT")], ..TextureRef::default() }) }) .collect(); let tref = |v: Option<&Value>| -> Option { @@ -593,7 +594,15 @@ fn materials(j: &Value, limits: &Limits, scene: &mut Scene) -> Result<()> { // `EXT_texture_webp`: the image when the texture has no fallback `source`. let webp = || texture.get("extensions").and_then(|e| e.get("EXT_texture_webp")).and_then(|e| idx(e, "source")); let image = idx(texture, "source").or_else(webp).filter(|i| *i < images)?; - Some(TextureRef { image, uv_set: idx(v, "texCoord").unwrap_or(0) as u32, wrap: [wrap(sampler, "wrapS"), wrap(sampler, "wrapT")] }) + let tt = v.get("extensions").and_then(|e| e.get("KHR_texture_transform")); + // The extension's own `texCoord` overrides the texture info's. + let uv_set = tt.and_then(|t| idx(t, "texCoord")).or_else(|| idx(v, "texCoord")).unwrap_or(0); + Some(TextureRef { + image, + uv_set: u32::try_from(uv_set).unwrap_or(u32::MAX), + wrap: [wrap(sampler, "wrapS"), wrap(sampler, "wrapT")], + transform: tt.map(uv_transform), + }) }; for m in list { let null = Value::Null; @@ -780,11 +789,25 @@ fn cameras_and_lights(j: &Value, limits: &Limits, scene: &mut Scene) -> Result<( Ok(()) } +/// A `KHR_texture_transform` object; a missing or unusable member keeps its default. +fn uv_transform(t: &Value) -> UvTransform { + let finite = |v: f64, default: f32| Some(v as f32).filter(|v| v.is_finite()).unwrap_or(default); + let d = UvTransform::default(); + let [ou, ov] = nums(t, "offset", [0.0; 2]); + let [su, sv] = nums(t, "scale", [1.0; 2]); + UvTransform { + offset: [finite(ou, d.offset[0]), finite(ov, d.offset[1])], + rotation: finite(num(t, "rotation", 0.0), d.rotation), + scale: [finite(su, d.scale[0]), finite(sv, d.scale[1])], + } +} + /// Required extensions that only change how a file looks (textures, material models) or that /// the reader handles: the geometry reads without the others being understood. fn check_extensions(j: &Value, scene: &mut Scene) -> Result<()> { - const LOOKS: [&str; 4] = ["KHR_texture_transform", "KHR_texture_basisu", "MSFT_texture_dds", "KHR_lights_punctual"]; - const READ: [&str; 5] = [ + const LOOKS: [&str; 3] = ["KHR_texture_basisu", "MSFT_texture_dds", "KHR_lights_punctual"]; + const READ: [&str; 6] = [ + TEXTURE_TRANSFORM, "KHR_mesh_quantization", "KHR_materials_unlit", "KHR_materials_emissive_strength", @@ -967,7 +990,12 @@ impl Textures { self.textures.push((image, sampler)); self.textures.len() - 1 }); - Some(json!({ "index": index, "texCoord": t.uv_set })) + let mut out = json!({ "index": index, "texCoord": t.uv_set }); + if let (Some(tt), Some(o)) = (t.transform, out.as_object_mut()) { + let ext = json!({ "offset": tt.offset, "rotation": tt.rotation, "scale": tt.scale }); + o.insert("extensions".into(), json!({ TEXTURE_TRANSFORM: ext })); + } + Some(out) } } @@ -988,6 +1016,10 @@ fn material_json(m: &Material, textures: &mut Textures, extensions: &mut Vec<&'s extensions.push(name); } } + let slots = [m.base_color_texture, m.metallic_roughness_texture, m.normal_texture, m.occlusion_texture, m.emissive_texture]; + if slots.iter().flatten().any(|t| t.transform.is_some()) && !extensions.contains(&TEXTURE_TRANSFORM) { + extensions.push(TEXTURE_TRANSFORM); + } let set = |o: &mut Value, key: &str, v: Option| { if let (Some(v), Some(o)) = (v, o.as_object_mut()) { o.insert(key.into(), v); @@ -1027,7 +1059,13 @@ fn check_finite(scene: &Scene) -> Result<()> { let materials = scene.materials.iter().all(|m| { let values = [m.metallic, m.roughness, m.normal_scale, m.occlusion_strength]; let cutoff = if let AlphaMode::Mask(c) = m.alpha_mode { c } else { 0.0 }; - m.base_color.iter().chain(&m.emissive).chain(&values).all(|x| x.is_finite()) && cutoff.is_finite() + let slots = [&m.base_color_texture, &m.metallic_roughness_texture, &m.normal_texture, &m.occlusion_texture, &m.emissive_texture]; + let transforms = slots + .into_iter() + .flatten() + .filter_map(|t| t.transform) + .all(|t| t.offset.iter().chain(&t.scale).chain([&t.rotation]).all(|x| x.is_finite())); + m.base_color.iter().chain(&m.emissive).chain(&values).all(|x| x.is_finite()) && cutoff.is_finite() && transforms }); if positions && nodes && materials { Ok(()) } else { Err(malformed(KIND, "a position, transform or material value is not finite")) } } diff --git a/crates/mesh/src/lib.rs b/crates/mesh/src/lib.rs index 59870ff31..6017c8dd2 100644 --- a/crates/mesh/src/lib.rs +++ b/crates/mesh/src/lib.rs @@ -365,6 +365,52 @@ pub struct TextureRef { pub image: usize, pub uv_set: u32, pub wrap: [Wrap; 2], + /// Where the slot's UVs land before the image is looked up (glTF `KHR_texture_transform`). + pub transform: Option, +} + +/// A UV transform: scale, then rotate by `rotation` radians, then add `offset`, in the order and +/// with the signs of glTF's `KHR_texture_transform` (v runs down the image). +/// +/// Compared and hashed by bits, so [`TextureRef`] keeps `Eq` and `Hash`. +#[derive(Clone, Copy, Debug)] +pub struct UvTransform { + pub offset: [f32; 2], + pub rotation: f32, + pub scale: [f32; 2], +} + +impl Default for UvTransform { + fn default() -> Self { + Self { offset: [0.0; 2], rotation: 0.0, scale: [1.0; 2] } + } +} + +impl UvTransform { + /// The transformed coordinate. + pub fn apply(&self, [u, v]: [f32; 2]) -> [f32; 2] { + let (sin, cos) = self.rotation.sin_cos(); + let (su, sv) = (u * self.scale[0], v * self.scale[1]); + [cos * su + sin * sv + self.offset[0], cos * sv - sin * su + self.offset[1]] + } + + fn bits(&self) -> [u32; 5] { + [self.offset[0], self.offset[1], self.rotation, self.scale[0], self.scale[1]].map(f32::to_bits) + } +} + +impl PartialEq for UvTransform { + fn eq(&self, other: &Self) -> bool { + self.bits() == other.bits() + } +} + +impl Eq for UvTransform {} + +impl std::hash::Hash for UvTransform { + fn hash(&self, state: &mut H) { + self.bits().hash(state); + } } /// A metallic-roughness material: the simple parameters every format here can carry. diff --git a/crates/mesh/src/tests/gltf.rs b/crates/mesh/src/tests/gltf.rs index 13db18a87..8892fe241 100644 --- a/crates/mesh/src/tests/gltf.rs +++ b/crates/mesh/src/tests/gltf.rs @@ -4,7 +4,7 @@ use super::hammer; use crate::gltf::{MAX_UV_SETS, MAX_ZERO_COMPONENTS, base64_decode, glb_container, read, split_glb, uri_decode, write_glb}; use crate::{ AlphaMode, ChannelPath, Corner, Error, IDENTITY, Image, Interpolation, LightKind, Limits, Material, Mesh, NONE, Node, Part, Projection, Scene, - TextureRef, Wrap, face_normal, no_external, transform_point, + TextureRef, UvTransform, Wrap, face_normal, no_external, transform_point, }; /// Builds the binary chunk with its buffer views and accessors. @@ -198,7 +198,7 @@ fn embedded_and_external_resources() { (Some(&png[..]), Some("image/png"), None) ); // The texture slot keeps its UV set and wrap modes. - assert_eq!(s.materials[0].base_color_texture, Some(TextureRef { image: 0, uv_set: 1, wrap: [Wrap::Clamp, Wrap::Mirror] })); + assert_eq!(s.materials[0].base_color_texture, Some(TextureRef { image: 0, uv_set: 1, wrap: [Wrap::Clamp, Wrap::Mirror], transform: None })); // No scene in the file: every node that is nobody's child is a root. assert_eq!(s.roots, [0]); @@ -222,6 +222,44 @@ fn embedded_and_external_resources() { assert!(parse(&gltf_text("data:;base64,!!!", "x.png").0).is_err()); } +/// A one-material file whose base colour texture info is `info`. +fn texture_info(info: Value) -> Scene { + let (doc, bin) = gltf_text("", "data:image/png;base64,iVBORw0KGgo="); + let mut v: Value = serde_json::from_slice(&doc).unwrap(); + v["materials"][0]["pbrMetallicRoughness"]["baseColorTexture"] = info; + v["buffers"][0]["uri"] = json!(format!("data:application/octet-stream;base64,{}", base64(&bin))); + parse(&serde_json::to_vec(&v).unwrap()).unwrap() +} + +#[test] +fn a_texture_transform_is_read_with_its_own_uv_set() { + let t = |s: &Scene| s.materials[0].base_color_texture.unwrap(); + let ext = json!({ "offset": [0.5, 0.25], "rotation": std::f64::consts::FRAC_PI_2, "scale": [2, 3], "texCoord": 1 }); + let s = texture_info(json!({ "index": 0, "texCoord": 0, "extensions": { "KHR_texture_transform": ext } })); + assert_eq!(t(&s).uv_set, 1, "the extension's texCoord wins"); + let tt = t(&s).transform.unwrap(); + // (1, 0): scaled to (2, 0), turned to (0, -2), moved to (0.5, -1.75). + let [u, v] = tt.apply([1.0, 0.0]); + assert!((u - 0.5).abs() < 1e-6 && (v + 1.75).abs() < 1e-6, "({u}, {v})"); + // Missing or unusable members keep their defaults. + let s = texture_info(json!({ "index": 0, "texCoord": 1, "extensions": { "KHR_texture_transform": { "scale": "big", "offset": [2] } } })); + assert_eq!((t(&s).uv_set, t(&s).transform), (1, Some(UvTransform { offset: [2.0, 0.0], ..UvTransform::default() }))); + assert_eq!(texture_info(json!({ "index": 0 })).materials[0].base_color_texture.unwrap().transform, None); +} + +/// The extension's own example (offset (0, 1), a quarter turn, half scale), which draws only the +/// image's lower-left quadrant; v runs down. +#[test] +fn the_extensions_own_example_draws_the_lower_left_quadrant() { + let ext = json!({ "offset": [0, 1], "rotation": std::f64::consts::FRAC_PI_2, "scale": [0.5, 0.5] }); + let s = texture_info(json!({ "index": 0, "extensions": { "KHR_texture_transform": ext } })); + let tt = s.materials[0].base_color_texture.unwrap().transform.unwrap(); + for uv in [[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]] { + let [u, v] = tt.apply(uv); + assert!((-1e-6..=0.5 + 1e-6).contains(&u) && (0.5 - 1e-6..=1.0 + 1e-6).contains(&v), "{uv:?} to ({u}, {v})"); + } +} + #[test] fn texture_and_sampler_inventory_includes_unreferenced_entries() { let doc = serde_json::to_vec(&json!({ @@ -237,7 +275,10 @@ fn texture_and_sampler_inventory_includes_unreferenced_entries() { let scene = read(&doc, &Limits::default(), &mut |_| Some(vec![])).unwrap(); assert_eq!( scene.texture_variants, - [TextureRef { image: 0, uv_set: 0, wrap: [Wrap::Clamp, Wrap::Mirror] }, TextureRef { image: 0, uv_set: 0, wrap: [Wrap::Repeat; 2] },] + [ + TextureRef { image: 0, wrap: [Wrap::Clamp, Wrap::Mirror], ..TextureRef::default() }, + TextureRef { image: 0, wrap: [Wrap::Repeat; 2], ..TextureRef::default() }, + ] ); assert!(scene.validate().is_ok()); @@ -470,7 +511,7 @@ fn what_is_not_read_is_refused_or_named() { json!({ "extensionsRequired": ["KHR_texture_transform", "KHR_materials_clearcoat", "KHR_mesh_quantization", "KHR_materials_unlit"] }), )) .unwrap(); - assert_eq!(s.warnings.len(), 2); + assert_eq!(s.warnings.len(), 1, "texture transforms are read: {:?}", s.warnings); assert!(parse(b"{ not json").is_err()); assert!(parse(b"").is_err()); } @@ -687,7 +728,8 @@ fn painted() -> Scene { ], ..Mesh::default() }; - let wood = TextureRef { image: 0, uv_set: 1, wrap: [Wrap::Clamp, Wrap::Repeat] }; + let tile = UvTransform { offset: [0.25, -1.5], rotation: 0.5, scale: [2.0, 4.0] }; + let wood = TextureRef { image: 0, uv_set: 1, wrap: [Wrap::Clamp, Wrap::Repeat], transform: Some(tile) }; let materials = vec![ Material { name: "Wood".into(), @@ -727,6 +769,14 @@ fn written_files_read_back() { let back = parse(&glb).unwrap(); back.validate().unwrap(); assert!(back.warnings.is_empty(), "{:?}", back.warnings); + let uses_transform = |glb: &[u8]| { + let used: Value = serde_json::from_slice(split_glb(glb).unwrap().0).unwrap(); + used["extensionsUsed"].as_array().map_or(0, |a| a.iter().filter(|e| *e == "KHR_texture_transform").count()) + }; + assert_eq!(uses_transform(&glb), 1); + let mut plain = painted(); + plain.materials.iter_mut().filter_map(|m| m.base_color_texture.as_mut()).for_each(|t| t.transform = None); + assert_eq!(uses_transform(&write_glb(&plain, &Limits::default()).unwrap()), 0, "listed only when used"); // The hierarchy: names, placement, and the mesh without triangles gone from its node. assert_eq!(back.roots, [2]); assert_eq!( @@ -764,6 +814,10 @@ fn writer_refuses_what_is_not_gltf() { s.materials[0].roughness = f32::NAN; assert!(write_glb(&s, &limits).is_err()); let mut s = painted(); + let t = s.materials.iter_mut().find_map(|m| m.base_color_texture.as_mut().and_then(|t| t.transform.as_mut())).unwrap(); + t.rotation = f32::NAN; + assert!(write_glb(&s, &limits).is_err(), "a texture transform that is not finite"); + let mut s = painted(); s.meshes[0].parts[0].corners[0].position = 50; assert!(write_glb(&s, &limits).is_err()); let mut s = painted(); diff --git a/crates/mesh/src/threemf.rs b/crates/mesh/src/threemf.rs index 50afc5b7e..a8c0abc97 100644 --- a/crates/mesh/src/threemf.rs +++ b/crates/mesh/src/threemf.rs @@ -365,7 +365,7 @@ impl Build<'_, '_> { .ok_or_else(|| too_large(KIND, format!("textures of more than {} bytes", self.limits.max_data_bytes)))?; self.scene.external.push(t.path.clone()); self.scene.images.push(Image { name: String::new(), uri: Some(t.path.clone()), mime_type: t.content_type.clone(), data }); - Some(TextureRef { image: self.scene.images.len() - 1, uv_set: 0, wrap: t.wrap }) + Some(TextureRef { image: self.scene.images.len() - 1, wrap: t.wrap, ..TextureRef::default() }) } None => None, }; From a7009395fcbdcded2c6adeffc26950cbe32bc608 Mon Sep 17 00:00:00 2001 From: Ken Mantle Date: Mon, 16 Nov 2026 21:29:51 -0500 Subject: [PATCH 12/64] craft-prc: write triangle-mesh scenes as PRC (#1934) --- crates/prc/Cargo.toml | 2 +- crates/prc/README.md | 14 +- crates/prc/src/acof.rs | 17 +- crates/prc/src/lib.rs | 8 + crates/prc/src/tree/mod.rs | 13 ++ crates/prc/src/tree/style.rs | 21 +- crates/prc/src/tree/tests.rs | 2 +- crates/prc/src/write/bits.rs | 164 +++++++++++++++ crates/prc/src/write/bounds.rs | 45 ++++ crates/prc/src/write/container.rs | 80 +++++++ crates/prc/src/write/mod.rs | 287 +++++++++++++++++++++++++ crates/prc/src/write/readback.rs | 32 +++ crates/prc/src/write/sections.rs | 300 ++++++++++++++++++++++++++ crates/prc/src/write/tess.rs | 118 +++++++++++ crates/prc/src/write/tests.rs | 339 ++++++++++++++++++++++++++++++ crates/prc/src/write/textures.rs | 240 +++++++++++++++++++++ crates/prc/src/write/validate.rs | 292 +++++++++++++++++++++++++ crates/prc/src/write/vec3.rs | 53 +++++ 18 files changed, 2016 insertions(+), 11 deletions(-) create mode 100644 crates/prc/src/write/bits.rs create mode 100644 crates/prc/src/write/bounds.rs create mode 100644 crates/prc/src/write/container.rs create mode 100644 crates/prc/src/write/mod.rs create mode 100644 crates/prc/src/write/readback.rs create mode 100644 crates/prc/src/write/sections.rs create mode 100644 crates/prc/src/write/tess.rs create mode 100644 crates/prc/src/write/tests.rs create mode 100644 crates/prc/src/write/textures.rs create mode 100644 crates/prc/src/write/validate.rs create mode 100644 crates/prc/src/write/vec3.rs diff --git a/crates/prc/Cargo.toml b/crates/prc/Cargo.toml index 08d3d2563..37fce806a 100644 --- a/crates/prc/Cargo.toml +++ b/crates/prc/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "craft-prc" -description = "PRC 3D model reader (ISO 14739-1): container, bit-level primitives, schema" +description = "PRC 3D model reader and triangle-mesh writer (ISO 14739-1)" version.workspace = true edition.workspace = true license.workspace = true diff --git a/crates/prc/README.md b/crates/prc/README.md index c76d0af5b..084b42374 100644 --- a/crates/prc/README.md +++ b/crates/prc/README.md @@ -1,6 +1,6 @@ # craft-prc -A reader for PRC (ISO 14739-1), the 3D model format a PDF `/3D` stream of `/Subtype /PRC` carries (ISO 32000-2 §13.6.3). +A reader and triangle-mesh writer for PRC (ISO 14739-1), the 3D model format a PDF `/3D` stream of `/Subtype /PRC` carries (ISO 32000-2 §13.6.3). - Standalone: no PDF code and no app code. The caller hands it the stream's bytes; drawing the model stays in the app. - **Licence:** MIT OR Apache-2.0. Inflation through `flate2` with a pure-Rust backend (`miniz_oxide` unless the app's build selects `zlib-rs`). @@ -42,3 +42,15 @@ BitReader: bit, bits, character, unsigned_integer, integer, integer_vbn, double_ - Not yet in the crate: stored-normal or one-status compressed mesh reconstruction, textures. - The `Double` code table's rows come from [prc-rs](https://github.com/ralovich/prc-rs) (MIT); its notice is in `src/acof/table.rs`. A few reading choices also follow prc-rs; each is marked `// prc-rs:` in the source. + +## Writing + +```rust +write_prc(&MeshScene) -> Result // one file structure, readable by PrcFile::parse +MeshScene::bounds() -> Option<[[f64; 3]; 2]> // the placed triangles' box, for a 3D view +``` + +- A `MeshScene` is nodes (name, optional 4x4 matrix, optional mesh, children), roots, meshes of triangle primitives (positions, optional per-vertex normals and texture coordinates, a material), materials (RGBA and emissive) and PNG or JPEG textures with S and T wraps. +- The whole scene is checked before a bit is written: indices, finite numbers, a tree (one parent per node, no repeated root, nesting at most `MAX_NODE_DEPTH`, 64, the reader's walk limit), and each texture's header. A failure is `PrcWriteError`, never a partial stream. +- `PrcWriteReport` holds the stream and counts what the writer supplied itself: flat normals for primitives without normals, and empty primitives dropped. +- Not written: lights, markups, views, B-rep, compressed tessellation. diff --git a/crates/prc/src/acof.rs b/crates/prc/src/acof.rs index fc11a663a..de53d44e2 100644 --- a/crates/prc/src/acof.rs +++ b/crates/prc/src/acof.rs @@ -58,10 +58,21 @@ pub(crate) fn lookup(nbits: u32, code: u32) -> Option { table()?.get(&key(nbits, code)).copied() } -/// The `(nbits, code)` of IEEE exponent `e`'s row, the test writer's half of [`lookup`]. -#[cfg(test)] +/// The `(nbits, code)` of IEEE exponent `e`'s row (`e` in 0..=2047), the writer's half of [`lookup`]. pub(crate) fn exponent_code(e: u32) -> Option<(u32, u32)> { - table()?.iter().find(|(_, v)| matches!(v, Entry::Exponent(hi) if (hi >> 20) & 0x7ff == e)).map(|(&k, _)| (k >> 24, k & 0xff_ffff)) + static CODES: OnceLock>> = OnceLock::new(); + let codes = CODES.get_or_init(|| { + let mut codes = vec![None; 2048]; + for (&k, v) in table().into_iter().flatten() { + if let Entry::Exponent(upper) = v + && let Some(slot) = codes.get_mut((upper >> 20) as usize & 0x7ff) + { + *slot = Some((k >> 24, k & 0xff_ffff)); + } + } + codes + }); + codes.get(e as usize).copied().flatten() } #[cfg(test)] diff --git a/crates/prc/src/lib.rs b/crates/prc/src/lib.rs index 74c6cd52a..6cdf5a4c8 100644 --- a/crates/prc/src/lib.rs +++ b/crates/prc/src/lib.rs @@ -7,6 +7,9 @@ //! tessellations and walks the product tree into placed, coloured meshes //! ([`PrcFile::placements`], [`PrcFile::model_tree`]). //! +//! [`write_prc`] writes a triangle-mesh scene ([`MeshScene`]: named nodes, shared meshes, colours, +//! PNG/JPEG base-colour textures) as a single-file-structure stream. +//! //! Clause numbers in `[WD x.y]` refer to the PRC working draft, ISO/TC 171/SC 2 N570. //! //! Every read is bounded: inflation by [`MAX_INFLATED_BYTES`] (or a caller's limit), decoded @@ -27,6 +30,7 @@ mod tess; #[cfg(test)] mod testw; mod tree; +mod write; pub use bits::{BitReader, MAX_DECODED_ELEMENTS, MAX_SCHEMA_STEPS}; pub use container::{FileStructure, MAX_FILE_STRUCTURES, MAX_INFLATED_BYTES, PRC_READER_VERSION, PrcFile, PrcHeader, SectionKind, UniqueId}; @@ -35,3 +39,7 @@ pub use geometry::Matrix; pub use schema::Schema; pub use tess::{Tessellation, TriangleMesh, TriangleStyle}; pub use tree::{EntityOverrides, MAX_PLACEMENTS, ModelNode, ModelUnits, NameSource, Placement, Rgba, StyleAlpha}; +pub use write::{ + MAX_NODE_DEPTH, MeshScene, PrcWriteError, PrcWriteReport, SceneMaterial, SceneMesh, SceneNode, ScenePrimitive, SceneTexture, TextureWrap, + write_prc, +}; diff --git a/crates/prc/src/tree/mod.rs b/crates/prc/src/tree/mod.rs index db2d5352c..5f20435e1 100644 --- a/crates/prc/src/tree/mod.rs +++ b/crates/prc/src/tree/mod.rs @@ -353,6 +353,19 @@ fn places_by_system(tree: &Tree) -> bool { tree.parts.iter().flatten().any(|i| !i.local.is_empty()) || tree.products.iter().flat_map(|p| &p.overrides).any(|o| o.local != 0) } +#[cfg(test)] +impl PrcFile { + /// Each file structure's materials' emissive colours, in material order. + pub(crate) fn material_emissives(&self) -> Result>>, PrcError> { + let of = |fs: &crate::FileStructure| { + let mut r = BitReader::new(fs.section(SectionKind::Globals)); + let schema = Schema::read(&mut r)?; + Ok(Ctx::new(r, &schema, fs.authoring_version).globals()?.emissives()) + }; + self.file_structures.iter().map(of).collect() + } +} + #[cfg(test)] mod markup_tests; #[cfg(test)] diff --git a/crates/prc/src/tree/style.rs b/crates/prc/src/tree/style.rs index d313fb2f6..4ccd66fe0 100644 --- a/crates/prc/src/tree/style.rs +++ b/crates/prc/src/tree/style.rs @@ -69,8 +69,9 @@ pub(crate) struct Style { /// A `materials` entry as far as colour. #[derive(Debug, Clone, Copy, PartialEq)] pub(crate) enum Material { - /// `Material` (702): `diffuse + 1` (a colour index) and the diffuse alpha. - Plain { diffuse: u32, alpha: f64 }, + /// `Material` (702): `diffuse + 1` and `emissive + 1` (colour indices) and the + /// diffuse alpha. + Plain { diffuse: u32, emissive: u32, alpha: f64 }, /// `TextureApplication` (711) [WD 7.5.6]: `material_generic_index + 1`, the material /// under the texture. Textured { base: u32 }, @@ -93,6 +94,16 @@ pub(crate) fn biased(list: &[T], biased: u32) -> Option<&T> { } impl Globals { + /// Each material's emissive colour; `None` for a texture application or no emission. + #[cfg_attr(not(test), expect(dead_code, reason = "called by unit tests"))] + pub(crate) fn emissives(&self) -> Vec> { + let of = |m: &Material| match *m { + Material::Plain { emissive, .. } => self.colour(emissive), + Material::Textured { .. } => None, + }; + self.materials.iter().map(of).collect() + } + /// The colour a style or material names by `biased` (`index + 1`). Stored indices count /// the colour array's doubles, so `colours[i]` is stored as `3i + 1`; an index that is /// not of that form names nothing. @@ -114,7 +125,7 @@ impl Globals { m = biased(&self.materials, base)?; } match *m { - Material::Plain { diffuse, alpha } => (self.colour(diffuse)?, alpha), + Material::Plain { diffuse, alpha, .. } => (self.colour(diffuse)?, alpha), Material::Textured { .. } => return None, } } else { @@ -234,14 +245,14 @@ impl Ctx<'_, '_> { MATERIAL => { self.r.unsigned_integer()?; // ambient + 1 let diffuse = self.r.unsigned_integer()?; - self.r.unsigned_integer()?; // emissive + 1 + let emissive = self.r.unsigned_integer()?; self.r.unsigned_integer()?; // specular + 1 self.r.double()?; // shininess self.r.double()?; // ambient alpha let alpha = self.r.double()?; self.r.double()?; // emissive alpha self.r.double()?; // specular alpha - Material::Plain { diffuse, alpha } + Material::Plain { diffuse, emissive, alpha } } TEXTURE_APPLICATION => { let base = self.r.unsigned_integer()?; diff --git a/crates/prc/src/tree/tests.rs b/crates/prc/src/tree/tests.rs index fe9c72aa5..bf5a38faf 100644 --- a/crates/prc/src/tree/tests.rs +++ b/crates/prc/src/tree/tests.rs @@ -647,7 +647,7 @@ fn a_colour_index_counts_doubles() { fn style_alpha_rules_combine_transparency_with_material_alpha() { let g = |alpha, transparency| Globals { colours: vec![BLUE], - materials: vec![Material::Plain { diffuse: 1, alpha }], + materials: vec![Material::Plain { diffuse: 1, emissive: 0, alpha }], styles: vec![Style { is_material: true, index: 1, transparency }], ..Globals::default() }; diff --git a/crates/prc/src/write/bits.rs b/crates/prc/src/write/bits.rs new file mode 100644 index 000000000..565f723a5 --- /dev/null +++ b/crates/prc/src/write/bits.rs @@ -0,0 +1,164 @@ +//! The bit-level writer for PRC compressed sections: the inverse of +//! [`crate::bits::BitReader`] for the types the writer emits [WD 10.3, +//! 11.1-11.17]. + +use crate::acof; + +/// An MSB-first bit sink. +/// +/// Every value the writer can be handed is encodable except a non-finite +/// `Double`; one of those is recorded and reported by [`Self::finish`] +/// rather than written. +#[derive(Debug, Default, Clone)] +pub(crate) struct BitWriter { + bytes: Vec, + len: usize, + non_finite: bool, +} + +impl BitWriter { + /// The low `n` bits of `v` (`n` ≤ 64), most significant first. + pub(crate) fn put(&mut self, v: u64, n: u32) -> &mut Self { + for i in (0..n).rev() { + self.bit((v >> i) & 1 == 1); + } + self + } + + /// One bit; a PRC `Boolean`. + pub(crate) fn bit(&mut self, b: bool) -> &mut Self { + if self.len.is_multiple_of(8) { + self.bytes.push(0); + } + if b && let Some(last) = self.bytes.last_mut() { + *last |= 0x80 >> (self.len % 8); + } + self.len += 1; + self + } + + /// Every bit of `other`, unaligned. + #[cfg(test)] + pub(crate) fn append(&mut self, other: &Self) -> &mut Self { + for i in 0..other.len { + let byte = other.bytes.get(i / 8).copied().unwrap_or(0); + self.bit((byte >> (7 - i % 8)) & 1 == 1); + } + self.non_finite |= other.non_finite; + self + } + + /// An `UnsignedInteger` [WD 11.2]: per byte, a continuation bit then + /// eight bits, low byte first; a final zero bit. + pub(crate) fn uint(&mut self, mut v: u32) -> &mut Self { + while v != 0 { + self.bit(true).put(u64::from(v & 0xff), 8); + v >>= 8; + } + self.bit(false) + } + + /// An `Integer` [WD 11.3]: two's-complement bytes, low first, each + /// followed by a continue bit. + pub(crate) fn int(&mut self, v: i32) -> &mut Self { + if v == 0 { + return self.bit(false); + } + self.bit(true); + let mut v = i64::from(v); + loop { + let byte = (v & 0xff) as u8; + self.put(u64::from(byte), 8); + v >>= 8; + let done = (v == 0 && byte & 0x80 == 0) || (v == -1 && byte & 0x80 != 0); + self.bit(!done); + if done { + return self; + } + } + } + + /// A `String` [WD 11.4]: presence bit, byte count, raw UTF-8 bytes. + pub(crate) fn string(&mut self, s: Option<&str>) -> &mut Self { + let Some(s) = s else { + return self.bit(false); + }; + self.bit(true).uint(u32::try_from(s.len()).unwrap_or(u32::MAX)); + for b in s.bytes() { + self.put(u64::from(b), 8); + } + self + } + + /// A `Double` [WD 11.17]: ±0 as the two-bit zero code; any other finite + /// value as its exponent row, the sign, then the mantissa as literal + /// bytes, never as a back-reference to a previous double (the + /// simplest form a reader can take; the writer never needs the others). + pub(crate) fn double(&mut self, v: f64) -> &mut Self { + if v == 0.0 { + return self.put(0b01, 2); + } + let bits = v.to_bits(); + let Some((n, c)) = v.is_finite().then(|| acof::exponent_code(((bits >> 52) & 0x7ff) as u32)).flatten() else { + self.non_finite = true; + return self.put(0b01, 2); + }; + let le = bits.to_le_bytes(); + self.put(u64::from(c), n).bit(v < 0.0).bit(true).put(u64::from(le[6] & 0x0f), 4); + for &b in le[..6].iter().rev() { + self.bit(true).put(u64::from(b), 8); + } + self + } + + /// `n` doubles. + pub(crate) fn doubles(&mut self, vs: impl IntoIterator) -> &mut Self { + for v in vs { + self.double(v); + } + self + } + + /// The packed bytes, or `None` when a non-finite double was written. + pub(crate) fn finish(self) -> Option> { + (!self.non_finite).then_some(self.bytes) + } +} + +#[cfg(test)] +#[allow(clippy::unwrap_used)] +mod tests { + use super::*; + use crate::bits::BitReader; + + #[test] + fn every_type_reads_back() { + let values = [1.0, -0.5, 1e-300, 123_456.789, -6.02e23, 0.0, 2000.0]; + let mut w = BitWriter::default(); + w.uint(0).uint(300).int(-129).int(4).string(Some("glass")); + w.string(None).doubles(values); + let bytes = w.finish().unwrap(); + let mut r = BitReader::new(&bytes); + assert_eq!(r.unsigned_integer().unwrap(), 0); + assert_eq!(r.unsigned_integer().unwrap(), 300); + assert_eq!(r.integer().unwrap(), -129); + assert_eq!(r.integer().unwrap(), 4); + assert_eq!(r.string().unwrap().as_deref(), Some("glass")); + assert_eq!(r.string().unwrap(), None); + for v in values { + assert_eq!(r.double().unwrap(), v); + } + } + + #[test] + fn a_non_finite_double_fails_the_section() { + let mut w = BitWriter::default(); + w.double(f64::NAN); + assert!(w.finish().is_none()); + let mut inner = BitWriter::default(); + inner.double(f64::INFINITY); + let mut w = BitWriter::default(); + w.append(&inner); + assert!(w.finish().is_none()); + } +} diff --git a/crates/prc/src/write/bounds.rs b/crates/prc/src/write/bounds.rs new file mode 100644 index 000000000..b03c33b7a --- /dev/null +++ b/crates/prc/src/write/bounds.rs @@ -0,0 +1,45 @@ +//! The box a scene's triangles fill, for fitting a camera to it. + +use super::MeshScene; +use crate::Matrix; + +impl MeshScene { + /// The smallest axis-aligned box `[min, max]` holding every vertex of every triangle the + /// scene draws, placed by its nodes' matrices, in scene units. `None` when it draws no + /// triangle or a placed coordinate is not finite. Each node is visited once, so a scene that + /// is not a forest (which [`write_prc`](super::write_prc) refuses) still ends. + #[must_use] + pub fn bounds(&self) -> Option<[[f64; 3]; 2]> { + let mut seen = vec![false; self.nodes.len()]; + let mut stack: Vec<(usize, Matrix)> = self.roots.iter().map(|&r| (r, Matrix::IDENTITY)).collect(); + let mut out: Option<[[f64; 3]; 2]> = None; + while let Some((index, parent)) = stack.pop() { + let (Some(node), Some(visited)) = (self.nodes.get(index), seen.get_mut(index)) else { continue }; + if std::mem::replace(visited, true) { + continue; + } + let world = node.matrix.map_or(parent, |m| parent.multiply(&column_major(&m))); + for p in node.mesh.and_then(|m| self.meshes.get(m)).into_iter().flat_map(|m| &m.primitives) { + for i in p.triangles.iter().flatten() { + let Some(v) = usize::try_from(*i).ok().and_then(|i| p.positions.get(i)) else { continue }; + let q = world.transform_point(*v); + if !q.iter().all(|c| c.is_finite()) { + return None; + } + let [lo, hi] = out.get_or_insert([q, q]); + for ((l, h), c) in lo.iter_mut().zip(hi.iter_mut()).zip(q) { + *l = l.min(c); + *h = h.max(c); + } + } + } + stack.extend(node.children.iter().map(|&c| (c, world))); + } + out + } +} + +/// A column-major 4×4 matrix (glTF's order) as a [`Matrix`]. +fn column_major(m: &[f64; 16]) -> Matrix { + Matrix(std::array::from_fn(|row| std::array::from_fn(|col| m.get(col * 4 + row).copied().unwrap_or(0.0)))) +} diff --git a/crates/prc/src/write/container.rs b/crates/prc/src/write/container.rs new file mode 100644 index 000000000..e98f5007e --- /dev/null +++ b/crates/prc/src/write/container.rs @@ -0,0 +1,80 @@ +//! The PRC container writer: the file header, file-structure descriptions, +//! each structure's header and its five zlib sections, then the model file +//! [WD 6.1-6.2, 10.2]. The inverse of [`crate::PrcFile::parse`]. + +use std::io::Write as _; + +use crate::{PRC_READER_VERSION, UniqueId}; + +/// One file structure: its id, its five inflated sections in +/// [`crate::SectionKind`] order, and the uncompressed files its header +/// carries (texture pictures, WD 6.2.2). +pub(crate) struct Structure<'a> { + pub(crate) id: UniqueId, + pub(crate) sections: [&'a [u8]; 5], + pub(crate) files: Vec<&'a [u8]>, +} + +/// The ids a container carries besides its structures'. +pub(crate) struct Ids { + pub(crate) file: UniqueId, + pub(crate) application: UniqueId, +} + +fn zlib(data: &[u8]) -> Vec { + let mut e = flate2::write::ZlibEncoder::new(Vec::new(), flate2::Compression::default()); + // Writing into a Vec cannot fail. + drop(e.write_all(data)); + e.finish().unwrap_or_default() +} + +fn le(out: &mut Vec, vs: &[u32]) { + vs.iter().for_each(|v| out.extend_from_slice(&v.to_le_bytes())); +} + +/// Offsets past `u32::MAX` are unrepresentable; `None` then. +fn offset(at: usize) -> Option { + u32::try_from(at).ok() +} + +/// The PRC stream: version 8137 for reading and authoring (the version +/// this crate's reader is tested against), no file-header uncompressed files. `None` past 4 GiB. +pub(crate) fn container(structures: &[Structure<'_>], model: &[u8], ids: &Ids) -> Option> { + let v = PRC_READER_VERSION; + // "PRC", 2 versions, 2 ids, count; 48 bytes per description; model + // extent; uncompressed-file count. + let header_len = 3 + 4 * 11 + 48 * structures.len() + 8 + 4; + let mut body = Vec::new(); + let mut descriptions = Vec::new(); + for s in structures { + let start = offset(header_len + body.len())?; + body.extend_from_slice(b"PRC"); + le(&mut body, &[v, v]); + le(&mut body, &s.id.0); + le(&mut body, &ids.application.0); + le(&mut body, &[u32::try_from(s.files.len()).ok()?]); + for f in &s.files { + le(&mut body, &[u32::try_from(f.len()).ok()?]); + body.extend_from_slice(f); + } + le(&mut descriptions, &s.id.0); + le(&mut descriptions, &[0, 6, start]); + for section in s.sections { + le(&mut descriptions, &[offset(header_len + body.len())?]); + body.extend(zlib(section)); + } + } + let mf_start = offset(header_len + body.len())?; + body.extend(zlib(model)); + let mf_end = offset(header_len + body.len())?; + + let mut out = b"PRC".to_vec(); + le(&mut out, &[v, v]); + le(&mut out, &ids.file.0); + le(&mut out, &ids.application.0); + le(&mut out, &[u32::try_from(structures.len()).ok()?]); + out.extend(descriptions); + le(&mut out, &[mf_start, mf_end, 0]); + out.extend(body); + Some(out) +} diff --git a/crates/prc/src/write/mod.rs b/crates/prc/src/write/mod.rs new file mode 100644 index 000000000..150fa66de --- /dev/null +++ b/crates/prc/src/write/mod.rs @@ -0,0 +1,287 @@ +//! Writing a triangle-mesh scene as a PRC stream (Adobe PRC 8137, the +//! format 3D PDF embeds as `/Subtype /PRC`). +//! +//! The scene is a node hierarchy over shared meshes, the shape glTF and +//! most mesh formats carry. Each node becomes a `ProductOccurrence` named +//! for it (the names a viewer's model tree lists), each referenced mesh a +//! `PartDefinition`, each primitive a poly-B-rep item over one `TESS_3D` +//! styled by its material's RGB colour and transparency, or by a base-colour +//! texture over stored (u, v) coordinates. + +mod bits; +mod bounds; +mod container; +mod sections; +mod tess; +mod textures; +mod validate; +mod vec3; + +#[cfg(test)] +pub(crate) mod readback; +#[cfg(test)] +mod tests; + +use crate::UniqueId; + +pub(crate) use bits::BitWriter; + +/// How a texture repeats outside the 0–1 coordinate range. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)] +#[non_exhaustive] +pub enum TextureWrap { + /// Tiled. + #[default] + Repeat, + /// The edge texels extended. + Clamp, + /// Tiled, every other tile mirrored. + MirroredRepeat, +} + +/// A triangle-mesh scene to write as PRC. +/// +/// `nodes` form a forest: every index in [`SceneNode::children`] and +/// [`Self::roots`] names a node, no node has two parents, and a root has +/// none. Nodes no root reaches are not written. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct MeshScene { + /// Every node. + pub nodes: Vec, + /// The top-level nodes. More than one is written under an unnamed + /// root occurrence. + pub roots: Vec, + /// Meshes, shared by any number of nodes. + pub meshes: Vec, + /// Materials, named by [`ScenePrimitive::material`]. + pub materials: Vec, + /// Textures, named by [`SceneMaterial::texture`]. + pub textures: Vec, + /// Millimetres per scene unit: 1000 for metres (glTF), 1 for + /// millimetres. Positive and finite. + pub units_in_mm: f64, +} + +/// One node: a placement, an optional mesh, children. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct SceneNode { + /// The name a model tree shows; `None` writes a null name. + pub name: Option, + /// Placement relative to the parent, a column-major 4×4 matrix (glTF's + /// order); `None` for identity. The bottom row must be `0 0 0 1`. + pub matrix: Option<[f64; 16]>, + /// Index into [`MeshScene::meshes`]. + pub mesh: Option, + /// Indices into [`MeshScene::nodes`]. + pub children: Vec, +} + +/// A mesh: one or more primitives, each with its own material. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct SceneMesh { + /// The part name. + pub name: Option, + /// Its primitives; one with no triangles is not written. + pub primitives: Vec, +} + +/// One indexed triangle list. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct ScenePrimitive { + /// Vertex positions, in scene units. + pub positions: Vec<[f64; 3]>, + /// Per-vertex normals, the same length as `positions`; empty to have + /// the writer compute one flat normal per triangle (reported in + /// [`PrcWriteReport::flat_normals`]). + pub normals: Vec<[f64; 3]>, + /// Counter-clockwise triangles, indexing `positions`. + pub triangles: Vec<[u32; 3]>, + /// Index into [`MeshScene::materials`]; `None` leaves the colour to + /// the viewer. + pub material: Option, + /// Texture coordinates per vertex, the same length as `positions`, or + /// empty. (0, 0) is the picture's bottom-left corner and (1, 1) its + /// top-right. Written only when the material is textured; a textured + /// material over a primitive with none draws its base colour. + pub uvs: Vec<[f64; 2]>, +} + +/// A material as PRC can display it: one colour, its opacity and the +/// light it gives off. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct SceneMaterial { + /// The material's name (carried in the scene only; PRC styles are + /// unnamed). + pub name: Option, + /// Display (sRGB-encoded) red, green, blue and opacity, each 0–1; + /// opacity 1 is opaque. Values outside 0–1 are clamped. + pub rgba: [f64; 4], + /// Index into [`MeshScene::textures`]: a picture multiplying `rgba` + /// over the primitive's [`ScenePrimitive::uvs`]. + pub texture: Option, + /// Display (sRGB-encoded) light the surface gives off, each 0–1 + /// (clamped); black for none. A non-black one is written as the + /// material's emissive colour [WD 7.5.4], so its primitives are drawn + /// through a material style; a textured material's primitive without + /// coordinates is drawn in its RGB style and does not glow. + pub emissive: [f64; 3], +} + +/// A base-colour picture. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct SceneTexture { + /// A complete PNG or JPEG file, stored in the PRC as it is. + pub image: Vec, + /// Wrapping along u, then v. + pub wrap: [TextureWrap; 2], + /// Whether the picture's alpha multiplies the material's opacity; + /// otherwise only its colour is used. + pub alpha: bool, +} + +/// A written PRC stream and what the writer had to supply itself. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PrcWriteReport { + /// The PRC stream, ready for a 3D PDF's `/Subtype /PRC` stream. + pub prc: Vec, + /// Triangles written. + pub triangles: usize, + /// Primitives that had no normals, given flat per-triangle ones. + pub flat_normals: usize, + /// Primitives left out for holding no triangles. + pub empty_primitives: usize, + /// Primitives written with a texture and coordinates. + pub textured: usize, +} + +/// Why a scene could not be written. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +#[non_exhaustive] +pub enum PrcWriteError { + /// The scene draws nothing: no root reaches a triangle. + #[error("the scene holds no triangles")] + Empty, + /// An index names nothing: `what` with the offending `index`. + #[error("{what} index {index} is out of range")] + BadIndex { + /// What the index was for. + what: &'static str, + /// The value found. + index: usize, + }, + /// The nodes are not a forest (a node with two parents, a parented + /// root, or a nesting deeper than [`MAX_NODE_DEPTH`]). + #[error("the node hierarchy is not a tree: {0}")] + NotATree(&'static str), + /// A coordinate, normal, matrix entry, colour (emissive too) or the unit is NaN or + /// infinite, or the unit is not positive. + #[error("the scene holds a non-finite or invalid number ({0})")] + BadNumber(&'static str), + /// The scene's counts or the stream exceed what PRC can address + /// (32-bit counts and offsets). + #[error("the scene is too large for a PRC stream")] + TooLarge, + /// Texture `index` is not a PNG or JPEG file whose size can be read. + #[error("texture {index} is not a readable PNG or JPEG file")] + BadTexture { + /// Index into [`MeshScene::textures`]. + index: usize, + }, +} + +/// The deepest node nesting the writer accepts, counting a root as 1: this +/// crate's reader walks 64 levels below the root occurrence, and the writer +/// may add a root of its own. +pub const MAX_NODE_DEPTH: usize = 64; + +/// Write `scene` as a single-file-structure PRC stream. +/// +/// # Errors +/// +/// [`PrcWriteError`] when the scene is not a valid forest over valid +/// indices, holds a non-finite number or an unreadable texture, or draws +/// no triangle. +/// +/// # Example +/// +/// ``` +/// use craft_prc::{MeshScene, SceneMesh, SceneNode, ScenePrimitive, write_prc}; +/// +/// let tri = ScenePrimitive { +/// positions: vec![[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]], +/// triangles: vec![[0, 1, 2]], +/// ..ScenePrimitive::default() +/// }; +/// let scene = MeshScene { +/// nodes: vec![SceneNode { name: Some("tri".into()), mesh: Some(0), ..SceneNode::default() }], +/// roots: vec![0], +/// meshes: vec![SceneMesh { name: None, primitives: vec![tri] }], +/// materials: vec![], +/// textures: vec![], +/// units_in_mm: 1000.0, +/// }; +/// let report = write_prc(&scene)?; +/// assert_eq!(report.triangles, 1); +/// assert_eq!(report.flat_normals, 1); +/// let prc = craft_prc::PrcFile::parse(&report.prc).unwrap(); +/// assert_eq!(prc.placements().unwrap().len(), 1); +/// # Ok::<(), craft_prc::PrcWriteError>(()) +/// ``` +pub fn write_prc(scene: &MeshScene) -> Result { + let plan = validate::plan(scene)?; + let ids = ids(scene); + let tess = tess::section(scene, &plan)?; + let globals = sections::globals(scene, &plan).finish(); + let tree = sections::tree(scene, &plan).finish(); + let geometry = sections::empty_geometry(306).finish(); + let extra = sections::empty_geometry(307).finish(); + let model = sections::model_file(scene, &plan, ids.structure).finish(); + let (Some(globals), Some(tree), Some(geometry), Some(extra), Some(model)) = (globals, tree, geometry, extra, model) else { + return Err(PrcWriteError::BadNumber("matrix, colour or unit")); + }; + let structure = container::Structure { + id: ids.structure, + sections: [&globals, &tree, &tess.bytes, &geometry, &extra], + files: scene.textures.iter().map(|t| t.image.as_slice()).collect(), + }; + let prc = container::container(&[structure], &model, &ids.container).ok_or(PrcWriteError::TooLarge)?; + Ok(PrcWriteReport { + prc, + triangles: tess.triangles, + flat_normals: tess.flat_normals, + empty_primitives: plan.empty_primitives, + textured: tess.textured, + }) +} + +struct AllIds { + structure: UniqueId, + container: container::Ids, +} + +/// FNV-1a over the scene's debug form: the same scene always gets the same +/// ids, so writing is deterministic, and different scenes differ. +fn ids(scene: &MeshScene) -> AllIds { + struct Fnv(u64); + impl std::fmt::Write for Fnv { + fn write_str(&mut self, s: &str) -> std::fmt::Result { + for b in s.bytes() { + self.0 = (self.0 ^ u64::from(b)).wrapping_mul(0x0100_0000_01b3); + } + Ok(()) + } + } + let mut fnv = Fnv(0xcbf2_9ce4_8422_2325); + // Formatting into a hasher cannot fail. + std::fmt::Write::write_fmt(&mut fnv, format_args!("{scene:?}")).ok(); + let h = fnv.0; + let (hi, lo) = ((h >> 32) as u32, h as u32); + AllIds { + structure: UniqueId([hi, lo, 0x6372_6166, 1]), + container: container::Ids { + file: UniqueId([hi, lo, 0x6372_6166, 0]), + // "craf" "tlib": who wrote the stream. + application: UniqueId([0x6661_7263, 0x6269_6c74, 0, 1]), + }, + } +} diff --git a/crates/prc/src/write/readback.rs b/crates/prc/src/write/readback.rs new file mode 100644 index 000000000..f61e5a840 --- /dev/null +++ b/crates/prc/src/write/readback.rs @@ -0,0 +1,32 @@ +//! Test-only: a written stream read back through this crate's reader. + +#![allow(clippy::unwrap_used, clippy::expect_used)] + +use crate::{PrcFile, Tessellation, TriangleMesh}; + +/// What a PRC stream draws, every placement in world coordinates. +#[derive(Debug, Default)] +pub(crate) struct Model { + /// Triangles over every placement. + pub(crate) triangles: usize, + /// Each placement's colour as straight 8-bit RGBA. + pub(crate) colours: Vec>, + /// Each placement's mesh, placed. + pub(crate) meshes: Vec, +} + +/// `prc` parsed and its placements resolved to placed meshes. +pub(crate) fn assemble(prc: &[u8]) -> Model { + let file = PrcFile::parse(prc).unwrap(); + let tessellations: Vec> = file.file_structures.iter().map(|fs| fs.tessellations().unwrap()).collect(); + let mut out = Model::default(); + for p in file.placements().unwrap() { + let Some(Tessellation::Mesh(mesh)) = tessellations.get(p.file_structure).and_then(|t| t.get(p.tessellation)) else { + panic!("placement {p:?} names no mesh"); + }; + out.triangles += mesh.triangles.len(); + out.colours.push(p.colour.map(|c| [c.r, c.g, c.b, c.a].map(|v| (v.clamp(0.0, 1.0) * 255.0).round() as u8))); + out.meshes.push(mesh.transformed(&p.matrix)); + } + out +} diff --git a/crates/prc/src/write/sections.rs b/crates/prc/src/write/sections.rs new file mode 100644 index 000000000..4bc8912d4 --- /dev/null +++ b/crates/prc/src/write/sections.rs @@ -0,0 +1,300 @@ +//! The globals (303), tree (304 + 302), empty geometry (306, 307) and +//! model-file (301) entities [WD 7.3.3-7.3.11, 7.4.9-7.4.11, 7.5.3]. + +use super::validate::Plan; +use super::vec3::{cross, dot}; +use super::{BitWriter, MeshScene, SceneMaterial}; +use crate::UniqueId; + +const MODEL_FILE: u32 = 301; +const FILE_STRUCTURE: u32 = 302; +const GLOBALS: u32 = 303; +const TREE: u32 = 304; +const PRODUCT_OCCURRENCE: u32 = 310; +const PART_DEFINITION: u32 = 311; +const CARTESIAN_TRANSFORMATION: u32 = 202; +const GENERAL_TRANSFORMATION: u32 = 207; +const RI_POLY_BREP_MODEL: u32 = 237; +const STYLE: u32 = 701; +const LINE_PATTERN: u32 = 721; + +/// `PRC_GRAPHICS_Show` [WD 7.2.4.2]. +const SHOW: u16 = 0x0001; +/// `EPRCProductLoadStatus` given to every product written. +const LOAD_STATUS: i32 = 4; + +/// `ContentPRCBase` with no attributes and the current (section-start: +/// empty) name [WD 7.2.3]. +pub(super) fn base(w: &mut BitWriter) { + w.uint(0).bit(true); +} + +/// `ContentPRCBase` naming the entity explicitly; `None` is a null name. +fn named(w: &mut BitWriter, name: Option<&str>) { + w.uint(0).bit(false).string(name); +} + +/// `ContentPRCRefBase`: `ContentPRCBase`, CAD ids 0, then `id`. +pub(super) fn ref_base(w: &mut BitWriter, name: Option>, id: u32) { + match name { + None => base(w), + Some(n) => named(w, n), + } + w.uint(0).uint(0).uint(id); +} + +/// `PRCBaseWithGraphics` with explicit graphics: no layer, line style +/// `style` (`None` inheriting), behaviour Show. +fn graphics(w: &mut BitWriter, name: Option<&str>, id: u32, style: Option) { + ref_base(w, Some(name), id); + w.bit(false).uint(0).uint(style.map_or(0, |s| s + 1)).put(u64::from(SHOW & 0xff), 8).put(u64::from(SHOW >> 8), 8); +} + +/// Unique ids for referenceable entities, from 1. +struct Ids(u32); + +impl Ids { + fn next(&mut self) -> u32 { + self.0 += 1; + self.0 + } +} + +/// The globals section: an empty schema, one colour and one RGB style per +/// material, then the emissive colours, the texture entities, one material +/// style per textured and per glowing material, and the solid line pattern +/// every style names. +pub(super) fn globals(scene: &MeshScene, plan: &Plan) -> BitWriter { + let mut w = BitWriter::default(); + w.uint(0).uint(GLOBALS); + base(&mut w); + // No referenced structures; chord and angle tolerances; markup font + // helper empty. + w.uint(0).double(2000.0).double(40.0).string(Some("")).uint(0); + let emissive = super::textures::emissive_colours(scene); + let emissive_first = scene.materials.len() as u32; + w.uint(emissive_first + emissive.len() as u32); + for m in &scene.materials { + w.doubles(m.rgba[..3].iter().map(|c| c.clamp(0.0, 1.0))); + } + for c in emissive { + w.doubles(c); + } + let styles = plan.styles(scene) as u32; + super::textures::pictures(&mut w, &plan.pictures); + super::textures::definitions(&mut w, scene, 2 + styles); + let first = 2 + styles + scene.textures.len() as u32; + super::textures::materials(&mut w, (scene, plan), emissive_first, first); + w.uint(1).uint(LINE_PATTERN); + ref_base(&mut w, None, 1); + w.uint(2).double(1.0e6).double(0.0).double(0.0).bit(false); + w.uint(styles); + for (k, m) in scene.materials.iter().enumerate() { + w.uint(STYLE); + ref_base(&mut w, None, 2 + k as u32); + // Width 1, no vpicture, line pattern 1 (biased), an RGB colour + // (double-scaled biased index, WD 7.5.3). + w.double(1.0).bit(false).uint(1).bit(false); + w.uint(3 * k as u32 + 1); + transparency(&mut w, m); + w.bit(false).bit(false).bit(false); + } + for j in 0..plan.textured.len() as u32 { + w.uint(STYLE); + ref_base(&mut w, None, 2 + scene.materials.len() as u32 + j); + // As above, but a material: the TextureApplication entry (biased). + // The material carries the alpha too, but a reader may take a + // material alpha of 0 under a style without one as unset. + w.double(1.0).bit(false).uint(1).bit(true); + w.uint(2 * j + 2); + match plan.textured.get(j as usize).and_then(|&m| scene.materials.get(m)) { + Some(m) => transparency(&mut w, m), + None => { + w.bit(false); + } + } + w.bit(false).bit(false).bit(false); + } + let pairs = 2 * plan.textured.len() as u32; + let first_glow = 2 + (scene.materials.len() + plan.textured.len()) as u32; + for g in 0..plan.glowing.len() as u32 { + w.uint(STYLE); + ref_base(&mut w, None, first_glow + g); + // A material style naming the glowing material's `Material` + // (biased entry), which carries its own alpha. + w.double(1.0).bit(false).uint(1).bit(true); + w.uint(pairs + g + 1); + w.bit(false).bit(false).bit(false).bit(false); + } + // Fill patterns, reference coordinate systems, user data. + w.uint(0).uint(0).uint(0); + w +} + +/// An empty exact-geometry (306) or extra-geometry (307) section: no +/// topological contexts [WD 7.3.8, 7.3.9]. Viewers reject a zero-byte one. +pub(super) fn empty_geometry(kind: u32) -> BitWriter { + let mut w = BitWriter::default(); + w.uint(kind); + base(&mut w); + w.uint(0).uint(0); + w +} + +/// The tree section: parts, occurrences, then the file structure's +/// internal data. +pub(super) fn tree(scene: &MeshScene, plan: &Plan) -> BitWriter { + let mut ids = Ids(plan.global_ids(scene)); + let mut w = BitWriter::default(); + w.uint(TREE); + base(&mut w); + w.uint(plan.parts.len() as u32); + let mut tess = 0u32; + for &m in &plan.parts { + part(&mut w, scene, plan, m, &mut tess, &mut ids); + } + w.uint(plan.occurrences.len() as u32); + for o in &plan.occurrences { + occurrence(&mut w, scene, plan, o, &mut ids); + } + w.uint(FILE_STRUCTURE); + base(&mut w); + // The root occurrence is the last (biased index = count). + let next = ids.next(); + w.uint(next).uint(plan.occurrences.len() as u32).uint(0); + w +} + +/// Mesh `m`'s part: its bounding box and one poly-B-rep item per +/// tessellated primitive, numbered on from `tess`. +fn part(w: &mut BitWriter, scene: &MeshScene, plan: &Plan, m: usize, tess: &mut u32, ids: &mut Ids) { + let mesh = scene.meshes.get(m); + w.uint(PART_DEFINITION); + graphics(w, mesh.and_then(|m| m.name.as_deref()), ids.next(), None); + let mut lo = [f64::INFINITY; 3]; + let mut hi = [f64::NEG_INFINITY; 3]; + // A part's tessellations follow the previous parts', in part order. + let ours = plan.tessellations.get(*tess as usize..).unwrap_or(&[]).iter().take_while(|t| t.0 == m); + let prims: Vec<_> = ours.filter_map(|&(_, p)| mesh?.primitives.get(p)).collect(); + for v in prims.iter().flat_map(|p| &p.positions) { + for ((l, h), c) in lo.iter_mut().zip(hi.iter_mut()).zip(v) { + *l = l.min(*c); + *h = h.max(*c); + } + } + if prims.is_empty() { + (lo, hi) = ([1.0, 0.0, 0.0], [-1.0, 0.0, 0.0]); + } + w.doubles(lo).doubles(hi); + w.uint(prims.len() as u32); + for p in prims { + w.uint(RI_POLY_BREP_MODEL); + graphics(w, None, ids.next(), plan.style_of(scene, p)); + *tess += 1; + // No local coordinate system; tessellation (biased); not closed; + // no user data. + w.uint(0).uint(*tess).bit(false).uint(0); + } + // Markups (4 lists), views, user data. + w.uint(0).uint(0).uint(0).uint(0).uint(0).uint(0); +} + +fn occurrence(w: &mut BitWriter, scene: &MeshScene, plan: &Plan, o: &super::validate::Occ, ids: &mut Ids) { + let node = o.node.and_then(|n| scene.nodes.get(n)); + w.uint(PRODUCT_OCCURRENCE); + graphics(w, node.and_then(|n| n.name.as_deref()), ids.next(), None); + let part = node.and_then(|n| n.mesh).and_then(|m| *plan.part_of_mesh.get(m)?).map_or(0, |p| p + 1); + // Part (biased), no prototype, no external data, sons (raw). + w.uint(part).uint(0).uint(0).uint(o.sons.len() as u32); + for &s in &o.sons { + w.uint(s); + } + // Not suppressed; ProductInformation: units from the scene, no flags. + w.put(0, 8).bit(true).double(scene.units_in_mm).put(0, 8).int(LOAD_STATUS); + let matrix = node.and_then(|n| n.matrix).filter(|m| *m != IDENTITY); + w.bit(matrix.is_some()); + if let Some(m) = matrix { + transformation(w, &m); + } + // No entity references, markups (4 lists), views, no entity filter, + // display filters, scene display parameters, user data. + w.uint(0).uint(0).uint(0).uint(0).uint(0).uint(0); + w.bit(false).uint(0).uint(0).uint(0); +} + +const IDENTITY: [f64; 16] = [1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0]; + +/// A rotation (possibly mirrored) times a uniform scale as a +/// `CartesianTransformation` [WD 7.4.11]; anything else (shear, non-uniform +/// scale) as a column-major `GeneralTransformation` [WD 7.4.9]. +fn transformation(w: &mut BitWriter, m: &[f64; 16]) { + let mut cols = [[0.0; 3]; 4]; + for (dst, src) in cols.iter_mut().zip(m.as_chunks::<4>().0) { + for (d, s) in dst.iter_mut().zip(src) { + *d = *s; + } + } + let [x, y, z, t] = cols; + let det = dot(x, cross(y, z)); + let s = det.abs().cbrt(); + let unit = |v: [f64; 3]| v.map(|c| c / s); + let (rx, ry, rz) = (unit(x), unit(y), unit(z)); + let orthonormal = s > 1e-12 + && [(rx, rx, 1.0), (ry, ry, 1.0), (rz, rz, 1.0), (rx, ry, 0.0), (rx, rz, 0.0), (ry, rz, 0.0)] + .iter() + .all(|&(a, b, e)| (dot(a, b) - e).abs() < 1e-9); + if !orthonormal { + w.uint(GENERAL_TRANSFORMATION).doubles(m.iter().copied()); + return; + } + let rotated = det < 0.0 || rx != [1.0, 0.0, 0.0] || ry != [0.0, 1.0, 0.0]; + let scaled = (s - 1.0).abs() > 1e-12; + let mut b = 0u8; + if t != [0.0; 3] { + b |= 0x01; + } + if rotated { + b |= 0x02; + } + if det < 0.0 { + b |= 0x04; + } + if scaled { + b |= 0x08; + } + w.uint(CARTESIAN_TRANSFORMATION).put(u64::from(b), 8); + if b & 0x01 != 0 { + w.doubles(t); + } + if rotated { + w.doubles(rx).doubles(ry); + } + if scaled { + w.double(s); + } +} + +/// The model file: an empty schema, the units, the one root. +pub(super) fn model_file(scene: &MeshScene, plan: &Plan, structure: UniqueId) -> BitWriter { + let mut w = BitWriter::default(); + w.uint(0).uint(MODEL_FILE); + base(&mut w); + w.bit(true).double(scene.units_in_mm).uint(1); + for c in structure.0 { + w.uint(c); + } + // Root occurrence, the last (biased), active; file structure 0's index + // in the model file; no user data. + w.uint(plan.occurrences.len() as u32).bit(true).uint(0).uint(0); + w +} + +/// A style's transparency: a flag, and when the material is not opaque its +/// alpha as a byte. +fn transparency(w: &mut BitWriter, m: &SceneMaterial) { + let alpha = m.rgba[3].clamp(0.0, 1.0); + w.bit(alpha < 1.0); + if alpha < 1.0 { + w.put((alpha * 255.0).round() as u64, 8); + } +} diff --git a/crates/prc/src/write/tess.rs b/crates/prc/src/write/tess.rs new file mode 100644 index 000000000..e9c2f5cb7 --- /dev/null +++ b/crates/prc/src/write/tess.rs @@ -0,0 +1,118 @@ +//! The tessellation section (305): one `TESS_3D` (172) per primitive, each +//! a single `TESS_Face` (174) of plain triangles [WD 7.3.7, 7.8.5, 7.8.9]. + +use super::validate::Plan; +use super::vec3; +use super::{BitWriter, MeshScene, PrcWriteError, ScenePrimitive}; + +const TESSELLATION: u32 = 305; +const TESS_3D: u32 = 172; +const TESS_FACE: u32 = 174; +/// `PRC_FACETESSDATA_Triangle` [WD 7.8.9.2]. +const TRIANGLE: u32 = 0x2; +/// `PRC_FACETESSDATA_TriangleTextured`: each corner's normal, texture and +/// point indices [WD 7.8.9.2]. +const TRIANGLE_TEXTURED: u32 = 0x0200; + +/// The written section and its counts. +pub(super) struct Section { + pub(super) bytes: Vec, + pub(super) triangles: usize, + pub(super) flat_normals: usize, + pub(super) textured: usize, +} + +/// Every planned primitive's mesh, in plan order. +pub(super) fn section(scene: &MeshScene, plan: &Plan) -> Result { + let mut w = BitWriter::default(); + w.uint(TESSELLATION).uint(0).bit(true); + w.uint(plan.tessellations.len() as u32); + let (mut triangles, mut flat_normals, mut textured) = (0, 0, 0); + for &(m, p) in &plan.tessellations { + let Some(prim) = scene.meshes.get(m).and_then(|m| m.primitives.get(p)) else { + continue; + }; + triangles += prim.triangles.len(); + flat_normals += usize::from(prim.normals.is_empty()); + let uvs = plan.is_textured(scene, prim); + textured += usize::from(uvs); + tess_3d(&mut w, prim, uvs); + } + w.uint(0); + let bytes = w.finish().ok_or(PrcWriteError::BadNumber("position or normal"))?; + Ok(Section { bytes, triangles, flat_normals, textured }) +} + +/// The unit normal of triangle `t`, or +z for a degenerate one. +fn face_normal(p: &ScenePrimitive, t: [u32; 3]) -> [f64; 3] { + let at = |i: u32| p.positions.get(i as usize).copied().unwrap_or([0.0; 3]); + let (a, b, c) = (at(t[0]), at(t[1]), at(t[2])); + // Scaled by a power of two (exactly) to at most 1 first, so finite corners far apart give + // no infinite edge or product. + let big = a.iter().chain(&b).chain(&c).fold(0.0f64, |m, x| m.max(x.abs())); + let scale = if big > 1.0 { 2.0f64.powi(-(big.log2().ceil() as i32)) } else { 1.0 }; + let (a, b, c) = (a.map(|x| x * scale), b.map(|x| x * scale), c.map(|x| x * scale)); + let n = vec3::cross(vec3::sub(b, a), vec3::sub(c, a)); + vec3::normalize(n).unwrap_or([0.0, 0.0, 1.0]) +} + +/// `p` as a `TESS_3D`; with `uvs`, its texture coordinates too, a corner's +/// pair at twice its vertex index. +fn tess_3d(w: &mut BitWriter, p: &ScenePrimitive, uvs: bool) { + // Not calculated; the coordinates. + w.uint(TESS_3D).bit(false); + w.uint(3 * p.positions.len() as u32); + w.doubles(p.positions.iter().flatten().copied()); + // Has faces; no loops (8137 >= 7039); normals stored, not to be + // recalculated (8137 >= 7047). + w.bit(true).bit(false).bit(false); + let flat = p.normals.is_empty(); + if flat { + w.uint(3 * p.triangles.len() as u32); + for &t in &p.triangles { + w.doubles(face_normal(p, t)); + } + } else { + w.uint(3 * p.normals.len() as u32); + w.doubles(p.normals.iter().flatten().copied()); + } + // No wire; the (normal, [texture,] point) offsets of every corner. + let per_corner = if uvs { 3 } else { 2 }; + w.uint(0).uint(3 * per_corner * p.triangles.len() as u32); + for (k, t) in p.triangles.iter().enumerate() { + for v in t { + let n = if flat { k as u32 } else { *v }; + w.uint(3 * n); + if uvs { + w.uint(2 * v); + } + w.uint(3 * v); + } + } + // One face: no line attributes or wires, triangles from index 0, one + // texture-coordinate set or none, no vertex colours. + w.uint(1).uint(TESS_FACE).uint(0).uint(0).uint(0); + w.uint(if uvs { TRIANGLE_TEXTURED } else { TRIANGLE }).uint(0).uint(1).uint(p.triangles.len() as u32); + w.uint(u32::from(uvs)).bit(false); + if uvs { + w.uint(2 * p.uvs.len() as u32); + w.doubles(p.uvs.iter().flatten().copied()); + } else { + w.uint(0); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_huge_triangle_keeps_its_normal() { + let p = ScenePrimitive { positions: vec![[0.0; 3], [0.0, 1e200, 0.0], [0.0, 0.0, 1e200]], ..ScenePrimitive::default() }; + assert_eq!(face_normal(&p, [0, 1, 2]), [1.0, 0.0, 0.0]); + let p = ScenePrimitive { positions: vec![[-1e308, 0.0, 0.0], [1e308, 0.0, 0.0], [1e308, 1e308, 0.0]], ..ScenePrimitive::default() }; + assert_eq!(face_normal(&p, [0, 1, 2]), [0.0, 0.0, 1.0]); + let p = ScenePrimitive { positions: vec![[0.0; 3], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]], ..ScenePrimitive::default() }; + assert_eq!(face_normal(&p, [0, 1, 2]), [1.0, 0.0, 0.0]); + } +} diff --git a/crates/prc/src/write/tests.rs b/crates/prc/src/write/tests.rs new file mode 100644 index 000000000..add63d3fc --- /dev/null +++ b/crates/prc/src/write/tests.rs @@ -0,0 +1,339 @@ +//! write_prc → reader round trips. + +#![allow(clippy::unwrap_used, clippy::indexing_slicing)] + +use super::readback::assemble; +use super::*; +use crate::PrcFile; + +fn tri(material: Option, dx: f64) -> ScenePrimitive { + ScenePrimitive { + positions: vec![[dx, 0.0, 0.0], [dx + 1.0, 0.0, 0.0], [dx, 1.0, 0.0]], + triangles: vec![[0, 1, 2]], + material, + ..ScenePrimitive::default() + } +} + +fn node(name: &str, mesh: Option, children: Vec) -> SceneNode { + SceneNode { name: Some(name.into()), mesh, children, ..SceneNode::default() } +} + +/// A frame over a glass pane and a shared bolt placed twice. +fn scene() -> MeshScene { + let mut bolt2 = node("bolt-2", Some(1), vec![]); + let mut m = [0.0; 16]; + for (i, v) in [1.0, 1.0, 1.0, 1.0].into_iter().enumerate() { + m[i * 5] = v; + } + m[12] = 10.0; + bolt2.matrix = Some(m); + MeshScene { + nodes: vec![node("frame", None, vec![1, 2, 3]), node("glass", Some(0), vec![]), node("bolt-1", Some(1), vec![]), bolt2], + roots: vec![0], + meshes: vec![ + SceneMesh { name: Some("pane".into()), primitives: vec![tri(Some(0), 0.0)] }, + SceneMesh { name: Some("bolt".into()), primitives: vec![tri(Some(1), 5.0), tri(None, 7.0)] }, + ], + materials: vec![ + SceneMaterial { name: Some("glass".into()), rgba: [0.2, 0.4, 0.6, 0.4], texture: None, emissive: [0.0; 3] }, + SceneMaterial { name: Some("steel".into()), rgba: [1.0, 0.0, 0.0, 1.0], texture: None, emissive: [0.0; 3] }, + ], + textures: vec![], + units_in_mm: 1000.0, + } +} + +#[test] +fn triangles_colours_and_alpha_read_back() { + let r = write_prc(&scene()).unwrap(); + assert_eq!((r.triangles, r.flat_normals, r.empty_primitives), (3, 3, 0)); + let m = assemble(&r.prc); + // The glass once, the bolt's two primitives at both placements. + assert_eq!(m.triangles, 5); + let mut colours: Vec<_> = m.colours.iter().flatten().copied().collect(); + colours.sort_unstable(); + assert!(colours.contains(&[51, 102, 153, 102]), "{colours:?}"); + assert_eq!(colours.iter().filter(|c| **c == [255, 0, 0, 255]).count(), 2); +} + +#[test] +fn node_names_reach_the_model_tree() { + let r = write_prc(&scene()).unwrap(); + let tree = PrcFile::parse(&r.prc).unwrap().model_tree().unwrap(); + let names: Vec<_> = tree.iter().map(|n| n.name.as_deref()).collect(); + assert_eq!(names, [Some("frame"), Some("glass"), Some("bolt-1"), Some("bolt-2")]); + assert_eq!(tree[3].parent, Some(0)); +} + +#[test] +fn a_translation_moves_the_second_placement() { + let m = assemble(&write_prc(&scene()).unwrap().prc); + let xs: Vec = m.meshes.iter().flat_map(|t| t.positions.iter().map(|p| p[0])).collect(); + // bolt-1's first primitive starts at x = 5; bolt-2's at 15. + assert!(xs.contains(&5.0) && xs.contains(&15.0), "{xs:?}"); +} + +#[test] +fn a_non_uniform_scale_is_a_general_transformation() { + let mut s = scene(); + let mut m = [0.0; 16]; + (m[0], m[5], m[10], m[15]) = (2.0, 1.0, 1.0, 1.0); + s.nodes[3].matrix = Some(m); + let a = assemble(&write_prc(&s).unwrap().prc); + let xs: Vec = a.meshes.iter().flat_map(|t| t.positions.iter().map(|p| p[0])).collect(); + assert!(xs.contains(&10.0) && xs.contains(&12.0), "{xs:?}"); +} + +#[test] +fn several_roots_get_one_synthetic_root() { + let mut s = scene(); + s.nodes[0].children = vec![1]; + s.roots = vec![0, 2, 3]; + let tree = PrcFile::parse(&write_prc(&s).unwrap().prc).unwrap().model_tree().unwrap(); + assert_eq!(tree.len(), 5); + assert_eq!(tree[0].name, None); + assert!(tree[1..].iter().all(|n| n.parent.is_some())); +} + +#[test] +fn writing_is_deterministic() { + assert_eq!(write_prc(&scene()).unwrap().prc, write_prc(&scene()).unwrap().prc); +} + +#[test] +fn invalid_scenes_are_refused() { + let mut s = scene(); + s.nodes[0].children.push(1); + s.nodes[2].children.push(1); + assert!(matches!(write_prc(&s), Err(PrcWriteError::NotATree(_)))); + let mut s = scene(); + s.roots = vec![1]; + s.nodes[0].children.clear(); + s.meshes[0].primitives[0].triangles[0] = [0, 1, 9]; + assert_eq!(write_prc(&s), Err(PrcWriteError::BadIndex { what: "vertex", index: 9 })); + let mut s = scene(); + s.meshes[0].primitives[0].positions[0][1] = f64::NAN; + assert!(matches!(write_prc(&s), Err(PrcWriteError::BadNumber(_)))); + let mut s = scene(); + s.units_in_mm = 0.0; + assert!(matches!(write_prc(&s), Err(PrcWriteError::BadNumber(_)))); + let mut s = scene(); + s.meshes.iter_mut().flat_map(|m| &mut m.primitives).for_each(|p| p.triangles.clear()); + assert_eq!(write_prc(&s), Err(PrcWriteError::Empty)); + assert_eq!(write_prc(&MeshScene::default()), Err(PrcWriteError::BadNumber("units_in_mm"))); +} + +#[test] +fn a_root_listed_twice_is_refused_not_written_twice() { + let mut s = scene(); + s.roots = vec![0; 100]; + assert_eq!(write_prc(&s), Err(PrcWriteError::NotATree("a root is listed twice"))); +} + +#[test] +fn a_cycle_is_refused_not_looped() { + let mut s = scene(); + s.nodes[1].children.push(0); + assert!(write_prc(&s).is_err()); +} + +#[test] +fn a_mirrored_rotation_reads_back() { + // 90° about z, then mirror z, scale 2, translate y by 3: x' = -2y, + // y' = 2x + 3. + let mut s = scene(); + let mut m = [0.0; 16]; + (m[1], m[4], m[10], m[13], m[15]) = (2.0, -2.0, -2.0, 3.0, 1.0); + s.nodes[3].matrix = Some(m); + let a = assemble(&write_prc(&s).unwrap().prc); + let pts: Vec<[f64; 3]> = a.meshes.iter().flat_map(|t| t.positions.clone()).collect(); + // bolt's first vertex (5,0,0) → (0,13,0); (5,1,0) → (-2,13,0). + let near = |q: [f64; 3]| pts.iter().any(|p| (0..3).all(|i| (p[i] - q[i]).abs() < 1e-9)); + assert!(near([0.0, 13.0, 0.0]) && near([-2.0, 13.0, 0.0]), "{pts:?}"); +} + +/// Every son precedes the occurrence that uses it [WD 7.3.6], so a reader +/// can resolve the tree in one forward pass. +#[test] +fn every_son_precedes_its_father_and_the_root_is_last() { + for roots in [vec![0], vec![0, 2, 3]] { + let mut s = scene(); + if roots.len() > 1 { + s.nodes[0].children = vec![1]; + } + s.roots = roots; + let occ = validate::plan(&s).unwrap().occurrences; + for (i, o) in occ.iter().enumerate() { + assert!(o.sons.iter().all(|&son| (son as usize) < i), "{i}"); + } + let root = occ.len() - 1; + let fathered = |k: usize| occ.iter().any(|o| o.sons.contains(&(k as u32))); + assert!(!fathered(root)); + assert!((0..root).all(fathered), "every other occurrence has a father"); + } +} + +#[test] +fn textures_are_checked_before_writing() { + let mut s = scene(); + s.materials[1].texture = Some(0); + assert_eq!(write_prc(&s), Err(PrcWriteError::BadIndex { what: "texture", index: 0 })); + s.textures = vec![SceneTexture { image: b"GIF89a".to_vec(), ..SceneTexture::default() }]; + assert_eq!(write_prc(&s), Err(PrcWriteError::BadTexture { index: 0 })); + let mut s = scene(); + s.meshes[0].primitives[0].uvs = vec![[0.0, 0.0]]; + assert!(matches!(write_prc(&s), Err(PrcWriteError::BadIndex { .. }))); + // Coordinates under an untextured material are not written. + let mut s = scene(); + s.meshes[0].primitives[0].uvs = vec![[0.0, 0.0]; 3]; + assert_eq!(write_prc(&s).unwrap().textured, 0); +} + +#[test] +fn texture_coordinates_read_back() { + let mut s = scene(); + // A PNG signature and header claiming 1 x 2: enough for the writer. + let image = b"\x89PNG\r\n\x1a\n\0\0\0\x0dIHDR\0\0\0\x01\0\0\0\x02".to_vec(); + s.textures = vec![SceneTexture { image: image.clone(), wrap: [TextureWrap::Clamp, TextureWrap::MirroredRepeat], alpha: false }]; + s.materials[1].texture = Some(0); + s.meshes[1].primitives[0].uvs = vec![[0.5, 0.1], [0.5, 0.1], [0.5, 0.9]]; + let r = write_prc(&s).unwrap(); + assert_eq!(r.textured, 1); + let file = PrcFile::parse(&r.prc).unwrap(); + let pictures: Vec<&Vec> = file.file_structures.iter().flat_map(|fs| &fs.pictures).collect(); + assert_eq!(pictures, [&image], "the picture is stored as it is"); + let m = assemble(&r.prc); + let with_uvs: Vec<_> = m.meshes.iter().filter(|t| !t.uvs.is_empty()).collect(); + assert_eq!(with_uvs.len(), 2, "the bolt's primitive at both placements"); + assert!(with_uvs.iter().all(|t| t.uvs == [[0.5, 0.1], [0.5, 0.1], [0.5, 0.9]])); +} + +/// The box holds every placed triangle, a child placed through its parent's matrix too. +#[test] +fn bounds_follow_each_node_through_its_parents() { + let mut s = scene(); + let mut lift = [0.0; 16]; + (lift[0], lift[5], lift[10], lift[15], lift[14]) = (1.0, 1.0, 1.0, 1.0, 2.0); + s.nodes[0].matrix = Some(lift); + // bolt-2 starts at x 5 + 10 and ends at 8 + 10; everything is raised to z 2 by the frame. + assert_eq!(s.bounds(), Some([[0.0, 0.0, 2.0], [18.0, 1.0, 2.0]])); + s.roots = vec![1]; + assert_eq!(s.bounds(), Some([[0.0, 0.0, 0.0], [1.0, 1.0, 0.0]]), "only what the roots reach"); + s.nodes[1].children = vec![1]; + assert_eq!(s.bounds(), Some([[0.0, 0.0, 0.0], [1.0, 1.0, 0.0]]), "a cycle ends"); + s.roots = vec![99]; + assert_eq!(s.bounds(), None, "nothing drawn"); +} + +/// `prc`'s materials' emissive colours as `[r, g, b]`, the unlit ones dropped. +fn emissives(prc: &[u8]) -> Vec<[f64; 3]> { + let all = PrcFile::parse(prc).unwrap().material_emissives().unwrap(); + all.into_iter().flatten().flatten().map(|c| [c.r, c.g, c.b]).collect() +} + +#[test] +fn an_emissive_colour_reads_back_on_its_material_only() { + let mut s = scene(); + s.materials[0].emissive = [0.0, 0.5, 1.0]; + let prc = write_prc(&s).unwrap().prc; + assert_eq!(emissives(&prc), [[0.0, 0.5, 1.0]]); + // The glass keeps its colour and alpha through the material style. + let colours: Vec<_> = assemble(&prc).colours.into_iter().flatten().collect(); + assert!(colours.contains(&[51, 102, 153, 102]), "{colours:?}"); + assert!(emissives(&write_prc(&scene()).unwrap().prc).is_empty()); + // A wholly transparent material does not glow. + s.materials[0].rgba[3] = 0.0; + assert!(emissives(&write_prc(&s).unwrap().prc).is_empty()); +} + +#[test] +fn a_textured_material_carries_its_glow() { + let mut s = scene(); + let image = b"\x89PNG\r\n\x1a\n\0\0\0\x0dIHDR\0\0\0\x01\0\0\0\x02".to_vec(); + s.textures = vec![SceneTexture { image, wrap: [TextureWrap::Clamp, TextureWrap::Clamp], alpha: false }]; + s.materials[1].texture = Some(0); + s.materials[1].emissive = [1.0, 0.0, 0.0]; + s.meshes[1].primitives[0].uvs = vec![[0.5, 0.1], [0.5, 0.1], [0.5, 0.9]]; + let r = write_prc(&s).unwrap(); + assert_eq!(r.textured, 1); + assert_eq!(emissives(&r.prc), [[1.0, 0.0, 0.0]]); +} + +/// A chain of `n` nodes, the last holding the pane. +fn chain(n: usize) -> MeshScene { + let mut s = scene(); + s.nodes = (0..n).map(|i| node("link", (i + 1 == n).then_some(0), if i + 1 < n { vec![i + 1] } else { vec![] })).collect(); + s +} + +/// The writer accepts no deeper nesting than this crate's reader walks, with +/// one root or with the root the writer adds over several. +#[test] +fn the_deepest_accepted_chain_reads_back() { + for roots in [1, 2] { + let mut s = chain(MAX_NODE_DEPTH); + if roots == 2 { + s.nodes.push(node("bolt", Some(1), vec![])); + s.roots = vec![0, MAX_NODE_DEPTH]; + } + let file = PrcFile::parse(&write_prc(&s).unwrap().prc).unwrap(); + assert!(file.model_tree().is_ok(), "{roots} root(s)"); + assert!(!file.placements().unwrap().is_empty()); + } + assert_eq!(write_prc(&chain(MAX_NODE_DEPTH + 1)), Err(PrcWriteError::NotATree("nested too deeply"))); +} + +#[test] +fn supplied_normals_are_stored_not_replaced() { + let mut s = scene(); + let up = [[0.0, 0.0, 1.0], [0.0, 0.6, 0.8], [0.6, 0.0, 0.8]]; + s.meshes[0].primitives[0].normals = up.to_vec(); + let r = write_prc(&s).unwrap(); + assert_eq!(r.flat_normals, 2, "only the bolt's primitives get flat normals"); + let file = PrcFile::parse(&r.prc).unwrap(); + let meshes: Vec<_> = file.file_structures.iter().flat_map(|fs| fs.tessellations().unwrap()).collect(); + let supplied = |t: &&crate::Tessellation| matches!(t, crate::Tessellation::Mesh(m) if m.normals.len() == 3); + let Some(crate::Tessellation::Mesh(pane)) = meshes.iter().find(supplied) else { panic!("{meshes:?}") }; + assert_eq!(pane.normals, up); + assert_eq!(pane.triangle_normals, [[0, 1, 2]]); + assert!(!pane.normals_recalculated); + let mut s = scene(); + s.meshes[0].primitives[0].normals = vec![[0.0, 0.0, 1.0]]; + assert!(matches!(write_prc(&s), Err(PrcWriteError::BadIndex { .. })), "one normal for three vertices"); +} + +/// A wholly transparent textured material stays transparent: its style says so, not only its +/// material, whose alpha of 0 a reader may take as unset. +#[test] +fn a_transparent_textured_material_reads_back_transparent() { + let mut s = scene(); + let image = b"\x89PNG\r\n\x1a\n\0\0\0\x0dIHDR\0\0\0\x01\0\0\0\x02".to_vec(); + s.textures = vec![SceneTexture { image, wrap: [TextureWrap::Clamp, TextureWrap::Clamp], alpha: false }]; + s.materials[1].texture = Some(0); + s.materials[1].rgba[3] = 0.0; + s.meshes[1].primitives[0].uvs = vec![[0.5, 0.1], [0.5, 0.1], [0.5, 0.9]]; + let prc = write_prc(&s).unwrap().prc; + let colours: Vec<_> = assemble(&prc).colours.into_iter().flatten().collect(); + assert!(colours.iter().filter(|c| c[..3] == [255, 0, 0]).all(|c| c[3] == 0), "{colours:?}"); + assert!(colours.iter().any(|c| c[..3] == [255, 0, 0]), "{colours:?}"); +} + +/// What the roots do not reach is checked too. +#[test] +fn unreached_nodes_and_meshes_are_checked() { + let mut s = scene(); + s.nodes.push(node("stray", Some(999), vec![])); + assert_eq!(write_prc(&s), Err(PrcWriteError::BadIndex { what: "mesh", index: 999 })); + let mut s = scene(); + s.meshes.push(SceneMesh { name: None, primitives: vec![tri(Some(999), 0.0)] }); + assert_eq!(write_prc(&s), Err(PrcWriteError::BadIndex { what: "material", index: 999 })); + let mut s = scene(); + s.nodes.push(node("a", None, vec![5])); + s.nodes.push(node("b", None, vec![4])); + assert_eq!(write_prc(&s), Err(PrcWriteError::NotATree("a cycle"))); + // An unreached tree is fine. + let mut s = scene(); + s.nodes.push(node("spare", Some(0), vec![])); + assert!(write_prc(&s).is_ok()); +} diff --git a/crates/prc/src/write/textures.rs b/crates/prc/src/write/textures.rs new file mode 100644 index 000000000..5e92a2fde --- /dev/null +++ b/crates/prc/src/write/textures.rs @@ -0,0 +1,240 @@ +//! The globals' texture entities: `Picture` (703), `TextureDefinition` (712) +//! and the materials array of `Material` (702) / `TextureApplication` (711) +//! pairs [WD 7.5.4-7.5.7]. + +use super::TextureWrap; +use super::sections::{base, ref_base}; +use super::validate::Plan; +use super::{BitWriter, MeshScene, SceneMaterial}; + +const MATERIAL: u32 = 702; +const PICTURE: u32 = 703; +const TEXTURE_APPLICATION: u32 = 711; +const TEXTURE_DEFINITION: u32 = 712; + +/// `EPRCPictureDataFormat`, counted from 0. +pub(super) const FORMAT_PNG: u32 = 0; +pub(super) const FORMAT_JPEG: u32 = 1; +/// Mapping type "stored": the coordinates come from the tessellation. +const MAPPING_STORED: i32 = 1; +/// `PRC_TEXTURE_MAPPING_DIFFUSE`. The specification does not give its +/// value; with the first bit, Acrobat Reader draws a synthetic textured +/// quad with its texels in place. +const MAPPING_DIFFUSE: u32 = 0x0001; +/// Components: red, green, blue, and alpha (WD 7.5.7 Table 100). +const COMPONENTS_RGB: u8 = 0x07; +const COMPONENTS_RGBA: u8 = 0x0F; +/// Texture function "modulate", 0-based: glTF multiplies the base colour +/// factor by the texel. +const FUNCTION_MODULATE: i32 = 1; +/// Applying mode: lighting. +const APPLY_LIGHTING: u8 = 0x01; + +/// A picture's format, width and height, read from its file header; `None` +/// when it is neither a PNG nor a JPEG with a frame header, or it has no pixels. +pub(crate) fn picture_info(image: &[u8]) -> Option<(u32, u32, u32)> { + let info = if image.starts_with(b"\x89PNG\r\n\x1a\n") && image.get(12..16) == Some(b"IHDR") { + let be = |at: usize| Some(u32::from_be_bytes(image.get(at..at + 4)?.try_into().ok()?)); + (FORMAT_PNG, be(16)?, be(20)?) + } else { + let (w, h) = jpeg_size(image)?; + (FORMAT_JPEG, w, h) + }; + (info.1 > 0 && info.2 > 0).then_some(info) +} + +/// The width and height in a JPEG's first frame header (SOFn, ITU-T T.81 +/// B.2.2). +fn jpeg_size(b: &[u8]) -> Option<(u32, u32)> { + if !b.starts_with(&[0xFF, 0xD8]) { + return None; + } + let mut at = 2; + loop { + // Fill bytes before a marker. + while b.get(at) == Some(&0xFF) && b.get(at + 1) == Some(&0xFF) { + at += 1; + } + if *b.get(at)? != 0xFF { + return None; + } + let marker = *b.get(at + 1)?; + if matches!(marker, 0x01 | 0xD0..=0xD7) { + at += 2; + continue; + } + let len = usize::from(u16::from_be_bytes([*b.get(at + 2)?, *b.get(at + 3)?])); + let sof = matches!(marker, 0xC0..=0xCF) && !matches!(marker, 0xC4 | 0xC8 | 0xCC); + if sof { + let h = u16::from_be_bytes([*b.get(at + 5)?, *b.get(at + 6)?]); + let w = u16::from_be_bytes([*b.get(at + 7)?, *b.get(at + 8)?]); + return Some((u32::from(w), u32::from(h))); + } + if marker == 0xDA || len < 2 { + return None; + } + at += 2 + len; + } +} + +/// The stored wrapping mode, 0-based as a reader defaults to +/// (`WrapBase::ZeroBased`): 1 repeat, 4 clamp to edge, 5 mirrored repeat. +fn wrap_code(w: TextureWrap) -> i32 { + match w { + TextureWrap::Repeat => 1, + TextureWrap::Clamp => 4, + TextureWrap::MirroredRepeat => 5, + } +} + +/// Pictures, one per texture, file `k` of the structure header for +/// texture `k`; `info` is each one's [`picture_info`]. +pub(super) fn pictures(w: &mut BitWriter, info: &[(u32, u32, u32)]) { + w.uint(info.len() as u32); + for (k, &(format, width, height)) in info.iter().enumerate() { + w.uint(PICTURE); + base(w); + w.uint(format).uint(k as u32 + 1).uint(width).uint(height); + } +} + +/// Texture definitions, one per texture over picture `k`, with unique ids +/// from `first_id`. +pub(super) fn definitions(w: &mut BitWriter, scene: &MeshScene, first_id: u32) { + w.uint(scene.textures.len() as u32); + for (k, t) in scene.textures.iter().enumerate() { + w.uint(TEXTURE_DEFINITION); + ref_base(w, None, first_id + k as u32); + // Picture (biased), dimension 2, stored mapping, diffuse. + w.uint(k as u32 + 1).put(2, 8).int(MAPPING_STORED).uint(MAPPING_DIFFUSE); + // No intensities (1.0); RGB(A) components; modulate; no blend + // sources; lighting; the S and T wraps; no transformation. + let components = if t.alpha { COMPONENTS_RGBA } else { COMPONENTS_RGB }; + w.uint(0).uint(1).put(u64::from(components), 8); + w.int(FUNCTION_MODULATE).int(0).int(0); + w.put(u64::from(APPLY_LIGHTING), 8); + w.int(wrap_code(t.wrap[0])).int(wrap_code(t.wrap[1])); + w.bit(false); + } +} + +/// Whether `m` gives off light the writer carries: a non-black emission +/// on a material that is not wholly transparent. +pub(super) fn glows(m: &SceneMaterial) -> bool { + m.rgba[3] > 0.0 && m.emissive.iter().any(|&c| c > 0.0) +} + +/// The emissive colours, 0–1, of the materials that [`glows`], in material +/// order; the globals write them after the materials' colours. +pub(super) fn emissive_colours(scene: &MeshScene) -> Vec<[f64; 3]> { + scene.materials.iter().filter(|m| glows(m)).map(|m| m.emissive.map(|c| c.clamp(0.0, 1.0))).collect() +} + +/// The materials array, with unique ids from `first_id`: per textured +/// material (`plan.textured`) its base `Material` then the +/// `TextureApplication` naming it, then per glowing untextured material +/// (`plan.glowing`) a `Material`. Emissive colours count from colour +/// `emissive_first`, in [`emissive_colours`] order. +pub(super) fn materials(w: &mut BitWriter, (scene, plan): (&MeshScene, &Plan), emissive_first: u32, first_id: u32) { + w.uint((2 * plan.textured.len() + plan.glowing.len()) as u32); + // Double-scaled, biased (WD 7.5.3); 0 names none. + let emissive = |m: usize| { + if scene.materials.get(m).is_some_and(glows) { + let before = scene.materials.iter().take(m).filter(|m| glows(m)).count() as u32; + 3 * (emissive_first + before) + 1 + } else { + 0 + } + }; + let mut id = first_id; + for (j, &m) in plan.textured.iter().enumerate() { + let Some(mat) = scene.materials.get(m) else { + continue; + }; + material(w, (m, mat), emissive(m), id); + w.uint(TEXTURE_APPLICATION); + ref_base(w, None, id + 1); + let texture = mat.texture.map_or(0, |t| t as u32 + 1); + // Base material (biased entry), definition, no next level, UV set 1. + w.uint(2 * j as u32 + 1).uint(texture).uint(0).uint(1); + id += 2; + } + for &m in &plan.glowing { + if let Some(mat) = scene.materials.get(m) { + material(w, (m, mat), emissive(m), id); + id += 1; + } + } +} + +/// Material `m`'s `Material` (702) with id `id`: ambient and diffuse its +/// base colour, `emissive` its emissive colour index, no specular. +fn material(w: &mut BitWriter, (m, mat): (usize, &SceneMaterial), emissive: u32, id: u32) { + let alpha = mat.rgba[3].clamp(0.0, 1.0); + // Double-scaled colour index of material m's colour (WD 7.5.3). + let colour = 3 * m as u32 + 1; + w.uint(MATERIAL); + ref_base(w, None, id); + w.uint(colour).uint(colour).uint(emissive).uint(0); + w.double(0.0).doubles([alpha; 4]); +} + +#[cfg(test)] +// Test code: a panic is the failure report. +#[allow(clippy::unwrap_used, clippy::indexing_slicing)] +mod tests { + use super::super::SceneTexture; + use super::*; + + #[test] + fn png_and_jpeg_sizes_are_read_from_their_headers() { + let mut png = b"\x89PNG\r\n\x1a\n\0\0\0\x0dIHDR".to_vec(); + png.extend([0, 0, 1, 2, 0, 0, 0, 3]); + assert_eq!(picture_info(&png), Some((FORMAT_PNG, 258, 3))); + // SOI, an APP0 of 4 bytes, fill, SOF2 (progressive) 8-bit 5 x 7. + let jpeg = [0xFF, 0xD8, 0xFF, 0xE0, 0, 4, 0, 0, 0xFF, 0xFF, 0xC2, 0, 11, 8, 0, 5, 0, 7]; + assert_eq!(picture_info(&jpeg), Some((FORMAT_JPEG, 7, 5))); + // A DHT (C4) is not a frame header; scan data before a frame is not + // read through. + let no_frame = [0xFF, 0xD8, 0xFF, 0xC4, 0, 2, 0xFF, 0xDA, 0, 2]; + assert_eq!(picture_info(&no_frame), None); + assert_eq!(picture_info(b"RIFF....WEBP"), None); + assert_eq!(picture_info(&png[..20]), None, "a cut IHDR"); + let mut empty = png.clone(); + empty[16..20].copy_from_slice(&[0; 4]); + assert_eq!(picture_info(&empty), None, "a PNG no pixels wide"); + let flat = [0xFF, 0xD8, 0xFF, 0xC0, 0, 11, 8, 0, 0, 0, 7]; + assert_eq!(picture_info(&flat), None, "a JPEG no lines high"); + } + + /// The written definition's components and S and T wraps. + fn definition(t: SceneTexture) -> (u8, [i32; 2]) { + let scene = MeshScene { textures: vec![t], ..MeshScene::default() }; + let mut w = BitWriter::default(); + definitions(&mut w, &scene, 7); + let bytes = w.finish().unwrap(); + let mut r = crate::BitReader::new(&bytes); + // Count, type, base (no attributes, default name), no CAD id, no CAD persistent id, id. + assert_eq!([r.unsigned_integer().unwrap(), r.unsigned_integer().unwrap(), r.unsigned_integer().unwrap()], [1, TEXTURE_DEFINITION, 0]); + assert!(r.bit().unwrap()); + assert_eq!([r.unsigned_integer().unwrap(), r.unsigned_integer().unwrap(), r.unsigned_integer().unwrap()], [0, 0, 7]); + // Picture, dimension, mapping, mapped attribute, intensities, one component set. + assert_eq!(r.unsigned_integer().unwrap(), 1); + assert_eq!(r.character().unwrap(), 2); + assert_eq!([r.integer().unwrap()], [MAPPING_STORED]); + r.unsigned_integer().unwrap(); + assert_eq!([r.unsigned_integer().unwrap(), r.unsigned_integer().unwrap()], [0, 1]); + let components = r.character().unwrap(); + // Function, the two blend sources, applying mode. + assert_eq!([r.integer().unwrap(), r.integer().unwrap(), r.integer().unwrap()], [FUNCTION_MODULATE, 0, 0]); + r.character().unwrap(); + (components, [r.integer().unwrap(), r.integer().unwrap()]) + } + + #[test] + fn wraps_and_alpha_are_written() { + let t = SceneTexture { image: vec![], wrap: [TextureWrap::Clamp, TextureWrap::MirroredRepeat], alpha: true }; + assert_eq!(definition(t), (COMPONENTS_RGBA, [4, 5])); + assert_eq!(definition(SceneTexture::default()), (COMPONENTS_RGB, [1, 1])); + } +} diff --git a/crates/prc/src/write/validate.rs b/crates/prc/src/write/validate.rs new file mode 100644 index 000000000..5b2d9c54c --- /dev/null +++ b/crates/prc/src/write/validate.rs @@ -0,0 +1,292 @@ +//! Checking a [`MeshScene`] and laying it out as PRC entities: the +//! occurrence order, which meshes become parts, which primitives become +//! tessellations. + +use super::{MAX_NODE_DEPTH, MeshScene, PrcWriteError, ScenePrimitive}; + +/// One `ProductOccurrence`: the node it is for (`None` for the synthetic +/// root over several roots) and its sons as occurrence indices. +pub(super) struct Occ { + pub(super) node: Option, + pub(super) sons: Vec, +} + +/// The scene as PRC entities. +pub(super) struct Plan { + /// Occurrences, sons before fathers, the root last. + pub(super) occurrences: Vec, + /// Mesh index of each part. + pub(super) parts: Vec, + /// Part index of each mesh, when it is placed. + pub(super) part_of_mesh: Vec>, + /// `(mesh, primitive)` of each tessellation, in section order. + pub(super) tessellations: Vec<(usize, usize)>, + pub(super) empty_primitives: usize, + /// Each texture's picture format, width and height. + pub(super) pictures: Vec<(u32, u32, u32)>, + /// The textured materials, in material order; the `j`th has material + /// style `materials.len() + j`. + pub(super) textured: Vec, + /// The untextured materials that glow, in material order; the `g`th + /// has material style `materials.len() + textured.len() + g`. + pub(super) glowing: Vec, +} + +impl Plan { + /// Whether `p` is drawn with its material's texture: the material has + /// one and `p` has coordinates. + pub(super) fn is_textured(&self, scene: &MeshScene, p: &ScenePrimitive) -> bool { + !p.uvs.is_empty() && p.material.and_then(|m| scene.materials.get(m)).is_some_and(|m| m.texture.is_some()) + } + + /// The 0-based style `p` names: its material's textured style when + /// [`Self::is_textured`], else its RGB style. + pub(super) fn style_of(&self, scene: &MeshScene, p: &ScenePrimitive) -> Option { + let m = p.material?; + if self.is_textured(scene, p) { + // `textured` and `glowing` are in material order. + let j = self.textured.binary_search(&m).ok()?; + return Some((scene.materials.len() + j) as u32); + } + if let Ok(g) = self.glowing.binary_search(&m) { + return Some((scene.materials.len() + self.textured.len() + g) as u32); + } + Some(m as u32) + } + + /// The last unique id the globals take: the line pattern, the styles, + /// the texture definitions, two materials per textured material and + /// one per glowing one. + pub(super) fn global_ids(&self, scene: &MeshScene) -> u32 { + let materials = 2 * self.textured.len() + self.glowing.len(); + (1 + self.styles(scene) + scene.textures.len() + materials) as u32 + } + + /// How many styles the globals write: one RGB style per material, then + /// the textured and the glowing materials' material styles. + pub(super) fn styles(&self, scene: &MeshScene) -> usize { + scene.materials.len() + self.textured.len() + self.glowing.len() + } +} + +fn bad(what: &'static str, index: usize) -> PrcWriteError { + PrcWriteError::BadIndex { what, index } +} + +fn count(n: usize) -> Result { + u32::try_from(n).map_err(|_| PrcWriteError::TooLarge) +} + +/// Check `scene` and lay it out. +pub(super) fn plan(scene: &MeshScene) -> Result { + check_numbers(scene)?; + check_forest(scene)?; + // Style ids and double-scaled colour indices (a base and an emissive + // colour per material) are u32s. + count(scene.materials.len().saturating_mul(6).saturating_add(2))?; + count(scene.textures.len().saturating_mul(3))?; + // Every global id sum (`global_ids`, the first texture id) is under + // four per material, three per texture and a constant. + count(scene.materials.len().saturating_mul(4).saturating_add(scene.textures.len().saturating_mul(3)).saturating_add(8))?; + // The whole scene, what the roots do not reach included. + for node in &scene.nodes { + if let Some(m) = node.mesh.filter(|&m| m >= scene.meshes.len()) { + return Err(bad("mesh", m)); + } + } + for prim in scene.meshes.iter().flat_map(|m| &m.primitives) { + check_primitive(scene, prim)?; + } + let occurrences = occurrences(scene)?; + let mut plan = Plan { + occurrences, + parts: Vec::new(), + part_of_mesh: vec![None; scene.meshes.len()], + tessellations: Vec::new(), + empty_primitives: 0, + pictures: pictures(scene)?, + textured: textured(scene)?, + glowing: scene.materials.iter().enumerate().filter(|(_, m)| m.texture.is_none() && super::textures::glows(m)).map(|(i, _)| i).collect(), + }; + for o in &plan.occurrences { + let Some(m) = o.node.and_then(|n| scene.nodes.get(n)?.mesh) else { + continue; + }; + let Some(slot) = plan.part_of_mesh.get_mut(m) else { + return Err(bad("mesh", m)); + }; + if slot.is_none() { + *slot = Some(count(plan.parts.len())?); + plan.parts.push(m); + } + } + for &m in &plan.parts { + for (p, prim) in scene.meshes.get(m).into_iter().flat_map(|m| m.primitives.iter().enumerate()) { + if prim.triangles.is_empty() { + plan.empty_primitives += 1; + } else { + plan.tessellations.push((m, p)); + } + } + } + if plan.tessellations.is_empty() { + return Err(PrcWriteError::Empty); + } + count(plan.tessellations.len())?; + Ok(plan) +} + +/// Each texture's [`super::textures::picture_info`]. +fn pictures(scene: &MeshScene) -> Result, PrcWriteError> { + scene.textures.iter().enumerate().map(|(index, t)| super::textures::picture_info(&t.image).ok_or(PrcWriteError::BadTexture { index })).collect() +} + +/// The materials with a texture, each naming one that exists. +fn textured(scene: &MeshScene) -> Result, PrcWriteError> { + let mut out = Vec::new(); + for (m, mat) in scene.materials.iter().enumerate() { + match mat.texture { + Some(t) if t >= scene.textures.len() => return Err(bad("texture", t)), + Some(_) => out.push(m), + None => {} + } + } + Ok(out) +} + +fn check_primitive(scene: &MeshScene, p: &ScenePrimitive) -> Result<(), PrcWriteError> { + if let Some(m) = p.material.filter(|&m| m >= scene.materials.len()) { + return Err(bad("material", m)); + } + if !p.normals.is_empty() && p.normals.len() != p.positions.len() { + return Err(bad("normal count", p.normals.len())); + } + if !p.uvs.is_empty() && p.uvs.len() != p.positions.len() { + return Err(bad("texture coordinate count", p.uvs.len())); + } + // Every count the tessellation writes is a u32, coordinates three to a + // vertex and corner indices up to nine to a triangle. + count(p.positions.len().saturating_mul(3))?; + count(p.triangles.len().saturating_mul(9))?; + let n = p.positions.len(); + match p.triangles.iter().flatten().find(|&&v| v as usize >= n) { + Some(&v) => Err(bad("vertex", v as usize)), + None => Ok(()), + } +} + +fn finite(vs: impl IntoIterator, what: &'static str) -> Result<(), PrcWriteError> { + match vs.into_iter().all(f64::is_finite) { + true => Ok(()), + false => Err(PrcWriteError::BadNumber(what)), + } +} + +fn check_numbers(scene: &MeshScene) -> Result<(), PrcWriteError> { + if !(scene.units_in_mm.is_finite() && scene.units_in_mm > 0.0) { + return Err(PrcWriteError::BadNumber("units_in_mm")); + } + for n in &scene.nodes { + if let Some(m) = n.matrix { + finite(m, "matrix")?; + if [m[3], m[7], m[11], m[15]] != [0.0, 0.0, 0.0, 1.0] { + return Err(PrcWriteError::BadNumber("matrix bottom row")); + } + } + } + finite(scene.materials.iter().flat_map(|m| m.rgba), "colour")?; + finite(scene.materials.iter().flat_map(|m| m.emissive), "emissive colour")?; + for p in scene.meshes.iter().flat_map(|m| &m.primitives) { + finite(p.positions.iter().flatten().copied(), "position")?; + finite(p.normals.iter().flatten().copied(), "normal")?; + finite(p.uvs.iter().flatten().copied(), "texture coordinate")?; + } + Ok(()) +} + +/// Every child and root names a node, no node has two parents, no root +/// has one or is listed twice, no chain from a root is deeper than +/// [`MAX_NODE_DEPTH`], and no node, reached or not, is on a cycle. +/// With one parent at most each and distinct parentless roots, what the +/// roots reach has no cycle and holds each node once, so the occurrences +/// number no more than the nodes. +fn check_forest(scene: &MeshScene) -> Result<(), PrcWriteError> { + let n = scene.nodes.len(); + let mut parent = vec![None; n]; + for (i, node) in scene.nodes.iter().enumerate() { + for &c in &node.children { + let slot = parent.get_mut(c).ok_or_else(|| bad("child node", c))?; + if slot.replace(i).is_some() { + return Err(PrcWriteError::NotATree("a node has two parents")); + } + } + } + let mut rooted = vec![false; n]; + for &r in &scene.roots { + match (parent.get(r), rooted.get_mut(r)) { + (Some(None), Some(seen)) if !*seen => *seen = true, + (Some(None), Some(_)) => return Err(PrcWriteError::NotATree("a root is listed twice")), + (Some(Some(_)), _) => return Err(PrcWriteError::NotATree("a root has a parent")), + _ => return Err(bad("root node", r)), + } + } + let mut depth = vec![0usize; n]; + let mut stack: Vec = scene.roots.clone(); + while let Some(i) = stack.pop() { + let d = depth.get(i).copied().unwrap_or(0).saturating_add(1); + if d > MAX_NODE_DEPTH { + return Err(PrcWriteError::NotATree("nested too deeply")); + } + for &c in scene.nodes.get(i).map(|n| n.children.as_slice()).unwrap_or(&[]) { + if let Some(slot) = depth.get_mut(c) { + *slot = d; + } + stack.push(c); + } + } + // Nodes the roots do not reach: with one parent each, a node no parentless node reaches + // is on a cycle. + let mut seen = vec![false; n]; + let mut stack: Vec = (0..n).filter(|&i| parent.get(i).is_some_and(Option::is_none)).collect(); + while let Some(i) = stack.pop() { + if let Some(s) = seen.get_mut(i).filter(|s| !**s) { + *s = true; + stack.extend(scene.nodes.get(i).map(|n| n.children.as_slice()).unwrap_or(&[])); + } + } + if seen.contains(&false) { + return Err(PrcWriteError::NotATree("a cycle")); + } + Ok(()) +} + +/// Occurrences with every son before its father and the root last +/// [WD 7.3.6], under a +/// synthetic root when there is not exactly one. +fn occurrences(scene: &MeshScene) -> Result, PrcWriteError> { + let mut out = Vec::new(); + let synthetic = scene.roots.len() != 1; + if synthetic { + out.push(Occ { node: None, sons: Vec::new() }); + } + // (node, parent occurrence) + let mut stack: Vec<(usize, Option)> = scene.roots.iter().rev().map(|&r| (r, synthetic.then_some(0))).collect(); + while let Some((node, parent)) = stack.pop() { + let me = out.len(); + if let Some(p) = parent.and_then(|p| out.get_mut(p)) { + p.sons.push(count(me)?); + } + out.push(Occ { node: Some(node), sons: Vec::new() }); + let children = scene.nodes.get(node).map(|n| n.children.as_slice()).unwrap_or(&[]); + stack.extend(children.iter().rev().map(|&c| (c, Some(me)))); + } + let last = count(out.len())?.saturating_sub(1); + // Reversed pre-order: each subtree precedes its root; sons keep their order. + out.reverse(); + for o in &mut out { + for s in &mut o.sons { + *s = last.saturating_sub(*s); + } + } + Ok(out) +} diff --git a/crates/prc/src/write/vec3.rs b/crates/prc/src/write/vec3.rs new file mode 100644 index 000000000..bea911487 --- /dev/null +++ b/crates/prc/src/write/vec3.rs @@ -0,0 +1,53 @@ +//! Three-component vector arithmetic for the writer's normals. + +/// A point or direction, `[x, y, z]`. +pub(crate) type Vec3 = [f64; 3]; + +/// `a - b`. +pub(crate) fn sub(a: Vec3, b: Vec3) -> Vec3 { + [a[0] - b[0], a[1] - b[1], a[2] - b[2]] +} + +/// The dot product `a · b`. +pub(crate) fn dot(a: Vec3, b: Vec3) -> f64 { + a[0] * b[0] + a[1] * b[1] + a[2] * b[2] +} + +/// The right-handed cross product `a × b`. +pub(crate) fn cross(a: Vec3, b: Vec3) -> Vec3 { + [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]] +} + +/// `a` scaled to unit length; `None` when its length is zero or not finite. Divided by its +/// largest component first, so a finite vector too long or too short to square keeps its direction. +pub(crate) fn normalize(a: Vec3) -> Option { + // `f64::max` passes over a NaN, so finiteness is checked on every component. + let big = a.iter().fold(0.0f64, |m, c| m.max(c.abs())); + if !(a.iter().all(|c| c.is_finite()) && big > 0.0) { + return None; + } + let a = a.map(|c| c / big); + let l = dot(a, a).sqrt(); + Some(a.map(|c| c / l)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn cross_follows_the_right_hand_rule() { + assert_eq!(cross([1.0, 0.0, 0.0], [0.0, 1.0, 0.0]), [0.0, 0.0, 1.0]); + assert_eq!(cross([0.0, 1.0, 0.0], [1.0, 0.0, 0.0]), [0.0, 0.0, -1.0]); + } + + #[test] + fn normalize_rejects_degenerate_vectors() { + assert_eq!(normalize([0.0, 4.0, 0.0]), Some([0.0, 1.0, 0.0])); + assert_eq!(normalize([0.0; 3]), None); + assert_eq!(normalize([f64::INFINITY, 0.0, 0.0]), None); + assert_eq!(normalize([f64::NAN, 1.0, 0.0]), None); + assert_eq!(normalize([0.0, 0.0, 1e300]), Some([0.0, 0.0, 1.0])); + assert_eq!(normalize([0.0, -1e-300, 0.0]), Some([0.0, -1.0, 0.0])); + } +} From 76902ae85ed74b642394663cc704acb90522bfd5 Mon Sep 17 00:00:00 2001 From: scks1 <126534658+scks1@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:29:55 -0500 Subject: [PATCH 13/64] craft-latex: a box shows only its text, and settings show nothing (#1915) --- crates/latex/src/parser.rs | 377 ++++++++++++++++++++-------------- crates/latex/src/tests.rs | 97 +++++++++ crates/latex/tests/hostile.rs | 17 ++ 3 files changed, 339 insertions(+), 152 deletions(-) diff --git a/crates/latex/src/parser.rs b/crates/latex/src/parser.rs index 91e419a0f..12971f1d0 100644 --- a/crates/latex/src/parser.rs +++ b/crates/latex/src/parser.rs @@ -16,100 +16,111 @@ pub fn import(bytes: &[u8]) -> Document { d } -/// Commands dropped together with their arguments (layout and definitions, not text). -const DROP_WITH_ARGS: &[&str] = &[ - "documentclass", - "usepackage", - "RequirePackage", - "newcommand", - "renewcommand", - "providecommand", - "newcommand*", - "renewcommand*", - "providecommand*", - "newenvironment", - "renewenvironment", - "DeclareMathOperator", - "DeclareMathOperator*", - "def", - "let", - "setlength", - "addtolength", - "setcounter", - "addtocounter", - "stepcounter", - "refstepcounter", - "vspace", - "vspace*", - "hspace", - "hspace*", - "vskip", - "hskip", - "pagestyle", - "thispagestyle", - "pagenumbering", - "bibliographystyle", - "bibliography", - "addbibresource", - "printbibliography", - "input", - "include", - "includeonly", - "graphicspath", - "hypersetup", - "definecolor", - "geometry", - "numberwithin", - "newtheorem", - "newtheorem*", - "theoremstyle", - "phantom", - "hphantom", - "vphantom", - "index", - "nocite", - "addcontentsline", - "markboth", - "markright", - "linespread", - "setstretch", - "fancyhf", - "fancyhead", - "fancyfoot", - "lstset", - "captionsetup", - "setmainfont", - "setsansfont", - "setmonofont", - "newfontfamily", - "date", - "thanks", - "maketitle*", - "tableofcontents", - "listoffigures", - "listoftables", - "appendix", - "frontmatter", - "mainmatter", - "backmatter", - "cline", - "hline", - "toprule", - "midrule", - "bottomrule", - "cmidrule", - "addlinespace", - "endhead", - "endfirsthead", - "endfoot", - "endlastfoot", - "rowcolor", - "arraystretch", - "smallskip", - "medskip", - "bigskip", - "today", - "and", +/// Commands dropped together with their arguments (layout and definitions, not text), each with +/// the arguments it takes in order: `m` is one `{…}` group or command, and `o` is every `[…]` there. +/// Text after the last argument stays text. +pub(super) const DROP_WITH_ARGS: &[(&str, &str)] = &[ + ("documentclass", "omo"), + ("usepackage", "omo"), + ("RequirePackage", "omo"), + ("newcommand", "mom"), + ("renewcommand", "mom"), + ("providecommand", "mom"), + ("newcommand*", "mom"), + ("renewcommand*", "mom"), + ("providecommand*", "mom"), + ("newenvironment", "momm"), + ("renewenvironment", "momm"), + ("DeclareMathOperator", "mm"), + ("DeclareMathOperator*", "mm"), + ("def", "m"), + ("let", ""), + ("setlength", "mm"), + ("addtolength", "mm"), + ("setcounter", "mm"), + ("addtocounter", "mm"), + ("stepcounter", "m"), + ("refstepcounter", "m"), + ("vspace", "m"), + ("vspace*", "m"), + ("hspace", "m"), + ("hspace*", "m"), + ("vskip", "m"), + ("hskip", "m"), + ("pagestyle", "m"), + ("thispagestyle", "m"), + ("pagenumbering", "m"), + ("bibliographystyle", "m"), + ("bibliography", "m"), + ("addbibresource", "om"), + ("printbibliography", "o"), + ("input", "m"), + ("include", "m"), + ("includeonly", "m"), + ("graphicspath", "m"), + ("hypersetup", "m"), + ("definecolor", "ommm"), + ("geometry", "m"), + ("numberwithin", "omm"), + ("newtheorem", "momo"), + ("newtheorem*", "mm"), + ("theoremstyle", "m"), + ("phantom", "m"), + ("hphantom", "m"), + ("vphantom", "m"), + ("index", "om"), + ("nocite", "m"), + ("addcontentsline", "mmm"), + ("markboth", "mm"), + ("markright", "m"), + ("linespread", "m"), + ("setstretch", "m"), + ("fancyhf", "om"), + ("fancyhead", "om"), + ("fancyfoot", "om"), + ("lstset", "m"), + ("captionsetup", "om"), + ("setmainfont", "omo"), + ("setsansfont", "omo"), + ("setmonofont", "omo"), + ("newfontfamily", "momo"), + ("date", "m"), + ("thanks", "m"), + ("hyphenation", "m"), + ("addvspace", "m"), + ("enlargethispage", "m"), + ("enlargethispage*", "m"), + ("selectlanguage", "m"), + ("newcounter", "mo"), + ("settowidth", "mm"), + ("settoheight", "mm"), + ("settodepth", "mm"), + ("maketitle*", ""), + ("tableofcontents", ""), + ("listoffigures", ""), + ("listoftables", ""), + ("appendix", ""), + ("frontmatter", ""), + ("mainmatter", ""), + ("backmatter", ""), + ("cline", "m"), + ("hline", ""), + ("toprule", "o"), + ("midrule", "o"), + ("bottomrule", "o"), + ("cmidrule", "om"), + ("addlinespace", "o"), + ("endhead", ""), + ("endfirsthead", ""), + ("endfoot", ""), + ("endlastfoot", ""), + ("rowcolor", "omo"), + ("arraystretch", ""), + ("smallskip", ""), + ("medskip", ""), + ("bigskip", ""), + ("today", ""), + ("and", ""), ]; /// Paragraph-level context from the enclosing environments. @@ -128,8 +139,9 @@ pub(super) struct Parser<'a> { fmt: Fmt, /// Paragraph context of the enclosing environments. ctx: Ctx, - /// Text that followed an optional argument's `]` in the same token, emitted next. - pending: Option, + /// Text that followed an optional argument's `]` in the same token, emitted next. A slice + /// of the token, so reading `[]` after `[]` copies nothing. + pending: Option<&'a str>, /// Open lists: ordered? lists: Vec, page_break: bool, @@ -228,35 +240,47 @@ impl<'a> Parser<'a> { /// The tokens of an optional `[…]` argument, if one follows. pub(super) fn opt_arg(&mut self) -> Option { - let save = self.pos; - self.skip_spaces(); - let Some(Tok::Text(s)) = self.t.get(self.pos) else { - self.pos = save; - return None; - }; - if !s.starts_with('[') { - self.pos = save; - return None; + let t = self.t; + let mut out = String::new(); + if let Some(p) = self.pending.take() { + // Text left after the previous argument's `]` comes first: in `\makebox[3cm][l]` the + // second argument is in the first one's token and waits there. + let Some(body) = p.trim_start().strip_prefix('[') else { + self.pending = Some(p); + return None; + }; + if self.close_opt(body, &mut out) { + return Some(out); + } + } else { + let save = self.pos; + self.skip_spaces(); + let Some(Tok::Text(s)) = t.get(self.pos) else { + self.pos = save; + return None; + }; + // LaTeX skips spaces before an optional argument, and in `\\begin{figure} [h]` the + // space and the `[` share one text token. + let Some(body) = s.trim_start().strip_prefix('[') else { + self.pos = save; + return None; + }; + self.pos += 1; + if self.close_opt(body, &mut out) { + return Some(out); + } } // Collect raw text up to the matching `]` (no nested brackets across tokens). - let mut out = String::new(); - let mut first = true; - while let Some(tok) = self.t.get(self.pos) { + while let Some(tok) = t.get(self.pos) { + if matches!(tok, Tok::Par) { + break; + } + self.pos += 1; match tok { Tok::Text(s) => { - let s = if first { s.get(1..).unwrap_or("") } else { s.as_str() }; - first = false; - if let Some(end) = s.find(']') { - out.push_str(s.get(..end).unwrap_or("")); - let rest = s.get(end + 1..).unwrap_or("").to_string(); - self.pos += 1; - if !rest.trim().is_empty() { - // The text after `]` comes next (tokens are shared, so it waits here). - self.pending = Some(rest); - } + if self.close_opt(s, &mut out) { return Some(out); } - out.push_str(s); } Tok::Open => out.push('{'), Tok::Close => out.push('}'), @@ -267,14 +291,29 @@ impl<'a> Parser<'a> { out.push('\\'); out.push_str(c); } - Tok::Par => break, _ => {} } - self.pos += 1; } Some(out) } + /// Adds `s` to an optional argument's text up to its `]`. True when the `]` was there; the + /// text after it then comes next (tokens are shared, so it waits in `pending`). + fn close_opt(&mut self, s: &'a str, out: &mut String) -> bool { + let Some(end) = s.find(']') else { + out.push_str(s); + return false; + }; + out.push_str(s.get(..end).unwrap_or("")); + let rest = s.get(end + 1..).unwrap_or(""); + // Checked from the start only: a no-break space stays in its token, so the end can be a + // long run of whitespace that every argument in a row would read again. + if !rest.trim_start().is_empty() { + self.pending = Some(rest); + } + true + } + /// The tokens of a `{…}` argument (or a single token), consumed. pub(super) fn arg_tokens(&mut self) -> &'a [Tok] { self.skip_spaces(); @@ -358,45 +397,44 @@ impl<'a> Parser<'a> { self.fmt = saved_fmt; } - /// Skip every `[…]` and `{…}` argument that follows (and, for definitions, the macro name). + /// Skip a dropped command's arguments, as its `DROP_WITH_ARGS` entry lists them. fn drop_args(&mut self, name: &str) { - if matches!(name, "newcommand" | "renewcommand" | "providecommand" | "newcommand*" | "renewcommand*" | "providecommand*" | "def" | "let") { - self.skip_spaces(); - if matches!(self.t.get(self.pos), Some(Tok::Cmd(_))) { - self.pos += 1; - } - if name == "let" { + if name == "let" { + for _ in 0..2 { self.skip_spaces(); if matches!(self.t.get(self.pos), Some(Tok::Cmd(_))) { self.pos += 1; } - return; } - if name == "def" { - // `\def\x#1{…}`: the parameter text, then the body. - while matches!(self.t.get(self.pos), Some(Tok::Text(_))) { - self.pos += 1; - } + return; + } + if name == "def" { + // `\def\x#1{…}`: the macro name and its parameter text come before the body. + self.skip_spaces(); + if matches!(self.t.get(self.pos), Some(Tok::Cmd(_))) { + self.pos += 1; + } + while matches!(self.t.get(self.pos), Some(Tok::Text(_))) { + self.pos += 1; } } - loop { + let args = DROP_WITH_ARGS.iter().find(|(n, _)| *n == name).map_or("", |(_, a)| *a); + for kind in args.chars() { + if kind == 'o' { + // Text after a `]` waits in `pending`: another `[…]`, or the text that follows. + while self.opt_arg().is_some() {} + continue; + } + if self.pending.is_some() { + return; + } let save = self.pos; self.skip_spaces(); - match self.t.get(self.pos) { - Some(Tok::Open) => { - let _ = self.arg_tokens(); - } - Some(Tok::Text(s)) if s.starts_with('[') => { - let _ = self.opt_arg(); - if self.pending.is_some() { - return; - } - } - _ => { - self.pos = save; - return; - } + if !matches!(self.t.get(self.pos), Some(Tok::Open | Tok::Cmd(_))) { + self.pos = save; + return; } + let _ = self.arg_tokens(); } } @@ -412,7 +450,7 @@ impl<'a> Parser<'a> { /// Parse until `\end{env}` (when given), a closing brace at this level, or the end. fn flush_pending(&mut self) { if let Some(p) = self.pending.take() { - self.text(&ligatures(&p)); + self.text(&ligatures(p)); } } @@ -515,7 +553,7 @@ impl<'a> Parser<'a> { let mut chars = t.chars(); let first = chars.next().map(String::from).unwrap_or_default(); if !chars.as_str().is_empty() { - self.pending = Some(chars.as_str().to_string()); + self.pending = Some(chars.as_str()); } first } @@ -710,6 +748,36 @@ impl<'a> Parser<'a> { self.flush(); self.text(&format!("[{}] ", label.unwrap_or(key))); } + "parbox" | "raisebox" | "scalebox" | "resizebox" | "resizebox*" | "rotatebox" => { + // The box's position, size, scale or angle place it; only its last argument is + // text. + match name { + "parbox" => { + let _ = self.opt_arg(); + let _ = self.opt_arg(); + let _ = self.opt_arg(); + let _ = self.arg_raw(); + } + "raisebox" => { + let _ = self.arg_raw(); + let _ = self.opt_arg(); + let _ = self.opt_arg(); + } + "scalebox" => { + let _ = self.arg_raw(); + let _ = self.opt_arg(); + } + "rotatebox" => { + let _ = self.opt_arg(); + let _ = self.arg_raw(); + } + _ => { + let _ = self.arg_raw(); + let _ = self.arg_raw(); + } + } + self.with_arg(|_| {}); + } "multicolumn" | "multirow" => { // Outside a tabular: keep the content. let _ = self.arg_raw(); @@ -718,7 +786,7 @@ impl<'a> Parser<'a> { self.with_arg(|_| {}); } "begin" | "end" => {} - n if DROP_WITH_ARGS.contains(&n) => self.drop_args(n), + n if DROP_WITH_ARGS.iter().any(|(d, _)| *d == n) => self.drop_args(n), _ => { // Unknown: drop the command, keep its arguments' text. let _ = self.opt_arg(); @@ -818,6 +886,11 @@ impl<'a> Parser<'a> { | "proposition" => { // Floats and boxes: their content, in order. let _ = self.opt_arg(); + if name == "minipage" { + // `[position][height][inner position]`. + let _ = self.opt_arg(); + let _ = self.opt_arg(); + } if matches!(name, "minipage" | "subfigure" | "multicols" | "multicols*") { let _ = self.arg_raw(); } diff --git a/crates/latex/src/tests.rs b/crates/latex/src/tests.rs index 24c8c15b1..9bc8b6c72 100644 --- a/crates/latex/src/tests.rs +++ b/crates/latex/src/tests.rs @@ -340,6 +340,103 @@ fn leading_brackets_stay_text() { assert_eq!(back.plain_text(Default::default()), "[x] done"); } +#[test] +fn a_second_optional_argument_is_not_text() { + // Both optional arguments sit in one token (`[3cm][l]`), and the second was left over as text. + for src in ["a\\makebox[3cm][l]{x}b", "a\\framebox[3cm][r]{x}b", "a\\makebox[3cm] [l]{x}b"] { + assert_eq!(texts(&format!("\\begin{{document}}{src}\\end{{document}}")), vec!["axb".to_string()], "{src}"); + } + let t = texts("\\begin{document}\\begin{minipage}[t][2cm][c]{3cm}x\\end{minipage}\\end{document}"); + assert_eq!(t, vec!["x".to_string()]); +} + +#[test] +fn an_optional_argument_after_a_space_is_not_text() { + // A space before the `[` kept the whole argument as text. + for src in ["\\begin{figure} [h]x\\end{figure}", "\\begin{minipage} [t]{3cm}x\\end{minipage}"] { + assert_eq!(texts(&format!("\\begin{{document}}{src}\\end{{document}}")), vec!["x".to_string()], "{src}"); + } + assert_eq!(texts("a\\\\ [2pt]b"), ["a\nb"]); +} + +#[test] +fn a_definition_with_a_default_argument_shows_nothing() { + // `[2][x]`: the default was left over as text, and the definition's body with it. + assert_eq!(texts("\\begin{document}\\newcommand{\\foo}[2][x]{#1 and #2}word\\end{document}"), vec!["word".to_string()]); + assert_eq!(texts("\\begin{document}\\newcommand{\\foo}[2] [x]{#1 and #2}word\\end{document}"), vec!["word".to_string()]); +} + +#[test] +fn a_box_shows_only_its_text() { + // The box's position, size, scale or angle showed before its text. + for src in [ + "a\\parbox{3cm}{x}b", + "a\\parbox[t][2cm][s]{3cm}{x}b", + "a\\raisebox{2pt}{x}b", + "a\\raisebox{2pt}[0pt][0pt]{x}b", + "a\\raisebox{2pt} [0pt] [0pt]{x}b", + "a\\scalebox{2}{x}b", + "a\\scalebox{2}[1]{x}b", + "a\\scalebox{2} [1]{x}b", + "a\\resizebox{2cm}{!}{x}b", + "a\\resizebox*{2cm}{1cm}{x}b", + "a\\rotatebox{90}{x}b", + "a\\rotatebox[origin=c]{90}{x}b", + ] { + assert_eq!(texts(&format!("\\begin{{document}}{src}\\end{{document}}")), vec!["axb".to_string()], "{src}"); + } +} + +#[test] +fn settings_that_are_not_text_show_nothing() { + for src in [ + "\\hyphenation{ta-ble}word", + "\\addvspace{1ex}word", + "\\enlargethispage{2\\baselineskip}word", + "\\enlargethispage*{1cm}word", + "\\selectlanguage{german}word", + "\\newlength{\\gap}\\settowidth{\\gap}{wide}word", + "\\newcounter{step}word", + ] { + assert_eq!(texts(&format!("\\begin{{document}}{src}\\end{{document}}")), vec!["word".to_string()], "{src}"); + } +} + +/// A dropped command takes only its own arguments: `\settowidth{\gap}{wide}{Visible}` keeps `Visible`. +#[test] +fn dropped_commands_keep_the_text_after_their_arguments() { + for src in [ + "\\hyphenation{ta-ble}{word}", + "\\addvspace{1ex}{word}", + "\\enlargethispage{2\\baselineskip}{word}", + "\\enlargethispage*{1cm}{word}", + "\\selectlanguage{german}{word}", + "\\newlength{\\gap}\\settowidth{\\gap}{wide}{word}", + "\\settoheight{\\gap}{tall}{word}", + "\\settodepth{\\gap}{deep}{word}", + "\\newcounter{step}[section]{word}", + "\\date{today}{word}", + "\\thanks{A note}{word}", + "\\captionsetup[figure]{font=it}{word}", + "\\fancyhf[LH]{Hidden}word", + "\\setlength{\\parskip}{1em}{word}", + "\\setlength\\parindent{0pt}word", + "\\newcommand\\foo[1][x]{body}{word}", + "\\newenvironment{note}[1]{begin}{end}{word}", + "\\def\\foo#1{body}{word}", + "\\newtheorem{thm}{Theorem}[section]{word}", + "\\addcontentsline{toc}{section}{Intro}{word}", + "\\bigskip{word}", + ] { + assert_eq!(texts(&format!("\\begin{{document}}{src}\\end{{document}}")), vec!["word".to_string()], "{src}"); + } + for (name, args) in crate::parser::DROP_WITH_ARGS { + let given: String = args.chars().map(|k| if k == 'o' { "[a]" } else { "{a}" }).collect(); + let src = format!("\\{name}{given}{{word}}"); + assert_eq!(texts(&format!("\\begin{{document}}{src}\\end{{document}}")), vec!["word".to_string()], "{src}"); + } +} + #[test] fn special_characters_round_trip() { let text = "50% of $5 & #1_a {b} ~c^ \\d |f| -- ``g'' tab\there"; diff --git a/crates/latex/tests/hostile.rs b/crates/latex/tests/hostile.rs index a1f249336..d8bf8df70 100644 --- a/crates/latex/tests/hostile.rs +++ b/crates/latex/tests/hostile.rs @@ -86,6 +86,23 @@ fn latex_labels_in_a_row_are_read_in_linear_time() { assert_eq!(d.plain_text(craft_wordmodel::StoryRef::Body).replace('\u{FFFC}', ""), "First second third."); } +/// Empty optional arguments in a row after a definition are skipped in linear time: the text after +/// each `]` is read where it lies in the token, not copied, and a run of no-break spaces at the +/// token's end is not read again for each argument. +#[test] +fn latex_optional_arguments_in_a_row_are_read_in_linear_time() { + let cases: [fn(usize) -> String; 3] = [ + |n| "\\newcommand{\\foo}".to_string() + &"[]".repeat(n) + "x", + |n| "\\usepackage".to_string() + &"[] ".repeat(n) + "x", + |n| "\\newcommand{\\foo}".to_string() + &"[]".repeat(n) + &"\u{a0}".repeat(n) + "\n\nx", + ]; + for make in cases { + assert_eq!(text(&make(3)), "x"); + let (small, large) = (fastest(&make(50_000)), fastest(&make(200_000))); + assert!(large < small * 8 + Duration::from_millis(50), "{small:?} for 50,000, {large:?} for 200,000"); + } +} + proptest::proptest! { #[test] fn fuzz_latex(s in "(\\\\(begin|end)\\{(itemize|tabular|verbatim|quote|center|x)\\}|\\\\[a-zA-Z]{1,8}\\*?|\\\\[^a-zA-Z]|[{}\\[\\]$&%~^_#]|\n\n|[a-z ]){0,150}") { From 5ea29f8f05a5c8eaaf43fd0bc4390bb8d0d400b3 Mon Sep 17 00:00:00 2001 From: el-j Date: Tue, 17 Nov 2026 03:30:00 +0100 Subject: [PATCH 14/64] craft-video: Hap video decoder and encoder (#1519) (#1911) --- crates/video/Cargo.toml | 6 + crates/video/README.md | 1 + crates/video/src/hap/dxt.rs | 220 +++++++++++++++ crates/video/src/hap/mod.rs | 481 +++++++++++++++++++++++++++++++++ crates/video/src/hap/snappy.rs | 233 ++++++++++++++++ crates/video/src/lib.rs | 4 + crates/video/tests/hap.rs | 315 +++++++++++++++++++++ 7 files changed, 1260 insertions(+) create mode 100644 crates/video/src/hap/dxt.rs create mode 100644 crates/video/src/hap/mod.rs create mode 100644 crates/video/src/hap/snappy.rs create mode 100644 crates/video/tests/hap.rs diff --git a/crates/video/Cargo.toml b/crates/video/Cargo.toml index 31504f309..acc40ef23 100644 --- a/crates/video/Cargo.toml +++ b/crates/video/Cargo.toml @@ -36,6 +36,8 @@ mpeg4 = ["mpeg4-encode"] mpeg4-encode = ["craft-media/bitstream"] # FFV1 lossless video (RFC 9043): version 3, range coder, decoder and encoder. ffv1 = [] +# Hap (Vidvox): decoder and encoder, with Snappy and chunked second stages. +hap = [] # Motion JPEG: a frame-level decoder and encoder over `craft-jpeg`. mjpeg = ["dep:craft-jpeg"] # Apple ProRes (SMPTE RDD 36): decoder and encoder. @@ -75,6 +77,10 @@ craft-media-testkit = { workspace = true } # The AVI muxer, for the MPEG-4 Part 2 encoder's end-to-end test. craft-media = { workspace = true, features = ["avi"] } +[[test]] +name = "hap" +required-features = ["hap"] + [[test]] name = "mjpeg" required-features = ["mjpeg"] diff --git a/crates/video/README.md b/crates/video/README.md index 14f1e3f44..a354f245e 100644 --- a/crates/video/README.md +++ b/crates/video/README.md @@ -23,6 +23,7 @@ No codec feature is on by default. | `vp8` | `vp8` | VP8 (RFC 6386): decoder | | `mpeg2` | [`mpeg2`](src/mpeg2/README.md) | MPEG-2 video (ITU-T H.262) and MPEG-1 video (ISO/IEC 11172-2): decoder (`mpeg2-decode` alone); MPEG-2 encoder with I, P and B pictures (`mpeg2-encode`, which also turns on the decoder) | | `mpeg4` | [`mpeg4`](src/mpeg4/README.md) | MPEG-4 Part 2 video (ISO/IEC 14496-2, the Xvid/DivX format): Simple profile encoder (`mpeg4-encode`) | +| `hap` | `hap` | Vidvox Hap: Hap, Hap Alpha, Hap Q, Hap Q Alpha and Hap Alpha-Only, decoder and encoder, with the Snappy and chunked second stages. DXT1, DXT5, scaled YCoCg-DXT5 and BC4 pictures decode in software; BC7 (Hap R) and BC6 (Hap HDR) frames are read and their blocks returned but not decoded to pictures. | | `mjpeg` | `mjpeg` | Motion JPEG: a decoder (baseline, extended and progressive Huffman JPEG; the Annex K tables for AVI `MJPG` packets that have none) and a baseline encoder, both over `craft-jpeg`. No two-field (MJPEG-A/B) packets and no lossless JPEG. | | `prores` | `prores` | Apple ProRes (SMPTE RDD 36): decoder and encoder | | `h264` | [`h264`](src/h264/decode/README.md) | ITU-T H.264 / AVC: decoder (`h264-decode` alone) and encoder (`h264-encode` alone) | diff --git a/crates/video/src/hap/dxt.rs b/crates/video/src/hap/dxt.rs new file mode 100644 index 000000000..af8fec748 --- /dev/null +++ b/crates/video/src/hap/dxt.rs @@ -0,0 +1,220 @@ +//! The block-compressed texture formats Hap carries: DXT1 (BC1), DXT5 (BC3) and RGTC1 (BC4), with +//! the scaled YCoCg colour transform of Hap Q. Blocks are 4x4 pixels, 8 bytes (DXT1, BC4) or 16 +//! bytes (DXT5). The decoders give RGBA and the encoders are range-fit block compressors: the +//! two endpoints are the extremes of the block's colours (or alphas) and each pixel takes the +//! nearest of the palette those endpoints make. + +/// A 4x4 block of RGBA pixels, row-major. +pub(super) type Block = [[u8; 4]; 16]; + +// The 5- and 6-bit endpoint channels widened to 8 bits as ffmpeg widens them (observed: its decoder +// is the reference for Hap pictures): about `v * 255 / 31` and `v * 255 / 63`, rounded, in fixed point. +fn expand5(v: u16) -> u8 { + ((u32::from(v) * 263 + 16) >> 5) as u8 +} +fn expand6(v: u16) -> u8 { + ((u32::from(v) * 259 + 32) >> 6) as u8 +} + +fn rgb565(c: u16) -> [u8; 3] { + [expand5((c >> 11) & 31), expand6((c >> 5) & 63), expand5(c & 31)] +} + +/// The four colours of a colour block. With `always_four` (the colour half of a DXT5 block) two +/// colours are interpolated at thirds between the endpoints; in DXT1 that is so only when the first +/// endpoint is above the second, and otherwise one colour is the half and one is black. +fn palette(c0: u16, c1: u16, always_four: bool) -> [[u8; 3]; 4] { + let (a, b) = (rgb565(c0), rgb565(c1)); + let mix = |wa: u32, wb: u32, d: u32| -> [u8; 3] { std::array::from_fn(|i| ((wa * u32::from(a[i]) + wb * u32::from(b[i])) / d) as u8) }; + if always_four || c0 > c1 { [a, b, mix(2, 1, 3), mix(1, 2, 3)] } else { [a, b, mix(1, 1, 2), [0; 3]] } +} + +/// Decode a DXT1 colour block (8 bytes) into the RGB of 16 pixels. +pub(super) fn decode_color(block: &[u8], always_four: bool) -> [[u8; 3]; 16] { + let c0 = u16::from_le_bytes([block[0], block[1]]); + let c1 = u16::from_le_bytes([block[2], block[3]]); + let pal = palette(c0, c1, always_four); + let bits = u32::from_le_bytes([block[4], block[5], block[6], block[7]]); + std::array::from_fn(|i| pal[((bits >> (2 * i)) & 3) as usize]) +} + +/// The eight alphas of a BC4 / DXT5 alpha block, from its two endpoints. +fn alpha_palette(a0: u8, a1: u8) -> [u8; 8] { + let (x, y) = (u32::from(a0), u32::from(a1)); + let mut p = [a0, a1, 0, 0, 0, 0, 0, 0]; + if a0 > a1 { + for i in 2..8u32 { + p[i as usize] = (((8 - i) * x + (i - 1) * y) / 7) as u8; + } + } else { + for i in 2..6u32 { + p[i as usize] = (((6 - i) * x + (i - 1) * y) / 5) as u8; + } + p[6] = 0; + p[7] = 255; + } + p +} + +/// Decode a BC4 / DXT5 alpha block (8 bytes) into 16 alphas. +pub(super) fn decode_alpha(block: &[u8]) -> [u8; 16] { + let pal = alpha_palette(block[0], block[1]); + let mut bits = 0u64; + for (i, &b) in block[2..8].iter().enumerate() { + bits |= u64::from(b) << (8 * i); + } + std::array::from_fn(|i| pal[((bits >> (3 * i)) & 7) as usize]) +} + +pub(super) fn decode_dxt1(block: &[u8]) -> Block { + let c = decode_color(block, false); + std::array::from_fn(|i| [c[i][0], c[i][1], c[i][2], 255]) +} + +pub(super) fn decode_dxt5(block: &[u8]) -> Block { + let a = decode_alpha(&block[..8]); + let c = decode_color(&block[8..16], true); + std::array::from_fn(|i| [c[i][0], c[i][1], c[i][2], a[i]]) +} + +/// Scaled YCoCg-DXT5 (Hap Q): the colour block holds Co, Cg and a scale in the red, green and blue +/// channels, the alpha block holds Y. +pub(super) fn decode_ycocg(block: &[u8]) -> Block { + let y = decode_alpha(&block[..8]); + let c = decode_color(&block[8..16], true); + std::array::from_fn(|i| { + let s = i32::from(c[i][2] >> 3) + 1; + let co = i32::from(c[i][0]) - 128; + let cg = i32::from(c[i][1]) - 128; + let y = i32::from(y[i]); + let (co, cg) = (co / s, cg / s); + let r = y + co - cg; + let g = y + cg; + let b = y - co - cg; + [r.clamp(0, 255) as u8, g.clamp(0, 255) as u8, b.clamp(0, 255) as u8, 255] + }) +} + +/// Decode a BC4 block (8 bytes) as an alpha mask. +pub(super) fn decode_bc4(block: &[u8]) -> [u8; 16] { + decode_alpha(block) +} + +// ----------------------------------------------------------------------------------- encoders + +fn pack565(c: [u8; 3]) -> u16 { + let r = (u16::from(c[0]) * 31 + 127) / 255; + let g = (u16::from(c[1]) * 63 + 127) / 255; + let b = (u16::from(c[2]) * 31 + 127) / 255; + (r << 11) | (g << 5) | b +} + +fn dist(a: [u8; 3], b: [u8; 3]) -> u32 { + (0..3).map(|i| (i32::from(a[i]) - i32::from(b[i])).pow(2) as u32).sum() +} + +/// Encode 16 RGB pixels as a DXT1 colour block. +pub(super) fn encode_color(px: &[[u8; 3]; 16], always_four: bool) -> [u8; 8] { + let mut lo = [255u8; 3]; + let mut hi = [0u8; 3]; + for p in px { + for i in 0..3 { + lo[i] = lo[i].min(p[i]); + hi[i] = hi[i].max(p[i]); + } + } + // Pull the endpoints in a little: the extremes of a box are rarely colours of the block. + for i in 0..3 { + let inset = (hi[i] - lo[i]) >> 4; + lo[i] += inset; + hi[i] -= inset; + } + let (mut c0, mut c1) = (pack565(hi), pack565(lo)); + if c0 < c1 { + std::mem::swap(&mut c0, &mut c1); + } + let mut out = [0u8; 8]; + out[..2].copy_from_slice(&c0.to_le_bytes()); + out[2..4].copy_from_slice(&c1.to_le_bytes()); + if c0 == c1 { + return out; // every index 0 + } + let pal = palette(c0, c1, always_four); + let mut bits = 0u32; + for (i, p) in px.iter().enumerate() { + let best = (0..4).min_by_key(|&k| dist(*p, pal[k])).unwrap_or(0); + bits |= (best as u32) << (2 * i); + } + out[4..].copy_from_slice(&bits.to_le_bytes()); + out +} + +/// Encode 16 alphas as a BC4 / DXT5 alpha block. +pub(super) fn encode_alpha(a: &[u8; 16]) -> [u8; 8] { + let hi = a.iter().copied().max().unwrap_or(0); + let lo = a.iter().copied().min().unwrap_or(0); + let mut out = [0u8; 8]; + out[0] = hi; + out[1] = lo; + if hi == lo { + return out; + } + let pal = alpha_palette(hi, lo); + let mut bits = 0u64; + for (i, &v) in a.iter().enumerate() { + let best = (0..8).min_by_key(|&k| (i32::from(v) - i32::from(pal[k])).abs()).unwrap_or(0); + bits |= (best as u64) << (3 * i); + } + for (i, b) in out[2..].iter_mut().enumerate() { + *b = (bits >> (8 * i)) as u8; + } + out +} + +fn rgb_of(block: &Block) -> [[u8; 3]; 16] { + std::array::from_fn(|i| [block[i][0], block[i][1], block[i][2]]) +} + +pub(super) fn encode_dxt1(block: &Block) -> [u8; 8] { + encode_color(&rgb_of(block), false) +} + +pub(super) fn encode_dxt5(block: &Block) -> [u8; 16] { + let a = encode_alpha(&std::array::from_fn(|i| block[i][3])); + let c = encode_color(&rgb_of(block), true); + let mut out = [0u8; 16]; + out[..8].copy_from_slice(&a); + out[8..].copy_from_slice(&c); + out +} + +pub(super) fn encode_bc4(block: &Block) -> [u8; 8] { + encode_alpha(&std::array::from_fn(|i| block[i][3])) +} + +/// Encode a block as scaled YCoCg-DXT5. +pub(super) fn encode_ycocg(block: &Block) -> [u8; 16] { + // Co = (R - B) / 2, Cg = (2G - R - B) / 4, Y = (R + 2G + B) / 4, all in 8 bits. + let co2: [i32; 16] = std::array::from_fn(|i| i32::from(block[i][0]) - i32::from(block[i][2])); + let cg4: [i32; 16] = std::array::from_fn(|i| 2 * i32::from(block[i][1]) - i32::from(block[i][0]) - i32::from(block[i][2])); + let m2 = co2.iter().map(|v| v.abs()).max().unwrap_or(0); // twice the largest Co + let m4 = cg4.iter().map(|v| v.abs()).max().unwrap_or(0); // four times the largest Cg + let mag = (m2 / 2).max(m4 / 4); + let s: i32 = if mag <= 31 { + 4 + } else if mag <= 63 { + 2 + } else { + 1 + }; + let colors: [[u8; 3]; 16] = std::array::from_fn(|i| { + let co = (128 + ((co2[i] * s + 1) >> 1)).clamp(0, 255) as u8; + let cg = (128 + ((cg4[i] * s + 2) >> 2)).clamp(0, 255) as u8; + [co, cg, ((s - 1) * 8) as u8] + }); + let y: [u8; 16] = std::array::from_fn(|i| ((i32::from(block[i][0]) + 2 * i32::from(block[i][1]) + i32::from(block[i][2]) + 2) >> 2) as u8); + let mut out = [0u8; 16]; + out[..8].copy_from_slice(&encode_alpha(&y)); + out[8..].copy_from_slice(&encode_color(&colors, true)); + out +} diff --git a/crates/video/src/hap/mod.rs b/crates/video/src/hap/mod.rs new file mode 100644 index 000000000..060ec8654 --- /dev/null +++ b/crates/video/src/hap/mod.rs @@ -0,0 +1,481 @@ +//! Hap video (Vidvox Hap): frames of GPU block-compressed textures, with an optional Snappy +//! second stage, written from the public Hap specification, the Snappy format description and +//! the S3TC / RGTC block formats. +//! +//! A Hap frame is one top-level section: a header (3-byte little-endian size and a type byte, or a +//! zero size and an 8-byte header with a 4-byte size) and its data. The type byte names the +//! texture format (low nibble) and the second-stage compressor (high nibble: none, Snappy, or +//! "chunked", where a table says how the texture is cut into chunks and how each is compressed). +//! A frame of type `0x0D` holds two such sections, the scaled YCoCg and alpha textures of Hap Q +//! Alpha. +//! +//! - [`Decoder`] reads frames. [`Decoder::decode_textures`] gives the block data as stored, ready +//! for upload to a GPU; [`Decoder::decode_rgba`] decodes DXT1, DXT5, scaled YCoCg-DXT5 (Hap Q), +//! Hap Q Alpha and the alpha-only format to RGBA pictures in software. BC7 (Hap R) and BC6 +//! (Hap HDR) frames are read, and their blocks returned, but not decoded to pictures. +//! - [`Encoder`] writes Hap, Hap Alpha, Hap Q, Hap Q Alpha and Hap Alpha-Only frames, optionally +//! Snappy-compressed and cut into chunks. +//! +//! The block compressors are range fits, not the slowest-and-best search a GPU-texture tool does: +//! the result is correct and decodes anywhere, but a little coarser than an exhaustive encoder's. +//! Decoding checks every size against the frame's dimensions before allocating, and a damaged frame +//! is an error, never a panic. + +mod dxt; +mod snappy; + +use crate::budget::DECODE_MEMORY_BUDGET; + +/// Codec errors. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The frame is damaged or not Hap. + #[error("invalid Hap frame: {0}")] + Invalid(String), + /// A valid frame this module does not decode to pictures. + #[error("unsupported Hap feature: {0}")] + Unsupported(String), + /// The dimensions or settings given cannot be used. + #[error("invalid Hap parameters: {0}")] + Input(String), +} + +/// `Result` of this module. +pub type Result = std::result::Result; + +/// The largest width or height, in pixels. +pub const MAX_DIMENSION: u32 = 32768; + +/// The texture formats a Hap frame can hold. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum TextureFormat { + /// RGB, DXT1 / BC1: 8 bytes per 4x4 block. + Dxt1, + /// RGBA, DXT5 / BC3: 16 bytes per block. + Dxt5, + /// Scaled YCoCg in DXT5 / BC3 (Hap Q): 16 bytes per block. + YcocgDxt5, + /// Alpha only, RGTC1 / BC4: 8 bytes per block. + Bc4Alpha, + /// RGBA, BPTC / BC7 (Hap R): 16 bytes per block. + Bc7, + /// Unsigned float RGB, BC6H (Hap HDR): 16 bytes per block. + Bc6Unsigned, + /// Signed float RGB, BC6H: 16 bytes per block. + Bc6Signed, +} + +impl TextureFormat { + const fn nibble(self) -> u8 { + match self { + Self::Dxt1 => 0xB, + Self::Dxt5 => 0xE, + Self::YcocgDxt5 => 0xF, + Self::Bc4Alpha => 0x1, + Self::Bc7 => 0xC, + Self::Bc6Unsigned => 0x2, + Self::Bc6Signed => 0x3, + } + } + + fn from_nibble(n: u8) -> Option { + Some(match n { + 0xB => Self::Dxt1, + 0xE => Self::Dxt5, + 0xF => Self::YcocgDxt5, + 0x1 => Self::Bc4Alpha, + 0xC => Self::Bc7, + 0x2 => Self::Bc6Unsigned, + 0x3 => Self::Bc6Signed, + _ => return None, + }) + } + + /// Bytes of one 4x4 block. + #[must_use] + pub const fn block_bytes(self) -> usize { + match self { + Self::Dxt1 | Self::Bc4Alpha => 8, + _ => 16, + } + } +} + +/// One texture of a frame: the block data as a GPU takes it (rows of 4x4 blocks, top to bottom, +/// the size rounded up to whole blocks). +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Texture { + pub format: TextureFormat, + pub data: Vec, +} + +/// A decoded picture: RGBA, 8 bits per channel, rows top to bottom. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Image { + pub width: u32, + pub height: u32, + pub rgba: Vec, +} + +fn check_dimensions(width: u32, height: u32) -> Result<()> { + if width == 0 || height == 0 || width > MAX_DIMENSION || height > MAX_DIMENSION { + return Err(Error::Input(format!("{width}x{height} is not a size from 1 to {MAX_DIMENSION} pixels a side"))); + } + if u64::from(width) * u64::from(height) * 4 > DECODE_MEMORY_BUDGET / 4 { + return Err(Error::Input(format!("{width}x{height} is above the memory budget"))); + } + Ok(()) +} + +fn blocks(width: u32, height: u32) -> (usize, usize) { + (width.div_ceil(4) as usize, height.div_ceil(4) as usize) +} + +fn texture_bytes(format: TextureFormat, width: u32, height: u32) -> usize { + let (bx, by) = blocks(width, height); + bx * by * format.block_bytes() +} + +// ------------------------------------------------------------------------------------ sections + +/// Split a section off the front of `data`: its type, its payload and what follows it. +fn section(data: &[u8]) -> Result<(u8, &[u8], &[u8])> { + let bad = || Error::Invalid("section header or size out of range".into()); + let head = data.get(..4).ok_or_else(bad)?; + let (mut size, mut start) = (usize::from(head[0]) | usize::from(head[1]) << 8 | usize::from(head[2]) << 16, 4usize); + if size == 0 { + let ext = data.get(4..8).ok_or_else(bad)?; + size = u32::from_le_bytes([ext[0], ext[1], ext[2], ext[3]]) as usize; + start = 8; + } + let end = start.checked_add(size).ok_or_else(bad)?; + let payload = data.get(start..end).ok_or_else(bad)?; + Ok((head[3], payload, &data[end..])) +} + +fn write_section(out: &mut Vec, kind: u8, payload: &[u8]) { + if payload.len() < 1 << 24 && !payload.is_empty() { + out.extend_from_slice(&[payload.len() as u8, (payload.len() >> 8) as u8, (payload.len() >> 16) as u8, kind]); + } else { + out.extend_from_slice(&[0, 0, 0, kind]); + out.extend_from_slice(&(payload.len() as u32).to_le_bytes()); + } + out.extend_from_slice(payload); +} + +const SECTION_MULTIPLE: u8 = 0x0D; +const SECTION_INSTRUCTIONS: u8 = 0x01; +const SECTION_COMPRESSORS: u8 = 0x02; +const SECTION_SIZES: u8 = 0x03; +const SECTION_OFFSETS: u8 = 0x04; +const CHUNK_NONE: u8 = 0x0A; +const CHUNK_SNAPPY: u8 = 0x0B; + +/// The uncompressed length a Snappy stream declares. +fn snappy_len(src: &[u8]) -> Option { + let (mut len, mut shift) = (0u64, 0u32); + for &b in src.iter().take(5) { + len |= u64::from(b & 0x7F) << shift; + if b & 0x80 == 0 { + return usize::try_from(len).ok(); + } + shift += 7; + } + None +} + +/// Decode one texture section holding `expected` bytes of the given format; returns the texture +/// and the bytes after the section. +fn decode_section(data: &[u8], width: u32, height: u32) -> Result<(Texture, &[u8])> { + let (kind, payload, rest) = section(data)?; + let format = TextureFormat::from_nibble(kind & 0x0F).ok_or_else(|| Error::Unsupported(format!("texture type {:#04x}", kind)))?; + let expected = texture_bytes(format, width, height); + let bytes = match kind >> 4 { + 0xA => { + if payload.len() != expected { + return Err(Error::Invalid(format!("texture of {} bytes, expected {expected}", payload.len()))); + } + payload.to_vec() + } + 0xB => snappy::decompress(payload, expected)?, + 0xC => decode_chunks(payload, expected)?, + _ => return Err(Error::Unsupported(format!("second-stage compressor in type {:#04x}", kind))), + }; + Ok((Texture { format, data: bytes }, rest)) +} + +fn decode_chunks(payload: &[u8], expected: usize) -> Result> { + let bad = |m: &str| Error::Invalid(format!("decode instructions: {m}")); + let (kind, instructions, data) = section(payload)?; + if kind != SECTION_INSTRUCTIONS { + return Err(bad("not a decode instructions container")); + } + let (mut compressors, mut sizes, mut offsets) = (None, None, None); + let mut rest = instructions; + while !rest.is_empty() { + let (k, body, next) = section(rest)?; + match k { + SECTION_COMPRESSORS => compressors = Some(body), + SECTION_SIZES => sizes = Some(body), + SECTION_OFFSETS => offsets = Some(body), + _ => {} // unknown sub-sections are skipped + } + rest = next; + } + let (compressors, sizes) = compressors.zip(sizes).ok_or_else(|| bad("missing the compressor or size table"))?; + let count = compressors.len(); + if sizes.len() != count * 4 || offsets.is_some_and(|o| o.len() != count * 4) { + return Err(bad("the tables differ in length")); + } + let word = |t: &[u8], i: usize| u32::from_le_bytes([t[4 * i], t[4 * i + 1], t[4 * i + 2], t[4 * i + 3]]) as usize; + let mut out = Vec::with_capacity(expected); + let mut running = 0usize; + for (i, &compressor) in compressors.iter().enumerate() { + let size = word(sizes, i); + let offset = offsets.map_or(running, |o| word(o, i)); + running = offset.checked_add(size).ok_or_else(|| bad("chunk out of range"))?; + let chunk = data.get(offset..running).ok_or_else(|| bad("chunk out of range"))?; + match compressor { + CHUNK_NONE => { + if out.len() + chunk.len() > expected { + return Err(bad("chunks exceed the texture")); + } + out.extend_from_slice(chunk); + } + CHUNK_SNAPPY => { + let n = snappy_len(chunk).ok_or_else(|| bad("damaged Snappy chunk"))?; + if out.len() + n > expected { + return Err(bad("chunks exceed the texture")); + } + out.extend_from_slice(&snappy::decompress(chunk, n)?); + } + other => return Err(Error::Unsupported(format!("chunk compressor {other:#04x}"))), + } + } + if out.len() != expected { + return Err(bad("chunks do not fill the texture")); + } + Ok(out) +} + +// ------------------------------------------------------------------------------------ decoder + +/// A Hap decoder for frames of one size. Every frame is independent. +#[derive(Debug, Clone)] +pub struct Decoder { + width: u32, + height: u32, +} + +impl Decoder { + /// A decoder for `width` x `height` frames. + pub fn new(width: u32, height: u32) -> Result { + check_dimensions(width, height)?; + Ok(Self { width, height }) + } + + /// The textures of one frame, as stored: one, or two for Hap Q Alpha. + pub fn decode_textures(&self, frame: &[u8]) -> Result> { + let (kind, payload, _) = section(frame)?; + if kind != SECTION_MULTIPLE { + return Ok(vec![decode_section(frame, self.width, self.height)?.0]); + } + let mut textures = Vec::new(); + let mut rest = payload; + while !rest.is_empty() { + if textures.len() == 2 { + return Err(Error::Invalid("more than two images".into())); + } + let (t, next) = decode_section(rest, self.width, self.height)?; + textures.push(t); + rest = next; + } + if textures.is_empty() { + return Err(Error::Invalid("no images".into())); + } + Ok(textures) + } + + /// Decode one frame to an RGBA picture. + pub fn decode_rgba(&self, frame: &[u8]) -> Result { + let textures = self.decode_textures(frame)?; + let formats: Vec = textures.iter().map(|t| t.format).collect(); + let (w, h) = (self.width as usize, self.height as usize); + let mut rgba = vec![0u8; w * h * 4]; + let (bx, by) = blocks(self.width, self.height); + let alpha_tex = match formats.as_slice() { + [TextureFormat::YcocgDxt5, TextureFormat::Bc4Alpha] => textures.get(1), + [TextureFormat::Dxt1] | [TextureFormat::Dxt5] | [TextureFormat::YcocgDxt5] | [TextureFormat::Bc4Alpha] => None, + [TextureFormat::Bc7 | TextureFormat::Bc6Unsigned | TextureFormat::Bc6Signed] => { + return Err(Error::Unsupported("BC7 and BC6H textures are not decoded to pictures".into())); + } + _ => return Err(Error::Unsupported("this combination of textures".into())), + }; + let main = &textures[0]; + let bb = main.format.block_bytes(); + for j in 0..by { + for i in 0..bx { + let at = (j * bx + i) * bb; + let block = &main.data[at..at + bb]; + let mut px = match main.format { + TextureFormat::Dxt1 => dxt::decode_dxt1(block), + TextureFormat::Dxt5 => dxt::decode_dxt5(block), + TextureFormat::YcocgDxt5 => dxt::decode_ycocg(block), + _ => { + let a = dxt::decode_bc4(block); + std::array::from_fn(|k| [255, 255, 255, a[k]]) + } + }; + if let Some(t) = alpha_tex { + let a = dxt::decode_bc4(&t.data[(j * bx + i) * 8..(j * bx + i) * 8 + 8]); + for (p, a) in px.iter_mut().zip(a) { + p[3] = a; + } + } + for (k, p) in px.iter().enumerate() { + let (x, y) = (i * 4 + k % 4, j * 4 + k / 4); + if x < w && y < h { + rgba[(y * w + x) * 4..(y * w + x) * 4 + 4].copy_from_slice(p); + } + } + } + } + Ok(Image { width: self.width, height: self.height, rgba }) + } +} + +// ------------------------------------------------------------------------------------ encoder + +/// The Hap variants the encoder writes. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum Variant { + /// Hap: RGB in DXT1 (`Hap1`). + Hap, + /// Hap Alpha: RGBA in DXT5 (`Hap5`). + HapAlpha, + /// Hap Q: scaled YCoCg in DXT5 (`HapY`), higher quality, no alpha. + HapQ, + /// Hap Q Alpha: scaled YCoCg plus a BC4 alpha texture (`HapM`). + HapQAlpha, + /// Hap Alpha-Only: BC4 alpha (`HapA`). + HapAlphaOnly, +} + +impl Variant { + /// The codec's FourCC. + #[must_use] + pub const fn fourcc(self) -> [u8; 4] { + match self { + Self::Hap => *b"Hap1", + Self::HapAlpha => *b"Hap5", + Self::HapQ => *b"HapY", + Self::HapQAlpha => *b"HapM", + Self::HapAlphaOnly => *b"HapA", + } + } +} + +/// A Hap encoder for frames of one size and variant. +#[derive(Debug, Clone)] +pub struct Encoder { + width: u32, + height: u32, + variant: Variant, + snappy: bool, + chunks: usize, +} + +impl Encoder { + /// An encoder with no second stage and no chunks. + pub fn new(width: u32, height: u32, variant: Variant) -> Result { + check_dimensions(width, height)?; + Ok(Self { width, height, variant, snappy: false, chunks: 1 }) + } + + /// Compress the textures with Snappy. + #[must_use] + pub fn with_snappy(mut self, on: bool) -> Self { + self.snappy = on; + self + } + + /// Cut each texture into `n` chunks (at least 1), which a decoder can decompress in parallel. + #[must_use] + pub fn with_chunks(mut self, n: usize) -> Self { + self.chunks = n.clamp(1, 4096); + self + } + + /// Encode one RGBA picture (`width * height * 4` bytes) as a Hap frame. + pub fn encode_rgba(&self, rgba: &[u8]) -> Result> { + let (w, h) = (self.width as usize, self.height as usize); + if rgba.len() != w * h * 4 { + return Err(Error::Input(format!("{} bytes of pixels for {w}x{h}", rgba.len()))); + } + let (bx, by) = blocks(self.width, self.height); + let block_at = |i: usize, j: usize| -> dxt::Block { + std::array::from_fn(|k| { + // Pixels past the edge repeat the last row and column. + let (x, y) = ((i * 4 + k % 4).min(w - 1), (j * 4 + k / 4).min(h - 1)); + let p = (y * w + x) * 4; + [rgba[p], rgba[p + 1], rgba[p + 2], rgba[p + 3]] + }) + }; + let build = |format: TextureFormat, f: &dyn Fn(&dxt::Block) -> Vec| -> Texture { + let mut data = Vec::with_capacity(bx * by * format.block_bytes()); + for j in 0..by { + for i in 0..bx { + data.extend_from_slice(&f(&block_at(i, j))); + } + } + Texture { format, data } + }; + let mut out = Vec::new(); + match self.variant { + Variant::Hap => self.write_texture(&mut out, &build(TextureFormat::Dxt1, &|b| dxt::encode_dxt1(b).to_vec())), + Variant::HapAlpha => self.write_texture(&mut out, &build(TextureFormat::Dxt5, &|b| dxt::encode_dxt5(b).to_vec())), + Variant::HapQ => self.write_texture(&mut out, &build(TextureFormat::YcocgDxt5, &|b| dxt::encode_ycocg(b).to_vec())), + Variant::HapAlphaOnly => self.write_texture(&mut out, &build(TextureFormat::Bc4Alpha, &|b| dxt::encode_bc4(b).to_vec())), + Variant::HapQAlpha => { + let mut inner = Vec::new(); + self.write_texture(&mut inner, &build(TextureFormat::YcocgDxt5, &|b| dxt::encode_ycocg(b).to_vec())); + self.write_texture(&mut inner, &build(TextureFormat::Bc4Alpha, &|b| dxt::encode_bc4(b).to_vec())); + write_section(&mut out, SECTION_MULTIPLE, &inner); + } + } + Ok(out) + } + + fn write_texture(&self, out: &mut Vec, t: &Texture) { + let nibble = t.format.nibble(); + if self.chunks <= 1 { + if self.snappy { + write_section(out, 0xB0 | nibble, &snappy::compress(&t.data)); + } else { + write_section(out, 0xA0 | nibble, &t.data); + } + return; + } + // Chunks of whole blocks, as even as they go. + let bb = t.format.block_bytes(); + let total_blocks = t.data.len() / bb; + let n = self.chunks.min(total_blocks).max(1); + let (mut compressors, mut sizes, mut data) = (Vec::new(), Vec::new(), Vec::new()); + for c in 0..n { + let (from, to) = (c * total_blocks / n * bb, (c + 1) * total_blocks / n * bb); + let raw = &t.data[from..to]; + let packed = if self.snappy { Some(snappy::compress(raw)).filter(|p| p.len() < raw.len()) } else { None }; + let (kind, body) = packed.as_deref().map_or((CHUNK_NONE, raw), |p| (CHUNK_SNAPPY, p)); + compressors.push(kind); + sizes.extend_from_slice(&(body.len() as u32).to_le_bytes()); + data.extend_from_slice(body); + } + let mut instructions = Vec::new(); + write_section(&mut instructions, SECTION_COMPRESSORS, &compressors); + write_section(&mut instructions, SECTION_SIZES, &sizes); + let mut payload = Vec::new(); + write_section(&mut payload, SECTION_INSTRUCTIONS, &instructions); + payload.extend_from_slice(&data); + write_section(out, 0xC0 | nibble, &payload); + } +} diff --git a/crates/video/src/hap/snappy.rs b/crates/video/src/hap/snappy.rs new file mode 100644 index 000000000..47b346b7f --- /dev/null +++ b/crates/video/src/hap/snappy.rs @@ -0,0 +1,233 @@ +//! Snappy raw (unframed) compression, written from the public Snappy format description: a varint +//! of the uncompressed length, then literal and copy elements. Hap uses it as the second-stage +//! compressor of its texture data. + +use super::Error; + +/// Decompress `src`, which must expand to exactly `expected` bytes. The length in the preamble is +/// checked before anything is allocated, so a hostile stream cannot ask for more than `expected`. +pub(super) fn decompress(src: &[u8], expected: usize) -> Result, Error> { + let bad = || Error::Invalid("Snappy data is damaged".into()); + // The varint preamble. + let (mut len, mut shift, mut pos) = (0u64, 0u32, 0usize); + loop { + let b = *src.get(pos).ok_or_else(bad)?; + pos += 1; + len |= u64::from(b & 0x7F) << shift; + if b & 0x80 == 0 { + break; + } + shift += 7; + if shift > 28 { + return Err(bad()); + } + } + if len != expected as u64 { + return Err(Error::Invalid(format!("Snappy data expands to {len} bytes, expected {expected}"))); + } + let mut out: Vec = Vec::with_capacity(expected); + while pos < src.len() { + let tag = src[pos]; + pos += 1; + match tag & 3 { + 0 => { + let mut n = usize::from(tag >> 2); + if n >= 60 { + let extra = n - 59; + let bytes = src.get(pos..pos + extra).ok_or_else(bad)?; + n = bytes.iter().rev().fold(0usize, |a, &b| (a << 8) | usize::from(b)); + pos += extra; + } + n += 1; + let lit = src.get(pos..pos.checked_add(n).ok_or_else(bad)?).ok_or_else(bad)?; + if out.len() + n > expected { + return Err(bad()); + } + out.extend_from_slice(lit); + pos += n; + } + kind => { + let (n, offset) = match kind { + 1 => { + let b = *src.get(pos).ok_or_else(bad)?; + pos += 1; + (4 + usize::from((tag >> 2) & 7), (usize::from(tag >> 5) << 8) | usize::from(b)) + } + 2 => { + let b = src.get(pos..pos + 2).ok_or_else(bad)?; + pos += 2; + (usize::from(tag >> 2) + 1, usize::from(u16::from_le_bytes([b[0], b[1]]))) + } + _ => { + let b = src.get(pos..pos + 4).ok_or_else(bad)?; + pos += 4; + (usize::from(tag >> 2) + 1, u32::from_le_bytes([b[0], b[1], b[2], b[3]]) as usize) + } + }; + if offset == 0 || offset > out.len() || out.len() + n > expected { + return Err(bad()); + } + // Copies may overlap their own output, so go byte by byte. + let start = out.len() - offset; + for i in 0..n { + let b = out[start + i]; + out.push(b); + } + } + } + } + if out.len() != expected { + return Err(bad()); + } + Ok(out) +} + +fn push_literal(out: &mut Vec, lit: &[u8]) { + let mut rest = lit; + while !rest.is_empty() { + let n = rest.len().min(1 << 24); + let (now, later) = rest.split_at(n); + let m = n - 1; + if m < 60 { + out.push((m as u8) << 2); + } else if m < 1 << 8 { + out.extend_from_slice(&[60 << 2, m as u8]); + } else if m < 1 << 16 { + out.extend_from_slice(&[61 << 2, m as u8, (m >> 8) as u8]); + } else { + out.extend_from_slice(&[62 << 2, m as u8, (m >> 8) as u8, (m >> 16) as u8]); + } + out.extend_from_slice(now); + rest = later; + } +} + +fn push_copy(out: &mut Vec, offset: usize, mut len: usize) { + while len > 0 { + // Copies of 4 to 11 bytes at offsets below 2048 take two bytes; the rest take three. + let n = if len >= 68 { + 64 + } else if len > 64 { + 60 + } else { + len + }; + if (4..=11).contains(&n) && offset < 2048 { + out.push(1 | (((n - 4) as u8) << 2) | (((offset >> 8) as u8) << 5)); + out.push(offset as u8); + } else { + out.push(2 | (((n - 1) as u8) << 2)); + out.extend_from_slice(&(offset as u16).to_le_bytes()); + } + len -= n; + } +} + +/// Compress `src` into a Snappy stream: greedy matching over a hash of four bytes, offsets up to +/// 64 KiB. +pub(super) fn compress(src: &[u8]) -> Vec { + let mut out = Vec::with_capacity(src.len() / 2 + 16); + let mut n = src.len(); + loop { + let b = (n & 0x7F) as u8; + n >>= 7; + if n == 0 { + out.push(b); + break; + } + out.push(b | 0x80); + } + const BITS: u32 = 15; + let mut table = vec![usize::MAX; 1 << BITS]; + let hash = |i: usize| -> usize { + let v = u32::from_le_bytes([src[i], src[i + 1], src[i + 2], src[i + 3]]); + (v.wrapping_mul(0x1E35_A7BD) >> (32 - BITS)) as usize + }; + let (mut i, mut lit_start) = (0usize, 0usize); + while i + 4 <= src.len() { + let h = hash(i); + let cand = table[h]; + table[h] = i; + if cand != usize::MAX && i - cand <= 65535 && src[cand..cand + 4] == src[i..i + 4] { + let mut len = 4; + while i + len < src.len() && src[cand + len] == src[i + len] { + len += 1; + } + push_literal(&mut out, &src[lit_start..i]); + push_copy(&mut out, i - cand, len); + i += len; + lit_start = i; + } else { + i += 1; + } + } + push_literal(&mut out, &src[lit_start..]); + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn round_trips_assorted_data() { + let mut seed = 1u32; + let mut noise = Vec::new(); + for _ in 0..5000 { + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + noise.push(seed as u8); + } + let cases: Vec> = vec![ + vec![], + vec![7], + vec![1, 2, 3], + vec![0; 100_000], + (0..70_000u32).map(|i| (i % 251) as u8).collect(), + noise.clone(), + [noise.clone(), noise].concat(), + b"abcabcabcabcabcabcabcabcabcabcabcabcabcabcabc".repeat(20), + ]; + for data in cases { + let packed = compress(&data); + assert_eq!(decompress(&packed, data.len()).expect("decompress"), data, "len {}", data.len()); + } + } + + #[test] + fn repetitive_data_gets_smaller() { + assert!(compress(&vec![5u8; 50_000]).len() < 3_000); + } + + #[test] + fn decodes_the_format_description_forms() { + // A literal, then a 1-byte-offset copy that overlaps its own output. + let s = [9, 0x0C, b'a', b'b', b'c', b'd', 0b0000_0101, 4]; + // "abcd" + copy len 4+... : length field (5>>2)&7 = 1 -> 5 bytes, offset 4 -> total 9. + assert_eq!(decompress(&s, 9).expect("decode"), b"abcdabcda"); + // A literal of 61 bytes uses the extra-length form. + let mut s = vec![61, 60 << 2, 60]; + s.extend_from_slice(&[3; 61]); + assert_eq!(decompress(&s, 61).expect("decode"), vec![3; 61]); + } + + #[test] + fn hostile_streams_are_errors() { + // Wrong length in the preamble. + assert!(decompress(&[5, 0x00, b'x'], 10).is_err()); + // Copy before any output. + assert!(decompress(&[4, 0b0000_0001, 1], 4).is_err()); + // Offset of zero. + assert!(decompress(&[8, 0x0C, b'a', b'b', b'c', b'd', 0b0000_0001, 0], 8).is_err()); + // Literal longer than the stream. + assert!(decompress(&[4, 0x0C, b'a'], 4).is_err()); + // Overlong varint. + assert!(decompress(&[0x80, 0x80, 0x80, 0x80, 0x80, 0x01], 0).is_err()); + // Output past the stated length. + assert!(decompress(&[2, 0x0C, b'a', b'b', b'c', b'd'], 2).is_err()); + // Too short. + assert!(decompress(&[4, 0x00, b'a'], 4).is_err()); + assert!(decompress(&[], 0).is_err()); + } +} diff --git a/crates/video/src/lib.rs b/crates/video/src/lib.rs index da4e32006..8085c42fa 100644 --- a/crates/video/src/lib.rs +++ b/crates/video/src/lib.rs @@ -11,6 +11,7 @@ //! | `mpeg2` | [`mpeg2`] | MPEG-2 video (ITU-T H.262) and MPEG-1 video: decoder (`mpeg2-decode`) and MPEG-2 I/P/B encoder (`mpeg2-encode`) | //! | `mpeg4` | [`mpeg4`] | MPEG-4 Part 2 video (ISO/IEC 14496-2, Xvid/DivX): Simple profile encoder (`mpeg4-encode`) | //! | `ffv1` | [`ffv1`] | FFV1 lossless video (RFC 9043): version 3, range coder, decoder and encoder | +//! | `hap` | [`hap`] | Vidvox Hap, Hap Alpha, Hap Q, Hap Q Alpha, Hap Alpha-Only: decoder and encoder | //! | `mjpeg` | [`mjpeg`] | Motion JPEG: frame-level decoder and baseline encoder over `craft-jpeg` | //! | `prores` | [`prores`] | Apple ProRes (SMPTE RDD 36): decoder and encoder | //! | `h264` | [`h264`] | ITU-T H.264 / AVC: decoder (`h264-decode`) and encoder (`h264-encode`) | @@ -46,6 +47,9 @@ pub mod mpeg4; #[cfg(feature = "ffv1")] pub mod ffv1; +#[cfg(feature = "hap")] +pub mod hap; + #[cfg(feature = "mjpeg")] pub mod mjpeg; diff --git a/crates/video/tests/hap.rs b/crates/video/tests/hap.rs new file mode 100644 index 000000000..e45dab7e9 --- /dev/null +++ b/crates/video/tests/hap.rs @@ -0,0 +1,315 @@ +//! Hap tests: round trips, chunking, hostile input, and ffmpeg's decoder as the reference (oracle; +//! skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). ffmpeg has no +//! Hap encoder here, so the oracle is one-way: it decodes the frames our encoder writes, in an AVI +//! file, to the pictures our decoder returns. + +use craft_media::avi::{AviWriter, MuxOptions, StreamSpec, VideoSpec}; +use craft_video::hap::{Decoder, Encoder, Error, Image, TextureFormat, Variant}; +use std::path::Path; +use std::process::Command; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +/// A picture of smooth gradients, hard edges, noise, flat areas and a soft alpha ramp. +fn picture(w: u32, h: u32, salt: u32) -> Vec { + let mut seed = 0x9E37_79B9u32 ^ salt; + let mut out = Vec::new(); + for y in 0..h { + for x in 0..w { + let (r, g, b) = match (y / 13 + x / 29) % 4 { + 0 => ((x * 3 + salt) as u8, (y * 4) as u8, ((x + y) * 2) as u8), + 1 => (xorshift(&mut seed) as u8, xorshift(&mut seed) as u8, xorshift(&mut seed) as u8), + 2 => (200, 40, 90), + _ => (if (x / 3) % 2 == 0 { 255 } else { 0 }, 128, if (y / 3) % 2 == 0 { 255 } else { 0 }), + }; + out.extend_from_slice(&[r, g, b, (x * 255 / w.max(1)) as u8]); + } + } + out +} + +/// Gradients, edges and flat areas, with no noise, the kind of picture block compression suits. +fn smooth(w: u32, h: u32) -> Vec { + let mut out = Vec::new(); + for y in 0..h { + for x in 0..w { + let (r, g, b) = match (y / 16 + x / 24) % 3 { + 0 => ((x * 255 / w.max(1)) as u8, (y * 255 / h.max(1)) as u8, 128), + 1 => (230, 60, 20), + _ => (if (x / 8) % 2 == 0 { 250 } else { 10 }, 120, 40), + }; + out.extend_from_slice(&[r, g, b, (x * 255 / w.max(1)) as u8]); + } + } + out +} + +fn psnr(a: &[u8], b: &[u8], channels: usize) -> f64 { + let (mut err, mut n) = (0f64, 0f64); + for (p, q) in a.chunks(4).zip(b.chunks(4)) { + for c in 0..channels { + err += (f64::from(p[c]) - f64::from(q[c])).powi(2); + n += 1.0; + } + } + if err == 0.0 { 99.0 } else { 10.0 * (255.0 * 255.0 * n / err).log10() } +} + +const VARIANTS: [Variant; 5] = [Variant::Hap, Variant::HapAlpha, Variant::HapQ, Variant::HapQAlpha, Variant::HapAlphaOnly]; + +fn channels(v: Variant) -> usize { + match v { + Variant::HapAlpha | Variant::HapQAlpha => 4, + _ => 3, + } +} + +#[test] +fn every_variant_round_trips_at_good_quality() { + for (w, h) in [(64u32, 48u32), (130, 70), (4, 4), (1, 1), (17, 5)] { + let src = smooth(w, h); + for v in VARIANTS { + for (snappy, chunks) in [(false, 1usize), (true, 1), (false, 3), (true, 4)] { + let enc = Encoder::new(w, h, v).expect("encoder").with_snappy(snappy).with_chunks(chunks); + let frame = enc.encode_rgba(&src).expect("encode"); + let img = Decoder::new(w, h).expect("decoder").decode_rgba(&frame).expect("decode"); + assert_eq!((img.width, img.height, img.rgba.len()), (w, h, (w * h * 4) as usize)); + if v == Variant::HapAlphaOnly { + let (a, b): (Vec, Vec) = (src.chunks(4).map(|p| p[3]).collect(), img.rgba.chunks(4).map(|p| p[3]).collect()); + let worst = a.iter().zip(&b).map(|(x, y)| x.abs_diff(*y)).max().unwrap_or(0); + assert!(worst <= 16, "{v:?} {w}x{h}: alpha off by {worst}"); + } else if w >= 16 && h >= 16 { + let q = psnr(&src, &img.rgba, channels(v).min(3)); + assert!(q > 30.0, "{v:?} {w}x{h} snappy={snappy} chunks={chunks}: {q:.1} dB"); + } + } + } + } +} + +#[test] +fn snappy_and_chunks_do_not_change_the_pixels() { + let (w, h) = (96, 64); + let src = picture(w, h, 3); + for v in VARIANTS { + let want = Decoder::new(w, h).expect("d").decode_rgba(&Encoder::new(w, h, v).expect("e").encode_rgba(&src).expect("enc")).expect("dec"); + for (snappy, chunks) in [(true, 1usize), (false, 5), (true, 7), (true, 600)] { + let frame = Encoder::new(w, h, v).expect("e").with_snappy(snappy).with_chunks(chunks).encode_rgba(&src).expect("enc"); + let got = Decoder::new(w, h).expect("d").decode_rgba(&frame).expect("dec"); + assert_eq!(got, want, "{v:?} snappy={snappy} chunks={chunks}"); + } + } +} + +#[test] +fn flat_colours_are_exact_in_rgb_variants() { + let (w, h) = (32, 32); + for v in [Variant::Hap, Variant::HapAlpha, Variant::HapQ, Variant::HapQAlpha] { + for rgb in [[0u8, 0, 0], [255, 255, 255], [255, 0, 0], [0, 255, 0], [0, 0, 255], [8, 16, 24]] { + let src: Vec = (0..w * h).flat_map(|_| [rgb[0], rgb[1], rgb[2], 255]).collect(); + let frame = Encoder::new(w, h, v).expect("e").encode_rgba(&src).expect("enc"); + let img = Decoder::new(w, h).expect("d").decode_rgba(&frame).expect("dec"); + let worst = src.iter().zip(&img.rgba).map(|(a, b)| a.abs_diff(*b)).max().unwrap_or(0); + // 565 endpoints and the YCoCg round trip put a flat colour within a few levels. + assert!(worst <= 8, "{v:?} {rgb:?}: off by {worst}"); + } + } +} + +#[test] +fn textures_come_back_as_stored() { + let src = picture(64, 32, 1); + let frame = Encoder::new(64, 32, Variant::HapQAlpha).expect("e").with_snappy(true).encode_rgba(&src).expect("enc"); + let t = Decoder::new(64, 32).expect("d").decode_textures(&frame).expect("textures"); + assert_eq!(t.len(), 2); + assert_eq!((t[0].format, t[0].data.len()), (TextureFormat::YcocgDxt5, 16 * 8 * 16)); + assert_eq!((t[1].format, t[1].data.len()), (TextureFormat::Bc4Alpha, 16 * 8 * 8)); + assert_eq!(Variant::HapQAlpha.fourcc(), *b"HapM"); +} + +#[test] +fn offsets_table_and_unknown_sections_are_honoured() { + // A chunked frame built by hand: two chunks, stored out of order through an offset table, and + // a sub-section of an unknown type that must be skipped. + let tex: Vec = (0..16 * 8).map(|i| i as u8).collect(); // 16 DXT1 blocks = 16x16 pixels + let sect = |kind: u8, p: &[u8]| { + let mut v = vec![p.len() as u8, (p.len() >> 8) as u8, (p.len() >> 16) as u8, kind]; + v.extend_from_slice(p); + v + }; + let (first, second) = tex.split_at(64); + let data = [second, first].concat(); // second half stored first + let mut ins = sect(0x02, &[0x0A, 0x0A]); + ins.extend(sect(0x7F, b"junk")); + ins.extend(sect(0x03, &[[64u32, 64].map(u32::to_le_bytes)].concat().concat())); + ins.extend(sect(0x04, &[[64u32, 0].map(u32::to_le_bytes)].concat().concat())); + let mut payload = sect(0x01, &ins); + payload.extend_from_slice(&data); + let frame = sect(0xCB, &payload); + let t = Decoder::new(16, 16).expect("d").decode_textures(&frame).expect("textures"); + assert_eq!(t[0].data, tex); +} + +#[test] +fn big_sections_use_the_long_header() { + // 1024 x 1024 DXT5 is 1 MiB; at 4096 x 4096 a section tops 16 MiB and needs the 8-byte header. + let (w, h) = (4096u32, 4096u32); + let src = vec![77u8; (w * h * 4) as usize]; + let frame = Encoder::new(w, h, Variant::HapAlpha).expect("e").encode_rgba(&src).expect("enc"); + assert_eq!(&frame[..3], &[0, 0, 0]); + assert_eq!(frame[3], 0xAE); + let t = Decoder::new(w, h).expect("d").decode_textures(&frame).expect("textures"); + assert_eq!(t[0].data.len(), 1024 * 1024 * 16); +} + +#[test] +fn bad_parameters_are_errors() { + assert!(matches!(Decoder::new(0, 10), Err(Error::Input(_)))); + assert!(matches!(Decoder::new(40_000, 10), Err(Error::Input(_)))); + assert!(matches!(Encoder::new(10, 0, Variant::Hap), Err(Error::Input(_)))); + assert!(matches!(Encoder::new(32768, 32768, Variant::Hap), Err(Error::Input(_)))); + let e = Encoder::new(8, 8, Variant::Hap).expect("e"); + assert!(matches!(e.encode_rgba(&[0; 10]), Err(Error::Input(_)))); +} + +#[test] +fn hostile_frames_are_errors_not_panics() { + let (w, h) = (32, 32); + let d = Decoder::new(w, h).expect("d"); + let src = picture(w, h, 9); + let good = Encoder::new(w, h, Variant::HapQAlpha).expect("e").with_snappy(true).with_chunks(3).encode_rgba(&src).expect("enc"); + assert!(d.decode_rgba(&good).is_ok()); + // Every truncation. + for n in 0..good.len() { + assert!(d.decode_rgba(&good[..n]).is_err(), "truncated to {n}"); + } + // Every single-byte corruption must be handled, with an error or a picture. + let mut seed = 3u32; + for _ in 0..3000 { + let mut bad = good.clone(); + let i = xorshift(&mut seed) as usize % bad.len(); + bad[i] = xorshift(&mut seed) as u8; + let _ = d.decode_rgba(&bad); + } + // Random bytes with plausible headers. + for kind in [0xAB, 0xBB, 0xCB, 0xAE, 0xBF, 0xCF, 0xA1, 0xB1, 0xC1, 0x0D, 0xAC, 0xA2, 0x00, 0xFF] { + for len in [0usize, 1, 3, 4, 8, 100] { + let mut f = vec![len as u8, 0, 0, kind]; + f.extend((0..len).map(|_| xorshift(&mut seed) as u8)); + let _ = d.decode_textures(&f); + let _ = d.decode_rgba(&f); + } + } + // Sizes that overflow or lie. + assert!(d.decode_rgba(&[0, 0, 0, 0xAB, 0xFF, 0xFF, 0xFF, 0xFF]).is_err()); + assert!(d.decode_rgba(&[0xFF, 0xFF, 0xFF, 0xAB]).is_err()); + assert!(d.decode_rgba(&[]).is_err()); + // BC7 frames are read but not turned into pictures. + let mut bc7 = vec![0, 4, 0, 0xAC]; + bc7.extend(vec![0u8; 1024]); + assert!(d.decode_textures(&bc7).is_ok()); + assert!(matches!(d.decode_rgba(&bc7), Err(Error::Unsupported(_)))); +} + +fn ffmpeg_pictures(ffmpeg: &Path, avi: &Path, pix_fmt: &str) -> Vec { + let out = Command::new(ffmpeg) + .args(["-hide_banner", "-nostdin", "-v", "error", "-i"]) + .arg(avi) + .args(["-f", "rawvideo", "-pix_fmt", pix_fmt, "-"]) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg failed on {}: {}", avi.display(), String::from_utf8_lossy(&out.stderr)); + out.stdout +} + +fn avi_of(fourcc: [u8; 4], w: u32, h: u32, frames: &[Vec]) -> Vec { + let spec = VideoSpec::new(fourcc, w, h, 25, 1); + let mut mux = AviWriter::new(std::io::Cursor::new(Vec::new()), vec![StreamSpec::Video(spec)], MuxOptions::default()).expect("writer"); + for f in frames { + mux.write_chunk(0, f, true).expect("chunk"); + } + mux.finish().expect("finish").into_inner() +} + +#[test] +fn ffmpeg_decodes_our_frames_to_our_pictures() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("hap"); + let mut worst_overall = 0u8; + for (w, h) in [(64u32, 48u32), (130, 70), (36, 20)] { + for v in VARIANTS { + for (snappy, chunks) in [(false, 1usize), (true, 1), (true, 4), (false, 3)] { + let enc = Encoder::new(w, h, v).expect("e").with_snappy(snappy).with_chunks(chunks); + let dec = Decoder::new(w, h).expect("d"); + let pics: Vec = (0..3).map(|i| dec.decode_rgba(&enc.encode_rgba(&picture(w, h, i)).expect("enc")).expect("dec")).collect(); + let frames: Vec> = (0..3).map(|i| enc.encode_rgba(&picture(w, h, i)).expect("enc")).collect(); + let name = format!("{}_{w}x{h}_{}_{chunks}.avi", String::from_utf8_lossy(&v.fourcc()), u8::from(snappy)); + let file = dir.join(&name); + std::fs::write(&file, avi_of(v.fourcc(), w, h, &frames)).expect("write fixture"); + let theirs = ffmpeg_pictures(&ffmpeg, &file, "rgba"); + let n = (w * h * 4) as usize; + assert_eq!(theirs.len(), 3 * n, "{name}: ffmpeg returned {} bytes", theirs.len()); + for (i, pic) in pics.iter().enumerate() { + let t = &theirs[i * n..(i + 1) * n]; + let worst = if v == Variant::HapAlphaOnly { + // ffmpeg decodes the alpha-only format to a grey picture. + pic.rgba.chunks(4).zip(t.chunks(4)).map(|(a, b)| a[3].abs_diff(b[0])).max().unwrap_or(0) + } else { + // Hap1 and HapY have no alpha: compare colour only. + let c = channels(v); + pic.rgba.chunks(4).zip(t.chunks(4)).flat_map(|(a, b)| (0..c).map(move |k| a[k].abs_diff(b[k]))).max().unwrap_or(0) + }; + worst_overall = worst_overall.max(worst); + assert!(worst == 0, "{name} frame {i}: ffmpeg differs from us by up to {worst}"); + } + } + } + } + eprintln!("worst difference from ffmpeg: {worst_overall}"); +} + +/// Arbitrary texture bytes, not only what our encoder writes, decode to what ffmpeg decodes: this +/// covers every endpoint order, palette index and YCoCg scale a block can hold. +#[test] +fn ffmpeg_decodes_arbitrary_blocks_to_our_pictures() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("hap"); + let mut seed = 0xDEAD_BEEFu32; + let (w, h) = (64u32, 64u32); + let blocks = (w / 4 * (h / 4)) as usize; + for (v, kind, block_bytes) in + [(Variant::Hap, 0xABu8, 8usize), (Variant::HapAlpha, 0xAE, 16), (Variant::HapQ, 0xAF, 16), (Variant::HapAlphaOnly, 0xA1, 8)] + { + let dec = Decoder::new(w, h).expect("d"); + let frames: Vec> = (0..20) + .map(|_| { + let n = blocks * block_bytes; + let mut f = vec![n as u8, (n >> 8) as u8, (n >> 16) as u8, kind]; + f.extend((0..n).map(|_| xorshift(&mut seed) as u8)); + f + }) + .collect(); + let file = dir.join(format!("random_{}.avi", String::from_utf8_lossy(&v.fourcc()))); + std::fs::write(&file, avi_of(v.fourcc(), w, h, &frames)).expect("write fixture"); + let theirs = ffmpeg_pictures(&ffmpeg, &file, "rgba"); + let n = (w * h * 4) as usize; + assert_eq!(theirs.len(), frames.len() * n); + for (i, f) in frames.iter().enumerate() { + let ours = dec.decode_rgba(f).expect("decode"); + let t = &theirs[i * n..(i + 1) * n]; + let same = if v == Variant::HapAlphaOnly { + ours.rgba.chunks(4).zip(t.chunks(4)).all(|(a, b)| a[3] == b[0]) + } else if v == Variant::HapAlpha { + ours.rgba == t + } else { + ours.rgba.chunks(4).zip(t.chunks(4)).all(|(a, b)| a[..3] == b[..3]) + }; + assert!(same, "{v:?} random frame {i} differs from ffmpeg"); + } + } +} From 38e5614b9c41cc96240d610cb3da50367b4fa42b Mon Sep 17 00:00:00 2001 From: Joseph Anglada Date: Mon, 16 Nov 2026 22:30:04 -0400 Subject: [PATCH 15/64] SmartArt: an item's opacity is read, written and drawn (#1906) --- crates/docx/src/read/chart.rs | 18 ++++++- crates/docx/src/read/chart/canvas.rs | 9 +++- crates/docx/src/read/chart/plot.rs | 4 +- crates/docx/src/read/chart/polar.rs | 2 +- crates/docx/src/read/diagram.rs | 10 +++- crates/docx/src/smart_art.rs | 63 +++++++++++++++++++++++- crates/flow/src/from_doc.rs | 9 +++- crates/odf/src/text/frames.rs | 2 +- crates/odf/src/text/tests_more/groups.rs | 18 ++++++- crates/odf/src/text/tests_more/shapes.rs | 15 +++++- crates/odf/src/text/writer/drawing.rs | 8 ++- crates/wordmodel/src/graphic.rs | 7 +++ crates/wordmodel/src/smart_art.rs | 7 ++- 13 files changed, 154 insertions(+), 18 deletions(-) diff --git a/crates/docx/src/read/chart.rs b/crates/docx/src/read/chart.rs index 4b7696eee..74ec1e760 100644 --- a/crates/docx/src/read/chart.rs +++ b/crates/docx/src/read/chart.rs @@ -129,7 +129,14 @@ fn placeholder(out: &mut Vec, space: &El, theme: &[Rgb], w: f32, h: } let Some(ty) = plot.els().find(|e| e.name.ends_with("Chart")) else { return }; backdrop(out, space, theme, w, h); - out.push(GraphicItem::Shape { rect: [0.0, 0.0, w, h], kind: ShapeKind::Rectangle, fill: None, stroke: Some(AXIS), stroke_width: 0.75 }); + out.push(GraphicItem::Shape { + rect: [0.0, 0.0, w, h], + kind: ShapeKind::Rectangle, + fill: None, + stroke: Some(AXIS), + stroke_width: 0.75, + alpha: 1.0, + }); let mut area = Rect { x: PAD, y: PAD, w: (w - 2.0 * PAD).max(1.0), h: (h - 2.0 * PAD).max(1.0) }; if let Some(t) = title_of(chart, &read_series(ty, false, theme)) { area = title_block(out, &t, area); @@ -150,7 +157,14 @@ pub(crate) fn chartex_items(space: Option<&El>, w: f32, h: f32) -> Vec 0.0 && h > 0.0) { return out; } - out.push(GraphicItem::Shape { rect: [0.0, 0.0, w, h], kind: ShapeKind::Rectangle, fill: None, stroke: Some(AXIS), stroke_width: 0.75 }); + out.push(GraphicItem::Shape { + rect: [0.0, 0.0, w, h], + kind: ShapeKind::Rectangle, + fill: None, + stroke: Some(AXIS), + stroke_width: 0.75, + alpha: 1.0, + }); let mut area = Rect { x: PAD, y: PAD, w: (w - 2.0 * PAD).max(1.0), h: (h - 2.0 * PAD).max(1.0) }; let chart = space.and_then(|s| s.child("cx:chart")); let title = chart.and_then(|c| c.child("cx:title")).and_then(|t| { diff --git a/crates/docx/src/read/chart/canvas.rs b/crates/docx/src/read/chart/canvas.rs index ab3fbf410..ce3025d40 100644 --- a/crates/docx/src/read/chart/canvas.rs +++ b/crates/docx/src/read/chart/canvas.rs @@ -69,7 +69,14 @@ pub(super) fn stroke(out: &mut Vec, segs: Vec, color: Rgb, } fn swatch(out: &mut Vec, x: f32, y: f32, color: Rgb) { - out.push(GraphicItem::Shape { rect: [x, y, SWATCH, SWATCH], kind: ShapeKind::Rectangle, fill: Some(color), stroke: None, stroke_width: 0.0 }); + out.push(GraphicItem::Shape { + rect: [x, y, SWATCH, SWATCH], + kind: ShapeKind::Rectangle, + fill: Some(color), + stroke: None, + stroke_width: 0.0, + alpha: 1.0, + }); } pub(super) fn seg(x0: f32, y0: f32, x1: f32, y1: f32) -> Vec { diff --git a/crates/docx/src/read/chart/plot.rs b/crates/docx/src/read/chart/plot.rs index 22d05b554..255b1c671 100644 --- a/crates/docx/src/read/chart/plot.rs +++ b/crates/docx/src/read/chart/plot.rs @@ -24,7 +24,7 @@ pub(super) fn backdrop(out: &mut Vec, space: &El, theme: &[Rgb], w: let stroke = ln.and_then(|l| fill_colour(l, theme)); let stroke_width = ln.and_then(|l| l.attr("w")).and_then(|v| measure(v, 12_700.0)).unwrap_or(0.75).clamp(0.0, 20.0); if fill.is_some() || stroke.is_some() { - out.push(GraphicItem::Shape { rect: [0.0, 0.0, w, h], kind: ShapeKind::Rectangle, fill, stroke, stroke_width }); + out.push(GraphicItem::Shape { rect: [0.0, 0.0, w, h], kind: ShapeKind::Rectangle, fill, stroke, stroke_width, alpha: 1.0 }); } } @@ -544,7 +544,7 @@ fn markers(out: &mut Vec, pts: impl Iterator, co let size = s.marker_size.filter(|v| v.is_finite()).unwrap_or(MARKER).clamp(2.0, 72.0); let h = size / 2.0; let shape = |out: &mut Vec, rect: [f32; 4], kind: ShapeKind| { - out.push(GraphicItem::Shape { rect, kind, fill: Some(colour), stroke: None, stroke_width: 0.0 }); + out.push(GraphicItem::Shape { rect, kind, fill: Some(colour), stroke: None, stroke_width: 0.0, alpha: 1.0 }); }; let mut strokes = Vec::new(); for (x, y) in pts { diff --git a/crates/docx/src/read/chart/polar.rs b/crates/docx/src/read/chart/polar.rs index cf5e7452e..b62ded6e5 100644 --- a/crates/docx/src/read/chart/polar.rs +++ b/crates/docx/src/read/chart/polar.rs @@ -96,7 +96,7 @@ pub(super) fn radar(out: &mut Vec, c: &Chart, area: Rect) { for (i, p) in ring.iter().enumerate() { if c.radar_marks && s.values.get(i).copied().flatten().is_some() { let rect = [p.0 as f32 - MARKER / 2.0, p.1 as f32 - MARKER / 2.0, MARKER, MARKER]; - out.push(GraphicItem::Shape { rect, kind: ShapeKind::Ellipse, fill: Some(col), stroke: None, stroke_width: 0.0 }); + out.push(GraphicItem::Shape { rect, kind: ShapeKind::Ellipse, fill: Some(col), stroke: None, stroke_width: 0.0, alpha: 1.0 }); } if let Some(text) = label_of(s, i) { labels.push(DataLabel { x: p.0 as f32, y: p.1 as f32, text, inside: false, pos: LabelPos::Above, off: 0.0 }); diff --git a/crates/docx/src/read/diagram.rs b/crates/docx/src/read/diagram.rs index 7b7bbeebf..39319dd1f 100644 --- a/crates/docx/src/read/diagram.rs +++ b/crates/docx/src/read/diagram.rs @@ -7,7 +7,7 @@ use craft_wordmodel::props::Rgb; use super::Reader; use super::chart::text_w; -use super::drawing_color::{color, paint}; +use super::drawing_color::{color, color_alpha, paint}; use crate::package::{Rel, Rels, rel_is, rt}; use crate::units::{MAX_LEN_PT, int}; use crate::xml::El; @@ -164,7 +164,7 @@ fn shape(sp: &El, xf: Xf, b: [f64; 4], theme: &[Rgb], fit: f32, image: &mut dyn }, }; match geo { - Geo::Kind(kind) => out.push(GraphicItem::Shape { rect, kind, fill, stroke, stroke_width }), + Geo::Kind(kind) => out.push(GraphicItem::Shape { rect, kind, fill, stroke, stroke_width, alpha: fill_opacity(sppr, theme) }), Geo::Poly(pts, closed) if !pts.is_empty() => { // Flip in the box, then turn about its centre (clockwise, y down). let (s, c) = rot.to_radians().sin_cos(); @@ -215,6 +215,12 @@ fn fill_of(sp: &El, sppr: Option<&El>, theme: &[Rgb]) -> Option { } } +/// How opaque a shape's own solid fill is, 0 to 1. +fn fill_opacity(sppr: Option<&El>, theme: &[Rgb]) -> f32 { + let solid = sppr.and_then(|p| p.child("a:solidFill")); + solid.and_then(|f| color_alpha(f, theme, None)).map_or(1.0, |(_, t)| 1.0 - t / 100.0) +} + /// A shape's outline colour and width in points (`a:ln`, else the style's line at 0.75 pt). fn line_of(sp: &El, sppr: Option<&El>, theme: &[Rgb]) -> (Option, f32) { let ln = sppr.and_then(|p| p.child("a:ln")); diff --git a/crates/docx/src/smart_art.rs b/crates/docx/src/smart_art.rs index a8002a6e6..1d4a90f50 100644 --- a/crates/docx/src/smart_art.rs +++ b/crates/docx/src/smart_art.rs @@ -156,6 +156,7 @@ impl Sh { /// keep the theme's background colour so adjacent nodes remain separated. fn recolor(&mut self, spec: &SmartArtSpec, i: usize) { let Some(c) = spec.items.get(i).and_then(|it| it.color) else { return }; + self.alpha = Some(u32::from(spec.items.get(i).and_then(|it| it.opacity).unwrap_or(100).min(100)) * 1000); for p in [&mut self.fill, &mut self.line] { if let Paint::Accent(_, tint) = *p { *p = Paint::Rgb(c, tint); @@ -788,7 +789,14 @@ pub fn data_xml(spec: &SmartArtSpec, drawing_rel: &str) -> String { Some(c) => { w.open("dgm:spPr", &[]); w.open("a:solidFill", &[]); - w.empty("a:srgbClr", &[("val", &c.hex())]); + match it.opacity { + Some(o) => { + w.open("a:srgbClr", &[("val", &c.hex())]); + w.empty("a:alpha", &[("val", &(u32::from(o.min(100)) * 1000).to_string())]); + w.close("a:srgbClr"); + } + None => w.empty("a:srgbClr", &[("val", &c.hex())]), + } w.close("a:solidFill"); w.close("dgm:spPr"); } @@ -1114,7 +1122,11 @@ pub(crate) fn spec_of(data: &El) -> Option { let text: String = p.child("dgm:t")?.child("a:p")?.children("a:r").filter_map(|r| r.child("a:t")).map(|t| t.text()).collect(); let color = p.child("dgm:spPr").and_then(|s| s.child("a:solidFill")).and_then(|f| f.child("a:srgbClr")).and_then(|c| Rgb::parse(c.attr("val")?)); - Some(SmartArtItem { text, level: (*l)?, color }) + let opacity = color.and_then(|_| { + let a = p.child("dgm:spPr")?.child("a:solidFill")?.child("a:srgbClr")?.child("a:alpha")?; + u8::try_from((a.attr("val")?.parse::().ok()? / 1000).min(100)).ok() + }); + Some(SmartArtItem { text, level: (*l)?, color, opacity }) }) .collect::>>()?; let spec = SmartArtSpec { layout, items, colors }.sanitized(); @@ -1256,3 +1268,50 @@ mod tests { } } } + +#[cfg(test)] +mod opacity_tests { + use super::*; + + #[test] + fn an_items_opacity_is_drawn_and_read_back() { + let mut spec = SmartArtSpec::sample(SmartArtLayout::Venn); + spec.items[0].color = Some(Rgb(0x12, 0x34, 0x56)); + spec.items[0].opacity = Some(12); + let drawing = drawing_xml(&spec, 400.0, 250.0); + assert!(drawing.contains(" { + GraphicItem::Shape { rect, kind, fill, stroke, stroke_width, alpha } if finite(rect) => { let look = BoxLook { - fill: fill.map(craft_wordmodel::fill::Fill::solid).filter(|_| *kind != ShapeKind::Line), + fill: fill + .map(|color| craft_wordmodel::fill::Fill::Solid { + color, + transparency: (1.0 - if alpha.is_finite() { alpha.clamp(0.0, 1.0) } else { 1.0 }) * 100.0, + }) + .filter(|_| *kind != ShapeKind::Line), line: stroke.filter(|_| stroke_width.is_finite() && *stroke_width > 0.0).map(|c| (c, stroke_width.min(12.0))), ..plain.clone() }; diff --git a/crates/odf/src/text/frames.rs b/crates/odf/src/text/frames.rs index cb8766906..e168695ef 100644 --- a/crates/odf/src/text/frames.rs +++ b/crates/odf/src/text/frames.rs @@ -233,7 +233,7 @@ impl Graphic { /// no fill; a gradient, hatch or bitmap stands as its colour. fn fill_with(&self, default: Option<&str>, defs: &Defs) -> Option { let color = self.fill_color.or(self.background.flatten()); - let solid = |c: Option| c.map(Fill::solid); + let solid = |c: Option| c.map(|color| Fill::Solid { color, transparency: (100.0 - self.opacity.unwrap_or(100.0)).clamp(0.0, 100.0) }); match self.fill.as_deref().or(default) { Some("none") => None, Some("solid") => solid(color), diff --git a/crates/odf/src/text/tests_more/groups.rs b/crates/odf/src/text/tests_more/groups.rs index 4fada68a9..3660ef072 100644 --- a/crates/odf/src/text/tests_more/groups.rs +++ b/crates/odf/src/text/tests_more/groups.rs @@ -121,7 +121,14 @@ fn a_diagram_is_saved_as_a_group_of_its_drawing() { let graphic = Graphic { kind: GraphicKind::Diagram, items: vec![ - GraphicItem::Shape { rect: [0.0, 0.0, 72.0, 36.0], kind: ShapeKind::RoundedRectangle, fill: Some(blue), stroke: None, stroke_width: 0.0 }, + GraphicItem::Shape { + rect: [0.0, 0.0, 72.0, 36.0], + kind: ShapeKind::RoundedRectangle, + fill: Some(blue), + stroke: None, + stroke_width: 0.0, + alpha: 1.0, + }, GraphicItem::Text { rect: [0.0, 0.0, 72.0, 36.0], text: "Plan".into(), @@ -132,7 +139,14 @@ fn a_diagram_is_saved_as_a_group_of_its_drawing() { font: None, angle: 0.0, }, - GraphicItem::Shape { rect: [90.0, 9.0, 18.0, 18.0], kind: ShapeKind::Arrow, fill: Some(blue), stroke: None, stroke_width: 0.0 }, + GraphicItem::Shape { + rect: [90.0, 9.0, 18.0, 18.0], + kind: ShapeKind::Arrow, + fill: Some(blue), + stroke: None, + stroke_width: 0.0, + alpha: 1.0, + }, ], w: 108.0, h: 36.0, diff --git a/crates/odf/src/text/tests_more/shapes.rs b/crates/odf/src/text/tests_more/shapes.rs index 8d1a9d5fd..f83174681 100644 --- a/crates/odf/src/text/tests_more/shapes.rs +++ b/crates/odf/src/text/tests_more/shapes.rs @@ -39,7 +39,7 @@ fn open() -> Document { ); let content = format!( r##" - + @@ -88,6 +88,12 @@ fn shapes_open_with_their_kind_size_look_and_text() { let Some(InlineObject::Shape { float, .. }) = d.body[2].as_para().unwrap().objects.first() else { panic!() }; assert_eq!((float.x, float.y), (72.0, 0.0)); assert_eq!(float.wrap, Wrap::BehindText); + let Some(InlineObject::Shape { fill: Some(craft_wordmodel::fill::Fill::Solid { transparency, .. }), .. }) = + d.body[0].as_para().unwrap().objects.first() + else { + panic!("the first shape has a solid fill"); + }; + assert_eq!(*transparency, 50.0); } #[test] @@ -100,6 +106,13 @@ fn shapes_round_trip() { } let back = import(&bytes).unwrap(); assert_eq!(shapes(&back), shapes(&d)); + assert!(c.contains("draw:opacity=\"50%\"")); + let Some(InlineObject::Shape { fill: Some(craft_wordmodel::fill::Fill::Solid { transparency, .. }), .. }) = + back.body[0].as_para().unwrap().objects.first() + else { + panic!("the first shape has a solid fill"); + }; + assert_eq!(*transparency, 50.0); assert_eq!(back.body[1].as_para().unwrap().text, d.body[1].as_para().unwrap().text); } diff --git a/crates/odf/src/text/writer/drawing.rs b/crates/odf/src/text/writer/drawing.rs index d49a07ea8..f06c5ef9c 100644 --- a/crates/odf/src/text/writer/drawing.rs +++ b/crates/odf/src/text/writer/drawing.rs @@ -53,7 +53,13 @@ pub(in crate::text) fn fill_attrs( } Some(f) => { let c = hex(f.main_color()); - format!("{} draw:fill=\"solid\" draw:fill-color=\"{c}\"", background(&c)) + let opacity = match f { + Fill::Solid { transparency, .. } if *transparency > 0.0 => { + format!(" draw:opacity=\"{:.0}%\"", (100.0 - transparency).clamp(0.0, 100.0)) + } + _ => String::new(), + }; + format!("{} draw:fill=\"solid\" draw:fill-color=\"{c}\"{opacity}", background(&c)) } None => format!("{} draw:fill=\"none\"", background("transparent")), } diff --git a/crates/wordmodel/src/graphic.rs b/crates/wordmodel/src/graphic.rs index cba7e766a..3a01e02f7 100644 --- a/crates/wordmodel/src/graphic.rs +++ b/crates/wordmodel/src/graphic.rs @@ -106,6 +106,9 @@ pub enum GraphicItem { stroke: Option, #[serde(default)] stroke_width: f32, + /// Opacity of `fill`, 0 to 1. + #[serde(default = "opaque")] + alpha: f32, }, /// A path: polygons, pie slices, line series. Path { @@ -153,3 +156,7 @@ pub enum PathSeg { Cubic(f32, f32, f32, f32, f32, f32), Close, } + +fn opaque() -> f32 { + 1.0 +} diff --git a/crates/wordmodel/src/smart_art.rs b/crates/wordmodel/src/smart_art.rs index 2d4371f6f..a02410df5 100644 --- a/crates/wordmodel/src/smart_art.rs +++ b/crates/wordmodel/src/smart_art.rs @@ -203,11 +203,14 @@ pub struct SmartArtItem { /// Fill of the item's shape in place of the style's colour. #[serde(default, skip_serializing_if = "Option::is_none")] pub color: Option, + /// Percent of `color` that shows (100 or none: solid). Needs `color`. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub opacity: Option, } impl SmartArtItem { pub fn new(text: impl Into, level: u8) -> SmartArtItem { - SmartArtItem { text: text.into(), level, color: None } + SmartArtItem { text: text.into(), level, color: None, opacity: None } } } @@ -256,6 +259,7 @@ impl SmartArtSpec { let mut prev: Option = None; for it in &mut self.items { it.text = clean_text(&it.text); + it.opacity = it.opacity.filter(|_| it.color.is_some()).map(|o| o.min(100)); let most = prev.map_or(0, |p| p.saturating_add(1)).min(MAX_LEVEL); it.level = it.level.min(most); prev = Some(it.level); @@ -271,6 +275,7 @@ impl SmartArtSpec { pub fn clear_custom_colors(&mut self) { for it in &mut self.items { it.color = None; + it.opacity = None; } } From 79f862597d78adbc48b6677c5f625799dcf0cdcd Mon Sep 17 00:00:00 2001 From: Ken Mantle Date: Mon, 16 Nov 2026 21:30:08 -0500 Subject: [PATCH 16/64] craft-pdf: a dictionary key written with raw spaces no longer fails the whole dictionary (cos) (#1905) --- crates/pdf/src/cos/document.rs | 8 +- crates/pdf/src/cos/document/objects.rs | 57 ++++++++++-- crates/pdf/src/cos/document/open.rs | 6 +- crates/pdf/src/cos/document/reader.rs | 4 +- crates/pdf/src/cos/document/state.rs | 34 ++++--- crates/pdf/src/cos/document/tests.rs | 122 ++++++++++++++++++++++++- crates/pdf/src/cos/parser.rs | 81 +++++++++++++++- 7 files changed, 278 insertions(+), 34 deletions(-) diff --git a/crates/pdf/src/cos/document.rs b/crates/pdf/src/cos/document.rs index 6082f4165..efeed81d1 100644 --- a/crates/pdf/src/cos/document.rs +++ b/crates/pdf/src/cos/document.rs @@ -25,7 +25,7 @@ pub(crate) use objects::Held; pub(crate) use reader::find; #[cfg(test)] use reader::rfind; -use state::{ObjStm, Slot, Unreadable}; +use state::{ObjStm, ObjectNotes, Slot}; pub(crate) use state::{ObjectReader, held_bytes}; pub use state::{ReadState, SourceIdentity}; #[cfg(test)] @@ -56,9 +56,9 @@ pub struct Document { /// decodes the stream again (`Document::load`). cache: Arc>, objstms: Arc>>>, - /// See [`Self::unreadable_objects`]. Shared by clones, like the caches: it describes the - /// source, and is reset wherever they are. - unreadable: Arc>, + /// See [`Self::unreadable_objects`] and [`Self::repaired_objects`]. Shared by clones, like + /// the caches: it describes the source, and is reset wherever they are. + object_notes: Arc>, /// What `/JBIG2Globals` streams of the file decode to, by object number: the images of a scan /// share them, and each would otherwise decode them again (see `Document::jbig2_globals`). jbig2_globals: Arc>>>>, diff --git a/crates/pdf/src/cos/document/objects.rs b/crates/pdf/src/cos/document/objects.rs index 2b8df8eb1..d7b7075f9 100644 --- a/crates/pdf/src/cos/document/objects.rs +++ b/crates/pdf/src/cos/document/objects.rs @@ -2,8 +2,8 @@ use std::collections::HashSet; use super::reader::find; use super::state::{ - LENGTHS, LoadGuard, ObjStm, ObjectReader, ReadFrame, ReadState, ScanLengths, Slot, SourceIdentity, loaded_bytes, loading, note_overlay_read, - note_read, objstm_member, overlay_reads, + LENGTHS, LoadGuard, Noted, ObjStm, ObjectNotes, ObjectReader, ReadFrame, ReadState, ScanLengths, Slot, SourceIdentity, loaded_bytes, loading, + note_overlay_read, note_read, objstm_member, overlay_reads, }; use super::xref::{Revision, XrefEntry, XrefIndex}; use super::{ @@ -106,18 +106,49 @@ impl Document { /// line says there were more. Opening again, authenticating or rebuilding the index starts /// the list afresh, as it does the object cache. pub fn unreadable_objects(&self) -> Vec { - let Ok(unreadable) = self.unreadable.lock() else { return Vec::new() }; - unreadable.lines(|num| self.overlay.contains_key(&num)) + let Ok(notes) = self.object_notes.lock() else { return Vec::new() }; + notes.unreadable.lines(|num| self.overlay.contains_key(&num), "could not be read") + } + + /// Objects of the file that were read only by repairing their syntax, lowest number first, as + /// lines such as "object 9 0 was repaired: a dictionary key written with spaces was read as one + /// key". Unlike [`Self::unreadable_objects`] nothing was lost, but the object is not what the + /// file wrote. Bounded, listed and reset as [`Self::unreadable_objects`] is; each object is + /// listed once however often it is read. + pub fn repaired_objects(&self) -> Vec { + let Ok(notes) = self.object_notes.lock() else { return Vec::new() }; + notes.repaired.lines(|num| self.overlay.contains_key(&num), "was repaired") } /// Record `num` as unreadable. `reason` is built only for an object not yet listed, so a file /// whose broken object is asked for again and again pays for it once. fn note_unreadable(&self, num: u32, reason: impl FnOnce() -> String) { - // A poisoned lock only means the object goes unlisted; the read itself still fails. - let Ok(mut unreadable) = self.unreadable.lock() else { return }; + self.note_object(num, |notes| &mut notes.unreadable, reason); + } + + fn note_spaced_key(&self, num: u32) { + self.note_object(num, |notes| &mut notes.repaired, || "a dictionary key written with spaces was read as one key".into()); + } + + /// [`Self::scan_for`] counted as a read of `num` of its own: a spaced key it joins is noted + /// under `num`, not under the object whose read called it. + fn scan_for_noting(&self, num: u32) -> Option<(ObjRef, Object)> { + let outer = crate::cos::parser::swap_spaced_keys(0); + let found = self.scan_for(num); + if crate::cos::parser::swap_spaced_keys(outer) > 0 && found.is_some() { + self.note_spaced_key(num); + } + found + } + + /// Record `num` in the list `pick` chooses, once. + fn note_object(&self, num: u32, pick: impl FnOnce(&mut ObjectNotes) -> &mut Noted, reason: impl FnOnce() -> String) { + // A poisoned lock only means the object goes unlisted; the read itself is unaffected. + let Ok(mut notes) = self.object_notes.lock() else { return }; + let list = pick(&mut notes); let hidden = |n: u32| self.overlay.contains_key(&n); - if unreadable.wants(num, hidden) { - unreadable.note(num, self.generation(num), &reason(), hidden); + if list.wants(num, hidden) { + list.note(num, self.generation(num), &reason(), hidden); } } @@ -582,10 +613,18 @@ impl Document { LoadGuard::enter(num).ok_or_else(|| CosError::Syntax { offset: 0, detail: format!("reference cycle while loading object {num}") })?; let _scope = crate::cos::security::FollowScope::enter(); let edits_read = overlay_reads(); + // Counts every attempt `load` makes, so an object found only at a second offset is listed + // if an abandoned copy had a spaced key: a rare false report, never a missed one. + let outer = crate::cos::parser::swap_spaced_keys(0); let frame = ReadFrame::enter(); let loaded = self.load(num, 0).map(Arc::new); let reads = frame.reads(); drop(frame); + // The notes are shared by clones, so a load that read this document's edits (an edited + // object stream) is not noted, as it is not cached below. + if crate::cos::parser::swap_spaced_keys(outer) > 0 && loaded.is_ok() && overlay_reads() == edits_read { + self.note_spaced_key(num); + } if let Err(e) = &loaded && !matches!(e, CosError::Poisoned) { @@ -759,7 +798,7 @@ impl Document { _ if self.overlay.contains_key(&num) || matches!(self.xref_entry(num), Some(XrefEntry::Free { .. })) => { return Err(CosError::MissingObject(num)); } - _ => Arc::new(self.scan_for(num).map(|(id, o)| self.decrypted(id, o)).ok_or(CosError::MissingObject(num))?), + _ => Arc::new(self.scan_for_noting(num).map(|(id, o)| self.decrypted(id, o)).ok_or(CosError::MissingObject(num))?), }; let Object::Stream(s) = &*loaded else { return Err(CosError::MissingObject(num)) }; let n = s.dict.int(b"N").unwrap_or(0).clamp(0, 1_000_000) as usize; diff --git a/crates/pdf/src/cos/document/open.rs b/crates/pdf/src/cos/document/open.rs index 4991412ce..6b53c14c5 100644 --- a/crates/pdf/src/cos/document/open.rs +++ b/crates/pdf/src/cos/document/open.rs @@ -24,7 +24,7 @@ impl Document { unlinked_update: false, cache: Arc::default(), objstms: Arc::default(), - unreadable: Arc::default(), + object_notes: Arc::default(), jbig2_globals: Arc::default(), stream_limit: crate::cos::object::MAX_DECODED, overlay: BTreeMap::new(), @@ -113,7 +113,7 @@ impl Document { unlinked_update: false, cache: Arc::default(), objstms: Arc::default(), - unreadable: Arc::default(), + object_notes: Arc::default(), jbig2_globals: Arc::default(), stream_limit: stream_limit.min(crate::cos::object::MAX_DECODED), overlay: BTreeMap::new(), @@ -256,7 +256,7 @@ impl Document { // Objects read while locating the catalog were read before decryption was possible. self.cache = Arc::default(); self.objstms = Arc::default(); - self.unreadable = Arc::default(); + self.object_notes = Arc::default(); Ok(()) } diff --git a/crates/pdf/src/cos/document/reader.rs b/crates/pdf/src/cos/document/reader.rs index 3e0b9684c..049d1fbd6 100644 --- a/crates/pdf/src/cos/document/reader.rs +++ b/crates/pdf/src/cos/document/reader.rs @@ -1,6 +1,6 @@ +use super::state::ObjectNotes; #[cfg(test)] use super::state::SECTION_READS; -use super::state::Unreadable; use super::xref::{ MAX_COMPACT_XREF_BYTES, MAX_COMPACT_XREF_ROWS, Revision, XrefEntry, XrefIndex, XrefRange, XrefRevisionSection, XrefSection, XrefSectionData, }; @@ -699,7 +699,7 @@ impl Document { } self.entries = Arc::new(XrefIndex::Materialized(Arc::new(entries.clone()), Arc::default())); self.cache.lock().map_err(|_| CosError::Poisoned)?.clear(); - *self.unreadable.lock().map_err(|_| CosError::Poisoned)? = Unreadable::default(); + *self.object_notes.lock().map_err(|_| CosError::Poisoned)? = ObjectNotes::default(); // Objects inside object streams. for num in objstms { if let Ok(o) = self.try_get(num) diff --git a/crates/pdf/src/cos/document/state.rs b/crates/pdf/src/cos/document/state.rs index 62ad2f8a3..50af04353 100644 --- a/crates/pdf/src/cos/document/state.rs +++ b/crates/pdf/src/cos/document/state.rs @@ -226,17 +226,25 @@ pub(super) fn objstm_member(num: i64, offset: i64, first: Option, len: us (start < len).then_some((num, start)) } -/// Objects the reader could not read, each with the reason (see `Document::unreadable_objects`). -/// Bounded: a document records past [`Unreadable::MAX`] of the objects it shows only the fact that -/// there were more. Entries a clone has edited are hidden from it and do not count, so the whole -/// list holds at most `MAX` plus the objects edited in clones. +/// What reading single objects found, shared by clones and reset with the object cache: the objects +/// that could not be read (`Document::unreadable_objects`) and those read with a repair +/// (`Document::repaired_objects`). #[derive(Debug, Default)] -pub(super) struct Unreadable { +pub(super) struct ObjectNotes { + pub(super) unreadable: Noted, + pub(super) repaired: Noted, +} + +/// Objects, each with a reason. Bounded: a document records past [`Noted::MAX`] of the objects it +/// shows only the fact that there were more. Entries a clone has edited are hidden from it and do +/// not count, so the whole list holds at most `MAX` plus the objects edited in clones. +#[derive(Debug, Default)] +pub(super) struct Noted { pub(super) objects: BTreeMap, pub(super) more: bool, } -impl Unreadable { +impl Noted { pub(super) const MAX: usize = 100; /// Characters of a reason kept: a parser's message can quote the bytes it stopped at. const REASON: usize = 160; @@ -263,18 +271,16 @@ impl Unreadable { } } - /// One line per recorded object not `hidden`, then one saying there were more, if there were. - pub(super) fn lines(&self, hidden: impl Fn(u32) -> bool) -> Vec { + /// One line per recorded object not `hidden`, saying what happened to it (`what`, as "could + /// not be read"), then one saying there were more, if there were. + pub(super) fn lines(&self, hidden: impl Fn(u32) -> bool, what: &str) -> Vec { // Clones share the list and each hides its own edits, so the list may hold more than // `MAX` entries in all; each document still shows at most `MAX`. let mut shown = self.objects.iter().filter(|(num, _)| !hidden(**num)); - let mut lines: Vec = shown - .by_ref() - .take(Self::MAX) - .map(|(num, (generation, reason))| format!("object {num} {generation} could not be read: {reason}")) - .collect(); + let mut lines: Vec = + shown.by_ref().take(Self::MAX).map(|(num, (generation, reason))| format!("object {num} {generation} {what}: {reason}")).collect(); if self.more || shown.next().is_some() { - lines.push(format!("more objects could not be read; only the first {} are listed", Self::MAX)); + lines.push(format!("more objects {what}; only the first {} are listed", Self::MAX)); } lines } diff --git a/crates/pdf/src/cos/document/tests.rs b/crates/pdf/src/cos/document/tests.rs index 836b8a0b3..4fb753289 100644 --- a/crates/pdf/src/cos/document/tests.rs +++ b/crates/pdf/src/cos/document/tests.rs @@ -823,7 +823,7 @@ fn an_entry_that_misses_its_object_is_found_by_searching_but_is_not_exact() { /// edit of that number still answers for it. #[test] fn an_unreadable_object_is_searched_for_once() { - let bodies = ["<< /Type /Catalog /Pages 2 0 R >>", "<< /Type /Pages /Kids [] /Count 0 >>", "<< /Odd Key(x) >>"]; + let bodies = ["<< /Type /Catalog /Pages 2 0 R >>", "<< /Type /Pages /Kids [] /Count 0 >>", "<< /Odd ) >>"]; let doc = Document::open(Arc::new(build(&bodies, "/Root 1 0 R /Info 3 0 R"))).unwrap(); FILE_SCANS.with(|scans| scans.set(0)); let first = doc.try_get(3); @@ -2711,3 +2711,123 @@ fn find_agrees_with_a_plain_window_search() { assert_eq!(find(&hay, needle, from, to), naive(&hay, needle, from, to), "{hay:?} {needle:?} {from} {to}"); } } + +/// A key written with spaces is joined (as in some Info dictionaries), and the object it was read +/// from is listed as repaired, once however often it is read. A sound object (a stream with an +/// indirect `/Length`) adds nothing. +#[test] +fn a_spaced_key_is_listed_once_as_a_repair_of_its_object() { + let file = build( + &[ + "<< /Type /Catalog /Pages 2 0 R >>", + "<< /Type /Pages /Kids [] /Count 0 >>", + "<< /Title (Report) /Universal PDF(Acme) >>", + "<< /Length 5 0 R >>\nstream\nabcd\nendstream", + "4", + ], + "/Root 1 0 R /Info 3 0 R", + ); + let doc = Document::open(Arc::new(file)).unwrap(); + assert!(doc.repaired_objects().is_empty(), "nothing has read object 3 yet"); + for _ in 0..3 { + let info = doc.get(ObjRef::new(3, 0)); + assert!(info.as_dict().is_some_and(|d| d.get(b"Universal PDF").is_some()), "{info:?}"); + } + assert!(doc.try_get(4).is_ok()); + let lines = doc.repaired_objects(); + assert_eq!(lines, ["object 3 0 was repaired: a dictionary key written with spaces was read as one key"], "{lines:?}"); + assert_eq!(doc.clone().repaired_objects(), lines, "clones share the list"); + assert!(doc.unreadable_objects().is_empty()); +} + +/// A scan of a fresh document lists the repaired object as a read does, and once. +#[test] +fn a_scan_lists_a_spaced_key_repair_once() { + let file = build( + &["<< /Type /Catalog /Pages 2 0 R >>", "<< /Type /Pages /Kids [] /Count 0 >>", "<< /Title (Report) /Universal PDF(Acme) >>"], + "/Root 1 0 R /Info 3 0 R", + ); + let doc = Document::open(Arc::new(file)).unwrap(); + assert_eq!(doc.scan_objects_checked().filter(|(_, o)| o.is_ok()).count(), 3); + assert_eq!(doc.scan_objects_checked().count(), 3); + assert_eq!(doc.repaired_objects(), ["object 3 0 was repaired: a dictionary key written with spaces was read as one key"]); +} + +/// A file holding object stream 4 with `members` (one object, numbered 3), the catalog and pages +/// as objects 1 and 2, and a cross-reference stream as object 5. `extra` is added to the stream's +/// dictionary; with `lost`, the table says the stream itself sits in stream 9, which is absent, so +/// only a scan of the file finds it. +fn objstm_file(members: &[u8], extra: &str, lost: bool) -> Vec { + let mut out = b"%PDF-1.5\n".to_vec(); + let mut offs = [0usize; 6]; + let mut obj = |out: &mut Vec, n: usize, body: &[u8]| { + offs[n] = out.len(); + out.extend_from_slice(format!("{n} 0 obj\n").as_bytes()); + out.extend_from_slice(body); + out.extend_from_slice(b"\nendobj\n"); + }; + obj(&mut out, 1, b"<< /Type /Catalog /Pages 2 0 R >>"); + obj(&mut out, 2, b"<< /Type /Pages /Kids [] /Count 0 >>"); + let mut stm = format!("<< /Type /ObjStm /N 1 /First 4 /Length {} {extra} >>\nstream\n", members.len()).into_bytes(); + stm.extend_from_slice(members); + stm.extend_from_slice(b"\nendstream"); + obj(&mut out, 4, &stm); + let xref_at = out.len(); + let mut rows = vec![0u8, 0, 0, 0, 0, 255]; + for (n, off) in offs.iter().enumerate().take(6).skip(1) { + let row = match n { + 3 => [2, 0, 0, 0, 4, 0], + 4 if lost => [2, 0, 0, 0, 9, 0], + 5 => [1, (xref_at >> 24) as u8, (xref_at >> 16) as u8, (xref_at >> 8) as u8, xref_at as u8, 0], + _ => [1, (off >> 24) as u8, (off >> 16) as u8, (off >> 8) as u8, *off as u8, 0], + }; + rows.extend_from_slice(&row); + } + let mut xs = format!("<< /Type /XRef /Size 6 /W [1 4 1] /Root 1 0 R /Info 3 0 R /Length {} >>\nstream\n", rows.len()).into_bytes(); + xs.extend_from_slice(&rows); + xs.extend_from_slice(b"\nendstream"); + let at = out.len(); + out.extend_from_slice(b"5 0 obj\n"); + out.extend_from_slice(&xs); + out.extend_from_slice(b"\nendobj\n"); + out.extend_from_slice(format!("startxref\n{at}\n%%EOF\n").as_bytes()); + out +} + +/// A member of an object stream with a spaced key is listed under its own number, not the +/// stream's. +#[test] +fn a_spaced_key_in_an_object_stream_member_is_listed_under_the_member() { + let doc = Document::open(Arc::new(objstm_file(b"3 0 << /Title (Report) /Universal PDF(Acme) >>", "", false))).unwrap(); + let info = doc.get(ObjRef::new(3, 0)); + assert!(info.as_dict().is_some_and(|d| d.get(b"Universal PDF").is_some()), "{info:?}"); + assert_eq!(doc.repaired_objects(), ["object 3 0 was repaired: a dictionary key written with spaces was read as one key"]); +} + +/// An object stream found only by a scan, whose dictionary has a spaced key, is listed under its +/// own number; the member read through it, which has none, is not listed. +#[test] +fn a_scanned_object_stream_with_a_spaced_key_is_listed_under_the_stream() { + let doc = Document::open(Arc::new(objstm_file(b"3 0 << /Title (Report) >>", "/Universal PDF(Acme)", true))).unwrap(); + let info = doc.get(ObjRef::new(3, 0)); + assert!(info.as_dict().is_some_and(|d| d.get(b"Title").is_some()), "{info:?}"); + assert_eq!(doc.repaired_objects(), ["object 4 0 was repaired: a dictionary key written with spaces was read as one key"]); +} + +/// A clone's edited object stream with a spaced key is not listed for the document it was cloned +/// from, whose own member has none. +#[test] +fn a_spaced_key_read_from_a_clone_edit_is_not_listed_for_the_source() { + let doc = Document::open(Arc::new(objstm_file(b"3 0 << /Title (Report) >>", "", false))).unwrap(); + let mut clone = doc.clone(); + let members = b"3 0 << /Title (Edited) /Universal PDF(Acme) >>".to_vec(); + let mut d = Dict::new(); + d.set(b"Type".to_vec(), Object::name("ObjStm")); + d.set(b"N".to_vec(), Object::Int(1)); + d.set(b"First".to_vec(), Object::Int(4)); + clone.set(ObjRef::new(4, 0), Object::Stream(Stream::from_raw(d, members))); + let edited = clone.get(ObjRef::new(3, 0)); + assert!(edited.as_dict().is_some_and(|d| d.get(b"Universal PDF").is_some()), "{edited:?}"); + assert!(doc.repaired_objects().is_empty(), "{:?}", doc.repaired_objects()); + assert!(doc.get(ObjRef::new(3, 0)).as_dict().is_some_and(|d| d.get(b"Universal PDF").is_none())); +} diff --git a/crates/pdf/src/cos/parser.rs b/crates/pdf/src/cos/parser.rs index 94e7f5b0b..5a0585ba3 100644 --- a/crates/pdf/src/cos/parser.rs +++ b/crates/pdf/src/cos/parser.rs @@ -294,8 +294,9 @@ impl<'a> Lexer<'a> { } Some(b'/') => { self.pos += 1; - let key = self.name_body(); + let mut key = self.name_body(); self.skip_ws(); + self.spaced_key_words(&mut key); // A key directly followed by `>>` has no value: treat as null. (A following // `/` is a name *value*, so it cannot signal a missing value.) if self.peek() == Some(b'>') && self.data.get(self.pos + 1) == Some(&b'>') { @@ -325,6 +326,37 @@ impl<'a> Lexer<'a> { } } + /// The rest of a key written with raw spaces, as in `/Universal PDF(...)` (seen in Info + /// dictionaries). Bare words join the key only when a string follows them: before a name, + /// number or keyword they are more likely a value missing its slash, and the dictionary + /// fails as before. At most [`Self::KEY_WORDS`] words. + fn spaced_key_words(&mut self, key: &mut Vec) { + let start = self.pos; + let mut words = Vec::new(); + while words.len() < Self::KEY_WORDS && self.peek().is_some_and(|b| is_regular(b) && !matches!(b, b'+' | b'-' | b'.' | b'0'..=b'9')) { + let at = self.pos; + if matches!(self.token(), b"true" | b"false" | b"null" | b"R" | b"obj" | b"endobj" | b"stream" | b"endstream") { + self.pos = at; + break; + } + self.pos = at; + words.push(self.name_body()); + self.skip_ws(); + } + if words.is_empty() || !matches!(self.peek(), Some(b'(' | b'<')) { + self.pos = start; + return; + } + for word in words { + key.push(b' '); + key.extend(word); + } + let _ = SPACED_KEYS.try_with(|c| c.set(c.get().saturating_add(1))); + } + + /// The most bare words [`Self::spaced_key_words`] joins to one key. + const KEY_WORDS: usize = 8; + fn number_or_ref(&mut self) -> Result { let start = self.pos; let first = self.number()?; @@ -404,6 +436,18 @@ fn real_prefix_len(s: &[u8]) -> usize { at } +thread_local! { + /// Keys [`Lexer::spaced_key_words`] joined on this thread (see [`swap_spaced_keys`]). + static SPACED_KEYS: std::cell::Cell = const { std::cell::Cell::new(0) }; +} + +/// Set the count of keys joined from words written with spaces, returning the count it replaces: +/// a reader swaps in 0 before parsing an object and the old count back after, so the count it gets +/// is that object's alone, objects parsed meanwhile included only through their own swaps. +pub(crate) fn swap_spaced_keys(count: u64) -> u64 { + SPACED_KEYS.try_with(|c| c.replace(count)).unwrap_or(0) +} + #[cfg(test)] thread_local! { /// Bytes searched for `endstream` on this thread. @@ -611,6 +655,41 @@ fn find_endstream(data: &[u8], from: usize, endstreams: Option<&EndstreamIndex>) mod tests { use super::*; + /// A key written with raw spaces reads as one key, and the rest of the dictionary reads. + #[test] + fn a_key_with_raw_spaces_keeps_the_dictionary() { + let Ok(Object::Dict(d)) = + Lexer::new(b"<< /Title (Report) /Universal PDF(Acme) /A B C#41 <4B> /T x\n<< /K 1 >> /Author (Ken) /On true /Off null >>", 0).object() + else { + panic!("the dictionary did not parse") + }; + let text = |k: &[u8]| d.get(k).and_then(|v| v.as_string().map(|s| s.to_text())); + assert_eq!(text(b"Title").as_deref(), Some("Report")); + assert_eq!(text(b"Universal PDF").as_deref(), Some("Acme")); + assert_eq!(text(b"A B CA").as_deref(), Some("K")); + assert!(matches!(d.get(b"T x"), Some(Object::Dict(_))), "a dictionary value"); + assert_eq!(text(b"Author").as_deref(), Some("Ken")); + assert_eq!(d.get(b"On"), Some(&Object::Bool(true)), "true is a value"); + assert_eq!(d.get(b"Off"), Some(&Object::Null), "null is a value"); + assert_eq!(d.len(), 7); + } + + /// A bare word before a name, a number or a keyword is a value missing its slash, not part of + /// the key: the dictionary fails as before, for the file's own repair, rather than read + /// with entries silently moved. + #[test] + fn a_bare_word_that_is_not_a_key_still_fails_the_dictionary() { + for bad in [ + &b"<< /Type Catalog /Pages 2 0 R >>"[..], + b"<< /Length 10 /Filter FlateDecode >>", + b"<< /Contents endobj 4 0 obj (x) >>", + b"<< /S Span >> BDC", + b"<< /K a b c d e f g h i (x) >>", + ] { + assert!(Lexer::new(bad, 0).object().is_err(), "{}", String::from_utf8_lossy(bad)); + } + } + #[test] fn numbers_with_multibyte_garbage_do_not_panic() { // From `cargo xtask fuzz`: "2 0 obj\n.\u{2014}" (an em dash after a dot). From 9e614b082faffd197e02eebea9ab5b06932bc711 Mon Sep 17 00:00:00 2001 From: Ken Mantle Date: Mon, 16 Nov 2026 21:30:13 -0500 Subject: [PATCH 17/64] craft-prc: keep a wire's vertex colours (#1904) --- crates/prc/README.md | 2 +- crates/prc/src/lib.rs | 2 +- crates/prc/src/tess.rs | 73 ++++++++++++++++++++++++++++-------- crates/prc/src/tess/tests.rs | 72 ++++++++++++++++++++++++++++++++--- 4 files changed, 126 insertions(+), 23 deletions(-) diff --git a/crates/prc/README.md b/crates/prc/README.md index 084b42374..ef35e062b 100644 --- a/crates/prc/README.md +++ b/crates/prc/README.md @@ -29,7 +29,7 @@ BitReader: bit, bits, character, unsigned_integer, integer, integer_vbn, double_ - `Unsupported` names constructs the reader cannot step over (schema pointer fields, `Value_CurveIs3D`). - `Tessellation::Mesh` is a `TriangleMesh`: positions, triangles, one triangle range per face, the stored normals and texture coordinates with each triangle's corner indices into them, and per-triangle line-attribute styles. - `Wire` is polylines; `Markup` is read past. + `Wire` is a `WireTessellation`: polylines and, when stored, each point's RGBA colour; `Markup` is read past. - `Tessellation::Compressed` is read to its end so later entities decode. Recalculated-normal meshes in the accepted 3T form are rebuilt when their arrays fit; stored-normal meshes and unsupported traversals stay `Compressed`. - A face may carry at most 8 texture-coordinate sets; more is `Malformed`. Optimised vertex colours are `Unsupported`. - The product tree: each drawable tessellation placed by its occurrence path's locations and the item's coordinate diff --git a/crates/prc/src/lib.rs b/crates/prc/src/lib.rs index 6cdf5a4c8..584331fb2 100644 --- a/crates/prc/src/lib.rs +++ b/crates/prc/src/lib.rs @@ -37,7 +37,7 @@ pub use container::{FileStructure, MAX_FILE_STRUCTURES, MAX_INFLATED_BYTES, PRC_ pub use error::PrcError; pub use geometry::Matrix; pub use schema::Schema; -pub use tess::{Tessellation, TriangleMesh, TriangleStyle}; +pub use tess::{Tessellation, TriangleMesh, TriangleStyle, WireTessellation}; pub use tree::{EntityOverrides, MAX_PLACEMENTS, ModelNode, ModelUnits, NameSource, Placement, Rgba, StyleAlpha}; pub use write::{ MAX_NODE_DEPTH, MeshScene, PrcWriteError, PrcWriteReport, SceneMaterial, SceneMesh, SceneNode, ScenePrimitive, SceneTexture, TextureWrap, diff --git a/crates/prc/src/tess.rs b/crates/prc/src/tess.rs index a7614b0a5..5fb4b764a 100644 --- a/crates/prc/src/tess.rs +++ b/crates/prc/src/tess.rs @@ -40,6 +40,28 @@ const WIRE_IS_CONTINUOUS: u32 = 0x2000_0000; /// Normal angles wider than this are not a `ShortArray` [WD 7.8.9.7]. const MAX_ANGLE_BITS: u32 = 16; +/// A `TESS_3D_Wire` [WD 7.8.7]: polylines in the entity's own frame. A closing wire ends on a +/// repeat of its first point; a continuous one is already joined to the wire before it. +#[derive(Debug, Clone, Default, PartialEq)] +#[non_exhaustive] +pub struct WireTessellation { + /// The polylines; one of fewer than two points draws nothing. + pub polylines: Vec>, + /// Each point's RGBA colour, parallel to `polylines` (RGB colours read opaque; a segment + /// colour [WD 7.8.7.2] goes to both its points). Empty when the wire stores none. + pub colours: Vec>, +} + +/// `flat` cut into runs as long as each of `wires`; empty when there are no colours or the lengths +/// disagree. +fn split_like(wires: &[Vec<[f64; 3]>], flat: Vec<[u8; 4]>) -> Vec> { + if flat.is_empty() || flat.len() != wires.iter().map(Vec::len).sum::() { + return Vec::new(); + } + let mut rest = flat.into_iter(); + wires.iter().map(|w| rest.by_ref().take(w.len()).collect()).collect() +} + /// One entry of the tessellation array; a representation item's `index_tessellation` selects /// one by position. #[derive(Debug, Clone, PartialEq)] @@ -47,8 +69,8 @@ const MAX_ANGLE_BITS: u32 = 16; pub enum Tessellation { /// A `TESS_3D` triangle mesh. Mesh(TriangleMesh), - /// A `TESS_3D_Wire`: polylines. - Wire(Vec>), + /// A `TESS_3D_Wire`: polylines and their colours. + Wire(WireTessellation), /// A `TESS_Markup` (PMI drawing), read past but not decoded. Markup, /// A `TESS_3D_Compressed` mesh, read past but not rebuilt: it stores its normals, or its @@ -155,28 +177,51 @@ impl Ctx<'_, '_> { self.doubles("tessellation coordinates") } - /// `VertexColors` [WD 7.8.7.2] for `count` points, read past. - fn vertex_colors(&mut self, count: usize, in_wire: bool) -> Result<(), PrcError> { + /// `VertexColors` [WD 7.8.7.2] for `count` points. Kept colours are charged to the element + /// budget before they are allocated; with `keep` false they are read past and none is stored. + fn vertex_colors(&mut self, count: usize, in_wire: bool, keep: bool) -> Result, PrcError> { let rgba = self.r.bit()?; // prc-rs: `is_segment_color` exists only inside a wire. let per_segment = in_wire && self.r.bit()?; if self.r.bit()? { return Err(PrcError::Unsupported("optimised vertex colours")); } + let points = count; let count = if per_segment { count / 2 } else { count }; let bytes = if rgba { 4 } else { 3 }; // The first colour is `8 * bytes` bits; every later one is at least its reuse bit. if count > 0 && (count - 1).saturating_add(8 * bytes) > self.r.remaining() { return Err(PrcError::Truncated("vertex colours")); } - for i in 0..count { - if i == 0 || !self.r.bit()? { - for _ in 0..bytes { - self.r.character()?; + if !keep { + for i in 0..count { + if i == 0 || !self.r.bit()? { + for _ in 0..bytes { + self.r.character()?; + } } } + return Ok(Vec::new()); } - Ok(()) + self.r.take_elements(points)?; + let mut out = Vec::with_capacity(points); + let mut last = [0, 0, 0, 255]; + for i in 0..count { + if i == 0 || !self.r.bit()? { + for c in last.iter_mut().take(bytes) { + *c = self.r.character()?; + } + } + out.push(last); + if per_segment { + out.push(last); + } + } + // An odd point count leaves the last point to the last segment. + if per_segment && count > 0 && out.len() < points { + out.push(last); + } + Ok(out) } /// `TESS_3D` (172) after its type code [WD 7.8.5]. @@ -237,7 +282,7 @@ impl Ctx<'_, '_> { let mut face = Face { flags, start, data, textures, styles, behaviour: 0 }; if self.r.bit()? { let n = face.point_count()?; - self.vertex_colors(n, false)?; + self.vertex_colors(n, false, false)?; } if !face.styles.is_empty() { let bits = self.r.unsigned_integer()?; @@ -248,7 +293,7 @@ impl Ctx<'_, '_> { } /// `TESS_3D_Wire` (175) after its type code [WD 7.8.7]. - fn wire(&mut self) -> Result>, PrcError> { + fn wire(&mut self) -> Result { let pts = points(&self.base_tess_data()?)?; let words = self.uints("wire indices")?; let mut wires: Vec> = Vec::new(); @@ -279,11 +324,9 @@ impl Ctx<'_, '_> { _ => wires.push(wire), } } - if self.r.bit()? { - self.vertex_colors(colours, true)?; - } + let flat = if self.r.bit()? { self.vertex_colors(colours, true, true)? } else { Vec::new() }; self.schema.skip_added_fields(TESS_3D_WIRE, &mut self.r)?; - Ok(wires) + Ok(WireTessellation { colours: split_like(&wires, flat), polylines: wires }) } /// `TESS_Markup` (176) after its type code [WD 7.8.8], read past. diff --git a/crates/prc/src/tess/tests.rs b/crates/prc/src/tess/tests.rs index 253e1c9d5..eb4933ceb 100644 --- a/crates/prc/src/tess/tests.rs +++ b/crates/prc/src/tess/tests.rs @@ -266,9 +266,12 @@ fn wires_close_and_continue_and_colours_are_counted() { // A second entity: a wrong colour count would desync it. wire(&mut b, false); let t = decode(§ion(2, &b), &Schema::default(), 8137).unwrap(); - for e in &t { + for (i, e) in t.iter().enumerate() { let Tessellation::Wire(w) = e else { panic!("not a wire") }; - assert_eq!(w, &[vec![[0., 0., 0.], [1., 0., 0.], [1., 1., 0.], [0., 1., 0.], [1., 1., 0.]]]); + assert_eq!(w.polylines, [vec![[0., 0., 0.], [1., 0., 0.], [1., 1., 0.], [0., 1., 0.], [1., 1., 0.]]]); + // Two red segment colours cover four points; the odd fifth takes the last one. + let want = if colours && i == 0 { vec![vec![[255, 0, 0, 255]; 5]] } else { Vec::new() }; + assert_eq!(w.colours, want, "colours {colours}, entity {i}"); } } } @@ -285,8 +288,28 @@ fn a_closing_wire_colours_its_implicit_point() { } wire(&mut b, false); let t = decode(§ion(2, &b), &Schema::default(), 8137).unwrap(); + let (Tessellation::Wire(a), Tessellation::Wire(b)) = (&t[0], &t[1]) else { panic!("not wires") }; + assert_eq!(a.polylines, b.polylines); + assert_eq!(a.colours, [vec![[0, 0, 1, 255]; 5]]); +} + +#[test] +fn per_point_rgba_colours_are_split_across_separate_wires() { + let mut b = W::default(); + square(&mut b, 175); + // Two separate two-point wires. + uints(&mut b, &[2, 0, 3, 2, 6, 9]); + // Colours present, RGBA, per point, not optimised: green, a reuse, then two new colours. + b.bit(true).bit(true).bit(false).bit(false).put(0x00ff_0080, 32); + b.bit(true); + b.bit(false).put(0x0102_0304, 32); + b.bit(false).put(0xffff_ffff, 32); + wire(&mut b, false); + let t = decode(§ion(2, &b), &Schema::default(), 8137).unwrap(); + let Tessellation::Wire(w) = &t[0] else { panic!("not a wire") }; + assert_eq!(w.polylines, [vec![[0., 0., 0.], [1., 0., 0.]], vec![[1., 1., 0.], [0., 1., 0.]]]); + assert_eq!(w.colours, [vec![[0, 255, 0, 128]; 2], vec![[1, 2, 3, 4], [255; 4]]]); assert!(matches!(t[1], Tessellation::Wire(_))); - assert_eq!(t[0], t[1]); } #[test] @@ -311,8 +334,9 @@ fn a_wire_without_indices_is_the_coordinate_polyline() { wire(&mut b, false); let t = decode(§ion(2, &b), &Schema::default(), 8137).unwrap(); let Tessellation::Wire(w) = &t[0] else { panic!("not a wire") }; - assert_eq!(w.len(), 1); - assert_eq!(w[0].len(), 4); + assert_eq!(w.polylines.len(), 1); + assert_eq!(w.polylines[0].len(), 4); + assert_eq!(w.colours, [vec![[0, 0, 1, 255]; 4]]); assert!(matches!(t[1], Tessellation::Wire(_))); } @@ -332,7 +356,8 @@ fn reused_vertex_colours_may_be_the_last_data() { } let t = decode(§ion(1, &b), &Schema::default(), 8137).unwrap(); let Tessellation::Wire(w) = &t[0] else { panic!("not a wire") }; - assert_eq!(w[0].len(), n as usize); + assert_eq!(w.polylines[0].len(), n as usize); + assert_eq!(w.colours[0].len(), n as usize); } /// A square as one triangle plus one 4-vertex fan (two entities, three triangles), the face @@ -1005,3 +1030,38 @@ fn the_globals_schema_and_the_tessellations_share_one_allowance() { assert!(within(need).is_ok()); assert!(matches!(within(need - 1), Err(PrcError::TooManyElements { .. }))); } + +/// A wire of [`SQUARE`]'s four points without indices, with four kept RGB colours or none. +fn bare_wire(colours: bool) -> W { + let mut b = W::default(); + square(&mut b, 175); + b.uint(0).bit(colours); + if colours { + b.bit(false).bit(false).bit(false).put(1, 24); + for _ in 1..4 { + b.bit(true); + } + } + section(1, &b) +} + +#[test] +fn kept_wire_colours_are_charged_before_they_are_made() { + let plain = spent(&bare_wire(false)); + assert_eq!(spent(&bare_wire(true)) - plain, 4); + let bytes = bare_wire(true).bytes(); + let schema = Schema::default(); + let r = Ctx::new(BitReader::with_elements(&bytes, plain), &schema, 8137).file_structure_tessellation(); + assert!(matches!(r, Err(PrcError::TooManyElements { .. })), "{r:?}"); +} + +#[test] +fn face_colours_that_are_read_past_are_not_charged() { + assert_eq!(spent(&styled_face_section(&[], 7, 0x30)), spent(&styled_face_section(&[], 0, 0x30))); +} + +#[test] +fn wires_without_colours_make_no_colour_lists() { + assert!(split_like(&[Vec::new(), Vec::new()], Vec::new()).is_empty()); + assert_eq!(split_like(&[vec![[0.0; 3]]], vec![[1; 4]]), [vec![[1; 4]]]); +} From b1d3abc55ee2e48aa835651d0171d031ee8cab84 Mon Sep 17 00:00:00 2001 From: Joseph Anglada Date: Mon, 16 Nov 2026 22:30:17 -0400 Subject: [PATCH 18/64] DOCX: the parts of a package that cannot be read are listed on the document (#1902) --- crates/docx/src/package.rs | 5 +++++ crates/docx/src/read.rs | 1 + crates/docx/src/read/chunk.rs | 16 ++++++++++++---- crates/docx/tests/it/alt_chunks.rs | 27 ++++++++++++++++++++++++++- crates/docx/tests/it/malformed.rs | 25 +++++++++++++++++++++++++ crates/opc/src/read.rs | 19 ++++++++++++++----- crates/wordmodel/src/document.rs | 4 ++++ crates/wordmodel/src/lib.rs | 3 +++ 8 files changed, 90 insertions(+), 10 deletions(-) diff --git a/crates/docx/src/package.rs b/crates/docx/src/package.rs index 53202850a..01b4d7474 100644 --- a/crates/docx/src/package.rs +++ b/crates/docx/src/package.rs @@ -233,6 +233,11 @@ impl Package { self.opc.size() } + /// The entries of the zip that could not be read and were left out, by name. + pub fn skipped(&self) -> &[String] { + self.opc.skipped() + } + /// A package from parts already in memory (a Flat OPC file, a converted document), by part /// name without the leading `/`. pub fn from_parts(files: BTreeMap>) -> Package { diff --git a/crates/docx/src/read.rs b/crates/docx/src/read.rs index 0f95b4f76..f3241d562 100644 --- a/crates/docx/src/read.rs +++ b/crates/docx/src/read.rs @@ -370,6 +370,7 @@ fn read_opened_in(pkg: &Package, chunks: ChunkState) -> Result<(Document, usize, } let (left, bytes, graphic) = (r.chunks.left, r.chunks.bytes, r.chunks.graphic); let mut doc = r.doc; + doc.skipped_parts.extend(pkg.skipped().iter().cloned()); doc.ensure_nonempty(); Ok((doc, left, bytes, graphic)) } diff --git a/crates/docx/src/read/chunk.rs b/crates/docx/src/read/chunk.rs index 2ffd3f96c..2dc1674a7 100644 --- a/crates/docx/src/read/chunk.rs +++ b/crates/docx/src/read/chunk.rs @@ -63,7 +63,7 @@ impl Reader<'_> { let chunk = AltChunk { content_type: &ct, part: &part, bytes }; // A WordprocessingML chunk is a package; one that isn't Word's fails to read (logged). let is_docx = bytes.starts_with(b"PK\x03\x04"); - let doc = if is_docx { self.read_nested(bytes, depth) } else { self.chunks.import.and_then(|f| f(&chunk)) }; + let doc = if is_docx { self.read_nested(bytes, depth, &part) } else { self.chunks.import.and_then(|f| f(&chunk)) }; let Some(mut doc) = doc else { log::warn!("docx: alternative format chunk {part} ({ct}) is in a format WordCraft can't bring in"); return; @@ -83,6 +83,8 @@ impl Reader<'_> { // The pictures the chunk's own reader dropped are the file's too (strict export, #6005), // each named by the chunk and its part in it (`word/afchunk1.docx > word/header1.xml`). // A chunk in another format brings none: those importers record nothing yet (#6007). + let skipped = std::mem::take(&mut doc.skipped_parts); + self.doc.skipped_parts.extend(skipped.into_iter().map(|name| format!("{part} > {name}"))); let nested = std::mem::take(&mut doc.missing_pictures); let list_len = nested.list.len() as u64; for mut item in nested.list { @@ -103,7 +105,7 @@ impl Reader<'_> { /// A WordprocessingML chunk: its document, read with the same importer and what is left of /// the budgets, its XML depth counting on from `depth`. - fn read_nested(&mut self, bytes: &[u8], depth: usize) -> Option { + fn read_nested(&mut self, bytes: &[u8], depth: usize, part: &str) -> Option { if self.chunks.nesting >= MAX_CHUNK_NESTING { log::warn!("docx: alternative format chunks nest deeper than {MAX_CHUNK_NESTING}; the inner ones are left out"); return None; @@ -112,8 +114,14 @@ impl Reader<'_> { Package::open_limited(bytes, MAX_PART, self.chunks.bytes).map_err(|e| log::warn!("docx: unreadable nested document chunk: {e}")).ok()?; self.chunks.bytes = self.chunks.bytes.saturating_sub(pkg.size()); let state = ChunkState { nesting: self.chunks.nesting + 1, depth: depth + 1, ..self.chunks }; - let (doc, left, bytes, graphic) = - super::read_opened_in(&pkg, state).map_err(|e| log::warn!("docx: unreadable nested document chunk: {e}")).ok()?; + let (doc, left, bytes, graphic) = match super::read_opened_in(&pkg, state) { + Ok(read) => read, + Err(e) => { + log::warn!("docx: unreadable nested document chunk: {e}"); + self.doc.skipped_parts.extend(pkg.skipped().iter().map(|name| format!("{part} > {name}"))); + return None; + } + }; self.chunks.left = left; self.chunks.bytes = bytes; self.chunks.graphic = graphic; diff --git a/crates/docx/tests/it/alt_chunks.rs b/crates/docx/tests/it/alt_chunks.rs index feaeb73b3..8fb853948 100644 --- a/crates/docx/tests/it/alt_chunks.rs +++ b/crates/docx/tests/it/alt_chunks.rs @@ -48,7 +48,7 @@ fn package_styled(body: &str, chunk: Option<(&str, &str, &[u8])>, styles: Option files.push(("[Content_Types].xml".into(), types.into_bytes())); let mut zw = zip::ZipWriter::new(std::io::Cursor::new(Vec::new())); for (name, bytes) in files { - zw.start_file(name, zip::write::SimpleFileOptions::default()).unwrap(); + zw.start_file(name, zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored)).unwrap(); zw.write_all(&bytes).unwrap(); } zw.finish().unwrap().into_inner() @@ -76,6 +76,19 @@ fn a_chunk_comes_in_through_the_importer_where_it_stands() { assert_eq!(body_lines(&read(&bytes).unwrap()), ["Before", "After"]); } +#[test] +fn unreadable_nested_main_part_is_reported_with_its_chunk() { + let mut inner = package(&p("Chunk"), None); + let document = inner.windows(b" word/document.xml".to_string()]); + assert_eq!(body_lines(&d), ["Before"]); +} + #[test] fn a_bookmark_opened_before_a_chunk_at_the_start_of_the_body_is_kept() { let body = format!(r#"{CHUNK}{}"#, p("After")); @@ -444,3 +457,15 @@ fn a_chunk_imported_twice_counts_its_dropped_pictures_past_the_list_once() { assert_eq!(d.missing_pictures.list.len(), craft_wordmodel::MAX_MISSING_PICTURES); assert_eq!(d.missing_pictures.total, n as u64); } + +#[test] +fn a_part_a_chunk_could_not_read_is_listed_with_the_chunk() { + let bytes = package(&format!("{}{CHUNK}", p("Before")), Some(("htm", "application/xhtml+xml", b"

x

"))); + let import = |_: &AltChunk| { + let mut d = Document::from_text("Chunk"); + d.skipped_parts = vec!["word/media/image1.png".to_string()]; + Some(d) + }; + let d = read_with(&bytes, &ReadOptions { chunks: Some(&import), ..Default::default() }).unwrap(); + assert_eq!(d.skipped_parts, vec!["word/afchunk.htm > word/media/image1.png".to_string()]); +} diff --git a/crates/docx/tests/it/malformed.rs b/crates/docx/tests/it/malformed.rs index fec0de990..b1c5b8f17 100644 --- a/crates/docx/tests/it/malformed.rs +++ b/crates/docx/tests/it/malformed.rs @@ -87,6 +87,31 @@ fn a_malformed_main_part_is_an_error_not_a_truncated_document() { assert_eq!(d.plain_text(craft_wordmodel::StoryRef::Body), "a <- b\nlast", "well-formed text still reads whole"); } +#[test] +fn a_part_with_a_bad_checksum_is_left_out_and_reported() { + let body = format!("kept"); + let build = |extra: &[u8]| { + let mut zw = zip::ZipWriter::new(std::io::Cursor::new(Vec::new())); + let stored = zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored); + zw.start_file("_rels/.rels", stored).unwrap(); + zw.write_all(ROOT_RELS.as_bytes()).unwrap(); + zw.start_file("word/document.xml", stored).unwrap(); + zw.write_all(body.as_bytes()).unwrap(); + zw.start_file("word/media/image1.png", stored).unwrap(); + zw.write_all(extra).unwrap(); + zw.finish().unwrap().into_inner() + }; + let sound = read(&build(b"PICTURE-BYTES-0123456789")).unwrap(); + assert!(sound.skipped_parts.is_empty(), "a sound file reports nothing"); + // The entry is stored as is, so one changed byte fails its checksum when it is read. + let mut z = build(b"PICTURE-BYTES-0123456789"); + let at = z.windows(7).position(|w| w == b"PICTURE").unwrap(); + z[at] = b'p'; + let damaged = read(&z).unwrap(); + assert_eq!(damaged.plain_text(craft_wordmodel::StoryRef::Body), "kept", "the rest still opens"); + assert_eq!(damaged.skipped_parts, vec!["word/media/image1.png".to_string()]); +} + #[test] fn deep_nesting_is_rejected() { let mut x = format!(""); diff --git a/crates/opc/src/read.rs b/crates/opc/src/read.rs index b35fc109d..326f3f628 100644 --- a/crates/opc/src/read.rs +++ b/crates/opc/src/read.rs @@ -39,6 +39,8 @@ pub struct Package { /// Lowercased part name → its stored spelling: part names are case-insensitive (ECMA-376 /// Part 2 §6.2.2.3), so every spelling is one part. lower: HashMap, + /// Names of the entries the archive could not produce, in archive order. + skipped: Vec, } impl Package { @@ -55,6 +57,7 @@ impl Package { let mut zip = open_zip(bytes, limits, u64::MAX)?; let skip = limits.oversized == Oversized::Skip; let mut files = BTreeMap::new(); + let mut skipped = Vec::new(); let (mut total, mut work) = (0u64, 0u64); let entries: Vec = zip.names().map(|n| n.into_owned()).collect(); for (i, entry) in entries.iter().enumerate() { @@ -97,19 +100,20 @@ impl Package { Err(e) => { work = work.saturating_add(size); log::warn!("opc: zip entry {name} unreadable: {e}"); + skipped.push(name); } } } - Ok(Package::new(files)) + Ok(Package::new(files, skipped)) } /// A package from parts already in memory (a Flat OPC file, a converted document), by part /// name. pub fn from_parts(files: BTreeMap>) -> Package { - Package::new(files.into_iter().map(|(name, bytes)| (stored_name(&name), Arc::new(bytes))).collect()) + Package::new(files.into_iter().map(|(name, bytes)| (stored_name(&name), Arc::new(bytes))).collect(), Vec::new()) } - fn new(mut files: BTreeMap>>) -> Package { + fn new(mut files: BTreeMap>>, skipped: Vec) -> Package { let mut lower: HashMap = HashMap::new(); let mut collides = false; for name in files.keys() { @@ -121,7 +125,7 @@ impl Package { } } if !collides { - return Package { files, lower }; + return Package { files, lower, skipped }; } // Entries whose names differ only in case are one part, so every spelling of the name // reaches the same stored entry. The spelling kept is the one a relationship names, so @@ -140,7 +144,12 @@ impl Package { files.retain(|name, _| lower.get(&name.to_ascii_lowercase()) == Some(name)); let dropped = before.saturating_sub(files.len()); log::warn!("opc: {dropped} zip entries are other spellings of parts already read; they are left out"); - Package { files, lower } + Package { files, lower, skipped } + } + + /// The entries of the archive that could not be read and were left out, by name. + pub fn skipped(&self) -> &[String] { + &self.skipped } /// The bytes of all its parts. diff --git a/crates/wordmodel/src/document.rs b/crates/wordmodel/src/document.rs index 0a1cc43bd..d12fb85dc 100644 --- a/crates/wordmodel/src/document.rs +++ b/crates/wordmodel/src/document.rs @@ -78,6 +78,7 @@ impl Document { media_index: MediaIndex::default(), kept: Default::default(), missing_pictures: Default::default(), + skipped_parts: Vec::new(), } } @@ -156,6 +157,7 @@ impl Document { media_index: _, kept: _, missing_pictures: _, + skipped_parts, } = self; let Document { body: other_body, @@ -177,6 +179,7 @@ impl Document { media_index: _, kept: _, missing_pictures: _, + skipped_parts: other_skipped_parts, } = other; same_blocks(body, other_body) && same_parts(parts, other_parts) @@ -194,6 +197,7 @@ impl Document { && same_bytes(media, other_media) && same_bytes(passthrough, other_passthrough) && same_glossary(glossary, other_glossary) + && skipped_parts == other_skipped_parts } pub fn story(&self, s: StoryRef) -> Option<&Blocks> { diff --git a/crates/wordmodel/src/lib.rs b/crates/wordmodel/src/lib.rs index 2b3fb2626..fbe28bb98 100644 --- a/crates/wordmodel/src/lib.rs +++ b/crates/wordmodel/src/lib.rs @@ -144,6 +144,9 @@ pub struct Document { /// export reports them); never saved, never drawn, ignored by `==`. #[serde(skip)] pub missing_pictures: MissingPictures, + /// Package parts a reader could not read and left out, by name; never saved. + #[serde(skip)] + pub skipped_parts: Vec, } #[cfg(test)] From ff5a8af742e6376d06d5f0d2ad92a0cd4bb54f73 Mon Sep 17 00:00:00 2001 From: ".CooCoo" Date: Mon, 16 Nov 2026 18:30:21 -0800 Subject: [PATCH 19/64] hayro-syntax, hayro-interpret: callers set the image byte and pixel limits (#1901) --- crates/pdf/tests/interpretation.rs | 122 ++++++++++++++++++ vendor/README.craft-reader.md | 10 ++ vendor/hayro-interpret/src/color.rs | 5 + vendor/hayro-interpret/src/x_object.rs | 35 ++++- .../hayro-syntax/src/decode_limits_tests.rs | 27 ++++ vendor/hayro-syntax/src/filter/mod.rs | 10 +- vendor/hayro-syntax/src/pdf.rs | 53 +++++++- vendor/hayro-syntax/src/reader.rs | 21 +-- 8 files changed, 266 insertions(+), 17 deletions(-) diff --git a/crates/pdf/tests/interpretation.rs b/crates/pdf/tests/interpretation.rs index 124746aaf..8b6737cb8 100644 --- a/crates/pdf/tests/interpretation.rs +++ b/crates/pdf/tests/interpretation.rs @@ -342,3 +342,125 @@ mod rectangles { assert_eq!(shapes.clips, 1); } } + +#[cfg(feature = "interpret")] +mod image_limits { + use craft_pdf::interpret::{ + BlendMode, ClipPath, Context, Device, GlyphDrawMode, Image, ImageData, InterpreterCache, InterpreterSettings, Paint, PathDrawMode, SoftMask, + TransformExt, font::Glyph, + }; + use craft_pdf::syntax::DecodeLimits; + use kurbo::{Affine, BezPath, Rect}; + + /// The RGB samples and alpha of a raster image. + type Pixels = (Vec, Option>); + + /// The pixels of each raster image drawn (`None`: it did not decode). + #[derive(Default)] + struct Images(Vec>); + + impl Images { + /// The RGB samples of each image, without alpha. + fn rgb(&self) -> Vec>> { + self.0.iter().map(|i| i.as_ref().map(|(rgb, _)| rgb.clone())).collect() + } + } + + impl Device<'_> for Images { + fn set_soft_mask(&mut self, _: Option>) {} + fn set_blend_mode(&mut self, _: BlendMode) {} + fn draw_path(&mut self, _: &BezPath, _: Affine, _: &Paint<'_>, _: &PathDrawMode) {} + fn push_clip_path(&mut self, _: &ClipPath) {} + fn push_transparency_group(&mut self, _: f32, _: Option>, _: BlendMode) {} + fn draw_glyph(&mut self, _: &Glyph<'_>, _: Affine, _: Affine, _: &Paint<'_>, _: &GlyphDrawMode) {} + fn draw_image(&mut self, image: Image<'_, '_>, _: Affine) { + let mut rgb = None; + if let Image::Raster(r) = image { + r.with_rgba( + |img, alpha| { + if let ImageData::Rgb(d) = img { + rgb = Some((d.data, alpha.map(|a| a.data))); + } + }, + None, + ); + } + self.0.push(rgb); + } + fn pop_clip_path(&mut self) {} + fn pop_transparency_group(&mut self) {} + } + + /// A page that draws a 4 × 2 `DeviceRGB` image of 8-bit samples 0, 1, … 23, read with `limits`. + /// The samples are one run-length literal run, written in hex. + fn draw(limits: DecodeLimits) -> Images { + draw_with(limits, RGB) + } + + /// The color space and sample size of [`draw`]'s image. + const RGB: &str = "/ColorSpace /DeviceRGB /BitsPerComponent 8"; + + /// [`draw`], with `extra` in the image's dictionary instead of [`RGB`]. + fn draw_with(limits: DecodeLimits, extra: &str) -> Images { + let run: Vec = [23].into_iter().chain(0..24).chain([128]).collect(); + let hex: String = run.iter().map(|b| format!("{b:02X}")).collect(); + let content = "q 4 0 0 2 0 0 cm /Im0 Do Q"; + let bytes = format!( + "%PDF-1.7\n1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj\n2 0 obj << /Type /Pages /Kids [3 0 R] /Count 1 >> endobj\n3 0 obj << /Type /Page /Parent 2 0 R /MediaBox [0 0 4 2] /Contents 4 0 R /Resources << /XObject << /Im0 5 0 R >> >> >> endobj\n4 0 obj << /Length {} >> stream\n{content}\nendstream endobj\n5 0 obj << /Type /XObject /Subtype /Image /Width 4 /Height 2 /Filter [/ASCIIHexDecode /RunLengthDecode] {extra} /Length {} >> stream\n{hex}>\nendstream endobj\ntrailer << /Root 1 0 R >>\n%%EOF", + content.len(), + hex.len() + 1 + ); + let options = craft_pdf::OpenOptions { decode_limits: limits, ..Default::default() }; + let pdf = craft_pdf::open_slice_with_options(bytes.as_bytes(), None, &options).unwrap(); + let page = &pdf.pages()[0]; + let cache = InterpreterCache::new(); + let mut context = + Context::new(page.initial_transform(true).to_kurbo(), Rect::new(0.0, 0.0, 4.0, 2.0), &cache, page.xref(), InterpreterSettings::default()); + let mut images = Images::default(); + craft_pdf::interpret_page(page, &mut context, &mut images).unwrap(); + images + } + + #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] + #[cfg_attr(not(target_arch = "wasm32"), test)] + fn device_rgb_samples_arrive_as_written() { + assert_eq!(draw(DecodeLimits::default()).0, [Some(((0..24).collect::>(), None))]); + // An inverted `/Decode` inverts them. + let inverted: Vec = (0..24).map(|s| 255 - s).collect(); + assert_eq!(draw_with(DecodeLimits::default(), &format!("{RGB} /Decode [1 0 1 0 1 0]")).rgb(), [Some(inverted)]); + } + + #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] + #[cfg_attr(not(target_arch = "wasm32"), test)] + fn a_color_key_mask_reads_device_rgb_samples() { + // Pixels 0 (0, 1, 2) and 1 (3, 4, 5) have every sample in 0 to 5, so they are masked out. + let images = draw_with(DecodeLimits::default(), &format!("{RGB} /Mask [0 5 0 5 0 5]")); + assert_eq!(images.0, [Some(((0..24).collect::>(), Some(vec![0, 0, 255, 255, 255, 255, 255, 255])))]); + } + + #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] + #[cfg_attr(not(target_arch = "wasm32"), test)] + fn a_color_key_mask_of_an_emptied_gray_image_reads_its_padding() { + // A 1-bit inverted gray image whose samples the byte limit leaves out: the missing samples + // read as 0, white once inverted, and inside the key range, so every pixel is masked out. + let images = + draw_with(DecodeLimits::default().with_max_decoded_image(0), "/ColorSpace /DeviceGray /BitsPerComponent 1 /Decode [1 0] /Mask [0 0]"); + assert_eq!(images.0, [Some((vec![255; 24], Some(vec![0; 8])))]); + } + + #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] + #[cfg_attr(not(target_arch = "wasm32"), test)] + fn the_pixel_limit_comes_from_the_document() { + assert_eq!(draw(DecodeLimits::default().with_max_image_pixels(7)).0, [None], "8 pixels are past a limit of 7"); + assert_eq!(draw(DecodeLimits::default().with_max_image_pixels(8)).rgb(), [Some((0..24).collect::>())]); + } + + #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] + #[cfg_attr(not(target_arch = "wasm32"), test)] + fn the_image_byte_limit_comes_from_the_document() { + // The run-length filter stops at 10 bytes: one row is left, its last two samples zero. + let cut: Vec = (0..10).chain([0, 0]).collect(); + assert_eq!(draw(DecodeLimits::default().with_max_decoded_image(10)).rgb(), [Some(cut)]); + assert_eq!(draw(DecodeLimits::default().with_max_decoded_image(1 << 40)).rgb(), [Some((0..24).collect::>())]); + } +} diff --git a/vendor/README.craft-reader.md b/vendor/README.craft-reader.md index 8fc625fb9..9cb4a5dee 100644 --- a/vendor/README.craft-reader.md +++ b/vendor/README.craft-reader.md @@ -98,6 +98,16 @@ the transferred decoder patches. Synthetic unit tests cover these boundaries; two version tests and the introductory doctest use synthetic PDFs so they do not rely on the absent upstream corpus. No corpus is copied. +`DecodeLimits` also carries the two image limits: `with_max_decoded_image` sets the most bytes +the last filter of an image of known size may produce (1 GiB by default), and +`with_max_image_pixels` sets the most pixels an image or mask may have for the interpreter to +decode it (2^28 by default, at most 2^32), before and after its codec decodes it. With 64-bit +pointers a caller may raise either one; elsewhere a raise is clamped to the default. +`image_size_ok` keeps the 2^28 default. An 8-bit `DeviceRGB` image with the default or inverted `/Decode` and no transfer function keeps its decoded samples as its +RGB data instead of copying them into a second buffer. Tests: +`decode_limits_tests::image_limits_default_and_caller_figures` in hayro-syntax and +`image_limits` in `crates/pdf/tests/interpretation.rs`. + Compatibility patches follow the resource scopes and text-showing order in [Hayro 0.8.0, revision ea9c81dc70cde40c64205986fdcfcd481fe934d8](https://github.com/LaurenzV/hayro/tree/ea9c81dc70cde40c64205986fdcfcd481fe934d8), under the same MIT OR Apache-2.0 licence. Explicit page and nested-object resource diff --git a/vendor/hayro-interpret/src/color.rs b/vendor/hayro-interpret/src/color.rs index 36e3e581b..48141a9d5 100644 --- a/vendor/hayro-interpret/src/color.rs +++ b/vendor/hayro-interpret/src/color.rs @@ -400,6 +400,11 @@ impl ColorSpace { matches!(self.0.as_ref(), ColorSpaceType::DeviceGray) } + /// Whether this is `DeviceRGB`, whose 8-bit samples are their own RGB values. + pub(crate) fn is_device_rgb(&self) -> bool { + matches!(self.0.as_ref(), ColorSpaceType::DeviceRgb) + } + /// Get the number of components of the color space. pub(crate) fn num_components(&self) -> u8 { match self.0.as_ref() { diff --git a/vendor/hayro-interpret/src/x_object.rs b/vendor/hayro-interpret/src/x_object.rs index 7730884cb..d13bb911f 100644 --- a/vendor/hayro-interpret/src/x_object.rs +++ b/vendor/hayro-interpret/src/x_object.rs @@ -673,7 +673,8 @@ fn decode_context<'a>( ) -> Option> { // PdfCraft patch: images and masks over `MAX_IMAGE_PIXELS` are not decoded at all (the // renderer skips them anyway): a fuzzed `/W 4294967295` stencil mask allocated gigabytes here. - if !image_size_ok(obj.width, obj.height) { + // The document's decode limits may set another pixel count. + if !image_size_within(obj.width, obj.height, obj.stream.decode_limits().max_image_pixels()) { (obj.warning_sink)(InterpreterWarning::ImageDecodeFailure); return None; } @@ -711,6 +712,11 @@ fn decode_context<'a>( (d.width, d.height) }) .unwrap_or((obj.width, obj.height)); + // Craft patch: the size an image codec decoded to is held to the same limit. + if !image_size_within(width, height, obj.stream.decode_limits().max_image_pixels()) { + (obj.warning_sink)(InterpreterWarning::ImageDecodeFailure); + return None; + } let color_space = color_space .or_else(|| { @@ -810,6 +816,7 @@ fn decode_raster( .color_space .inverted_default_decode_arr(ctx.bits_per_component as f32); + let mut rgb_moved = false; let image_data = if ctx.bits_per_component == 8 && ctx.color_space.supports_u8() && obj.transfer_function.is_none() @@ -842,6 +849,17 @@ fn decode_raster( interpolate: obj.interpolate, scale_factors: ctx.scale_factors, })) + } else if ctx.color_space.is_device_rgb() { + // Craft patch: `DeviceRGB` samples are taken as they are, without a second buffer + // of the image's size (`fix_image_length` made them whole rows). + rgb_moved = true; + Some(ImageData::Rgb(RgbData { + data: core::mem::take(&mut ctx.decoded.data).into_owned(), + width: ctx.width, + height, + interpolate: obj.interpolate, + scale_factors: ctx.scale_factors, + })) } else { let mut output_buf = vec![0; ctx.width as usize * height as usize * 3]; ctx.color_space @@ -944,6 +962,7 @@ fn decode_raster( obj, &mut ctx.decoded, Some(&image), + rgb_moved, &ctx.color_space, ctx.bits_per_component, ctx.width, @@ -994,6 +1013,7 @@ pub(crate) fn decode_inks( obj, &mut ctx.decoded, None, + false, &cs, bpc, ctx.width, @@ -1115,10 +1135,14 @@ fn decode_mask_bytes( Some(data) } +/// Craft patch: `rgb_moved` says that `image_data` holds the image's own 8-bit `DeviceRGB` +/// samples, moved out of `decoded` (see `decode_raster`). +#[allow(clippy::too_many_arguments)] fn resolve_alpha( obj: &ImageXObject<'_>, decoded: &mut FilterResult<'_>, image_data: Option<&ImageData>, + rgb_moved: bool, color_space: &ColorSpace, bits_per_component: u8, width: u32, @@ -1158,6 +1182,7 @@ fn resolve_alpha( // TODO: Make this less ugly. let raw_data = match image_data { Some(ImageData::Luma(d)) => &d.data, + Some(ImageData::Rgb(d)) if rgb_moved => &d.data, _ => decoded.data.as_ref(), }; @@ -1486,7 +1511,13 @@ fn convert_each(cs: &ColorSpace, input: &[f32], n: usize, output: &mut [u8]) { /// PdfCraft patch: whether an image or mask of `width` × `height` may be decoded (at most /// 2^28 pixels, the renderer's `MAX_IMAGE_PIXELS`). pub fn image_size_ok(width: u32, height: u32) -> bool { - width > 0 && height > 0 && u64::from(width) * u64::from(height) <= 1 << 28 + image_size_within(width, height, 1 << 28) +} + +/// Whether an image or mask of `width` × `height` has at most `max_pixels` pixels and is not +/// empty. +fn image_size_within(width: u32, height: u32, max_pixels: u64) -> bool { + width > 0 && height > 0 && u64::from(width) * u64::from(height) <= max_pixels } #[cfg(test)] diff --git a/vendor/hayro-syntax/src/decode_limits_tests.rs b/vendor/hayro-syntax/src/decode_limits_tests.rs index 9f95fb72d..5d2585c07 100644 --- a/vendor/hayro-syntax/src/decode_limits_tests.rs +++ b/vendor/hayro-syntax/src/decode_limits_tests.rs @@ -179,6 +179,33 @@ fn final_known_size_images_keep_their_distinct_pixel_budget() { assert_eq!(crate::filter::decode_limit(&ImageDecodeParams::default(), true, limits), 32); } +#[test] +fn image_limits_default_and_caller_figures() { + let limits = DecodeLimits::default(); + assert_eq!((limits.max_decoded_image(), limits.max_image_pixels()), (1 << 30, 1 << 28)); + // An image of 31404 × 31403 RGB pixels: 2.96 GB, past the default. + let params = ImageDecodeParams { width: 31_404, height: 31_403, bpc: Some(8), num_components: Some(3), ..Default::default() }; + assert_eq!(crate::filter::decode_limit(¶ms, true, limits) as u64, 1 << 30); + let raised = limits.with_max_decoded_image(4 << 30).with_max_image_pixels(1 << 30); + #[cfg(target_pointer_width = "64")] + { + assert_eq!((raised.max_decoded_image(), raised.max_image_pixels()), (4 << 30, 1 << 30)); + assert_eq!(crate::filter::decode_limit(¶ms, true, raised) as u64, 4 << 30); + assert_eq!(raised.with_max_decoded_stream(32).max_decoded_image(), 4 << 30, "lowering the stream limit keeps the image limits"); + assert_eq!(limits.with_max_image_pixels(u64::MAX).max_image_pixels(), 1 << 32); + } + #[cfg(not(target_pointer_width = "64"))] + assert_eq!(raised, limits, "a raise is clamped to the defaults"); + assert_eq!(raised.max_decoded_stream(), MAX_DECODED_STREAM, "the stream limit is kept"); + assert_eq!(raised.with_max_decoded_image(64).max_decoded_stream(), MAX_DECODED_STREAM); + // A context made without a document keeps every limit it is given. + for given in [limits, limits.with_max_decoded_stream(32), raised, limits.with_max_image_pixels(5)] { + assert_eq!(crate::reader::ReaderContext::dummy_with_limits(given).decode_limits(), given); + } + let small = ImageDecodeParams { width: 64, height: 1, bpc: Some(8), num_components: Some(1), ..Default::default() }; + assert_eq!(crate::filter::decode_limit(&small, true, limits.with_max_decoded_image(100)), 100); +} + #[test] fn object_stream_limit_applies_after_successful_root_xref() { let (bytes, _, _) = object_stream_pdf(false); diff --git a/vendor/hayro-syntax/src/filter/mod.rs b/vendor/hayro-syntax/src/filter/mod.rs index f25e7b101..c52f5d2ab 100644 --- a/vendor/hayro-syntax/src/filter/mod.rs +++ b/vendor/hayro-syntax/src/filter/mod.rs @@ -145,8 +145,12 @@ impl Filter { pub const MAX_DECODED_STREAM: usize = 256 << 20; /// PdfCraft patch: the most bytes they may produce for an image of known size, however large it -/// says it is. -const MAX_DECODED_IMAGE: u64 = 1 << 30; +/// says it is, unless the document's [`DecodeLimits`](crate::DecodeLimits) set another figure. +pub(crate) const MAX_DECODED_IMAGE: u64 = 1 << 30; + +/// The most pixels an image or mask may have for the interpreter to decode it, unless the +/// document's [`DecodeLimits`](crate::DecodeLimits) set another figure. +pub(crate) const MAX_IMAGE_PIXELS: u64 = 1 << 28; /// PdfCraft patch: the output limit for one filter of a stream decoded with `params`; `last` /// says whether it is the last filter. The last filter of an image whose size, bits per @@ -165,7 +169,7 @@ pub(crate) fn decode_limit(params: &ImageDecodeParams, last: bool, limits: crate } let bits = u64::from(params.width) * u64::from(components) * u64::from(bpc); let pixels = bits.div_ceil(8).saturating_mul(u64::from(params.height)); - let image = pixels.saturating_mul(2).min(MAX_DECODED_IMAGE); + let image = pixels.saturating_mul(2).min(limits.max_decoded_image()); usize::try_from(image).unwrap_or(MAX_DECODED_STREAM) } diff --git a/vendor/hayro-syntax/src/pdf.rs b/vendor/hayro-syntax/src/pdf.rs index 88b881b7f..a67a775a9 100644 --- a/vendor/hayro-syntax/src/pdf.rs +++ b/vendor/hayro-syntax/src/pdf.rs @@ -20,26 +20,63 @@ use crate::metadata::Metadata; /// budget, not this ordinary materialization limit. `Page::page_stream` materializes that /// same stream and does use this limit, so the two paths can produce different lengths. /// These limits do not impose a total document memory or execution-time limit. +/// +/// The image limits bound one image `XObject` or mask of known size: the bytes its last Flate, +/// LZW or RunLength filter may produce, and the pixels the interpreter decodes, whatever its +/// filters. Their defaults are 1 GiB and 2^28 pixels. A caller that can hold larger images +/// raises them; where pointers are narrower than 64 bits, a raise is clamped to the default. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct DecodeLimits { max_decoded_stream: usize, + max_decoded_image: u64, + max_image_pixels: u64, } impl DecodeLimits { - /// The existing ordinary stream limit, 256 MiB. - pub const DEFAULT: Self = Self { max_decoded_stream: crate::filter::MAX_DECODED_STREAM }; + /// The existing limits: 256 MiB for an ordinary stream, 1 GiB and 2^28 pixels for an image. + pub const DEFAULT: Self = Self { + max_decoded_stream: crate::filter::MAX_DECODED_STREAM, + max_decoded_image: crate::filter::MAX_DECODED_IMAGE, + max_image_pixels: crate::filter::MAX_IMAGE_PIXELS, + }; /// Lower the maximum expanded bytes per ordinary stream. Requests above the existing /// 256 MiB ceiling are clamped; zero permits no ordinary materialized expansion. /// This does not lower the separate incremental page-content budget. pub const fn with_max_decoded_stream(self, max: usize) -> Self { - Self { max_decoded_stream: if max < self.max_decoded_stream { max } else { self.max_decoded_stream } } + Self { max_decoded_stream: if max < self.max_decoded_stream { max } else { self.max_decoded_stream }, ..self } } /// The maximum expanded bytes per ordinary stream. pub const fn max_decoded_stream(self) -> usize { self.max_decoded_stream } + + /// Set the most bytes the last Flate, LZW or RunLength filter of an image of known size may + /// produce, lower or (with 64-bit pointers) higher than the 1 GiB default. The filter also + /// stops at twice the image's own pixel bytes. + pub const fn with_max_decoded_image(self, max: u64) -> Self { + Self { max_decoded_image: narrow_clamp(max, crate::filter::MAX_DECODED_IMAGE), ..self } + } + + /// The most bytes the last Flate, LZW or RunLength filter of an image of known size may + /// produce. + pub const fn max_decoded_image(self) -> u64 { + self.max_decoded_image + } + + /// Set the most pixels an image or mask may have for the interpreter to decode it, lower or + /// (with 64-bit pointers) higher than the 2^28 default, up to 2^32. A larger image is + /// skipped with an image decode warning. + pub const fn with_max_image_pixels(self, max: u64) -> Self { + let max = if max > MAX_RAISED_IMAGE_PIXELS { MAX_RAISED_IMAGE_PIXELS } else { max }; + Self { max_image_pixels: narrow_clamp(max, crate::filter::MAX_IMAGE_PIXELS), ..self } + } + + /// The most pixels an image or mask may have for the interpreter to decode it. + pub const fn max_image_pixels(self) -> u64 { + self.max_image_pixels + } } impl Default for DecodeLimits { @@ -48,6 +85,16 @@ impl Default for DecodeLimits { } } +/// The most pixels [`DecodeLimits::with_max_image_pixels`] sets: the sample and byte counts of +/// such an image (up to 32 components of 4 bytes) fit a 64-bit `usize`. +const MAX_RAISED_IMAGE_PIXELS: u64 = 1 << 32; + +/// `max`, or `default` when `max` is higher and pointers are narrower than 64 bits: the sizes +/// derived from a larger image overflow `usize` there. +const fn narrow_clamp(max: u64, default: u64) -> u64 { + if usize::BITS < 64 && max > default { default } else { max } +} + /// A PDF file. pub struct Pdf { xref: Arc, diff --git a/vendor/hayro-syntax/src/reader.rs b/vendor/hayro-syntax/src/reader.rs index 65b64765e..3c661ddab 100644 --- a/vendor/hayro-syntax/src/reader.rs +++ b/vendor/hayro-syntax/src/reader.rs @@ -127,7 +127,9 @@ struct ReaderContextData<'a> { #[derive(Clone, Debug)] enum ReaderContextInner<'a> { Shared(Arc>), - Dummy { in_content_stream: bool, limits: crate::DecodeLimits }, + /// Craft patch: the default limits with `max_decoded_stream` (other limits are in a + /// `ControlledDummy`), so the context stays the size of an object's fields. + Dummy { in_content_stream: bool, max_decoded_stream: usize }, ControlledDummy(Arc), } @@ -135,7 +137,7 @@ enum ReaderContextInner<'a> { struct ControlledDummy { in_content_stream: bool, limits: crate::DecodeLimits, - control: crate::cancel::Control, + control: Option, } /// Context for reading PDF objects. @@ -158,34 +160,35 @@ impl<'a> ReaderContext<'a> { } pub(crate) fn dummy_with_limits(limits: crate::DecodeLimits) -> Self { - Self(ReaderContextInner::Dummy { in_content_stream: false, limits }) + Self::dummy_with_control(limits, None) } pub(crate) fn dummy_with_control(limits: crate::DecodeLimits, control: Option) -> Self { - match control { - Some(control) => Self(ReaderContextInner::ControlledDummy(Arc::new(ControlledDummy { in_content_stream: false, limits, control }))), - None => Self::dummy_with_limits(limits), + let max_decoded_stream = limits.max_decoded_stream(); + if control.is_none() && limits == crate::DecodeLimits::DEFAULT.with_max_decoded_stream(max_decoded_stream) { + return Self(ReaderContextInner::Dummy { in_content_stream: false, max_decoded_stream }); } + Self(ReaderContextInner::ControlledDummy(Arc::new(ControlledDummy { in_content_stream: false, limits, control }))) } pub(crate) fn control(&self) -> Option<&crate::cancel::Control> { match &self.0 { ReaderContextInner::Shared(inner) => inner.xref.control(), ReaderContextInner::Dummy { .. } => None, - ReaderContextInner::ControlledDummy(inner) => Some(&inner.control).filter(|c| c.active()), + ReaderContextInner::ControlledDummy(inner) => inner.control.as_ref().filter(|c| c.active()), } } pub(crate) fn decode_limits(&self) -> crate::DecodeLimits { match &self.0 { ReaderContextInner::Shared(inner) => inner.xref.decode_limits(), - ReaderContextInner::Dummy { limits, .. } => *limits, + ReaderContextInner::Dummy { max_decoded_stream, .. } => crate::DecodeLimits::DEFAULT.with_max_decoded_stream(*max_decoded_stream), ReaderContextInner::ControlledDummy(inner) => inner.limits, } } pub(crate) fn dummy_ref() -> &'static Self { - &Self(ReaderContextInner::Dummy { in_content_stream: true, limits: crate::DecodeLimits::DEFAULT }) + &Self(ReaderContextInner::Dummy { in_content_stream: true, max_decoded_stream: crate::filter::MAX_DECODED_STREAM }) } #[inline] From 746d6e33df4d61cbe7dcfbbd84408d4f71157cd8 Mon Sep 17 00:00:00 2001 From: Hamza Naveed <45464935+Hamza0101@users.noreply.github.com> Date: Tue, 17 Nov 2026 07:30:24 +0500 Subject: [PATCH 20/64] craft-drawingml: elbow connector handles take the spec's whole adjust range (#1892) --- crates/drawingml/src/preset/build.rs | 17 +++++++++++------ crates/drawingml/src/preset/tests.rs | 11 +++++++++++ 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/crates/drawingml/src/preset/build.rs b/crates/drawingml/src/preset/build.rs index f8996a93c..30019804f 100644 --- a/crates/drawingml/src/preset/build.rs +++ b/crates/drawingml/src/preset/build.rs @@ -1115,6 +1115,9 @@ fn flowchart_and_star_shapes(c: &Ctx) -> Option { Some(g) } +/// The range presetShapeDefinitions gives the elbows' handles (`minX` / `maxX`, `minY` / `maxY`). +const ADJ_LIMIT: f64 = 2_147_483_647.0; + fn callout_wave_and_connector_shapes(c: &Ctx) -> Option { let name = c.name; let w = c.w; @@ -1197,28 +1200,30 @@ fn callout_wave_and_connector_shapes(c: &Ctx) -> Option { } // The elbows of ECMA-376's presetShapeDefinitions: 3 has one middle leg, 4 adds a // horizontal one at `adj2`, 5 a third vertical one at `adj3`. 4 and 5 were drawn as 3. + // Their handles take the spec's whole range (its `ahXY` min and max), so dragging one + // never clamps a value an imported route uses. "bentConnector3" => { let x1 = w * a(0) / 1e5; let l = Pb::new().m(0.0, 0.0).l(x1, 0.0).l(x1, h).l(w, h).take(); let mut g = Geometry { paths: vec![stroke_only(l)], text_rect: full, handles: vec![], sites: vec![Point::ZERO, Point::new(w, h)] }; - g.handles.push(Handle::new(0, Point::new(0.0, h / 2.0), Vec2::new(w / 1e5, 0.0), a(0), -1e6, 1e6)); + g.handles.push(Handle::new(0, Point::new(0.0, h / 2.0), Vec2::new(w / 1e5, 0.0), a(0), -ADJ_LIMIT, ADJ_LIMIT)); g } "bentConnector4" => { let (x1, y2) = (w * a(0) / 1e5, h * a(1) / 1e5); let l = Pb::new().m(0.0, 0.0).l(x1, 0.0).l(x1, y2).l(w, y2).l(w, h).take(); let mut g = Geometry { paths: vec![stroke_only(l)], text_rect: full, handles: vec![], sites: vec![Point::ZERO, Point::new(w, h)] }; - g.handles.push(Handle::new(0, Point::new(0.0, y2 / 2.0), Vec2::new(w / 1e5, 0.0), a(0), -1e6, 1e6)); - g.handles.push(Handle::new(1, Point::new((x1 + w) / 2.0, 0.0), Vec2::new(0.0, h / 1e5), a(1), -1e6, 1e6)); + g.handles.push(Handle::new(0, Point::new(0.0, y2 / 2.0), Vec2::new(w / 1e5, 0.0), a(0), -ADJ_LIMIT, ADJ_LIMIT)); + g.handles.push(Handle::new(1, Point::new((x1 + w) / 2.0, 0.0), Vec2::new(0.0, h / 1e5), a(1), -ADJ_LIMIT, ADJ_LIMIT)); g } "bentConnector5" => { let (x1, y2, x3) = (w * a(0) / 1e5, h * a(1) / 1e5, w * a(2) / 1e5); let l = Pb::new().m(0.0, 0.0).l(x1, 0.0).l(x1, y2).l(x3, y2).l(x3, h).l(w, h).take(); let mut g = Geometry { paths: vec![stroke_only(l)], text_rect: full, handles: vec![], sites: vec![Point::ZERO, Point::new(w, h)] }; - g.handles.push(Handle::new(0, Point::new(0.0, y2 / 2.0), Vec2::new(w / 1e5, 0.0), a(0), -1e6, 1e6)); - g.handles.push(Handle::new(1, Point::new((x1 + x3) / 2.0, 0.0), Vec2::new(0.0, h / 1e5), a(1), -1e6, 1e6)); - g.handles.push(Handle::new(2, Point::new(0.0, (y2 + h) / 2.0), Vec2::new(w / 1e5, 0.0), a(2), -1e6, 1e6)); + g.handles.push(Handle::new(0, Point::new(0.0, y2 / 2.0), Vec2::new(w / 1e5, 0.0), a(0), -ADJ_LIMIT, ADJ_LIMIT)); + g.handles.push(Handle::new(1, Point::new((x1 + x3) / 2.0, 0.0), Vec2::new(0.0, h / 1e5), a(1), -ADJ_LIMIT, ADJ_LIMIT)); + g.handles.push(Handle::new(2, Point::new(0.0, (y2 + h) / 2.0), Vec2::new(w / 1e5, 0.0), a(2), -ADJ_LIMIT, ADJ_LIMIT)); g } // The curved connectors follow the same legs with cubic Béziers. diff --git a/crates/drawingml/src/preset/tests.rs b/crates/drawingml/src/preset/tests.rs index 0427d1a3e..deddd5fb8 100644 --- a/crates/drawingml/src/preset/tests.rs +++ b/crates/drawingml/src/preset/tests.rs @@ -452,6 +452,17 @@ fn the_three_and_four_bend_elbows_follow_their_adjust_values() { let g = build("bentConnector5", 200.0, 100.0, &[25000.0, 75000.0, 60000.0]).unwrap(); let pos: Vec<(f64, f64)> = g.handles.iter().map(|h| (h.pos.x, h.pos.y)).collect(); assert_eq!(pos, [(50.0, 37.5), (85.0, 75.0), (120.0, 87.5)]); + // A handle dragged far out keeps the value: the spec's range is ±2147483647, and PowerPoint's + // routing gives a thin connector box values well beyond ±1000000 (a leg 50 pt beside a 1 pt + // wide box is 5000000). + for name in ["bentConnector3", "bentConnector4", "bentConnector5"] { + let g = build(name, 200.0, 100.0, &[]).unwrap(); + for h in &g.handles { + for v in [5_000_000.0, -5_000_000.0] { + assert_eq!(h.value_at(h.origin + h.dir * v), v, "{name} handle {}", h.index); + } + } + } } // curvedConnector2 is one cubic (l,t)…(r,b) through (wd2,t) and (r,hd2); 4 and 5 bend at the same From 6dbf8871ab7eabde575650cfb30a385eec884733 Mon Sep 17 00:00:00 2001 From: Aleksander Helgaker Date: Tue, 17 Nov 2026 03:30:28 +0100 Subject: [PATCH 21/64] scraft-format: add the session room tone (#1876) --- crates/scraft-format/src/lib.rs | 2 ++ crates/scraft-format/src/room_tone.rs | 52 +++++++++++++++++++++++++++ crates/scraft-format/src/session.rs | 30 ++++++++++++++++ 3 files changed, 84 insertions(+) create mode 100644 crates/scraft-format/src/room_tone.rs diff --git a/crates/scraft-format/src/lib.rs b/crates/scraft-format/src/lib.rs index c54d7f934..22d69b953 100644 --- a/crates/scraft-format/src/lib.rs +++ b/crates/scraft-format/src/lib.rs @@ -12,6 +12,7 @@ mod clip; mod ids; mod markers; mod mixer; +mod room_tone; mod session; mod source; mod track; @@ -27,6 +28,7 @@ pub use markers::{Group, MarkerKind, MemoryLocation}; pub use mixer::{ Bus, ChannelFormat, INSERT_SLOTS, Insert, Mixer, OutputPath, Route, SEND_SLOTS, SendSlot, Speaker, SurroundPan, fader_db_to_pos, fader_pos_to_db, }; +pub use room_tone::RoomTone; pub use session::{ AutoName, BitDepthSetting, EditMode, EditState, FEET_FRAMES_START, MAX_COMMENT_CHARS, MAX_NAME_CHARS, SESSION_EXTENSION, Session, SessionError, Tool, TrackView, ZoomState, ZoomToggle, truncate_chars, diff --git a/crates/scraft-format/src/room_tone.rs b/crates/scraft-format/src/room_tone.rs new file mode 100644 index 000000000..0634c4092 --- /dev/null +++ b/crates/scraft-format/src/room_tone.rs @@ -0,0 +1,52 @@ +//! The session's room tone: a stretch of recorded silence used to fill gaps instead of digital +//! silence. + +use crate::SourceId; +use crate::soundcraft_time::{MAX_POSITION, Samples}; + +/// A window onto an audio source chosen as the session's room tone. Filling a gap places clips +/// that play this window, so the fill stays ordinary, editable clips on the timeline. +#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)] +pub struct RoomTone { + pub source: SourceId, + /// Where the window starts in the source (samples). + pub offset: Samples, + /// Window length (samples, > 0). + pub length: Samples, + /// Clip gain the fill clips get (dB), taken from the clip the tone was chosen from. + #[serde(default)] + pub gain_db: f32, +} + +impl RoomTone { + /// The window repaired for a source of `frames` frames, or `None` when nothing playable is left. + pub fn sanitized(mut self, frames: u64) -> Option { + let frames = Samples::try_from(frames).unwrap_or(MAX_POSITION).min(MAX_POSITION); + if self.offset < 0 || self.offset >= frames || self.length <= 0 { + return None; + } + self.length = self.length.min(frames - self.offset); + self.gain_db = if self.gain_db.is_finite() { self.gain_db.clamp(-144.0, 36.0) } else { 0.0 }; + Some(self) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn tone(offset: Samples, length: Samples) -> RoomTone { + RoomTone { source: SourceId(1), offset, length, gain_db: 0.0 } + } + + #[test] + fn a_window_past_the_source_is_cut_to_fit_or_dropped() { + assert_eq!(tone(100, 50).sanitized(1000), Some(tone(100, 50))); + assert_eq!(tone(900, 500).sanitized(1000), Some(tone(900, 100))); + assert_eq!(tone(1000, 10).sanitized(1000), None); + assert_eq!(tone(-1, 10).sanitized(1000), None); + assert_eq!(tone(0, 0).sanitized(1000), None); + let loud = RoomTone { gain_db: f32::NAN, ..tone(0, 10) }; + assert_eq!(loud.sanitized(1000).map(|t| t.gain_db), Some(0.0)); + } +} diff --git a/crates/scraft-format/src/session.rs b/crates/scraft-format/src/session.rs index 021cab8bc..9ba090958 100644 --- a/crates/scraft-format/src/session.rs +++ b/crates/scraft-format/src/session.rs @@ -378,6 +378,9 @@ pub struct Session { /// Performance). Independent of undo so a restore survives later edits. #[serde(default)] pub midi_originals: std::collections::BTreeMap, + /// The recorded silence that `edit.room_tone_fill` fills gaps with. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub room_tone: Option, #[serde(skip)] pub pool: SourcePool, /// The folder relative source paths point into: where the session was opened or last saved. @@ -427,6 +430,7 @@ impl Session { next_id: 1, comments: String::new(), midi_originals: std::collections::BTreeMap::new(), + room_tone: None, pool: SourcePool::default(), folder: None, }; @@ -867,6 +871,8 @@ impl Session { self.outputs.iter_mut().for_each(|o| truncate_chars(&mut o.name, MAX_NAME_CHARS)); self.groups.iter_mut().for_each(|g| truncate_chars(&mut g.name, MAX_NAME_CHARS)); self.sources.iter_mut().for_each(|s| truncate_chars(&mut s.name, MAX_NAME_CHARS)); + // A room tone must play part of a source the session still lists. + self.room_tone = self.room_tone.and_then(|t| self.sources.iter().find(|s| s.id == t.source).and_then(|s| t.sanitized(s.frames))); // Drop performances whose clip no longer exists anywhere (any playlist). let clip_ids: std::collections::BTreeSet = self.tracks.iter().flat_map(|t| t.playlists.iter().flat_map(|p| p.clips.iter().map(|c| c.id.0))).collect(); @@ -1306,6 +1312,30 @@ mod tests { assert!(s.next_id > t.0); } + #[test] + fn a_loaded_room_tone_must_play_a_listed_source() { + let mut s = Session::default(); + let id = SourceId(s.alloc()); + s.sources.push(crate::Source { + id, + name: "Tone".into(), + path: "Tone.wav".into(), + channels: 1, + frames: 1000, + sample_rate: 48_000, + format: crate::FileFormat::Wav, + time_reference: 0, + unsaved: false, + }); + s.room_tone = Some(crate::RoomTone { source: id, offset: 400, length: 5000, gain_db: -3.0 }); + let loaded = Session::from_json(&s.to_json().unwrap()).unwrap(); + assert_eq!(loaded.room_tone, Some(crate::RoomTone { source: id, offset: 400, length: 600, gain_db: -3.0 }), "cut to the source"); + s.room_tone = Some(crate::RoomTone { source: SourceId(999), offset: 0, length: 10, gain_db: 0.0 }); + assert_eq!(Session::from_json(&s.to_json().unwrap()).unwrap().room_tone, None, "an unknown source is dropped"); + s.room_tone = None; + assert!(!s.to_json().unwrap().contains("room_tone"), "sessions without one are written as before"); + } + #[test] fn loaded_automation_is_clamped_to_its_range() { // #884: a session file can carry points outside a lane's range; load clamps them. From 352c06857d0a3bc38aebd687b7480023b9a03652 Mon Sep 17 00:00:00 2001 From: el-j Date: Tue, 17 Nov 2026 03:30:32 +0100 Subject: [PATCH 22/64] craft-audio: GSM 06.10 full-rate speech decoder and encoder (#1534) (#1874) --- crates/audio/Cargo.toml | 8 + crates/audio/README.md | 1 + crates/audio/src/gsm.rs | 1038 ++++++++++++++++++++++++++++++ crates/audio/src/lib.rs | 5 +- crates/audio/tests/gsm_oracle.rs | 138 ++++ 5 files changed, 1189 insertions(+), 1 deletion(-) create mode 100644 crates/audio/src/gsm.rs create mode 100644 crates/audio/tests/gsm_oracle.rs diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index fe28cec3f..22f012011 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -46,6 +46,10 @@ qoa = ["qoa-decode", "qoa-encode"] qoa-decode = [] qoa-encode = [] opus-encode = [] +# GSM 06.10 full-rate speech: decoder and encoder in the `gsm` module, each on its own. +gsm = ["gsm-decode", "gsm-encode"] +gsm-decode = [] +gsm-encode = [] ac3-decode = ["craft-media/bitstream"] mpa-decode = ["craft-media/bitstream"] # MPEG-1/2 Layer III (MP3) decoder (`mp3::Decoder`). @@ -92,6 +96,10 @@ required-features = ["decode", "encode"] name = "flac_decode" required-features = ["flac-decode", "flac-encode"] +[[test]] +name = "gsm_oracle" +required-features = ["gsm"] + [[test]] name = "qoa_oracle" required-features = ["qoa"] diff --git a/crates/audio/README.md b/crates/audio/README.md index 7469a9401..10080ebbe 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -44,6 +44,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou | `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` | | `mp3-decode` | `mp3::Decoder`, `mp3::InfoTag` | `mpa-decode` | | `mp3-encode` | `mp3::Encoder`; `encode`, `FileEncoder` for MP3 | craft-media `bitstream` | +| `gsm-decode`, `gsm-encode` (`gsm`) | `gsm::Decoder`, `gsm::Encoder`, `gsm::decode`, `gsm::encode`: GSM 06.10 full-rate speech, bit-exact, raw `.gsm` and WAV (GSM 6.10) packings | none | | `peaks` | `peaks::Peaks` | none | | `rayon` | parallel AAC encoding (with `aac-encode`) | `rayon` | | `serde` | `Serialize`/`Deserialize` on the shared types | `serde` | diff --git a/crates/audio/src/gsm.rs b/crates/audio/src/gsm.rs new file mode 100644 index 000000000..450922c29 --- /dev/null +++ b/crates/audio/src/gsm.rs @@ -0,0 +1,1038 @@ +//! GSM 06.10 full-rate speech (RPE-LTP): a decoder (feature `gsm-decode`) and an encoder (feature +//! `gsm-encode`), 8 kHz mono, 13 kbit/s. +//! +//! Written from the public ETSI specification (GSM 06.10 / 3GPP TS 46.010, clause 5: the bit-exact +//! fixed-point description of the coder and decoder, and its tables). A frame is 160 samples +//! (20 ms) coded as 76 parameters in 260 bits: eight log-area ratios for the short-term filter, +//! then four sub-frames of 40 samples, each with a long-term lag and gain, an RPE grid position, +//! a block amplitude and thirteen 3-bit pulses. +//! +//! The arithmetic is the specification's own 16-bit saturating arithmetic, so the output is bit +//! exact. Samples are `i16`; the coder uses the upper 13 bits of its input and the decoder's +//! output has its three low bits clear, as the specification says. +//! +//! Two packings of the 260 bits are supported ([`Packing`]): +//! +//! - [`Packing::Raw`]: 33 bytes per frame, the signature nibble `0xD` and then the parameters +//! most significant bit first (the packing of RFC 3551 and of `.gsm` files). +//! - [`Packing::Wav49`]: 65 bytes per pair of frames, the parameters least significant bit first +//! (the packing of the WAV format tag `0x31`, "GSM 6.10"). +//! +//! Any 260 bits are a decodable frame, so decoding never fails on content, only on length. +//! Each stream starts from the specification's initial state. + +// Index loops follow the specification's pseudo-code, which numbers the arrays the same way. +#![allow(clippy::needless_range_loop)] +// The two halves share the arithmetic, tables and synthesis helpers; with only one feature on, some +// of them are unused. +#![cfg_attr(not(all(feature = "gsm-decode", feature = "gsm-encode")), allow(dead_code))] + +use std::fmt; + +/// Samples in a frame. +pub const FRAME_SAMPLES: usize = 160; +/// Samples in a sub-frame. +pub const SUBFRAME_SAMPLES: usize = 40; +/// Bytes of a frame in the [`Packing::Raw`] packing. +pub const RAW_FRAME_BYTES: usize = 33; +/// Bytes of a pair of frames in the [`Packing::Wav49`] packing. +pub const WAV49_BLOCK_BYTES: usize = 65; +/// The sampling rate, in Hz. +pub const SAMPLE_RATE: u32 = 8000; + +/// How the 260 bits of a frame are laid out in bytes. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum Packing { + /// 33 bytes per frame: `0xD` then the parameters, most significant bit first. + Raw, + /// 65 bytes per two frames: the parameters least significant bit first, with no signature. + Wav49, +} + +impl Packing { + /// Bytes of one block: a frame for [`Packing::Raw`], two frames for [`Packing::Wav49`]. + #[must_use] + pub const fn block_bytes(self) -> usize { + match self { + Self::Raw => RAW_FRAME_BYTES, + Self::Wav49 => WAV49_BLOCK_BYTES, + } + } + + /// Samples of one block. + #[must_use] + pub const fn block_samples(self) -> usize { + match self { + Self::Raw => FRAME_SAMPLES, + Self::Wav49 => 2 * FRAME_SAMPLES, + } + } +} + +/// What went wrong reading GSM data. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Error { + /// The data is not a whole number of blocks. + Truncated { + /// The bytes in each block. + block: usize, + /// The bytes given. + len: usize, + }, + /// A raw frame does not start with the signature nibble `0xD`. + BadSignature { + /// The byte offset of the frame. + offset: usize, + }, +} + +impl fmt::Display for Error { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::Truncated { block, len } => write!(f, "GSM data of {len} bytes is not a whole number of {block}-byte blocks"), + Self::BadSignature { offset } => write!(f, "GSM frame at byte {offset} does not start with the signature 0xD"), + } + } +} + +impl std::error::Error for Error {} + +// ------------------------------------------------------------------ the specification's arithmetic + +const MIN16: i32 = -32768; +const MAX16: i32 = 32767; + +fn sat16(x: i32) -> i32 { + x.clamp(MIN16, MAX16) +} +fn add(a: i32, b: i32) -> i32 { + sat16(a + b) +} +fn sub(a: i32, b: i32) -> i32 { + sat16(a - b) +} +fn mult(a: i32, b: i32) -> i32 { + if a == MIN16 && b == MIN16 { MAX16 } else { (a * b) >> 15 } +} +fn mult_r(a: i32, b: i32) -> i32 { + if a == MIN16 && b == MIN16 { MAX16 } else { (a * b + 16384) >> 15 } +} +fn abs16(a: i32) -> i32 { + if a == MIN16 { MAX16 } else { a.abs() } +} +fn l_add(a: i32, b: i32) -> i32 { + a.saturating_add(b) +} +fn l_sub(a: i32, b: i32) -> i32 { + a.saturating_sub(b) +} +fn l_mult(a: i32, b: i32) -> i32 { + let p = (i64::from(a) * i64::from(b)) << 1; + p.clamp(i64::from(i32::MIN), i64::from(i32::MAX)) as i32 +} +/// A 16-bit variable assigned from a wider value: the low 16 bits, signed. +fn w16(x: i32) -> i32 { + i32::from(x as i16) +} +/// The specification's `<<`: a negative count shifts right. +fn asl(x: i32, n: i32) -> i32 { + if n >= 0 { x.wrapping_shl(n.min(31) as u32) } else { asr(x, -n) } +} +/// The specification's `>>`: a negative count shifts left. +fn asr(x: i32, n: i32) -> i32 { + if n >= 0 { x >> n.min(31) } else { asl(x, -n) } +} +/// Left shifts that normalize a 32-bit value into `[2^30, 2^31)` (or its negative counterpart). +fn norm(x: i32) -> i32 { + if x == 0 { + return 0; + } + let y = if x < 0 { !x } else { x }; + if y == 0 { 31 } else { y.leading_zeros() as i32 - 1 } +} +/// Fractional division of `num` by `denum`, `0 < num <= denum`, as the specification gives it. +fn div(num: i32, denum: i32) -> i32 { + let (mut l_num, mut q) = (num, 0); + for _ in 0..15 { + q <<= 1; + l_num = l_num.wrapping_shl(1); + if l_num >= denum { + l_num = l_num.wrapping_sub(denum); + q += 1; + } + } + q +} + +// ------------------------------------------------------------------------------ the tables + +/// Table 5.1: `A`, `B`, `MIC`, `MAC` of the log-area ratio quantizers. +const A: [i32; 8] = [20480, 20480, 20480, 20480, 13964, 15360, 8534, 9036]; +const B: [i32; 8] = [0, 0, 2048, -2560, 94, -1792, -341, -1144]; +const MIC: [i32; 8] = [-32, -32, -16, -16, -8, -8, -4, -4]; +const MAC: [i32; 8] = [31, 31, 15, 15, 7, 7, 3, 3]; +/// Table 5.2: `1 / A`. +const INVA: [i32; 8] = [13107, 13107, 13107, 13107, 19223, 17476, 31454, 29708]; +/// Table 5.3a: decision levels of the long-term gain quantizer. +const DLB: [i32; 4] = [6554, 16384, 26214, 32767]; +/// Table 5.3b: its quantization levels. +const QLB: [i32; 4] = [3277, 11469, 21299, 32767]; +/// Table 5.4: the weighting filter. +const H: [i32; 11] = [-134, -374, 0, 2054, 5741, 8192, 5741, 2054, 0, -374, -134]; +/// Table 5.5: normalized inverse mantissa. +const NRFAC: [i32; 8] = [29128, 26215, 23832, 21846, 20165, 18725, 17476, 16384]; +/// Table 5.6: normalized direct mantissa. +const FAC: [i32; 8] = [18431, 20479, 22527, 24575, 26623, 28671, 30719, 32767]; + +// -------------------------------------------------------------------------- the parameters + +/// The parameters of one 40-sample sub-frame. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct SubFrame { + /// Long-term lag, 7 bits (40 to 120 from a coder). + pub lag: u8, + /// Long-term gain index, 2 bits. + pub gain: u8, + /// RPE grid position, 2 bits. + pub grid: u8, + /// Block amplitude, 6 bits. + pub xmax: u8, + /// The 13 RPE pulses, 3 bits each. + pub pulses: [u8; 13], +} + +/// The 76 parameters of one frame. A decoder uses only the low bits each field is allowed. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct Frame { + /// The eight log-area ratios, 6, 6, 5, 5, 4, 4, 3 and 3 bits, offset to be non-negative. + pub lar: [u8; 8], + /// The four sub-frames. + pub sub: [SubFrame; 4], +} + +const LAR_BITS: [u32; 8] = [6, 6, 5, 5, 4, 4, 3, 3]; +const SUB_FIELDS: usize = 4 + 13; +const PARAMS: usize = 8 + 4 * SUB_FIELDS; + +fn field_bits(i: usize) -> u32 { + if i < 8 { + return LAR_BITS.get(i).copied().unwrap_or(0); + } + match (i - 8) % SUB_FIELDS { + 0 => 7, + 1 | 2 => 2, + 3 => 6, + _ => 3, + } +} + +impl Frame { + fn values(&self) -> [u8; PARAMS] { + let mut v = [0u8; PARAMS]; + v[..8].copy_from_slice(&self.lar); + for (j, s) in self.sub.iter().enumerate() { + let at = 8 + j * SUB_FIELDS; + v[at] = s.lag; + v[at + 1] = s.gain; + v[at + 2] = s.grid; + v[at + 3] = s.xmax; + v[at + 4..at + SUB_FIELDS].copy_from_slice(&s.pulses); + } + v + } + + fn from_values(v: &[u8; PARAMS]) -> Self { + let mut f = Self::default(); + f.lar.copy_from_slice(&v[..8]); + for (j, s) in f.sub.iter_mut().enumerate() { + let at = 8 + j * SUB_FIELDS; + s.lag = v[at]; + s.gain = v[at + 1]; + s.grid = v[at + 2]; + s.xmax = v[at + 3]; + s.pulses.copy_from_slice(&v[at + 4..at + SUB_FIELDS]); + } + f + } + + /// The frame in the [`Packing::Raw`] layout. + #[must_use] + pub fn to_raw(&self) -> [u8; RAW_FRAME_BYTES] { + let mut out = [0u8; RAW_FRAME_BYTES]; + out[0] = 0xD0; + let mut pos = 4usize; + for (i, &v) in self.values().iter().enumerate() { + let w = field_bits(i); + for b in (0..w).rev() { + if (u32::from(v) >> b) & 1 == 1 { + out[pos / 8] |= 0x80 >> (pos % 8); + } + pos += 1; + } + } + out + } + + /// A frame from the [`Packing::Raw`] layout; fails when the signature nibble is not `0xD`. + pub fn from_raw(bytes: &[u8; RAW_FRAME_BYTES]) -> Result { + if bytes[0] >> 4 != 0xD { + return Err(Error::BadSignature { offset: 0 }); + } + let mut v = [0u8; PARAMS]; + let mut pos = 4usize; + for (i, slot) in v.iter_mut().enumerate() { + let mut x = 0u8; + for _ in 0..field_bits(i) { + x = (x << 1) | ((bytes[pos / 8] >> (7 - pos % 8)) & 1); + pos += 1; + } + *slot = x; + } + Ok(Self::from_values(&v)) + } + + /// Two frames in the [`Packing::Wav49`] layout. + #[must_use] + pub fn pair_to_wav49(a: &Self, b: &Self) -> [u8; WAV49_BLOCK_BYTES] { + let mut out = [0u8; WAV49_BLOCK_BYTES]; + let mut pos = 0usize; + for f in [a, b] { + for (i, &v) in f.values().iter().enumerate() { + for bit in 0..field_bits(i) { + if (u32::from(v) >> bit) & 1 == 1 { + out[pos / 8] |= 1 << (pos % 8); + } + pos += 1; + } + } + } + out + } + + /// Two frames from the [`Packing::Wav49`] layout. + #[must_use] + pub fn pair_from_wav49(bytes: &[u8; WAV49_BLOCK_BYTES]) -> [Self; 2] { + let mut pos = 0usize; + let mut frames = [Self::default(); 2]; + for f in &mut frames { + let mut v = [0u8; PARAMS]; + for (i, slot) in v.iter_mut().enumerate() { + let mut x = 0u8; + for bit in 0..field_bits(i) { + x |= ((bytes[pos / 8] >> (pos % 8)) & 1) << bit; + pos += 1; + } + *slot = x; + } + *f = Self::from_values(&v); + } + frames + } +} + +// ------------------------------------------------------------------- shared synthesis pieces + +/// Clause 5.2.8: the decoded log-area ratios `LARpp` of a frame's coded ones. +fn decode_lar(lar: &[u8; 8]) -> [i32; 8] { + let mut out = [0i32; 8]; + for i in 0..8 { + let c = i32::from(lar[i] & ((1u8 << LAR_BITS[i]) - 1)); + let t1 = w16(add(c, MIC[i]) << 10); + let t2 = w16(B[i] << 1); + let t1 = sub(t1, t2); + let t1 = mult_r(INVA[i], t1); + out[i] = add(t1, t1); + } + out +} + +/// Clause 5.2.9.1: the interpolated log-area ratios of segment `seg` (0 to 3). +fn interpolate(prev: &[i32; 8], cur: &[i32; 8], seg: usize) -> [i32; 8] { + let mut out = [0i32; 8]; + for i in 0..8 { + out[i] = match seg { + 0 => add(add(prev[i] >> 2, cur[i] >> 2), prev[i] >> 1), + 1 => add(prev[i] >> 1, cur[i] >> 1), + 2 => add(add(prev[i] >> 2, cur[i] >> 2), cur[i] >> 1), + _ => cur[i], + }; + } + out +} + +/// Clause 5.2.9.2: reflection coefficients from log-area ratios. +fn reflection(larp: &[i32; 8]) -> [i32; 8] { + let mut rp = [0i32; 8]; + for i in 0..8 { + let a = abs16(larp[i]); + let t = if a < 11059 { + w16(a << 1) + } else if a < 20070 { + add(a, 11059) + } else { + add(a >> 2, 26112) + }; + rp[i] = if larp[i] < 0 { sub(0, t) } else { t }; + } + rp +} + +/// The sample ranges the four sets of interpolated coefficients cover. +const SEGMENTS: [(usize, usize); 4] = [(0, 12), (13, 26), (27, 39), (40, 159)]; + +/// The exponent and mantissa of a block amplitude (clause 5.2.15). +fn exp_mant(xmaxc: i32) -> (i32, i32) { + let mut exp = 0; + if xmaxc > 15 { + exp = (xmaxc >> 3) - 1; + } + let mut mant = xmaxc - (exp << 3); + if mant == 0 { + exp = -4; + mant = 15; + } else { + let mut itest = false; + for _ in 0..3 { + if mant > 7 { + itest = true; + } + if !itest { + mant = (mant << 1) + 1; + exp -= 1; + } + } + } + (exp, mant - 8) +} + +/// Clauses 5.2.16 and 5.2.17: the 40 samples of the long-term residual from a sub-frame's RPE data. +fn rpe_decode(s: &SubFrame) -> [i32; SUBFRAME_SAMPLES] { + let (exp, mant) = exp_mant(i32::from(s.xmax & 0x3F)); + let temp1 = FAC[mant as usize & 7]; + let temp2 = 6 - exp; + let temp3 = asl(1, temp2 - 1); + let mut ep = [0i32; SUBFRAME_SAMPLES]; + let grid = usize::from(s.grid & 3); + for (i, &p) in s.pulses.iter().enumerate() { + let t = sub(i32::from(p & 7) << 1, 7); + let t = w16(t << 12); + let t = mult_r(temp1, t); + let t = add(t, temp3); + let at = grid + 3 * i; + if at < SUBFRAME_SAMPLES { + ep[at] = asr(t, temp2); + } + } + ep +} + +/// The long-term lag, gain and reconstructed-residual history shared by coder and decoder. +#[derive(Clone)] +struct Synth { + /// The reconstructed short-term residual: `dp[-120..-1]`, oldest first. + dp: [i32; 120], + nrp: i32, + /// The short-term synthesis (or analysis) lattice state. + v: [i32; 9], + prev_lar: [i32; 8], +} + +impl Synth { + fn new() -> Self { + Self { dp: [0; 120], nrp: 40, v: [0; 9], prev_lar: [0; 8] } + } + + /// Clauses 5.3.1 and 5.3.2 for one sub-frame: the reconstructed residual, which is also pushed + /// into the history. + fn long_term(&mut self, s: &SubFrame) -> [i32; SUBFRAME_SAMPLES] { + let erp = rpe_decode(s); + let mut nr = i32::from(s.lag & 0x7F); + if !(40..=120).contains(&nr) { + nr = self.nrp; + } + self.nrp = nr; + let brp = QLB[usize::from(s.gain & 3)]; + let mut drp = [0i32; SUBFRAME_SAMPLES]; + for k in 0..SUBFRAME_SAMPLES { + // dp[k - nr] with k - nr in -120..=-1 is the history; later samples are this sub-frame's own. + let idx = 120 + k as i32 - nr; + let past = if idx < 120 { self.dp[idx as usize] } else { drp[(idx - 120) as usize] }; + drp[k] = add(erp[k], mult_r(brp, past)); + } + self.dp.copy_within(40.., 0); + self.dp[80..].copy_from_slice(&drp); + drp + } +} + +// ------------------------------------------------------------------------------ the decoder + +#[cfg(feature = "gsm-decode")] +/// A GSM 06.10 decoder. It keeps the filter and long-term state between frames. +#[derive(Clone)] +pub struct Decoder { + synth: Synth, + msr: i32, +} + +#[cfg(feature = "gsm-decode")] +impl Default for Decoder { + fn default() -> Self { + Self::new() + } +} + +#[cfg(feature = "gsm-decode")] +impl Decoder { + /// A decoder in the specification's initial state. + #[must_use] + pub fn new() -> Self { + Self { synth: Synth::new(), msr: 0 } + } + + /// Decode one frame into 160 samples (clause 5.3). + pub fn decode_frame(&mut self, frame: &Frame) -> [i16; FRAME_SAMPLES] { + let cur = decode_lar(&frame.lar); + let mut wt = [0i32; FRAME_SAMPLES]; + for (j, s) in frame.sub.iter().enumerate() { + let drp = self.synth.long_term(s); + wt[j * SUBFRAME_SAMPLES..(j + 1) * SUBFRAME_SAMPLES].copy_from_slice(&drp); + } + let mut sr = [0i32; FRAME_SAMPLES]; + for (seg, &(k0, k1)) in SEGMENTS.iter().enumerate() { + let rrp = reflection(&interpolate(&self.synth.prev_lar, &cur, seg)); + for k in k0..=k1 { + let mut sri = wt[k]; + for i in 1..=8 { + sri = sub(sri, mult_r(rrp[8 - i], self.synth.v[8 - i])); + self.synth.v[9 - i] = add(self.synth.v[8 - i], mult_r(rrp[8 - i], sri)); + } + sr[k] = sri; + self.synth.v[0] = sri; + } + } + self.synth.prev_lar = cur; + let mut out = [0i16; FRAME_SAMPLES]; + for k in 0..FRAME_SAMPLES { + self.msr = add(sr[k], mult_r(self.msr, 28180)); + let up = add(self.msr, self.msr); + out[k] = ((up >> 3) << 3) as i16; + } + out + } +} + +// ------------------------------------------------------------------------------ the encoder + +#[cfg(feature = "gsm-encode")] +/// A GSM 06.10 encoder. It keeps the filter and long-term state between frames. +#[derive(Clone)] +pub struct Encoder { + synth: Synth, + z1: i32, + l_z2: i32, + mp: i32, + /// The short-term analysis filter state. + u: [i32; 8], +} + +#[cfg(feature = "gsm-encode")] +impl Default for Encoder { + fn default() -> Self { + Self::new() + } +} + +#[cfg(feature = "gsm-encode")] +impl Encoder { + /// An encoder in the specification's initial state. + #[must_use] + pub fn new() -> Self { + Self { synth: Synth::new(), z1: 0, l_z2: 0, mp: 0, u: [0; 8] } + } + + /// Clauses 5.2.0 to 5.2.3: scaling, offset compensation and pre-emphasis. + fn preprocess(&mut self, input: &[i16; FRAME_SAMPLES]) -> [i32; FRAME_SAMPLES] { + let mut s = [0i32; FRAME_SAMPLES]; + for k in 0..FRAME_SAMPLES { + let so = (i32::from(input[k]) >> 3) << 2; + let s1 = sub(so, self.z1); + self.z1 = so; + let mut l_s2 = s1 << 15; + let msp = self.l_z2 >> 15; + let lsp = l_sub(self.l_z2, msp << 15); + let temp = mult_r(lsp, 32735); + l_s2 = l_add(l_s2, temp); + self.l_z2 = l_add(l_mult(msp, 32735) >> 1, l_s2); + let sof = w16(l_add(self.l_z2, 16384) >> 15); + s[k] = add(sof, mult_r(self.mp, -28180)); + self.mp = sof; + } + s + } + + /// Clauses 5.2.4 to 5.2.7: the coded log-area ratios of the frame. + fn analyse(s: &[i32; FRAME_SAMPLES]) -> [u8; 8] { + // Autocorrelation, with the signal scaled so the sums cannot overflow. + let smax = s.iter().map(|&x| abs16(x)).max().unwrap_or(0); + let scalauto = if smax == 0 { 0 } else { 4 - norm(smax << 16) }; + let mut sc = *s; + if scalauto > 0 { + let temp = 16384 >> (scalauto - 1); + for x in &mut sc { + *x = mult_r(*x, temp); + } + } + let mut l_acf = [0i32; 9]; + for (k, acf) in l_acf.iter_mut().enumerate() { + for i in k..FRAME_SAMPLES { + *acf = l_add(*acf, l_mult(sc[i], sc[i - k])); + } + } + // Schur recursion for the reflection coefficients. + let mut r = [0i32; 9]; + if l_acf[0] != 0 { + let t = norm(l_acf[0]); + let mut acf = [0i32; 9]; + for k in 0..9 { + acf[k] = w16(l_acf[k].wrapping_shl(t as u32) >> 16); + } + let mut kk = [0i32; 9]; + for i in 1..=7 { + kk[9 - i] = acf[i]; + } + let mut p = acf; + for n in 1..=8 { + if p[0] < abs16(p[1]) { + break; + } + r[n] = div(abs16(p[1]), p[0]); + if p[1] > 0 { + r[n] = sub(0, r[n]); + } + if n == 8 { + break; + } + p[0] = add(p[0], mult_r(p[1], r[n])); + for m in 1..=8 - n { + p[m] = add(p[m + 1], mult_r(kk[9 - m], r[n])); + kk[9 - m] = add(kk[9 - m], mult_r(p[m + 1], r[n])); + } + } + } + // Log-area ratios, quantized and offset to be non-negative. + let mut lar = [0u8; 8]; + for i in 0..8 { + let mut t = abs16(r[i + 1]); + t = if t < 22118 { + t >> 1 + } else if t < 31130 { + sub(t, 11059) + } else { + w16(sub(t, 26112) << 2) + }; + let l = if r[i + 1] < 0 { sub(0, t) } else { t }; + let mut c = add(add(mult(A[i], l), B[i]), 256) >> 9; + c = c.clamp(MIC[i], MAC[i]); + lar[i] = (c - MIC[i]) as u8; + } + lar + } + + /// Encode 160 samples into one frame (clause 5.2). + pub fn encode_frame(&mut self, input: &[i16; FRAME_SAMPLES]) -> Frame { + let s = self.preprocess(input); + let mut frame = Frame { lar: Self::analyse(&s), ..Frame::default() }; + + // Short-term analysis filtering with the quantized coefficients. + let cur = decode_lar(&frame.lar); + let mut d = [0i32; FRAME_SAMPLES]; + for (seg, &(k0, k1)) in SEGMENTS.iter().enumerate() { + let rp = reflection(&interpolate(&self.synth.prev_lar, &cur, seg)); + for k in k0..=k1 { + let mut di = s[k]; + let mut sav = di; + for i in 0..8 { + let temp = add(self.u[i], mult_r(rp[i], di)); + di = add(di, mult_r(rp[i], self.u[i])); + self.u[i] = sav; + sav = temp; + } + d[k] = di; + } + } + self.synth.prev_lar = cur; + + for (j, sub_frame) in frame.sub.iter_mut().enumerate() { + let mut dj = [0i32; SUBFRAME_SAMPLES]; + dj.copy_from_slice(&d[j * SUBFRAME_SAMPLES..(j + 1) * SUBFRAME_SAMPLES]); + *sub_frame = self.code_subframe(&dj); + } + frame + } + + /// Clauses 5.2.11 to 5.2.18 for one sub-frame. + fn code_subframe(&mut self, d: &[i32; SUBFRAME_SAMPLES]) -> SubFrame { + let dp = self.synth.dp; + let hist = |k: usize, lambda: i32| dp[(120 + k as i32 - lambda) as usize]; + + // Long-term lag: the maximum cross-correlation with the reconstructed residual. + let dmax = d.iter().map(|&x| abs16(x)).max().unwrap_or(0); + let mut temp = 0; + let mut scal = 0; + if dmax != 0 { + temp = norm(dmax << 16); + } + if temp <= 6 { + scal = 6 - temp; + } + let mut wt = [0i32; SUBFRAME_SAMPLES]; + for k in 0..SUBFRAME_SAMPLES { + wt[k] = d[k] >> scal; + } + let mut l_max = 0i32; + let mut nc = 40i32; + for lambda in 40..=120 { + let mut l_result = 0i32; + for k in 0..SUBFRAME_SAMPLES { + l_result = l_add(l_result, l_mult(wt[k], hist(k, lambda))); + } + if l_result > l_max { + nc = lambda; + l_max = l_result; + } + } + l_max >>= 6 - scal; + + // Long-term gain. + for k in 0..SUBFRAME_SAMPLES { + wt[k] = hist(k, nc) >> 3; + } + let mut l_power = 0i32; + for k in 0..SUBFRAME_SAMPLES { + l_power = l_add(l_power, l_mult(wt[k], wt[k])); + } + let bc = if l_max <= 0 { + 0 + } else if l_max >= l_power { + 3 + } else { + let t = norm(l_power); + let r = w16(l_max.wrapping_shl(t as u32) >> 16); + let s = w16(l_power.wrapping_shl(t as u32) >> 16); + (0..3).find(|&b| r <= mult(s, DLB[b])).unwrap_or(3) + }; + + // Long-term analysis filtering. + let bp = QLB[bc]; + let mut dpp = [0i32; SUBFRAME_SAMPLES]; + let mut e = [0i32; SUBFRAME_SAMPLES]; + for k in 0..SUBFRAME_SAMPLES { + dpp[k] = mult_r(bp, hist(k, nc)); + e[k] = sub(d[k], dpp[k]); + } + + // Weighting filter, RPE grid selection. + let mut w = [0i32; 50]; + w[5..45].copy_from_slice(&e); + let mut x = [0i32; SUBFRAME_SAMPLES]; + for k in 0..SUBFRAME_SAMPLES { + let mut l_result = 8192i32; + for i in 0..11 { + l_result = l_add(l_result, l_mult(w[k + i], H[i])); + } + l_result = l_add(l_result, l_result); + l_result = l_add(l_result, l_result); + x[k] = l_result >> 16; + } + let mut em = 0i32; + let mut mc = 0usize; + for m in 0..4 { + let mut l_result = 0i32; + for i in 0..13 { + let t = x[m + 3 * i] >> 2; + l_result = l_add(l_result, l_mult(t, t)); + } + if l_result > em { + mc = m; + em = l_result; + } + } + let mut xm = [0i32; 13]; + for i in 0..13 { + xm[i] = x[mc + 3 * i]; + } + + // APCM quantization. + let xmax = xm.iter().map(|&v| abs16(v)).max().unwrap_or(0); + let mut exp = 0; + let mut t = xmax >> 9; + let mut itest = false; + for _ in 0..=5 { + if t <= 0 { + itest = true; + } + t >>= 1; + if !itest { + exp += 1; + } + } + let xmaxc = add(xmax >> (exp + 5), exp << 3); + let (exp, mant) = exp_mant(xmaxc); + let temp1 = 6 - exp; + let temp2 = NRFAC[mant as usize & 7]; + let mut pulses = [0u8; 13]; + for i in 0..13 { + let t = w16(asl(xm[i], temp1)); + let t = mult(t, temp2); + pulses[i] = (add(t >> 12, 4)).clamp(0, 7) as u8; + } + let coded = SubFrame { lag: nc as u8, gain: bc as u8, grid: mc as u8, xmax: xmaxc.clamp(0, 63) as u8, pulses }; + + // Reconstruct, exactly as the decoder will, to keep the history in step. + let ep = rpe_decode(&coded); + self.synth.dp.copy_within(40.., 0); + for k in 0..SUBFRAME_SAMPLES { + self.synth.dp[80 + k] = add(ep[k], dpp[k]); + } + coded + } +} + +// --------------------------------------------------------------------------------- streams + +#[cfg(feature = "gsm-decode")] +/// Decode a stream of whole blocks into 8 kHz samples. A [`Packing::Raw`] stream is checked for the +/// signature nibble of every frame. +pub fn decode(data: &[u8], packing: Packing) -> Result, Error> { + let block = packing.block_bytes(); + if !data.len().is_multiple_of(block) { + return Err(Error::Truncated { block, len: data.len() }); + } + let mut dec = Decoder::new(); + let mut out = Vec::with_capacity(data.len() / block * packing.block_samples()); + for (n, chunk) in data.chunks_exact(block).enumerate() { + match packing { + Packing::Raw => { + let mut b = [0u8; RAW_FRAME_BYTES]; + b.copy_from_slice(chunk); + let frame = Frame::from_raw(&b).map_err(|_| Error::BadSignature { offset: n * block })?; + out.extend_from_slice(&dec.decode_frame(&frame)); + } + Packing::Wav49 => { + let mut b = [0u8; WAV49_BLOCK_BYTES]; + b.copy_from_slice(chunk); + for frame in Frame::pair_from_wav49(&b) { + out.extend_from_slice(&dec.decode_frame(&frame)); + } + } + } + } + Ok(out) +} + +#[cfg(feature = "gsm-encode")] +/// Encode 8 kHz samples. The last block is padded with silence to a whole block, so the output +/// decodes to `samples.len()` rounded up to a block, with the first `samples.len()` as the signal. +#[must_use] +pub fn encode(samples: &[i16], packing: Packing) -> Vec { + let per_block = packing.block_samples(); + let mut enc = Encoder::new(); + let mut out = Vec::with_capacity(samples.len().div_ceil(per_block) * packing.block_bytes()); + for chunk in samples.chunks(per_block) { + let mut padded = [0i16; 2 * FRAME_SAMPLES]; + padded[..chunk.len()].copy_from_slice(chunk); + let mut frame = |at: usize| { + let mut input = [0i16; FRAME_SAMPLES]; + input.copy_from_slice(&padded[at..at + FRAME_SAMPLES]); + enc.encode_frame(&input) + }; + match packing { + Packing::Raw => out.extend_from_slice(&frame(0).to_raw()), + Packing::Wav49 => { + let a = frame(0); + let b = frame(FRAME_SAMPLES); + out.extend_from_slice(&Frame::pair_to_wav49(&a, &b)); + } + } + } + out +} + +#[cfg(all(test, feature = "gsm-decode", feature = "gsm-encode"))] +mod tests { + use super::*; + + fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed + } + + fn speechlike(n: usize) -> Vec { + let mut seed = 0x1234_5678u32; + (0..n) + .map(|i| { + let t = i as f64 / 8000.0; + let f0 = 120.0 + 30.0 * (t * 3.0).sin(); + let v = (t * f0 * std::f64::consts::TAU).sin() * 6000.0 + + (t * 3.0 * f0 * std::f64::consts::TAU).sin() * 2500.0 + + f64::from(xorshift(&mut seed) % 400) + - 200.0; + (v * (0.6 + 0.4 * (t * 5.0).sin())) as i16 + }) + .collect() + } + + #[test] + fn arithmetic_matches_the_specification() { + assert_eq!(add(32767, 1), 32767); + assert_eq!(sub(-32768, 1), -32768); + assert_eq!(mult(-32768, -32768), 32767); + assert_eq!(mult_r(-32768, -32768), 32767); + assert_eq!(mult_r(16384, 16384), 8192); + assert_eq!(abs16(-32768), 32767); + assert_eq!(div(5, 5), 32767); + assert_eq!(div(1, 2), 16384); + assert_eq!(norm(1), 30); + assert_eq!(norm(0x4000_0000), 0); + assert_eq!(norm(-1), 31); + assert_eq!(norm(i32::MIN), 0); + assert_eq!(asl(1, -1), 0); + assert_eq!(asr(-8, 1), -4); + assert_eq!(l_mult(-32768, -32768), i32::MAX); + } + + #[test] + fn raw_packing_round_trips_every_field() { + let mut seed = 99u32; + for _ in 0..200 { + let mut v = [0u8; PARAMS]; + for (i, x) in v.iter_mut().enumerate() { + *x = (xorshift(&mut seed) & ((1 << field_bits(i)) - 1)) as u8; + } + let frame = Frame::from_values(&v); + let raw = frame.to_raw(); + assert_eq!(raw[0] >> 4, 0xD); + assert_eq!(Frame::from_raw(&raw), Ok(frame)); + let pair = Frame::pair_to_wav49(&frame, &Frame::default()); + assert_eq!(Frame::pair_from_wav49(&pair), [frame, Frame::default()]); + let pair = Frame::pair_to_wav49(&Frame::default(), &frame); + assert_eq!(Frame::pair_from_wav49(&pair)[1], frame); + } + assert_eq!((0..PARAMS).map(field_bits).sum::(), 260); + } + + #[test] + fn a_raw_frame_needs_its_signature() { + let mut raw = Frame::default().to_raw(); + raw[0] = 0x30; + assert_eq!(Frame::from_raw(&raw), Err(Error::BadSignature { offset: 0 })); + assert_eq!(decode(&raw, Packing::Raw), Err(Error::BadSignature { offset: 0 })); + } + + #[test] + fn partial_blocks_are_rejected() { + assert_eq!(decode(&[0xD0; 32], Packing::Raw), Err(Error::Truncated { block: 33, len: 32 })); + assert_eq!(decode(&[0; 66], Packing::Wav49), Err(Error::Truncated { block: 65, len: 66 })); + assert_eq!(decode(&[], Packing::Raw), Ok(vec![])); + } + + #[test] + fn silence_stays_near_silence() { + let pcm = vec![0i16; 160 * 4]; + for packing in [Packing::Raw, Packing::Wav49] { + let bytes = encode(&pcm, packing); + let out = decode(&bytes, packing).expect("decode"); + assert_eq!(out.len(), pcm.len()); + // The quantizers have no exact zero, so silence comes back as a faint residue. + assert!(out.iter().all(|&s| s.abs() <= 32), "{packing:?}: {:?}", out.iter().map(|s| s.abs()).max()); + } + } + + #[test] + fn output_has_three_clear_low_bits() { + let out = decode(&encode(&speechlike(1600), Packing::Raw), Packing::Raw).expect("decode"); + assert!(out.iter().all(|&s| s & 7 == 0)); + } + + #[test] + fn speech_survives_the_round_trip() { + let pcm = speechlike(8000); + for packing in [Packing::Raw, Packing::Wav49] { + let out = decode(&encode(&pcm, packing), packing).expect("decode"); + assert_eq!(out.len(), pcm.len()); + let (mut sig, mut err) = (0f64, 0f64); + for i in 400..pcm.len() { + let (a, b) = (f64::from(pcm[i]), f64::from(out[i])); + sig += a * a; + err += (a - b) * (a - b); + } + let snr = 10.0 * (sig / err).log10(); + assert!(snr > 8.0, "{packing:?}: SNR {snr:.1} dB"); + } + } + + #[test] + fn encoding_is_deterministic_and_packings_agree() { + let pcm = speechlike(1600); + assert_eq!(encode(&pcm, Packing::Raw), encode(&pcm, Packing::Raw)); + let raw = decode(&encode(&pcm, Packing::Raw), Packing::Raw).expect("raw"); + let wav = decode(&encode(&pcm, Packing::Wav49), Packing::Wav49).expect("wav49"); + assert_eq!(raw, wav); + } + + #[test] + fn short_input_is_padded_to_a_block() { + assert_eq!(encode(&[], Packing::Raw), Vec::::new()); + assert_eq!(encode(&[100; 1], Packing::Raw).len(), 33); + assert_eq!(encode(&[100; 161], Packing::Raw).len(), 66); + assert_eq!(encode(&[100; 1], Packing::Wav49).len(), 65); + assert_eq!(encode(&[100; 321], Packing::Wav49).len(), 130); + } + + #[test] + fn any_bits_decode_without_panicking() { + let mut seed = 7u32; + for _ in 0..300 { + let mut v = [0u8; PARAMS]; + for x in &mut v { + // Fields wider than their width and lags outside 40..=120 must be tolerated. + *x = xorshift(&mut seed) as u8; + } + let frame = Frame::from_values(&v); + let mut dec = Decoder::new(); + for _ in 0..3 { + let _ = dec.decode_frame(&frame); + } + } + } + + #[test] + fn extreme_input_encodes_without_panicking() { + for pattern in [i16::MAX, i16::MIN] { + let pcm = vec![pattern; 1600]; + let out = decode(&encode(&pcm, Packing::Raw), Packing::Raw).expect("decode"); + assert_eq!(out.len(), 1600); + } + let alternating: Vec = (0..3200).map(|i| if i % 2 == 0 { i16::MAX } else { i16::MIN }).collect(); + let _ = encode(&alternating, Packing::Wav49); + let mut seed = 5u32; + let noise: Vec = (0..3200).map(|_| xorshift(&mut seed) as i16).collect(); + let _ = encode(&noise, Packing::Raw); + } + + #[test] + fn a_decoder_keeps_state_between_frames() { + let bytes = encode(&speechlike(1600), Packing::Raw); + let whole = decode(&bytes, Packing::Raw).expect("whole"); + let mut dec = Decoder::new(); + let mut piecewise = Vec::new(); + for b in bytes.as_chunks::<33>().0 { + piecewise.extend_from_slice(&dec.decode_frame(&Frame::from_raw(b).expect("frame"))); + } + assert_eq!(whole, piecewise); + } +} diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index e4a1c1695..3a9cecd38 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -30,7 +30,8 @@ //! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and //! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`] //! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-decode`: the frame and file decoder; -//! `flac-encode`: the packet encoder), [`qoa`] (`qoa-decode`, `qoa-encode`: whole QOA files). +//! `flac-encode`: the packet encoder), [`qoa`] (`qoa-decode`, `qoa-encode`: whole QOA files), +//! [`gsm`] (`gsm-decode`, `gsm-encode`: GSM 06.10 full-rate speech). //! //! The shared types below build with no features. @@ -41,6 +42,8 @@ pub mod ac3; #[cfg(any(feature = "alac-decode", feature = "alac-encode"))] pub mod alac; mod buffer; +#[cfg(any(feature = "gsm-decode", feature = "gsm-encode"))] +pub mod gsm; mod layout; #[cfg(any(feature = "mp3-encode", feature = "mp3-decode"))] pub mod mp3; diff --git a/crates/audio/tests/gsm_oracle.rs b/crates/audio/tests/gsm_oracle.rs new file mode 100644 index 000000000..ec9c2f799 --- /dev/null +++ b/crates/audio/tests/gsm_oracle.rs @@ -0,0 +1,138 @@ +//! GSM 06.10 against ffmpeg's decoder as the reference (oracle; skipped when ffmpeg is absent, a +//! failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`): ffmpeg decodes what our encoder writes, in both +//! packings, to exactly the samples our decoder returns, and so does arbitrary frame data. + +use craft_audio::gsm::{Packing, decode, encode}; +use std::path::Path; +use std::process::Command; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +fn signal(frames: usize) -> Vec { + let mut seed = 0x9E37_79B9u32; + (0..frames * 160) + .map(|i| { + let t = i as f64 / 8000.0; + let f0 = 110.0 + 40.0 * (t * 2.0).sin(); + let voiced = (t * f0 * std::f64::consts::TAU).sin() * 7000.0 + (t * 4.0 * f0 * std::f64::consts::TAU).sin() * 2000.0; + let noise = f64::from(xorshift(&mut seed) % 3000) - 1500.0; + // Voiced stretches, noise bursts, silence and full-scale clipping. + match (i / 1600) % 5 { + 0 | 1 => voiced as i16, + 2 => noise as i16, + 3 => 0, + _ => (voiced * 6.0).clamp(-32768.0, 32767.0) as i16, + } + }) + .collect() +} + +fn wav49_file(blocks: &[u8], samples: usize) -> Vec { + let mut fmt = Vec::new(); + fmt.extend_from_slice(&0x31u16.to_le_bytes()); // GSM 6.10 + fmt.extend_from_slice(&1u16.to_le_bytes()); + fmt.extend_from_slice(&8000u32.to_le_bytes()); + fmt.extend_from_slice(&1625u32.to_le_bytes()); + fmt.extend_from_slice(&65u16.to_le_bytes()); + fmt.extend_from_slice(&0u16.to_le_bytes()); + fmt.extend_from_slice(&2u16.to_le_bytes()); + fmt.extend_from_slice(&320u16.to_le_bytes()); + let mut body = b"WAVE".to_vec(); + body.extend_from_slice(b"fmt "); + body.extend_from_slice(&(fmt.len() as u32).to_le_bytes()); + body.extend_from_slice(&fmt); + body.extend_from_slice(b"fact"); + body.extend_from_slice(&4u32.to_le_bytes()); + body.extend_from_slice(&(samples as u32).to_le_bytes()); + body.extend_from_slice(b"data"); + body.extend_from_slice(&(blocks.len() as u32).to_le_bytes()); + body.extend_from_slice(blocks); + let mut out = b"RIFF".to_vec(); + out.extend_from_slice(&(body.len() as u32).to_le_bytes()); + out.extend_from_slice(&body); + out +} + +fn ffmpeg_decode(ffmpeg: &Path, file: &Path, forced_format: Option<&str>) -> Vec { + let mut cmd = Command::new(ffmpeg); + cmd.args(["-v", "error", "-y"]); + if let Some(f) = forced_format { + cmd.args(["-f", f]); + } + let out = cmd.arg("-i").arg(file).args(["-f", "s16le", "-acodec", "pcm_s16le", "-"]).output().expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg failed on {}: {}", file.display(), String::from_utf8_lossy(&out.stderr)); + out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect() +} + +/// Frames whose long-term and RPE fields are arbitrary, over the log-area ratios of real speech. +/// Random log-area ratios give filters that overflow at every sample, where the specification's +/// saturating arithmetic and other decoders' differ; here every field of every sub-frame still +/// takes all of its values, with the amplitude and gain kept where the signal stays in range. +fn random_frames(n: usize, seed: &mut u32) -> Vec { + let speech = encode(&signal(n), Packing::Raw); + let mut out = Vec::new(); + for b in speech.as_chunks::<33>().0 { + let mut frame = craft_audio::gsm::Frame::from_raw(b).expect("frame"); + for s in &mut frame.sub { + s.lag = 40 + (xorshift(seed) % 81) as u8; + s.gain = (xorshift(seed) % 3) as u8; + s.grid = (xorshift(seed) & 3) as u8; + s.xmax = (xorshift(seed) % 26) as u8; + for p in &mut s.pulses { + *p = (xorshift(seed) & 7) as u8; + } + } + out.extend_from_slice(&frame.to_raw()); + } + out +} + +#[test] +fn ffmpeg_decodes_our_raw_streams_to_the_same_samples() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("gsm"); + for frames in [1usize, 2, 7, 50, 120] { + let bytes = encode(&signal(frames), Packing::Raw); + let file = dir.join(format!("ours_{frames}.gsm")); + std::fs::write(&file, &bytes).expect("write fixture"); + let theirs = ffmpeg_decode(&ffmpeg, &file, Some("gsm")); + let ours = decode(&bytes, Packing::Raw).expect("decode"); + assert_eq!(theirs.len(), ours.len(), "{frames} frames: sample count"); + assert!(theirs == ours, "{frames} frames: samples differ"); + } +} + +#[test] +fn ffmpeg_decodes_our_wav49_streams_to_the_same_samples() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("gsm"); + for frames in [2usize, 4, 20, 100] { + let pcm = signal(frames); + let bytes = encode(&pcm, Packing::Wav49); + let file = dir.join(format!("ours_{frames}.wav")); + std::fs::write(&file, wav49_file(&bytes, pcm.len())).expect("write fixture"); + let theirs = ffmpeg_decode(&ffmpeg, &file, None); + let ours = decode(&bytes, Packing::Wav49).expect("decode"); + assert_eq!(theirs.len(), ours.len(), "{frames} frames: sample count"); + assert!(theirs == ours, "{frames} frames: samples differ"); + } +} + +#[test] +fn ffmpeg_and_we_decode_arbitrary_frames_identically() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("gsm"); + let mut seed = 0xC0FF_EE11u32; + let bytes = random_frames(300, &mut seed); + let file = dir.join("random.gsm"); + std::fs::write(&file, &bytes).expect("write fixture"); + let theirs = ffmpeg_decode(&ffmpeg, &file, Some("gsm")); + let ours = decode(&bytes, Packing::Raw).expect("decode"); + assert_eq!(theirs.len(), ours.len()); + assert!(theirs == ours, "arbitrary frames decode differently"); +} From d09d31c109e64157de28220d6148d6aa985daf7d Mon Sep 17 00:00:00 2001 From: el-j Date: Tue, 17 Nov 2026 03:30:36 +0100 Subject: [PATCH 23/64] craft-audio: Bluetooth Low Complexity Subband Coding (SBC) audio codec (#1537) (#1839) --- crates/audio/Cargo.toml | 6 + crates/audio/src/lib.rs | 2 + crates/audio/src/sbc.rs | 1999 ++++++++++++++++++++++++++++++ crates/audio/tests/sbc_oracle.rs | 298 +++++ 4 files changed, 2305 insertions(+) create mode 100644 crates/audio/src/sbc.rs create mode 100644 crates/audio/tests/sbc_oracle.rs diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index 22f012011..607fb00b9 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -62,6 +62,8 @@ ac3-encode = ["craft-media/bitstream"] eac3-encode = ["craft-media/bitstream"] # MPEG-1/2 Layer III (MP3) encoder (`mp3`). mp3-encode = ["craft-media/bitstream"] +# Bluetooth Low Complexity Subband Coding (SBC) audio codec (`sbc`). +sbc = [] # Multi-resolution waveform overviews (`peaks`). peaks = [] # Encode AAC channels in parallel (with `aac-encode`). @@ -104,6 +106,10 @@ required-features = ["gsm"] name = "qoa_oracle" required-features = ["qoa"] +[[test]] +name = "sbc_oracle" +required-features = ["sbc"] + [[example]] name = "info" required-features = ["decode"] diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 3a9cecd38..8aa3af36d 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -59,6 +59,8 @@ pub mod peaks; pub mod qoa; #[cfg(feature = "decode-native")] mod read; +#[cfg(feature = "sbc")] +pub mod sbc; #[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))] mod track; #[cfg(feature = "vorbis-encode")] diff --git a/crates/audio/src/sbc.rs b/crates/audio/src/sbc.rs new file mode 100644 index 000000000..35165e966 --- /dev/null +++ b/crates/audio/src/sbc.rs @@ -0,0 +1,1999 @@ +//! Bluetooth Low Complexity Subband Coding (SBC) audio codec. +//! +//! Clean-room implementation based on Bluetooth SIG Advanced Audio Distribution Profile +//! (A2DP) Specification v1.3, Appendix B (Section 12: "Technical Specification of SBC") +//! and Hands-Free Profile (HFP 1.6) mSBC specification. +//! +//! SBC is a subband codec designed to deliver audio quality with low computational +//! complexity, operating at 16 kHz, 32 kHz, 44.1 kHz, or 48 kHz in Mono, Dual Channel, +//! Stereo, or Joint Stereo configurations with 4 or 8 subbands. + +#![allow(clippy::excessive_precision, clippy::needless_range_loop, clippy::cognitive_complexity, clippy::too_many_arguments)] + +const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024; +const MAX_SAMPLES: usize = 64 * 1024 * 1024; + +/// Standard SBC syncword byte (`0x9C`). +pub const SYNCWORD_SBC: u8 = 0x9C; +/// mSBC wideband speech syncword byte (`0xAD`). +pub const SYNCWORD_MSBC: u8 = 0xAD; + +/// Offset table for 4 subbands loudness bit allocation (Table 12.21). +pub static OFFSET4: [[i8; 4]; 4] = [[-1, 0, 0, 0], [-2, 0, 0, 1], [-2, 0, 0, 1], [-2, 0, 0, 1]]; + +/// Offset table for 8 subbands loudness bit allocation (Table 12.22). +pub static OFFSET8: [[i8; 8]; 4] = [[-2, 0, 0, 0, 0, 0, 0, 1], [-3, 0, 0, 0, 0, 0, 1, 2], [-4, 0, 0, 0, 0, 0, 1, 2], [-4, 0, 0, 0, 0, 0, 1, 2]]; + +/// Analysis and synthesis filter coefficients for 4 subbands (Table 12.23). +pub(crate) static PROTO_4_40: [f32; 40] = [ + 0.0000000000e+00_f32, + 5.3654897600e-04_f32, + 1.4918835700e-03_f32, + 2.7337090400e-03_f32, + 3.8372019300e-03_f32, + 3.8920514900e-03_f32, + 1.8658169100e-03_f32, + -3.0601228600e-03_f32, + 1.0913762000e-02_f32, + 2.0438508700e-02_f32, + 2.8875739200e-02_f32, + 3.2193929000e-02_f32, + 2.5876781100e-02_f32, + 6.1324518600e-03_f32, + -2.8821727400e-02_f32, + -7.7646349400e-02_f32, + 1.3559327400e-01_f32, + 1.9498784100e-01_f32, + 2.4663666200e-01_f32, + 2.8182820300e-01_f32, + 2.9431533200e-01_f32, + 2.8182820300e-01_f32, + 2.4663666200e-01_f32, + 1.9498784100e-01_f32, + -1.3559327400e-01_f32, + -7.7646349400e-02_f32, + -2.8821727400e-02_f32, + 6.1324518600e-03_f32, + 2.5876781100e-02_f32, + 3.2193929000e-02_f32, + 2.8875739200e-02_f32, + 2.0438508700e-02_f32, + -1.0913762000e-02_f32, + -3.0601228600e-03_f32, + 1.8658169100e-03_f32, + 3.8920514900e-03_f32, + 3.8372019300e-03_f32, + 2.7337090400e-03_f32, + 1.4918835700e-03_f32, + 5.3654897600e-04_f32, +]; + +/// Analysis and synthesis filter coefficients for 8 subbands (Table 12.24). +pub(crate) static PROTO_8_80: [f32; 80] = [ + 0.0000000000e+00_f32, + 1.5657539800e-04_f32, + 3.4325642500e-04_f32, + 5.5462020200e-04_f32, + 8.2391950600e-04_f32, + 1.1399250700e-03_f32, + 1.4764016900e-03_f32, + 1.7837172500e-03_f32, + 2.0118254200e-03_f32, + 2.1037198900e-03_f32, + 1.9945455400e-03_f32, + 1.6165628300e-03_f32, + 9.0215450200e-04_f32, + -1.7880536100e-04_f32, + -1.6497309800e-03_f32, + -3.4971745400e-03_f32, + 5.6594947300e-03_f32, + 8.0294116300e-03_f32, + 1.0458444300e-02_f32, + 1.2747233500e-02_f32, + 1.4652526300e-02_f32, + 1.5904560300e-02_f32, + 1.6220847100e-02_f32, + 1.5318410600e-02_f32, + 1.2937180600e-02_f32, + 8.8575754000e-03_f32, + 2.9240844200e-03_f32, + -4.9157802400e-03_f32, + -1.4640407600e-02_f32, + -2.6109875200e-02_f32, + -3.9075138100e-02_f32, + -5.3187303200e-02_f32, + 6.7998943100e-02_f32, + 8.2984757800e-02_f32, + 9.7575391800e-02_f32, + 1.1119668900e-01_f32, + 1.2326454800e-01_f32, + 1.3326441500e-01_f32, + 1.4075350500e-01_f32, + 1.4538984700e-01_f32, + 1.4695506800e-01_f32, + 1.4538984700e-01_f32, + 1.4075350500e-01_f32, + 1.3326441500e-01_f32, + 1.2326454800e-01_f32, + 1.1119668900e-01_f32, + 9.7575391800e-02_f32, + 8.2984757800e-02_f32, + -6.7998943100e-02_f32, + -5.3187303200e-02_f32, + -3.9075138100e-02_f32, + -2.6109875200e-02_f32, + -1.4640407600e-02_f32, + -4.9157802400e-03_f32, + 2.9240844200e-03_f32, + 8.8575754000e-03_f32, + 1.2937180600e-02_f32, + 1.5318410600e-02_f32, + 1.6220847100e-02_f32, + 1.5904560300e-02_f32, + 1.4652526300e-02_f32, + 1.2747233500e-02_f32, + 1.0458444300e-02_f32, + 8.0294116300e-03_f32, + -5.6594947300e-03_f32, + -3.4971745400e-03_f32, + -1.6497309800e-03_f32, + -1.7880536100e-04_f32, + 9.0215450200e-04_f32, + 1.6165628300e-03_f32, + 1.9945455400e-03_f32, + 2.1037198900e-03_f32, + 2.0118254200e-03_f32, + 1.7837172500e-03_f32, + 1.4764016900e-03_f32, + 1.1399250700e-03_f32, + 8.2391950600e-04_f32, + 5.5462020200e-04_f32, + 3.4325642500e-04_f32, + 1.5657539800e-04_f32, +]; + +/// Scaled synthesis filter prototype for 4 subbands. +pub(crate) static SYNTH_D_4: [f32; 40] = [ + -0.0000000000e+00_f32, + -2.1461959040e-03_f32, + -5.9675342800e-03_f32, + -1.0934836160e-02_f32, + -1.5348807720e-02_f32, + -1.5568205960e-02_f32, + -7.4632676400e-03_f32, + 1.2240491440e-02_f32, + -4.3655048000e-02_f32, + -8.1754034800e-02_f32, + -1.1550295680e-01_f32, + -1.2877571600e-01_f32, + -1.0350712440e-01_f32, + -2.4529807440e-02_f32, + 1.1528690960e-01_f32, + 3.1058539760e-01_f32, + -5.4237309600e-01_f32, + -7.7995136400e-01_f32, + -9.8654664800e-01_f32, + -1.1273128120e+00_f32, + -1.1772613280e+00_f32, + -1.1273128120e+00_f32, + -9.8654664800e-01_f32, + -7.7995136400e-01_f32, + 5.4237309600e-01_f32, + 3.1058539760e-01_f32, + 1.1528690960e-01_f32, + -2.4529807440e-02_f32, + -1.0350712440e-01_f32, + -1.2877571600e-01_f32, + -1.1550295680e-01_f32, + -8.1754034800e-02_f32, + 4.3655048000e-02_f32, + 1.2240491440e-02_f32, + -7.4632676400e-03_f32, + -1.5568205960e-02_f32, + -1.5348807720e-02_f32, + -1.0934836160e-02_f32, + -5.9675342800e-03_f32, + -2.1461959040e-03_f32, +]; + +/// Scaled synthesis filter prototype for 8 subbands. +pub(crate) static SYNTH_D_8: [f32; 80] = [ + -0.0000000000e+00_f32, + -1.2526031840e-03_f32, + -2.7460514000e-03_f32, + -4.4369616160e-03_f32, + -6.5913560480e-03_f32, + -9.1194005600e-03_f32, + -1.1811213520e-02_f32, + -1.4269738000e-02_f32, + -1.6094603360e-02_f32, + -1.6829759120e-02_f32, + -1.5956364320e-02_f32, + -1.2932502640e-02_f32, + -7.2172360160e-03_f32, + 1.4304428880e-03_f32, + 1.3197847840e-02_f32, + 2.7977396320e-02_f32, + -4.5275957840e-02_f32, + -6.4235293040e-02_f32, + -8.3667554400e-02_f32, + -1.0197786800e-01_f32, + -1.1722021040e-01_f32, + -1.2723648240e-01_f32, + -1.2976677680e-01_f32, + -1.2254728480e-01_f32, + -1.0349744480e-01_f32, + -7.0860603200e-02_f32, + -2.3392675360e-02_f32, + 3.9326241920e-02_f32, + 1.1712326080e-01_f32, + 2.0887900160e-01_f32, + 3.1260110480e-01_f32, + 4.2549842560e-01_f32, + -5.4399154480e-01_f32, + -6.6387806240e-01_f32, + -7.8060313440e-01_f32, + -8.8957351200e-01_f32, + -9.8611638400e-01_f32, + -1.0661153200e+00_f32, + -1.1260280400e+00_f32, + -1.1631187760e+00_f32, + -1.1756405440e+00_f32, + -1.1631187760e+00_f32, + -1.1260280400e+00_f32, + -1.0661153200e+00_f32, + -9.8611638400e-01_f32, + -8.8957351200e-01_f32, + -7.8060313440e-01_f32, + -6.6387806240e-01_f32, + 5.4399154480e-01_f32, + 4.2549842560e-01_f32, + 3.1260110480e-01_f32, + 2.0887900160e-01_f32, + 1.1712326080e-01_f32, + 3.9326241920e-02_f32, + -2.3392675360e-02_f32, + -7.0860603200e-02_f32, + -1.0349744480e-01_f32, + -1.2254728480e-01_f32, + -1.2976677680e-01_f32, + -1.2723648240e-01_f32, + -1.1722021040e-01_f32, + -1.0197786800e-01_f32, + -8.3667554400e-02_f32, + -6.4235293040e-02_f32, + 4.5275957840e-02_f32, + 2.7977396320e-02_f32, + 1.3197847840e-02_f32, + 1.4304428880e-03_f32, + -7.2172360160e-03_f32, + -1.2932502640e-02_f32, + -1.5956364320e-02_f32, + -1.6829759120e-02_f32, + -1.6094603360e-02_f32, + -1.4269738000e-02_f32, + -1.1811213520e-02_f32, + -9.1194005600e-03_f32, + -6.5913560480e-03_f32, + -4.4369616160e-03_f32, + -2.7460514000e-03_f32, + -1.2526031840e-03_f32, +]; + +pub(crate) static SYNTH_COS_4: [[f32; 4]; 8] = [ + [7.0710678119e-01_f32, -7.0710678119e-01_f32, -7.0710678119e-01_f32, 7.0710678119e-01_f32], + [3.8268343237e-01_f32, -9.2387953251e-01_f32, 9.2387953251e-01_f32, -3.8268343237e-01_f32], + [6.1232339957e-17_f32, -1.8369701987e-16_f32, 3.0616169979e-16_f32, -4.2862637970e-16_f32], + [-3.8268343237e-01_f32, 9.2387953251e-01_f32, -9.2387953251e-01_f32, 3.8268343237e-01_f32], + [-7.0710678119e-01_f32, 7.0710678119e-01_f32, 7.0710678119e-01_f32, -7.0710678119e-01_f32], + [-9.2387953251e-01_f32, -3.8268343237e-01_f32, 3.8268343237e-01_f32, 9.2387953251e-01_f32], + [-1.0000000000e+00_f32, -1.0000000000e+00_f32, -1.0000000000e+00_f32, -1.0000000000e+00_f32], + [-9.2387953251e-01_f32, -3.8268343237e-01_f32, 3.8268343237e-01_f32, 9.2387953251e-01_f32], +]; + +pub(crate) static SYNTH_COS_8: [[f32; 8]; 16] = [ + [ + 7.0710678119e-01_f32, + -7.0710678119e-01_f32, + -7.0710678119e-01_f32, + 7.0710678119e-01_f32, + 7.0710678119e-01_f32, + -7.0710678119e-01_f32, + -7.0710678119e-01_f32, + 7.0710678119e-01_f32, + ], + [ + 5.5557023302e-01_f32, + -9.8078528040e-01_f32, + 1.9509032202e-01_f32, + 8.3146961230e-01_f32, + -8.3146961230e-01_f32, + -1.9509032202e-01_f32, + 9.8078528040e-01_f32, + -5.5557023302e-01_f32, + ], + [ + 3.8268343237e-01_f32, + -9.2387953251e-01_f32, + 9.2387953251e-01_f32, + -3.8268343237e-01_f32, + -3.8268343237e-01_f32, + 9.2387953251e-01_f32, + -9.2387953251e-01_f32, + 3.8268343237e-01_f32, + ], + [ + 1.9509032202e-01_f32, + -5.5557023302e-01_f32, + 8.3146961230e-01_f32, + -9.8078528040e-01_f32, + 9.8078528040e-01_f32, + -8.3146961230e-01_f32, + 5.5557023302e-01_f32, + -1.9509032202e-01_f32, + ], + [ + 6.1232339957e-17_f32, + -1.8369701987e-16_f32, + 3.0616169979e-16_f32, + -4.2862637970e-16_f32, + 5.5109105962e-16_f32, + -2.4499125789e-15_f32, + -9.8033641995e-16_f32, + -2.6948419388e-15_f32, + ], + [ + -1.9509032202e-01_f32, + 5.5557023302e-01_f32, + -8.3146961230e-01_f32, + 9.8078528040e-01_f32, + -9.8078528040e-01_f32, + 8.3146961230e-01_f32, + -5.5557023302e-01_f32, + 1.9509032202e-01_f32, + ], + [ + -3.8268343237e-01_f32, + 9.2387953251e-01_f32, + -9.2387953251e-01_f32, + 3.8268343237e-01_f32, + 3.8268343237e-01_f32, + -9.2387953251e-01_f32, + 9.2387953251e-01_f32, + -3.8268343237e-01_f32, + ], + [ + -5.5557023302e-01_f32, + 9.8078528040e-01_f32, + -1.9509032202e-01_f32, + -8.3146961230e-01_f32, + 8.3146961230e-01_f32, + 1.9509032202e-01_f32, + -9.8078528040e-01_f32, + 5.5557023302e-01_f32, + ], + [ + -7.0710678119e-01_f32, + 7.0710678119e-01_f32, + 7.0710678119e-01_f32, + -7.0710678119e-01_f32, + -7.0710678119e-01_f32, + 7.0710678119e-01_f32, + 7.0710678119e-01_f32, + -7.0710678119e-01_f32, + ], + [ + -8.3146961230e-01_f32, + 1.9509032202e-01_f32, + 9.8078528040e-01_f32, + 5.5557023302e-01_f32, + -5.5557023302e-01_f32, + -9.8078528040e-01_f32, + -1.9509032202e-01_f32, + 8.3146961230e-01_f32, + ], + [ + -9.2387953251e-01_f32, + -3.8268343237e-01_f32, + 3.8268343237e-01_f32, + 9.2387953251e-01_f32, + 9.2387953251e-01_f32, + 3.8268343237e-01_f32, + -3.8268343237e-01_f32, + -9.2387953251e-01_f32, + ], + [ + -9.8078528040e-01_f32, + -8.3146961230e-01_f32, + -5.5557023302e-01_f32, + -1.9509032202e-01_f32, + 1.9509032202e-01_f32, + 5.5557023302e-01_f32, + 8.3146961230e-01_f32, + 9.8078528040e-01_f32, + ], + [ + -1.0000000000e+00_f32, + -1.0000000000e+00_f32, + -1.0000000000e+00_f32, + -1.0000000000e+00_f32, + -1.0000000000e+00_f32, + -1.0000000000e+00_f32, + -1.0000000000e+00_f32, + -1.0000000000e+00_f32, + ], + [ + -9.8078528040e-01_f32, + -8.3146961230e-01_f32, + -5.5557023302e-01_f32, + -1.9509032202e-01_f32, + 1.9509032202e-01_f32, + 5.5557023302e-01_f32, + 8.3146961230e-01_f32, + 9.8078528040e-01_f32, + ], + [ + -9.2387953251e-01_f32, + -3.8268343237e-01_f32, + 3.8268343237e-01_f32, + 9.2387953251e-01_f32, + 9.2387953251e-01_f32, + 3.8268343237e-01_f32, + -3.8268343237e-01_f32, + -9.2387953251e-01_f32, + ], + [ + -8.3146961230e-01_f32, + 1.9509032202e-01_f32, + 9.8078528040e-01_f32, + 5.5557023302e-01_f32, + -5.5557023302e-01_f32, + -9.8078528040e-01_f32, + -1.9509032202e-01_f32, + 8.3146961230e-01_f32, + ], +]; + +pub(crate) static ANALYSIS_COS_4: [[f32; 8]; 4] = [ + [ + 7.0710678119e-01_f32, + 9.2387953251e-01_f32, + 1.0000000000e+00_f32, + 9.2387953251e-01_f32, + 7.0710678119e-01_f32, + 3.8268343237e-01_f32, + 6.1232339957e-17_f32, + -3.8268343237e-01_f32, + ], + [ + -7.0710678119e-01_f32, + 3.8268343237e-01_f32, + 1.0000000000e+00_f32, + 3.8268343237e-01_f32, + -7.0710678119e-01_f32, + -9.2387953251e-01_f32, + -1.8369701987e-16_f32, + 9.2387953251e-01_f32, + ], + [ + -7.0710678119e-01_f32, + -3.8268343237e-01_f32, + 1.0000000000e+00_f32, + -3.8268343237e-01_f32, + -7.0710678119e-01_f32, + 9.2387953251e-01_f32, + 3.0616169979e-16_f32, + -9.2387953251e-01_f32, + ], + [ + 7.0710678119e-01_f32, + -9.2387953251e-01_f32, + 1.0000000000e+00_f32, + -9.2387953251e-01_f32, + 7.0710678119e-01_f32, + -3.8268343237e-01_f32, + -4.2862637970e-16_f32, + 3.8268343237e-01_f32, + ], +]; + +pub(crate) static ANALYSIS_COS_8: [[f32; 16]; 8] = [ + [ + 7.0710678119e-01_f32, + 8.3146961230e-01_f32, + 9.2387953251e-01_f32, + 9.8078528040e-01_f32, + 1.0000000000e+00_f32, + 9.8078528040e-01_f32, + 9.2387953251e-01_f32, + 8.3146961230e-01_f32, + 7.0710678119e-01_f32, + 5.5557023302e-01_f32, + 3.8268343237e-01_f32, + 1.9509032202e-01_f32, + 6.1232339957e-17_f32, + -1.9509032202e-01_f32, + -3.8268343237e-01_f32, + -5.5557023302e-01_f32, + ], + [ + -7.0710678119e-01_f32, + -1.9509032202e-01_f32, + 3.8268343237e-01_f32, + 8.3146961230e-01_f32, + 1.0000000000e+00_f32, + 8.3146961230e-01_f32, + 3.8268343237e-01_f32, + -1.9509032202e-01_f32, + -7.0710678119e-01_f32, + -9.8078528040e-01_f32, + -9.2387953251e-01_f32, + -5.5557023302e-01_f32, + -1.8369701987e-16_f32, + 5.5557023302e-01_f32, + 9.2387953251e-01_f32, + 9.8078528040e-01_f32, + ], + [ + -7.0710678119e-01_f32, + -9.8078528040e-01_f32, + -3.8268343237e-01_f32, + 5.5557023302e-01_f32, + 1.0000000000e+00_f32, + 5.5557023302e-01_f32, + -3.8268343237e-01_f32, + -9.8078528040e-01_f32, + -7.0710678119e-01_f32, + 1.9509032202e-01_f32, + 9.2387953251e-01_f32, + 8.3146961230e-01_f32, + 3.0616169979e-16_f32, + -8.3146961230e-01_f32, + -9.2387953251e-01_f32, + -1.9509032202e-01_f32, + ], + [ + 7.0710678119e-01_f32, + -5.5557023302e-01_f32, + -9.2387953251e-01_f32, + 1.9509032202e-01_f32, + 1.0000000000e+00_f32, + 1.9509032202e-01_f32, + -9.2387953251e-01_f32, + -5.5557023302e-01_f32, + 7.0710678119e-01_f32, + 8.3146961230e-01_f32, + -3.8268343237e-01_f32, + -9.8078528040e-01_f32, + -4.2862637970e-16_f32, + 9.8078528040e-01_f32, + 3.8268343237e-01_f32, + -8.3146961230e-01_f32, + ], + [ + 7.0710678119e-01_f32, + 5.5557023302e-01_f32, + -9.2387953251e-01_f32, + -1.9509032202e-01_f32, + 1.0000000000e+00_f32, + -1.9509032202e-01_f32, + -9.2387953251e-01_f32, + 5.5557023302e-01_f32, + 7.0710678119e-01_f32, + -8.3146961230e-01_f32, + -3.8268343237e-01_f32, + 9.8078528040e-01_f32, + 5.5109105962e-16_f32, + -9.8078528040e-01_f32, + 3.8268343237e-01_f32, + 8.3146961230e-01_f32, + ], + [ + -7.0710678119e-01_f32, + 9.8078528040e-01_f32, + -3.8268343237e-01_f32, + -5.5557023302e-01_f32, + 1.0000000000e+00_f32, + -5.5557023302e-01_f32, + -3.8268343237e-01_f32, + 9.8078528040e-01_f32, + -7.0710678119e-01_f32, + -1.9509032202e-01_f32, + 9.2387953251e-01_f32, + -8.3146961230e-01_f32, + -2.4499125789e-15_f32, + 8.3146961230e-01_f32, + -9.2387953251e-01_f32, + 1.9509032202e-01_f32, + ], + [ + -7.0710678119e-01_f32, + 1.9509032202e-01_f32, + 3.8268343237e-01_f32, + -8.3146961230e-01_f32, + 1.0000000000e+00_f32, + -8.3146961230e-01_f32, + 3.8268343237e-01_f32, + 1.9509032202e-01_f32, + -7.0710678119e-01_f32, + 9.8078528040e-01_f32, + -9.2387953251e-01_f32, + 5.5557023302e-01_f32, + -9.8033641995e-16_f32, + -5.5557023302e-01_f32, + 9.2387953251e-01_f32, + -9.8078528040e-01_f32, + ], + [ + 7.0710678119e-01_f32, + -8.3146961230e-01_f32, + 9.2387953251e-01_f32, + -9.8078528040e-01_f32, + 1.0000000000e+00_f32, + -9.8078528040e-01_f32, + 9.2387953251e-01_f32, + -8.3146961230e-01_f32, + 7.0710678119e-01_f32, + -5.5557023302e-01_f32, + 3.8268343237e-01_f32, + -1.9509032202e-01_f32, + -2.6948419388e-15_f32, + 1.9509032202e-01_f32, + -3.8268343237e-01_f32, + 5.5557023302e-01_f32, + ], +]; + +/// Sampling frequency of the SBC bitstream. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum SamplingFrequency { + /// 16 000 Hz + Freq16k, + /// 32 000 Hz + Freq32k, + /// 44 100 Hz + Freq44k1, + /// 48 000 Hz + Freq48k, +} + +impl SamplingFrequency { + /// Returns sampling frequency in Hz. + #[inline] + #[must_use] + pub const fn as_hz(self) -> u32 { + match self { + Self::Freq16k => 16_000, + Self::Freq32k => 32_000, + Self::Freq44k1 => 44_100, + Self::Freq48k => 48_000, + } + } + + /// Derives sampling frequency from Hz. + pub fn from_hz(hz: u32) -> Result { + match hz { + 16_000 => Ok(Self::Freq16k), + 32_000 => Ok(Self::Freq32k), + 44_100 => Ok(Self::Freq44k1), + 48_000 => Ok(Self::Freq48k), + _ => Err(Error::InvalidSampleRate(hz)), + } + } + + /// Returns the 2-bit header code. + #[inline] + #[must_use] + pub const fn code(self) -> u8 { + match self { + Self::Freq16k => 0b00, + Self::Freq32k => 0b01, + Self::Freq44k1 => 0b10, + Self::Freq48k => 0b11, + } + } + + /// Index into offset tables (0 to 3). + #[inline] + #[must_use] + pub const fn table_index(self) -> usize { + match self { + Self::Freq16k => 0, + Self::Freq32k => 1, + Self::Freq44k1 => 2, + Self::Freq48k => 3, + } + } +} + +/// Number of blocks per SBC frame. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum BlockCount { + /// 4 blocks + Blocks4, + /// 8 blocks + Blocks8, + /// 12 blocks + Blocks12, + /// 16 blocks + Blocks16, + /// 15 blocks (mSBC wideband speech) + Blocks15, +} + +impl BlockCount { + /// Returns integer block count. + #[inline] + #[must_use] + pub const fn count(self) -> usize { + match self { + Self::Blocks4 => 4, + Self::Blocks8 => 8, + Self::Blocks12 => 12, + Self::Blocks16 => 16, + Self::Blocks15 => 15, + } + } + + /// Derives block count from integer. + pub fn from_count(count: usize) -> Result { + match count { + 4 => Ok(Self::Blocks4), + 8 => Ok(Self::Blocks8), + 12 => Ok(Self::Blocks12), + 16 => Ok(Self::Blocks16), + 15 => Ok(Self::Blocks15), + _ => Err(Error::InvalidBlockCount(count)), + } + } + + /// Returns 2-bit header code. + #[inline] + #[must_use] + pub const fn code(self) -> u8 { + match self { + Self::Blocks4 => 0b00, + Self::Blocks8 => 0b01, + Self::Blocks12 => 0b10, + Self::Blocks16 | Self::Blocks15 => 0b11, + } + } +} + +/// Channel mode of the SBC bitstream. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ChannelMode { + /// 1 channel (Mono) + Mono, + /// 2 channels with independent bit allocation + DualChannel, + /// 2 channels with shared bit allocation + Stereo, + /// 2 channels with shared bit allocation and joint mid/side subbands + JointStereo, +} + +impl ChannelMode { + /// Returns number of audio channels. + #[inline] + #[must_use] + pub const fn channels(self) -> usize { + match self { + Self::Mono => 1, + Self::DualChannel | Self::Stereo | Self::JointStereo => 2, + } + } + + /// Returns 2-bit header code. + #[inline] + #[must_use] + pub const fn code(self) -> u8 { + match self { + Self::Mono => 0b00, + Self::DualChannel => 0b01, + Self::Stereo => 0b10, + Self::JointStereo => 0b11, + } + } +} + +/// Bit allocation method. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum AllocationMethod { + /// Psychoacoustic loudness allocation + #[default] + Loudness, + /// Signal-to-noise ratio allocation + Snr, +} + +impl AllocationMethod { + /// Returns 1-bit header code. + #[inline] + #[must_use] + pub const fn code(self) -> u8 { + match self { + Self::Loudness => 0, + Self::Snr => 1, + } + } +} + +/// Number of subbands. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Subbands { + /// 4 subbands + Subbands4, + /// 8 subbands + Subbands8, +} + +impl Subbands { + /// Returns number of subbands as integer. + #[inline] + #[must_use] + pub const fn count(self) -> usize { + match self { + Self::Subbands4 => 4, + Self::Subbands8 => 8, + } + } + + /// Derives Subbands from integer. + pub fn from_count(count: usize) -> Result { + match count { + 4 => Ok(Self::Subbands4), + 8 => Ok(Self::Subbands8), + _ => Err(Error::InvalidSubbands(count)), + } + } + + /// Returns 1-bit header code. + #[inline] + #[must_use] + pub const fn code(self) -> u8 { + match self { + Self::Subbands4 => 0, + Self::Subbands8 => 1, + } + } +} + +/// Parsed header of an SBC audio frame. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Header { + /// Syncword byte (`0x9C` or `0xAD`). + pub syncword: u8, + /// Sampling frequency. + pub sampling_frequency: SamplingFrequency, + /// Number of blocks. + pub blocks: BlockCount, + /// Channel mode. + pub channel_mode: ChannelMode, + /// Allocation method. + pub allocation_method: AllocationMethod, + /// Number of subbands. + pub subbands: Subbands, + /// Bitpool size (1 to 255). + pub bitpool: u8, + /// Stored CRC-8 parity check word. + pub crc_check: u8, + /// Joint stereo flags for subbands 0..subbands-1. + pub join: [bool; 8], +} + +impl Header { + /// Parses an SBC frame header from a byte slice. + pub fn parse(src: &[u8]) -> Result { + if src.len() < 4 { + return Err(Error::TruncatedFrame { expected: 4, actual: src.len() }); + } + let syncword = src[0]; + if syncword == SYNCWORD_MSBC { + let crc_check = src[3]; + return Ok(Self { + syncword, + sampling_frequency: SamplingFrequency::Freq16k, + blocks: BlockCount::Blocks15, + channel_mode: ChannelMode::Mono, + allocation_method: AllocationMethod::Loudness, + subbands: Subbands::Subbands8, + bitpool: 26, + crc_check, + join: [false; 8], + }); + } + if syncword != SYNCWORD_SBC { + return Err(Error::InvalidSyncword(syncword)); + } + let b1 = src[1]; + let freq_code = (b1 >> 6) & 3; + let blocks_code = (b1 >> 4) & 3; + let mode_code = (b1 >> 2) & 3; + let alloc_code = (b1 >> 1) & 1; + let subbands_code = b1 & 1; + + let sampling_frequency = match freq_code { + 0 => SamplingFrequency::Freq16k, + 1 => SamplingFrequency::Freq32k, + 2 => SamplingFrequency::Freq44k1, + _ => SamplingFrequency::Freq48k, + }; + let blocks = match blocks_code { + 0 => BlockCount::Blocks4, + 1 => BlockCount::Blocks8, + 2 => BlockCount::Blocks12, + _ => BlockCount::Blocks16, + }; + let channel_mode = match mode_code { + 0 => ChannelMode::Mono, + 1 => ChannelMode::DualChannel, + 2 => ChannelMode::Stereo, + _ => ChannelMode::JointStereo, + }; + let allocation_method = if alloc_code == 0 { AllocationMethod::Loudness } else { AllocationMethod::Snr }; + let subbands = if subbands_code == 0 { Subbands::Subbands4 } else { Subbands::Subbands8 }; + let bitpool = src[2]; + let crc_check = src[3]; + + let max_bitpool = match channel_mode { + ChannelMode::Mono | ChannelMode::DualChannel => 16 * subbands.count(), + ChannelMode::Stereo | ChannelMode::JointStereo => 32 * subbands.count(), + }; + if bitpool == 0 || (bitpool as usize) > max_bitpool { + return Err(Error::InvalidBitpool(bitpool)); + } + + let mut join = [false; 8]; + if channel_mode == ChannelMode::JointStereo && src.len() >= 5 { + let join_byte = src[4]; + let sb_count = subbands.count(); + for sb in 0..(sb_count.saturating_sub(1)) { + let bit_shift = 7 - (sb as u8); + join[sb] = ((join_byte >> bit_shift) & 1) != 0; + } + } + + Ok(Self { syncword, sampling_frequency, blocks, channel_mode, allocation_method, subbands, bitpool, crc_check, join }) + } + + /// Total length of the frame in bytes (Section 12.9). + #[must_use] + pub fn frame_length(&self) -> usize { + if self.syncword == SYNCWORD_MSBC { + return 57; + } + let nrof_subbands = self.subbands.count(); + let nrof_channels = self.channel_mode.channels(); + let nrof_blocks = self.blocks.count(); + let bitpool = self.bitpool as usize; + + let base = 4 + (4 * nrof_subbands * nrof_channels) / 8; + match self.channel_mode { + ChannelMode::Mono | ChannelMode::DualChannel => base + (nrof_blocks * nrof_channels * bitpool).div_ceil(8), + ChannelMode::Stereo => base + (nrof_blocks * bitpool).div_ceil(8), + ChannelMode::JointStereo => base + (nrof_subbands + nrof_blocks * bitpool).div_ceil(8), + } + } + + /// Number of audio samples per channel produced by this frame. + #[inline] + #[must_use] + pub const fn samples_per_frame(&self) -> usize { + self.blocks.count() * self.subbands.count() + } + + /// Number of audio channels. + #[inline] + #[must_use] + pub const fn channels(&self) -> usize { + self.channel_mode.channels() + } + + /// Sampling rate in Hz. + #[inline] + #[must_use] + pub const fn sample_rate(&self) -> u32 { + self.sampling_frequency.as_hz() + } + + /// Bit rate of the stream in bits per second (Section 12.9). + #[must_use] + pub fn bit_rate_bps(&self) -> u32 { + let flen = self.frame_length() as u64; + let fs = self.sample_rate() as u64; + let sub = self.subbands.count() as u64; + let blk = self.blocks.count() as u64; + let bps = (8 * flen * fs) / (sub * blk); + bps as u32 + } +} + +/// Information about a decoded SBC stream. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct StreamInfo { + /// Sample rate in Hz. + pub sample_rate: u32, + /// Channel count (1 or 2). + pub channels: usize, + /// Channel mode. + pub channel_mode: ChannelMode, + /// Block count. + pub blocks: usize, + /// Subband count. + pub subbands: usize, + /// Bitpool setting. + pub bitpool: u8, + /// Allocation method. + pub allocation_method: AllocationMethod, +} + +/// Errors encountered in SBC operations. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// Invalid SBC syncword. + #[error("invalid SBC syncword: {0:#04x}")] + InvalidSyncword(u8), + /// Frame truncated before complete read. + #[error("truncated frame: expected {expected} bytes, got {actual}")] + TruncatedFrame { + /// Expected byte length. + expected: usize, + /// Actual available byte length. + actual: usize, + }, + /// CRC-8 verification mismatch. + #[error("CRC-8 check failed: computed {computed:#04x}, frame header had {stored:#04x}")] + CrcMismatch { + /// Computed CRC-8 value. + computed: u8, + /// Stored CRC-8 in frame header. + stored: u8, + }, + /// Unsupported channel count. + #[error("unsupported channel count: {0} (must be 1 or 2)")] + InvalidChannels(usize), + /// Unsupported sample rate. + #[error("unsupported sample rate: {0} Hz (must be 16000, 32000, 44100, or 48000 Hz)")] + InvalidSampleRate(u32), + /// Unsupported block count. + #[error("unsupported block count: {0} (must be 4, 8, 12, or 16)")] + InvalidBlockCount(usize), + /// Unsupported subbands count. + #[error("unsupported subband count: {0} (must be 4 or 8)")] + InvalidSubbands(usize), + /// Invalid bitpool value. + #[error("invalid bitpool value: {0}")] + InvalidBitpool(u8), + /// Input exceeds safe maximum processing limit. + #[error("input exceeds safe maximum processing limit")] + InputTooLarge, + /// Memory allocation failed. + #[error("memory allocation failed")] + AllocationFailed, +} + +/// Computes CRC-8 with generator polynomial `0x1D` and initial state `0x0F` (Section 12.6.1.1). +pub fn crc8(bits: impl IntoIterator) -> u8 { + let mut crc: u8 = 0x0F; + for bit in bits { + let feedback = (crc >> 7) ^ (if bit { 1 } else { 0 }); + crc = crc.wrapping_shl(1) ^ (if feedback != 0 { 0x1D } else { 0 }); + } + crc +} + +struct BitReader<'a> { + data: &'a [u8], + byte_pos: usize, + bit_pos: u8, +} + +impl<'a> BitReader<'a> { + fn new(data: &'a [u8]) -> Self { + Self { data, byte_pos: 0, bit_pos: 7 } + } + + fn read_bits(&mut self, n: usize) -> Option { + if n == 0 { + return Some(0); + } + if n > 32 { + return None; + } + let mut val = 0u32; + for _ in 0..n { + if self.byte_pos >= self.data.len() { + return None; + } + let bit = (self.data[self.byte_pos] >> self.bit_pos) & 1; + val = (val << 1) | u32::from(bit); + if self.bit_pos == 0 { + self.bit_pos = 7; + self.byte_pos = self.byte_pos.saturating_add(1); + } else { + self.bit_pos -= 1; + } + } + Some(val) + } +} + +struct BitWriter { + bytes: Vec, + cur_byte: u8, + bit_pos: u8, +} + +impl BitWriter { + fn with_capacity(cap: usize) -> Result { + let mut bytes = Vec::new(); + bytes.try_reserve(cap).map_err(|_| Error::AllocationFailed)?; + Ok(Self { bytes, cur_byte: 0, bit_pos: 7 }) + } + + fn write_bits(&mut self, val: u32, n: usize) -> Result<(), Error> { + if n == 0 { + return Ok(()); + } + for i in (0..n).rev() { + let bit = ((val >> i) & 1) as u8; + self.cur_byte |= bit << self.bit_pos; + if self.bit_pos == 0 { + self.bytes.try_reserve(1).map_err(|_| Error::AllocationFailed)?; + self.bytes.push(self.cur_byte); + self.cur_byte = 0; + self.bit_pos = 7; + } else { + self.bit_pos -= 1; + } + } + Ok(()) + } + + fn flush(&mut self) -> Result<(), Error> { + if self.bit_pos < 7 { + self.bytes.try_reserve(1).map_err(|_| Error::AllocationFailed)?; + self.bytes.push(self.cur_byte); + self.cur_byte = 0; + self.bit_pos = 7; + } + Ok(()) + } + + fn finish(mut self) -> Result, Error> { + self.flush()?; + Ok(self.bytes) + } +} + +fn compute_header_crc( + b1: u8, + b2: u8, + channel_mode: ChannelMode, + subbands: usize, + channels: usize, + join: &[bool; 8], + scale_factors: &[[u8; 8]; 2], +) -> u8 { + let mut crc: u8 = 0x0F; + let mut feed_bit = |bit: bool| { + let feedback = (crc >> 7) ^ (if bit { 1 } else { 0 }); + crc = crc.wrapping_shl(1) ^ (if feedback != 0 { 0x1D } else { 0 }); + }; + for i in (0..8).rev() { + feed_bit(((b1 >> i) & 1) != 0); + } + for i in (0..8).rev() { + feed_bit(((b2 >> i) & 1) != 0); + } + if channel_mode == ChannelMode::JointStereo { + for sb in 0..(subbands.saturating_sub(1)) { + feed_bit(join[sb]); + } + feed_bit(false); // RFA + } + for ch in 0..channels { + for sb in 0..subbands { + let sf = scale_factors[ch][sb]; + for i in (0..4).rev() { + feed_bit(((sf >> i) & 1) != 0); + } + } + } + crc +} + +fn compute_bit_allocation( + subbands: usize, + channels: usize, + channel_mode: ChannelMode, + freq_idx: usize, + alloc_method: AllocationMethod, + bitpool: u16, + scale_factors: &[[u8; 8]; 2], + bits: &mut [[u8; 8]; 2], +) { + if channel_mode == ChannelMode::Mono || channel_mode == ChannelMode::DualChannel { + for ch in 0..channels { + let mut bitneed = [0i16; 8]; + if alloc_method == AllocationMethod::Snr { + for sb in 0..subbands { + bitneed[sb] = i16::from(scale_factors[ch][sb]); + } + } else { + for sb in 0..subbands { + let sf = scale_factors[ch][sb]; + if sf == 0 { + bitneed[sb] = -5; + } else { + let off = if subbands == 4 { OFFSET4[freq_idx][sb] as i16 } else { OFFSET8[freq_idx][sb] as i16 }; + let loudness = (sf as i16) - off; + bitneed[sb] = if loudness > 0 { loudness / 2 } else { loudness }; + } + } + } + + let mut max_bitneed = 0i16; + for sb in 0..subbands { + if bitneed[sb] > max_bitneed { + max_bitneed = bitneed[sb]; + } + } + + let mut bitcount = 0u16; + let mut slicecount = 0u16; + let mut bitslice = max_bitneed + 1; + + loop { + bitslice -= 1; + bitcount = bitcount.saturating_add(slicecount); + slicecount = 0; + for sb in 0..subbands { + let bn = bitneed[sb]; + if bn > bitslice + 1 && bn < bitslice + 16 { + slicecount = slicecount.saturating_add(1); + } else if bn == bitslice + 1 { + slicecount = slicecount.saturating_add(2); + } + } + if bitcount.saturating_add(slicecount) >= bitpool || bitslice <= -32 { + break; + } + } + + if bitcount.saturating_add(slicecount) == bitpool { + bitcount = bitcount.saturating_add(slicecount); + bitslice -= 1; + } + + for sb in 0..subbands { + let bn = bitneed[sb]; + if bn < bitslice + 2 { + bits[ch][sb] = 0; + } else { + let b = (bn - bitslice).clamp(0, 16); + bits[ch][sb] = b as u8; + } + } + + let mut sb = 0; + while bitcount < bitpool && sb < subbands { + if bits[ch][sb] >= 2 && bits[ch][sb] < 16 { + bits[ch][sb] = bits[ch][sb].saturating_add(1); + bitcount = bitcount.saturating_add(1); + } else if bitneed[sb] == bitslice + 1 && bitpool > bitcount.saturating_add(1) { + bits[ch][sb] = 2; + bitcount = bitcount.saturating_add(2); + } + sb += 1; + } + + let mut sb = 0; + while bitcount < bitpool && sb < subbands { + if bits[ch][sb] < 16 { + bits[ch][sb] = bits[ch][sb].saturating_add(1); + bitcount = bitcount.saturating_add(1); + } + sb += 1; + } + } + } else { + let mut bitneed = [[0i16; 8]; 2]; + if alloc_method == AllocationMethod::Snr { + for ch in 0..2 { + for sb in 0..subbands { + bitneed[ch][sb] = i16::from(scale_factors[ch][sb]); + } + } + } else { + for ch in 0..2 { + for sb in 0..subbands { + let sf = scale_factors[ch][sb]; + if sf == 0 { + bitneed[ch][sb] = -5; + } else { + let off = if subbands == 4 { OFFSET4[freq_idx][sb] as i16 } else { OFFSET8[freq_idx][sb] as i16 }; + let loudness = (sf as i16) - off; + bitneed[ch][sb] = if loudness > 0 { loudness / 2 } else { loudness }; + } + } + } + } + + let mut max_bitneed = 0i16; + for ch in 0..2 { + for sb in 0..subbands { + if bitneed[ch][sb] > max_bitneed { + max_bitneed = bitneed[ch][sb]; + } + } + } + + let mut bitcount = 0u16; + let mut slicecount = 0u16; + let mut bitslice = max_bitneed + 1; + + loop { + bitslice -= 1; + bitcount = bitcount.saturating_add(slicecount); + slicecount = 0; + for ch in 0..2 { + for sb in 0..subbands { + let bn = bitneed[ch][sb]; + if bn > bitslice + 1 && bn < bitslice + 16 { + slicecount = slicecount.saturating_add(1); + } else if bn == bitslice + 1 { + slicecount = slicecount.saturating_add(2); + } + } + } + if bitcount.saturating_add(slicecount) >= bitpool || bitslice <= -32 { + break; + } + } + + if bitcount.saturating_add(slicecount) == bitpool { + bitcount = bitcount.saturating_add(slicecount); + bitslice -= 1; + } + + for ch in 0..2 { + for sb in 0..subbands { + let bn = bitneed[ch][sb]; + if bn < bitslice + 2 { + bits[ch][sb] = 0; + } else { + let b = (bn - bitslice).clamp(0, 16); + bits[ch][sb] = b as u8; + } + } + } + + let mut ch = 0; + let mut sb = 0; + while bitcount < bitpool && sb < subbands { + if bits[ch][sb] >= 2 && bits[ch][sb] < 16 { + bits[ch][sb] = bits[ch][sb].saturating_add(1); + bitcount = bitcount.saturating_add(1); + } else if bitneed[ch][sb] == bitslice + 1 && bitpool > bitcount.saturating_add(1) { + bits[ch][sb] = 2; + bitcount = bitcount.saturating_add(2); + } + if ch == 1 { + ch = 0; + sb += 1; + } else { + ch = 1; + } + } + + let mut ch = 0; + let mut sb = 0; + while bitcount < bitpool && sb < subbands { + if bits[ch][sb] < 16 { + bits[ch][sb] = bits[ch][sb].saturating_add(1); + bitcount = bitcount.saturating_add(1); + } + if ch == 1 { + ch = 0; + sb += 1; + } else { + ch = 1; + } + } + } +} + +fn synth_subbands_4(v: &mut [f32; 160], s: &[f32; 8], out: &mut [i16; 8]) { + v.copy_within(0..72, 8); + for k in 0..8 { + let mut sum = 0.0f32; + for i in 0..4 { + sum += SYNTH_COS_4[k][i] * s[i]; + } + v[k] = sum; + } + let mut u = [0.0f32; 40]; + for i in 0..5 { + for j in 0..4 { + u[i * 8 + j] = v[i * 16 + j]; + u[i * 8 + 4 + j] = v[i * 16 + 12 + j]; + } + } + for j in 0..4 { + let mut sum = 0.0f32; + for i in 0..10 { + sum += u[j + 4 * i] * SYNTH_D_4[j + 4 * i]; + } + let clamped = sum.clamp(-32768.0, 32767.0).round() as i32; + out[j] = clamped as i16; + } +} + +fn synth_subbands_8(v: &mut [f32; 160], s: &[f32; 8], out: &mut [i16; 8]) { + v.copy_within(0..144, 16); + for k in 0..16 { + let mut sum = 0.0f32; + for i in 0..8 { + sum += SYNTH_COS_8[k][i] * s[i]; + } + v[k] = sum; + } + let mut u = [0.0f32; 80]; + for i in 0..5 { + for j in 0..8 { + u[i * 16 + j] = v[i * 32 + j]; + u[i * 16 + 8 + j] = v[i * 32 + 24 + j]; + } + } + for j in 0..8 { + let mut sum = 0.0f32; + for i in 0..10 { + sum += u[j + 8 * i] * SYNTH_D_8[j + 8 * i]; + } + let clamped = sum.clamp(-32768.0, 32767.0).round() as i32; + out[j] = clamped as i16; + } +} + +fn analysis_subbands_4(x: &mut [f32; 80], pcm_in: &[i16], s_out: &mut [f32; 8]) { + x.copy_within(0..36, 4); + for i in 0..4 { + x[3 - i] = pcm_in[i] as f32; + } + let mut y = [0.0f32; 8]; + for i in 0..8 { + let mut sum = 0.0f32; + for k in 0..5 { + let idx = i + k * 8; + sum += PROTO_4_40[idx] * x[idx]; + } + y[i] = sum; + } + for i in 0..4 { + let mut sum = 0.0f32; + for k in 0..8 { + sum += ANALYSIS_COS_4[i][k] * y[k]; + } + s_out[i] = sum; + } +} + +fn analysis_subbands_8(x: &mut [f32; 80], pcm_in: &[i16], s_out: &mut [f32; 8]) { + x.copy_within(0..72, 8); + for i in 0..8 { + x[7 - i] = pcm_in[i] as f32; + } + let mut y = [0.0f32; 16]; + for i in 0..16 { + let mut sum = 0.0f32; + for k in 0..5 { + let idx = i + k * 16; + sum += PROTO_8_80[idx] * x[idx]; + } + y[i] = sum; + } + for i in 0..8 { + let mut sum = 0.0f32; + for k in 0..16 { + sum += ANALYSIS_COS_8[i][k] * y[k]; + } + s_out[i] = sum; + } +} + +fn calculate_scalefactor(max_abs: f32) -> u8 { + let v = max_abs.abs() as u32; + if v == 0 { + return 0; + } + let mut sf = 0u8; + while sf < 15 && (1u32 << (sf + 1)) <= v { + sf += 1; + } + sf +} + +/// SBC audio decoder. +#[derive(Debug, Clone)] +pub struct Decoder { + v: [[f32; 160]; 2], +} + +impl Default for Decoder { + fn default() -> Self { + Self { v: [[0.0f32; 160]; 2] } + } +} + +impl Decoder { + /// Creates a new SBC decoder. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// Resets synthesis filterbank state. + pub fn reset(&mut self) { + self.v = [[0.0f32; 160]; 2]; + } + + /// Decodes a single SBC frame from `packet`, appending linear PCM samples to `dst`. + /// Returns the number of bytes consumed from `packet`. + pub fn decode_frame(&mut self, packet: &[u8], dst: &mut Vec) -> Result { + let header = Header::parse(packet)?; + let frame_len = header.frame_length(); + if packet.len() < frame_len { + return Err(Error::TruncatedFrame { expected: frame_len, actual: packet.len() }); + } + + let channels = header.channels(); + let subbands = header.subbands.count(); + let blocks = header.blocks.count(); + + let mut reader = BitReader::new(&packet[4..frame_len]); + + let mut join = [false; 8]; + if header.channel_mode == ChannelMode::JointStereo { + for sb in 0..(subbands.saturating_sub(1)) { + join[sb] = reader.read_bits(1).unwrap_or(0) != 0; + } + let _ = reader.read_bits(1); // RFA + } + + let mut scale_factors = [[0u8; 8]; 2]; + for ch in 0..channels { + for sb in 0..subbands { + scale_factors[ch][sb] = (reader.read_bits(4).unwrap_or(0) & 0x0F) as u8; + } + } + + // Verify CRC-8 + let expected_crc = if header.syncword == SYNCWORD_MSBC { + compute_header_crc(0x00, 0x00, ChannelMode::Mono, 8, 1, &[false; 8], &scale_factors) + } else { + compute_header_crc(packet[1], packet[2], header.channel_mode, subbands, channels, &join, &scale_factors) + }; + if expected_crc != header.crc_check { + return Err(Error::CrcMismatch { computed: expected_crc, stored: header.crc_check }); + } + + let mut bits = [[0u8; 8]; 2]; + compute_bit_allocation( + subbands, + channels, + header.channel_mode, + header.sampling_frequency.table_index(), + header.allocation_method, + u16::from(header.bitpool), + &scale_factors, + &mut bits, + ); + + let mut levels = [[0u32; 8]; 2]; + let mut scalefactors = [[0.0f32; 8]; 2]; + for ch in 0..channels { + for sb in 0..subbands { + levels[ch][sb] = (1u32 << bits[ch][sb]).saturating_sub(1); + scalefactors[ch][sb] = (1u32 << (u32::from(scale_factors[ch][sb]) + 1)) as f32; + } + } + + // Subband sample reconstruction + let mut sb_sample = [[[0.0f32; 8]; 2]; 16]; + for blk in 0..blocks { + for ch in 0..channels { + for sb in 0..subbands { + let lev = levels[ch][sb]; + if lev > 0 { + let raw_s = reader.read_bits(bits[ch][sb] as usize).unwrap_or(0); + let norm = ((raw_s as f32 * 2.0 + 1.0) / (lev as f32)) - 1.0; + sb_sample[blk][ch][sb] = scalefactors[ch][sb] * norm; + } else { + sb_sample[blk][ch][sb] = 0.0; + } + } + } + } + + // Joint stereo mid/side reconstruction + if header.channel_mode == ChannelMode::JointStereo { + for blk in 0..blocks { + for sb in 0..subbands { + if join[sb] { + let mid = sb_sample[blk][0][sb] + sb_sample[blk][1][sb]; + let side = sb_sample[blk][0][sb] - sb_sample[blk][1][sb]; + sb_sample[blk][0][sb] = mid; + sb_sample[blk][1][sb] = side; + } + } + } + } + + // Synthesis filterbank + let total_samples = blocks * subbands * channels; + dst.try_reserve(total_samples).map_err(|_| Error::AllocationFailed)?; + + let mut block_samples = [[[0i16; 8]; 2]; 16]; + for blk in 0..blocks { + for ch in 0..channels { + if subbands == 4 { + synth_subbands_4(&mut self.v[ch], &sb_sample[blk][ch], &mut block_samples[blk][ch]); + } else { + synth_subbands_8(&mut self.v[ch], &sb_sample[blk][ch], &mut block_samples[blk][ch]); + } + } + for sb in 0..subbands { + for ch in 0..channels { + dst.push(block_samples[blk][ch][sb]); + } + } + } + + Ok(frame_len) + } + + /// Decodes an entire buffer of concatenated SBC frames into interleaved 16-bit PCM. + pub fn decode(&mut self, src: &[u8], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + let mut offset = 0; + while offset < src.len() { + let consumed = self.decode_frame(&src[offset..], dst)?; + if consumed == 0 { + break; + } + offset = offset.saturating_add(consumed); + } + Ok(()) + } +} + +/// SBC audio encoder. +#[derive(Debug, Clone)] +pub struct Encoder { + sample_rate: u32, + channels: usize, + channel_mode: ChannelMode, + blocks: BlockCount, + subbands: Subbands, + bitpool: u8, + allocation_method: AllocationMethod, + x: [[f32; 80]; 2], +} + +impl Encoder { + /// Creates a new SBC encoder with custom configuration. + pub fn new( + sample_rate: u32, + channels: usize, + blocks: usize, + subbands: usize, + bitpool: u8, + allocation_method: AllocationMethod, + ) -> Result { + if channels != 1 && channels != 2 { + return Err(Error::InvalidChannels(channels)); + } + let freq = SamplingFrequency::from_hz(sample_rate)?; + let block_cnt = BlockCount::from_count(blocks)?; + let subband_cnt = Subbands::from_count(subbands)?; + let channel_mode = if channels == 1 { ChannelMode::Mono } else { ChannelMode::JointStereo }; + + let max_bitpool = match channel_mode { + ChannelMode::Mono | ChannelMode::DualChannel => 16 * subband_cnt.count(), + ChannelMode::Stereo | ChannelMode::JointStereo => 32 * subband_cnt.count(), + }; + if bitpool == 0 || (bitpool as usize) > max_bitpool { + return Err(Error::InvalidBitpool(bitpool)); + } + + if block_cnt == BlockCount::Blocks15 + && (sample_rate != 16_000 || channels != 1 || subbands != 8 || bitpool != 26 || allocation_method != AllocationMethod::Loudness) + { + return Err(Error::InvalidBlockCount(15)); + } + + Ok(Self { + sample_rate: freq.as_hz(), + channels, + channel_mode, + blocks: block_cnt, + subbands: subband_cnt, + bitpool, + allocation_method, + x: [[0.0f32; 80]; 2], + }) + } + + /// Resets analysis filterbank state. + pub fn reset(&mut self) { + self.x = [[0.0f32; 80]; 2]; + } + + /// Encodes a single frame of linear PCM samples into `dst`. + /// `pcm` must contain `blocks * subbands * channels` interleaved 16-bit samples. + pub fn encode_frame(&mut self, pcm: &[i16], dst: &mut Vec) -> Result<(), Error> { + let subbands = self.subbands.count(); + let blocks = self.blocks.count(); + let expected_samples = blocks * subbands * self.channels; + if pcm.len() < expected_samples { + return Err(Error::TruncatedFrame { expected: expected_samples, actual: pcm.len() }); + } + + // Polyphase analysis filterbank + let mut sb_samples = [[[0.0f32; 8]; 2]; 16]; + for blk in 0..blocks { + for ch in 0..self.channels { + let mut channel_buf = [0i16; 8]; + for i in 0..subbands { + let idx = (blk * subbands + i) * self.channels + ch; + channel_buf[i] = pcm[idx]; + } + if subbands == 4 { + analysis_subbands_4(&mut self.x[ch], &channel_buf, &mut sb_samples[blk][ch]); + } else { + analysis_subbands_8(&mut self.x[ch], &channel_buf, &mut sb_samples[blk][ch]); + } + } + } + + // Scale factors and joint stereo decisions + let mut scale_factors = [[0u8; 8]; 2]; + let mut join = [false; 8]; + + if self.channels == 2 && self.channel_mode == ChannelMode::JointStereo { + for sb in 0..subbands { + let mut max_l = 0.0f32; + let mut max_r = 0.0f32; + for blk in 0..blocks { + let al = sb_samples[blk][0][sb].abs(); + let ar = sb_samples[blk][1][sb].abs(); + if al > max_l { + max_l = al; + } + if ar > max_r { + max_r = ar; + } + } + let sf_l = calculate_scalefactor(max_l); + let sf_r = calculate_scalefactor(max_r); + + if sb < subbands.saturating_sub(1) { + let mut max_mid = 0.0f32; + let mut max_side = 0.0f32; + for blk in 0..blocks { + let mid = (sb_samples[blk][0][sb] + sb_samples[blk][1][sb]) * 0.5; + let side = (sb_samples[blk][0][sb] - sb_samples[blk][1][sb]) * 0.5; + let am = mid.abs(); + let asd = side.abs(); + if am > max_mid { + max_mid = am; + } + if asd > max_side { + max_side = asd; + } + } + let sf_mid = calculate_scalefactor(max_mid); + let sf_side = calculate_scalefactor(max_side); + + if u16::from(sf_l) + u16::from(sf_r) > u16::from(sf_mid) + u16::from(sf_side) { + join[sb] = true; + scale_factors[0][sb] = sf_mid; + scale_factors[1][sb] = sf_side; + for blk in 0..blocks { + let mid = (sb_samples[blk][0][sb] + sb_samples[blk][1][sb]) * 0.5; + let side = (sb_samples[blk][0][sb] - sb_samples[blk][1][sb]) * 0.5; + sb_samples[blk][0][sb] = mid; + sb_samples[blk][1][sb] = side; + } + continue; + } + } + + scale_factors[0][sb] = sf_l; + scale_factors[1][sb] = sf_r; + } + } else { + for ch in 0..self.channels { + for sb in 0..subbands { + let mut max_val = 0.0f32; + for blk in 0..blocks { + let a = sb_samples[blk][ch][sb].abs(); + if a > max_val { + max_val = a; + } + } + scale_factors[ch][sb] = calculate_scalefactor(max_val); + } + } + } + + // Bit allocation + let freq = SamplingFrequency::from_hz(self.sample_rate)?; + let mut bits = [[0u8; 8]; 2]; + compute_bit_allocation( + subbands, + self.channels, + self.channel_mode, + freq.table_index(), + self.allocation_method, + u16::from(self.bitpool), + &scale_factors, + &mut bits, + ); + + // Quantization + let mut levels = [[0u32; 8]; 2]; + let mut scalefactors = [[0.0f32; 8]; 2]; + for ch in 0..self.channels { + for sb in 0..subbands { + levels[ch][sb] = (1u32 << bits[ch][sb]).saturating_sub(1); + scalefactors[ch][sb] = (1u32 << (u32::from(scale_factors[ch][sb]) + 1)) as f32; + } + } + + let mut quantized = [[[0u32; 8]; 2]; 16]; + for blk in 0..blocks { + for ch in 0..self.channels { + for sb in 0..subbands { + let lev = levels[ch][sb]; + if lev > 0 { + let norm = sb_samples[blk][ch][sb] / scalefactors[ch][sb]; + let val = ((norm + 1.0) * (lev as f32)) * 0.5; + let q = val.floor() as i32; + quantized[blk][ch][sb] = (q.clamp(0, lev as i32)) as u32; + } + } + } + } + + // Frame header bytes + let is_msbc = self.blocks == BlockCount::Blocks15; + let (syncword, b1, b2, crc, flen) = if is_msbc { + let crc = compute_header_crc(0x00, 0x00, ChannelMode::Mono, 8, 1, &[false; 8], &scale_factors); + (SYNCWORD_MSBC, 0x00, 0x00, crc, 57) + } else { + let b1 = (freq.code() << 6) + | (self.blocks.code() << 4) + | (self.channel_mode.code() << 2) + | (self.allocation_method.code() << 1) + | self.subbands.code(); + let b2 = self.bitpool; + let crc = compute_header_crc(b1, b2, self.channel_mode, subbands, self.channels, &join, &scale_factors); + let flen = Header { + syncword: SYNCWORD_SBC, + sampling_frequency: freq, + blocks: self.blocks, + channel_mode: self.channel_mode, + allocation_method: self.allocation_method, + subbands: self.subbands, + bitpool: self.bitpool, + crc_check: crc, + join, + } + .frame_length(); + (SYNCWORD_SBC, b1, b2, crc, flen) + }; + + let mut writer = BitWriter::with_capacity(flen)?; + writer.write_bits(u32::from(syncword), 8)?; + writer.write_bits(u32::from(b1), 8)?; + writer.write_bits(u32::from(b2), 8)?; + writer.write_bits(u32::from(crc), 8)?; + + if self.channel_mode == ChannelMode::JointStereo { + for sb in 0..(subbands.saturating_sub(1)) { + writer.write_bits(if join[sb] { 1 } else { 0 }, 1)?; + } + writer.write_bits(0, 1)?; // RFA + } + + for ch in 0..self.channels { + for sb in 0..subbands { + writer.write_bits(u32::from(scale_factors[ch][sb]), 4)?; + } + } + + for blk in 0..blocks { + for ch in 0..self.channels { + for sb in 0..subbands { + if bits[ch][sb] > 0 { + writer.write_bits(quantized[blk][ch][sb], bits[ch][sb] as usize)?; + } + } + } + } + + let frame_bytes = writer.finish()?; + dst.try_reserve(frame_bytes.len()).map_err(|_| Error::AllocationFailed)?; + dst.extend_from_slice(&frame_bytes); + Ok(()) + } + + /// Encodes a stream of linear PCM samples into concatenated SBC frames. + pub fn encode(&mut self, pcm: &[i16], dst: &mut Vec) -> Result<(), Error> { + if pcm.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + let frame_samples = self.blocks.count() * self.subbands.count() * self.channels; + if !pcm.len().is_multiple_of(frame_samples) { + return Err(Error::TruncatedFrame { expected: frame_samples, actual: pcm.len() % frame_samples }); + } + let mut offset: usize = 0; + while offset.saturating_add(frame_samples) <= pcm.len() { + self.encode_frame(&pcm[offset..offset + frame_samples], dst)?; + offset = offset.saturating_add(frame_samples); + } + Ok(()) + } +} + +/// Decodes an entire SBC bitstream to 16-bit linear PCM and returns stream info. +pub fn decode(src: &[u8]) -> Result<(Vec, StreamInfo), Error> { + if src.is_empty() { + return Err(Error::TruncatedFrame { expected: 4, actual: 0 }); + } + let header = Header::parse(src)?; + let info = StreamInfo { + sample_rate: header.sample_rate(), + channels: header.channels(), + channel_mode: header.channel_mode, + blocks: header.blocks.count(), + subbands: header.subbands.count(), + bitpool: header.bitpool, + allocation_method: header.allocation_method, + }; + let mut decoder = Decoder::new(); + let mut dst = Vec::new(); + let mut offset = 0; + while offset < src.len() { + let frame_hdr = Header::parse(&src[offset..])?; + if frame_hdr.sample_rate() != info.sample_rate || frame_hdr.channels() != info.channels || frame_hdr.channel_mode != info.channel_mode { + return Err(Error::InvalidSampleRate(frame_hdr.sample_rate())); + } + let consumed = decoder.decode_frame(&src[offset..], &mut dst)?; + if consumed == 0 { + break; + } + offset = offset.saturating_add(consumed); + } + Ok((dst, info)) +} + +/// Encodes 16-bit linear PCM audio into an SBC bitstream using standard high-quality defaults. +pub fn encode(pcm: &[i16], sample_rate: u32, channels: usize, bitpool: u8) -> Result, Error> { + let mut encoder = Encoder::new( + sample_rate, + channels, + 16, // standard 16 blocks + 8, // standard 8 subbands + bitpool, + AllocationMethod::Loudness, + )?; + let mut dst = Vec::new(); + encoder.encode(pcm, &mut dst)?; + Ok(dst) +} diff --git a/crates/audio/tests/sbc_oracle.rs b/crates/audio/tests/sbc_oracle.rs new file mode 100644 index 000000000..62495ae16 --- /dev/null +++ b/crates/audio/tests/sbc_oracle.rs @@ -0,0 +1,298 @@ +#![cfg(feature = "sbc")] + +use craft_audio::sbc::{ + AllocationMethod, BlockCount, ChannelMode, Decoder, Encoder, Header, SYNCWORD_MSBC, SYNCWORD_SBC, SamplingFrequency, Subbands, decode, encode, +}; +use std::process::Command; + +fn pearson_correlation(x: &[i16], y: &[i16], lag: usize) -> f64 { + let n = x.len().min(y.len().saturating_sub(lag)); + if n == 0 { + return 0.0; + } + let x = &x[..n]; + let y = &y[lag..lag + n]; + let mean_x = x.iter().map(|&v| v as f64).sum::() / (n as f64); + let mean_y = y.iter().map(|&v| v as f64).sum::() / (n as f64); + let mut num = 0.0; + let mut denom_x = 0.0; + let mut denom_y = 0.0; + for (&a, &b) in x.iter().zip(y) { + let da = (a as f64) - mean_x; + let db = (b as f64) - mean_y; + num += da * db; + denom_x += da * da; + denom_y += db * db; + } + let denom = (denom_x * denom_y).sqrt(); + if denom > 0.0 { num / denom } else { 0.0 } +} + +fn generate_sine(sample_rate: u32, channels: usize, num_frames: usize) -> Vec { + let mut pcm = Vec::with_capacity(num_frames * channels); + for i in 0..num_frames { + let t = (i as f64) / (sample_rate as f64); + let s_l = (16000.0 * (2.0 * std::f64::consts::PI * 440.0 * t).sin()) as i16; + pcm.push(s_l); + if channels == 2 { + let s_r = (16000.0 * (2.0 * std::f64::consts::PI * 880.0 * t).sin()) as i16; + pcm.push(s_r); + } + } + pcm +} + +#[test] +fn test_header_parse_and_frame_length() { + // Standard SBC header: 0x9C, 44.1kHz, 16 blocks, Joint Stereo, Loudness, 8 subbands, bitpool 32 + let mut packet = vec![SYNCWORD_SBC, 0xBD, 32, 0x00]; + let header = Header::parse(&packet).expect("parse header"); + assert_eq!(header.sampling_frequency, SamplingFrequency::Freq44k1); + assert_eq!(header.blocks, BlockCount::Blocks16); + assert_eq!(header.channel_mode, ChannelMode::JointStereo); + assert_eq!(header.allocation_method, AllocationMethod::Loudness); + assert_eq!(header.subbands, Subbands::Subbands8); + assert_eq!(header.bitpool, 32); + assert_eq!(header.channels(), 2); + assert_eq!(header.samples_per_frame(), 128); + + // Frame length formula check + let expected_len = 4 + (4 * 8 * 2) / 8 + (8usize + 16 * 32).div_ceil(8); + assert_eq!(header.frame_length(), expected_len); + assert_eq!(header.frame_length(), 77); + + // mSBC header: 0xAD + packet[0] = SYNCWORD_MSBC; + let msbc_header = Header::parse(&packet).expect("parse msbc header"); + assert_eq!(msbc_header.frame_length(), 57); + assert_eq!(msbc_header.sample_rate(), 16000); + assert_eq!(msbc_header.channels(), 1); +} + +#[test] +fn test_silence_roundtrip() { + for &sample_rate in &[16_000u32, 32_000, 44_100, 48_000] { + for &channels in &[1usize, 2] { + for &subbands in &[4usize, 8] { + for &blocks in &[4usize, 8, 12, 16] { + let frame_samples = blocks * subbands * channels; + let pcm = vec![0i16; frame_samples * 4]; + let mut encoder = Encoder::new(sample_rate, channels, blocks, subbands, 32, AllocationMethod::Loudness).expect("create encoder"); + + let mut sbc_bytes = Vec::new(); + encoder.encode(&pcm, &mut sbc_bytes).expect("encode silence"); + assert!(!sbc_bytes.is_empty()); + + let mut decoder = Decoder::new(); + let mut decoded = Vec::new(); + decoder.decode(&sbc_bytes, &mut decoded).expect("decode silence"); + + assert_eq!(decoded.len(), pcm.len()); + for &s in &decoded { + assert!(s.abs() <= 16, "silence sample too large: {s}"); + } + } + } + } + } +} + +#[test] +fn test_sine_wave_roundtrip_fidelity() { + let sample_rate = 44_100u32; + let channels = 2usize; + let num_frames = 128 * 20; + let pcm = generate_sine(sample_rate, channels, num_frames); + + let sbc_bytes = encode(&pcm, sample_rate, channels, 32).expect("encode sine"); + let (decoded, info) = decode(&sbc_bytes).expect("decode sine"); + + assert_eq!(info.sample_rate, sample_rate); + assert_eq!(info.channels, channels); + assert_eq!(decoded.len(), pcm.len()); + + // 8-subband filterbank total delay is 73 samples per channel + let corr_l = pearson_correlation(&pcm[0..], &decoded[0..], 73 * 2); + assert!(corr_l > 0.98, "left channel correlation too low: {corr_l}"); +} + +#[test] +fn test_invalid_and_corrupt_inputs() { + let mut decoder = Decoder::new(); + let mut dst = Vec::new(); + + // Empty packet + assert!(decoder.decode_frame(&[], &mut dst).is_err()); + + // Too short header + assert!(decoder.decode_frame(&[SYNCWORD_SBC, 0x00], &mut dst).is_err()); + + // Invalid syncword + assert!(decoder.decode_frame(&[0x00, 0xBD, 32, 0x00], &mut dst).is_err()); + + // CRC mismatch + let bad_crc_frame = vec![SYNCWORD_SBC, 0xBD, 32, 0x55, 0x00, 0x00, 0x00, 0x00]; + assert!(decoder.decode_frame(&bad_crc_frame, &mut dst).is_err()); + + // Bitpool capacity exceeded (Mono 4 subbands capacity is 64; 65 must fail) + let bad_bitpool_frame = vec![SYNCWORD_SBC, 0x00, 65, 0x00]; + assert!(decoder.decode_frame(&bad_bitpool_frame, &mut dst).is_err()); + assert!(Encoder::new(16000, 1, 4, 4, 65, AllocationMethod::Loudness).is_err()); + + // Unsupported 15-block configuration (only 16kHz mono 8-subband 26-bitpool is valid mSBC) + assert!(Encoder::new(44100, 2, 15, 8, 32, AllocationMethod::Loudness).is_err()); + + // Incomplete PCM frames rejected by encoder + let mut enc = Encoder::new(44100, 2, 16, 8, 32, AllocationMethod::Loudness).expect("enc"); + let mut out = Vec::new(); + assert!(enc.encode(&[0i16; 100], &mut out).is_err()); + + // Valid mSBC encoding produces exact 57-byte mSBC frame + let mut msbc_enc = Encoder::new(16000, 1, 15, 8, 26, AllocationMethod::Loudness).expect("msbc enc"); + let mut msbc_out = Vec::new(); + msbc_enc.encode(&vec![0i16; 120], &mut msbc_out).expect("encode msbc frame"); + assert_eq!(msbc_out.len(), 57); + assert_eq!(msbc_out[0], SYNCWORD_MSBC); + + // Hostile fuzzed input should never panic + let mut seed = 0x1234_5678u32; + for len in [10, 50, 100, 500] { + let mut random_bytes = vec![0u8; len]; + for b in &mut random_bytes { + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + *b = seed as u8; + } + let _ = decoder.decode(&random_bytes, &mut dst); + } +} + +#[test] +fn test_oracle_ffmpeg_cross_verification() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { + return; + }; + let dir = craft_media_testkit::fixture_subdir("sbc"); + + // 1. FFmpeg decodes our encoded SBC files + for &(sample_rate, channels) in &[(16_000u32, 1usize), (44_100, 2), (48_000, 2)] { + let pcm = generate_sine(sample_rate, channels, 128 * 20); + let sbc_bytes = encode(&pcm, sample_rate, channels, 32).expect("encode sbc"); + + let sbc_file = dir.join(format!("ours_{sample_rate}_{channels}.sbc")); + std::fs::write(&sbc_file, &sbc_bytes).expect("write sbc fixture"); + + let out = Command::new(&ffmpeg) + .args(["-v", "error", "-y", "-i"]) + .arg(&sbc_file) + .args(["-f", "s16le", "-acodec", "pcm_s16le", "-"]) + .output() + .expect("run ffmpeg"); + + assert!(out.status.success(), "ffmpeg failed to decode our SBC: {}", String::from_utf8_lossy(&out.stderr)); + + let theirs: Vec = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + + assert!(!theirs.is_empty()); + let corr = pearson_correlation(&pcm, &theirs, 73 * channels); + assert!(corr > 0.95, "FFmpeg decoded output correlation against input too low ({sample_rate} Hz, {channels} ch): {corr}"); + } + + // 2. Our decoder decodes FFmpeg-encoded SBC files + for &(sample_rate, channels) in &[(16_000u32, 1usize), (44_100, 2), (48_000, 2)] { + let ff_sbc_file = dir.join(format!("ff_{sample_rate}_{channels}.sbc")); + let ff_enc = Command::new(&ffmpeg) + .args([ + "-v", + "error", + "-y", + "-f", + "lavfi", + "-i", + &format!("sine=frequency=440:duration=0.2:sample_rate={sample_rate}"), + "-c:a", + "sbc", + "-ac", + &channels.to_string(), + ]) + .arg(&ff_sbc_file) + .output() + .expect("ffmpeg encode sbc"); + + assert!(ff_enc.status.success(), "ffmpeg failed to encode SBC: {}", String::from_utf8_lossy(&ff_enc.stderr)); + + let ff_sbc_bytes = std::fs::read(&ff_sbc_file).expect("read ff sbc fixture"); + let (decoded, info) = decode(&ff_sbc_bytes).expect("decode ff sbc"); + assert_eq!(info.sample_rate, sample_rate); + assert_eq!(info.channels, channels); + assert!(!decoded.is_empty()); + + // Decode ff_sbc_file with ffmpeg as well to compare + let ff_raw = Command::new(&ffmpeg) + .args(["-v", "error", "-y", "-i"]) + .arg(&ff_sbc_file) + .args(["-f", "s16le", "-acodec", "pcm_s16le", "-"]) + .output() + .expect("ffmpeg decode raw"); + + let ff_pcm: Vec = ff_raw.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + + let corr = pearson_correlation(&decoded, &ff_pcm, 0); + assert!(corr > 0.99, "Our decoder output correlation against FFmpeg decoder output too low: {corr}"); + } + + // 3. Our decoder decodes FFmpeg-encoded mSBC wideband speech + let msbc_file = dir.join("ff_msbc.sbc"); + let ff_msbc_enc = Command::new(&ffmpeg) + .args(["-v", "error", "-y", "-f", "lavfi", "-i", "sine=frequency=440:duration=0.2:sample_rate=16000", "-c:a", "sbc", "-msbc", "1"]) + .arg(&msbc_file) + .output() + .expect("ffmpeg encode msbc"); + + assert!(ff_msbc_enc.status.success(), "ffmpeg failed to encode mSBC: {}", String::from_utf8_lossy(&ff_msbc_enc.stderr)); + + let msbc_bytes = std::fs::read(&msbc_file).expect("read msbc fixture"); + let (decoded, info) = decode(&msbc_bytes).expect("decode msbc"); + assert_eq!(info.sample_rate, 16000); + assert_eq!(info.channels, 1); + assert_eq!(info.blocks, 15); + assert_eq!(info.subbands, 8); + assert!(!decoded.is_empty()); + + let ff_msbc_raw = Command::new(&ffmpeg) + .args(["-v", "error", "-y", "-i"]) + .arg(&msbc_file) + .args(["-f", "s16le", "-acodec", "pcm_s16le", "-"]) + .output() + .expect("ffmpeg decode msbc raw"); + + let ff_msbc_pcm: Vec = ff_msbc_raw.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + + let corr = pearson_correlation(&decoded, &ff_msbc_pcm, 0); + assert!(corr > 0.99, "mSBC decoded output correlation against FFmpeg decoder too low: {corr}"); + + // 4. FFmpeg decodes our encoded mSBC file + let msbc_sine = generate_sine(16000, 1, 120 * 20); + let mut our_msbc_enc = Encoder::new(16000, 1, 15, 8, 26, AllocationMethod::Loudness).expect("msbc enc"); + let mut our_msbc_bytes = Vec::new(); + our_msbc_enc.encode(&msbc_sine, &mut our_msbc_bytes).expect("encode msbc"); + + let our_msbc_file = dir.join("ours_msbc.sbc"); + std::fs::write(&our_msbc_file, &our_msbc_bytes).expect("write our msbc fixture"); + + let our_msbc_out = Command::new(&ffmpeg) + .args(["-v", "error", "-y", "-i"]) + .arg(&our_msbc_file) + .args(["-f", "s16le", "-acodec", "pcm_s16le", "-"]) + .output() + .expect("ffmpeg decode our msbc"); + + assert!(our_msbc_out.status.success(), "ffmpeg failed to decode our mSBC: {}", String::from_utf8_lossy(&our_msbc_out.stderr)); + + let our_msbc_theirs: Vec = our_msbc_out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + + assert!(!our_msbc_theirs.is_empty()); + let corr_msbc = pearson_correlation(&msbc_sine, &our_msbc_theirs, 73); + assert!(corr_msbc > 0.95, "FFmpeg decoded output correlation against our mSBC input too low: {corr_msbc}"); +} From 76fc04feee97dbc070380ab491d6fcaab1c6c34a Mon Sep 17 00:00:00 2001 From: Hamza Naveed <45464935+Hamza0101@users.noreply.github.com> Date: Tue, 17 Nov 2026 07:30:40 +0500 Subject: [PATCH 24/64] craft-docx: relate the bibliography store from the main part, not the package (#1835) --- crates/docx/src/write/parts.rs | 6 +++++- crates/docx/tests/it/roundtrip.rs | 14 +++++++++++--- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/crates/docx/src/write/parts.rs b/crates/docx/src/write/parts.rs index 942da56c2..24d0558a3 100644 --- a/crates/docx/src/write/parts.rs +++ b/crates/docx/src/write/parts.rs @@ -227,6 +227,11 @@ pub(crate) fn write_parts(doc: &Document, flavor: Flavor) -> Result Result Date: Mon, 16 Nov 2026 18:30:43 -0800 Subject: [PATCH 25/64] docking: native palette windows use the X11 utility window type (#1833) --- crates/ui/src/docking/native_tests.rs | 44 ++++++++++++++++++++++++++ crates/ui/src/docking/render/native.rs | 25 +++++++++++++-- crates/ui/src/docking/surface.rs | 5 +++ crates/ui/src/docking/testing.rs | 12 ++++++- 4 files changed, 82 insertions(+), 4 deletions(-) diff --git a/crates/ui/src/docking/native_tests.rs b/crates/ui/src/docking/native_tests.rs index 70d69498a..9431c9625 100644 --- a/crates/ui/src/docking/native_tests.rs +++ b/crates/ui/src/docking/native_tests.rs @@ -577,6 +577,50 @@ fn viewer_windows_stay_shown_at_normal_level() { assert!(!d.host().commands.iter().any(|(_, c)| matches!(c, ViewportCommand::Visible(_))), "no window hides"); } +#[test] +fn palettes_are_x11_utility_windows_and_viewers_normal_ones() { + // Both kinds set `taskbar` to false, which egui applies on Windows. Under X11 on Linux a + // palette is a utility window and a viewer a normal one. + use egui::X11WindowType::{Normal, Utility}; + let palette = if cfg!(target_os = "linux") { Utility } else { Normal }; + let mut layout = layout(false); + layout.floating = vec![Floating::single(vec![5], 0, [300.0, 80.0, 240.0, 300.0]), Floating::single(vec![6], 0, [560.0, 80.0, 240.0, 300.0])]; + let mut d = driver(layout); + d.content.normal = vec![5]; + d.step(vec![]); + let types = |d: &DockDriver| { + [5, 6].map(|panel| { + let window = &d.host().windows[&d.viewport(window(d, panel).id)]; + (window.taskbar, window.window_type) + }) + }; + assert_eq!(types(&d), [(Some(false), Some(Normal)), (Some(false), Some(palette))]); + // The palette becomes a viewer. A new type recreates the window, which opens where it is. + let moved = [700.0, 120.0, 240.0, 300.0]; + d.layout.floating[1].native = Some(moved); + d.step(vec![]); + d.content.normal = vec![5, 6]; + d.step(vec![]); + assert_eq!(types(&d), [(Some(false), Some(Normal)), (Some(false), Some(Normal))]); + if cfg!(target_os = "linux") { + let position = d.host().windows[&d.viewport(window(&d, 6).id)].position; + assert_eq!(position, Some(pos2(moved[0], moved[1]))); + } + // The window system moves the window, and it becomes a palette again before the window + // reports its new place: the new window opens where the window system put it. + d.settle(); + let viewport = d.viewport(window(&d, 6).id); + let os_moved = Rect::from_min_size(pos2(820.0, 160.0), vec2(240.0, 300.0)); + d.host().windows.get_mut(&viewport).unwrap().rect = os_moved; + d.content.normal = vec![5]; + d.step(vec![]); + assert_eq!(types(&d), [(Some(false), Some(Normal)), (Some(false), Some(palette))]); + if cfg!(target_os = "linux") { + let position = d.host().windows[&d.viewport(window(&d, 6).id)].position; + assert_eq!(position, Some(os_moved.min)); + } +} + #[test] fn the_app_comes_forward_with_its_viewers_when_it_is_activated() { use egui::{ViewportId, WindowLevel}; diff --git a/crates/ui/src/docking/render/native.rs b/crates/ui/src/docking/render/native.rs index c21442697..f598d66df 100644 --- a/crates/ui/src/docking/render/native.rs +++ b/crates/ui/src/docking/render/native.rs @@ -13,7 +13,7 @@ use std::{fmt::Debug, hash::Hash, sync::Arc}; use egui::{ Color32, Context, CursorIcon, Event, Id, Key, LayerId, Modifiers, Order, Pos2, RawInput, Rect, ResizeDirection, Sense, Ui, UiBuilder, Vec2, - ViewportBuilder, ViewportClass, ViewportCommand, ViewportId, ViewportInfo, WindowLevel, pos2, vec2, + ViewportBuilder, ViewportClass, ViewportCommand, ViewportId, ViewportInfo, WindowLevel, X11WindowType, pos2, vec2, }; use super::Renderer; @@ -277,6 +277,8 @@ struct Place { /// The height of its bar while minimized, as it was last told. `known` keeps the expanded /// size meanwhile. collapsed: Option, + /// The X11 window type it opened with. + window_type: X11WindowType, } /// Whether two rects differ by more than rounding. @@ -557,6 +559,11 @@ impl Renderer<'_, P> { // A minimized window shows its bar and what `floating_body` draws below it. let collapsed = window.minimized.then(|| BAR_HEIGHT + self.minimized_body(window)); let shown = |[x, y, w, h]: [f32; 4]| [x, y, w, collapsed.unwrap_or(h)]; + // Under X11 on Linux a palette is a utility window, which GNOME and KDE Plasma leave off + // the taskbar. egui ignores the type elsewhere, Wayland included, so there it stays the + // same and egui does not recreate the window when its panels change. + let x11 = cfg!(target_os = "linux") && !wayland(ctx, env_session()); + let window_type = if normal || !x11 { X11WindowType::Normal } else { X11WindowType::Utility }; let mut place = match ctx.data(|d| d.get_temp::(key)) { Some(mut place) => { // The application changed the window's place (undo, reset, a reloaded layout): @@ -583,9 +590,18 @@ impl Renderer<'_, P> { }; seen.insert(window.id); ctx.data_mut(|d| d.insert_temp(seen_key, seen)); - Place { spawn, known: spawn, pending: Some(now + MOVE_WAIT), corrected: false, collapsed: None } + Place { spawn, known: spawn, pending: Some(now + MOVE_WAIT), corrected: false, collapsed: None, window_type } } }; + // egui recreates a window whose type changes. The new window opens where the old one was: + // where the window system last put it, unless a move the application commanded has not + // landed yet. The collapsed height a minimized window reports is not the size to keep. + if place.window_type != window_type { + let waiting = place.pending.is_some_and(|until| now < until); + let latest = info.as_ref().and_then(placed).filter(|_| !waiting && !moving(ctx)); + let at = latest.map_or(place.known, |[x, y, w, h]| [x, y, w, if place.collapsed.is_some() { place.known[3] } else { h }]); + place = Place { spawn: at, known: at, pending: Some(now + MOVE_WAIT), corrected: false, collapsed: None, window_type }; + } // Minimized or expanded: the window keeps its top-left corner and width, and its // height is fixed while it shows only its bar. // The limits go first: the OS clamps the new size to the limits it has. @@ -615,7 +631,10 @@ impl Renderer<'_, P> { (false, true) => WindowLevel::AlwaysOnTop, (false, false) => INACTIVE_PALETTE, }) - .with_taskbar(false); + // No taskbar entry. egui applies `taskbar` only on Windows, and the window type only + // under X11 on Linux. + .with_taskbar(false) + .with_window_type(place.window_type); // The bar replaces the OS title bar. macOS keeps the frame, with its title bar and // buttons hidden: AppKit resizes a movable window from its edges and corners with its // own cursors, and draws its rounded corners and standard shadow. diff --git a/crates/ui/src/docking/surface.rs b/crates/ui/src/docking/surface.rs index 8f8568641..77827a1a9 100644 --- a/crates/ui/src/docking/surface.rs +++ b/crates/ui/src/docking/surface.rs @@ -1164,6 +1164,11 @@ impl<'a, P: Clone + Eq + Hash + Debug + Send + Sync + 'static> DockArea<'a, P> { /// kept for a later run with it on. By default it is on, except on Wayland: the compositor /// reports no window positions, so a native window could not dock again by drag or open /// where it was. + /// + /// A native window has no taskbar entry on Windows. Under X11 on Linux, a palette window has + /// the utility window type, which GNOME and KDE Plasma leave off the taskbar; taskbars that + /// list utility windows unless they are transient for another window (Xfce, MATE) still list + /// it. A native Wayland window and a window under X11 on the BSDs get neither setting. pub fn native_windows(mut self, on: bool) -> Self { self.native_windows = Some(on); self diff --git a/crates/ui/src/docking/testing.rs b/crates/ui/src/docking/testing.rs index 98563362a..feab58c94 100644 --- a/crates/ui/src/docking/testing.rs +++ b/crates/ui/src/docking/testing.rs @@ -467,6 +467,12 @@ pub struct HostWindow { pub visible: bool, /// The window level its builder asked for on its last frame. pub level: Option, + /// Its builder's `position` on its last frame: where the window opens when egui creates it. + pub position: Option, + /// Its builder's `taskbar` setting on its last frame. + pub taskbar: Option, + /// Its builder's X11 window type on its last frame. + pub window_type: Option, /// Frames it drew. pub frames: usize, /// Events for its next frame, in its own coordinates. @@ -567,11 +573,14 @@ impl NativeHost { let builder = &viewport.builder; let rect = Rect::from_min_size(builder.position.unwrap_or_default() + host.frame, builder.inner_size.unwrap_or(vec2(300.0, 200.0))); let visible = builder.visible.unwrap_or(true); - let level = builder.window_level; + let (level, position, taskbar, window_type) = (builder.window_level, builder.position, builder.taskbar, builder.window_type); host.windows.entry(id).or_insert_with(|| HostWindow { rect, visible, level, + position, + taskbar, + window_type, frames: 0, events: Vec::new(), close: false, @@ -587,6 +596,7 @@ impl NativeHost { let Some(window) = host.windows.get_mut(&id) else { return }; window.frames += 1; window.level = level; + (window.position, window.taskbar, window.window_type) = (position, taskbar, window_type); if std::mem::take(&mut window.close) && let Some(info) = viewports.get_mut(&id) { From 996a6b50427aa44f497746fc5656ee81f2408171 Mon Sep 17 00:00:00 2001 From: batistalucasv Date: Mon, 16 Nov 2026 23:30:48 -0300 Subject: [PATCH 26/64] craft-html: container background does not leak into character shading (#1786) (#1803) --- crates/flow/src/from_doc.rs | 10 +- crates/flow/tests/round_trip.rs | 22 + crates/html/src/doc.rs | 2 +- crates/html/src/doc/builder.rs | 110 ++++- crates/html/src/doc/css.rs | 467 +++++++++++++++++- crates/html/src/doc/export.rs | 77 ++- crates/html/src/doc/tests.rs | 831 ++++++++++++++++++++++++++++++++ 7 files changed, 1497 insertions(+), 22 deletions(-) diff --git a/crates/flow/src/from_doc.rs b/crates/flow/src/from_doc.rs index ee9158280..549602ec5 100644 --- a/crates/flow/src/from_doc.rs +++ b/crates/flow/src/from_doc.rs @@ -197,7 +197,7 @@ fn para_extra(doc: &Document, p: &craft_wordmodel::props::ParaProps) -> Option Vec { if c == PAGE_BREAK { if !hidden { out.push_text(&std::mem::take(&mut buf), &f); + let extra = out.extra.as_ref().and_then(|x| { + let mut x = (**x).clone(); + x.drop_cap = None; + x.drop_cap_distance = None; + (x != craft_wordmodel::props::ParaProps::default()).then(|| Box::new(x)) + }); let next = Para { kind, list: None, @@ -562,7 +568,7 @@ fn flow_paras_in(doc: &Document, p: &Paragraph, opts: FlowOpts) -> Vec { mark_ins: None, mark_del: None, fmt_change: None, - extra: None, + extra, mark: None, kept: None, wrap: None, diff --git a/crates/flow/tests/round_trip.rs b/crates/flow/tests/round_trip.rs index 33a508485..9be4213d5 100644 --- a/crates/flow/tests/round_trip.rs +++ b/crates/flow/tests/round_trip.rs @@ -99,3 +99,25 @@ fn pictures_are_sniffed_and_sized_from_their_headers() { let wide = make_img(PNG.to_vec(), Some(1000.0), Some(500.0), "").unwrap(); assert_eq!((wide.w, wide.h), (468.0, 234.0)); } + +#[test] +fn drop_cap_not_repeated_after_page_break() { + let mut doc = craft_wordmodel::Document::default(); + let mut para = craft_wordmodel::Paragraph::with_text("Before\x0cAfter", craft_wordmodel::props::CharProps::default()); + para.props.drop_cap = Some(3); + para.props.drop_cap_distance = Some(72.0); + para.props.shading = Some(craft_wordmodel::Rgb(255, 0, 0)); + doc.body = vec![std::sync::Arc::new(craft_wordmodel::Block::Para(para))]; + + let flow = craft_flow::from_doc_with(&doc, craft_flow::FlowOpts { paras: true, ..Default::default() }); + let paras: Vec<_> = flow.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p) } else { None }).collect(); + assert_eq!(paras.len(), 2); + // First paragraph keeps drop cap and shading + assert_eq!(paras[0].extra.as_ref().and_then(|x| x.drop_cap), Some(3)); + assert_eq!(paras[0].extra.as_ref().and_then(|x| x.drop_cap_distance), Some(72.0)); + assert_eq!(paras[0].extra.as_ref().and_then(|x| x.shading), Some(craft_wordmodel::Rgb(255, 0, 0))); + // Continuation clears drop cap, but preserves shading + assert_eq!(paras[1].extra.as_ref().and_then(|x| x.drop_cap), None); + assert_eq!(paras[1].extra.as_ref().and_then(|x| x.drop_cap_distance), None); + assert_eq!(paras[1].extra.as_ref().and_then(|x| x.shading), Some(craft_wordmodel::Rgb(255, 0, 0))); +} diff --git a/crates/html/src/doc.rs b/crates/html/src/doc.rs index 56b8aabbc..c8598639e 100644 --- a/crates/html/src/doc.rs +++ b/crates/html/src/doc.rs @@ -21,7 +21,7 @@ use std::sync::Arc; use craft_wordmodel::props::LineSpacing; use craft_wordmodel::props::VAlign; -use craft_wordmodel::{Align, Document}; +use craft_wordmodel::{Align, Document, Rgb}; use craft_flow::{ self as model, Cell, FBlock, FTable, Flow, Fmt, Inline, Kind, ListInfo, Meta, Para, Spacing, base64_encode, data_uri, make_img, mime_of, diff --git a/crates/html/src/doc/builder.rs b/crates/html/src/doc/builder.rs index 32ba2a7f3..68bb7d8db 100644 --- a/crates/html/src/doc/builder.rs +++ b/crates/html/src/doc/builder.rs @@ -1,7 +1,7 @@ use super::css::{apply_style, css_len_pt, strip_important}; use super::import::{PAGE_FONT, PAGE_HEADING_SIZES, collapse_ws}; use super::{ - Align, Arc, Cell, FBlock, FTable, Flow, Fmt, Inline, Kind, LineSpacing, ListInfo, Meta, Para, Spacing, VAlign, data_uri, make_img, model, + Align, Arc, Cell, FBlock, FTable, Flow, Fmt, Inline, Kind, LineSpacing, ListInfo, Meta, Para, Rgb, Spacing, VAlign, data_uri, make_img, model, parse_color, }; @@ -31,6 +31,11 @@ struct El { name: String, kind: ElKind, fmt: Fmt, + /// Block or container background declared on this element (e.g. div, p, pre, table, cell), + /// kept separate from character shading (`fmt.background`) so child elements can explicitly + /// inherit it (`background: inherit` / `background-color: inherit`) and table cells can + /// resolve shading through transparent row groups or rows (#1786). + block_background: Option, /// Margins, indents and line height its CSS states (blocks only; they don't inherit; on a /// page's spans, their margins). spacing: Spacing, @@ -54,6 +59,7 @@ struct TableB { struct ElementStyle { fmt: Fmt, + block_background: Option, align: Option, preserve: bool, page_break: bool, @@ -650,6 +656,16 @@ impl<'r> Builder<'r> { } let pb_before = self.stack.iter_mut().rev().take_while(|e| e.kind != ElKind::Cell).any(|e| std::mem::take(&mut e.page_break)); p.page_break = pb_before || std::mem::take(&mut self.pending_page_break); + let block_shading = self + .stack + .iter() + .rev() + .take_while(|e| e.kind != ElKind::Cell && e.kind != ElKind::Table) + .filter(|e| self.page || !matches!(e.name.as_str(), "body" | "html")) + .find_map(|e| e.block_background); + if let Some(bg) = block_shading { + p.extra.get_or_insert_with(Default::default).shading = Some(bg); + } self.para = Some(p); } self.para.get_or_insert_with(Para::default) @@ -700,6 +716,35 @@ impl<'r> Builder<'r> { && prev.list.is_some() && prev.list.map(|l| l.level) == level { + let prev_bg = prev.extra.as_ref().and_then(|x| x.shading); + let cont_bg = p.extra.as_ref().and_then(|x| x.shading); + if prev_bg != cont_bg { + if let Some(bg) = prev_bg { + for inline in &mut prev.inlines { + let fmt = match inline { + Inline::Text(_, fmt) | Inline::Ruby { fmt, .. } => fmt, + _ => continue, + }; + if fmt.background.is_none() { + fmt.background = Some(bg); + } + } + if let Some(extra) = &mut prev.extra { + extra.shading = None; + } + } + if let Some(bg) = cont_bg { + for inline in &mut p.inlines { + let fmt = match inline { + Inline::Text(_, fmt) | Inline::Ruby { fmt, .. } => fmt, + _ => continue, + }; + if fmt.background.is_none() { + fmt.background = Some(bg); + } + } + } + } prev.push_text("\n", &Fmt::default()); prev.inlines.extend(p.inlines); return; @@ -933,6 +978,11 @@ impl<'r> Builder<'r> { { self.pop_to(k); } + if matches!(name, "tbody" | "thead" | "tfoot") + && let Some(k) = self.find_open(|e| matches!(e.name.as_str(), "tbody" | "thead" | "tfoot"), |e| e.kind == ElKind::Table) + { + self.pop_to(k); + } if is_table_part && !self.tables.is_empty() { if matches!(name, "td" | "th") && let Some(k) = self.find_open(|e| e.kind == ElKind::Cell, |e| matches!(e.kind, ElKind::Table | ElKind::Tr)) @@ -1049,11 +1099,34 @@ impl<'r> Builder<'r> { fmt.color.get_or_insert(craft_wordmodel::Rgb(0, 0, 0)); fmt.size = PAGE_HEADING_SIZES.get(usize::from(n.clamp(1, 6)) - 1).copied(); } - apply_style(css, &mut fmt, &mut align, &mut preserve, &mut page_break, &mut page_break_after); + if kind != ElKind::Inline { + // CSS background does not inherit from inline ancestors to non-inline elements (#1786). + // HTML bgcolor presentational attribute supplies the initial background, which can be + // overridden or cleared by CSS declarations in apply_style. + fmt.background = attr(attrs, "bgcolor").and_then(parse_color); + } + let parent_bg = self + .stack + .last() + .and_then(|e| if !self.page && matches!(e.name.as_str(), "body" | "html") { None } else { e.fmt.background.or(e.block_background) }); + apply_style(css, &mut fmt, &mut align, &mut preserve, &mut page_break, &mut page_break_after, parent_bg); if kind == ElKind::Pre { preserve = true; } - ElementStyle { fmt, align, preserve, page_break, page_break_after } + // CSS background-color does not inherit to child text runs; container elements (div, p, + // pre, table, row groups, cells, etc.) do not set character shading (#1786). Container + // backgrounds are saved to `block_background` for paragraph shading on block containers, + // explicit child inheritance (`background: inherit`), and table cell shading, while + // character shading `fmt.background` is kept `None`. + let block_background = if kind != ElKind::Inline { fmt.background.take() } else { None }; + let has_root_bg = + block_background.is_some() || self.stack.iter().any(|e| matches!(e.name.as_str(), "body" | "html") && e.block_background.is_some()); + if !self.page && matches!(name, "body" | "html") && has_root_bg { + // A pasted fragment drops the root background; its foreground was chosen for that + // background, so drop it too rather than painting light text on the page default. + fmt.color = None; + } + ElementStyle { fmt, block_background, align, preserve, page_break, page_break_after } } pub(super) fn start(&mut self, name: &str, attrs: &[(String, String)], self_close: bool) { @@ -1089,7 +1162,7 @@ impl<'r> Builder<'r> { self.flush(); } let css = self.css_of(name, attrs); - let ElementStyle { mut fmt, align, preserve, page_break, page_break_after } = self.element_style(name, attrs, kind, &css); + let ElementStyle { mut fmt, block_background, align, preserve, page_break, page_break_after } = self.element_style(name, attrs, kind, &css); match kind { ElKind::Table => self.tables.push(TableB { rows: Vec::new(), row: None, bordered: declares_border(attrs, &css, true) }), ElKind::Tr => { @@ -1115,7 +1188,20 @@ impl<'r> Builder<'r> { } let num = |k: &str| attr(attrs, k).and_then(|v| v.trim().parse::().ok()).map(|v| v.clamp(1, 63)); let colspan = num("colspan").unwrap_or(1); - let shading = attr(attrs, "bgcolor").and_then(parse_color).or(fmt.background); + let shading = block_background.or_else(|| { + for e in self.stack.iter().rev() { + if !self.page && matches!(e.name.as_str(), "body" | "html") { + continue; + } + if let Some(bg) = e.block_background { + return Some(bg); + } + if e.kind == ElKind::Cell { + break; + } + } + None + }); let mut valign = attr(attrs, "valign").and_then(|v| match v.trim().to_ascii_lowercase().as_str() { "top" => Some(VAlign::Top), "middle" | "center" => Some(VAlign::Center), @@ -1153,7 +1239,19 @@ impl<'r> Builder<'r> { let spacing = if (kind != ElKind::Inline || self.page) && !matches!(name, "body" | "html") { block_spacing(&css) } else { Spacing::default() }; let auto_margins = self.page && (name == "p" || matches!(kind, ElKind::Heading(_))); - self.stack.push(El { name: name.to_string(), kind, fmt, spacing, auto_margins, align, preserve, page_break, page_break_after, used: false }); + self.stack.push(El { + name: name.to_string(), + kind, + fmt, + block_background, + spacing, + auto_margins, + align, + preserve, + page_break, + page_break_after, + used: false, + }); } pub(super) fn end(&mut self, name: &str) { diff --git a/crates/html/src/doc/css.rs b/crates/html/src/doc/css.rs index 9dc6d7526..b5b230dc8 100644 --- a/crates/html/src/doc/css.rs +++ b/crates/html/src/doc/css.rs @@ -1,6 +1,6 @@ use super::builder::decls; use super::import::PAGE_FONT; -use super::{Align, Fmt, model, parse_color}; +use super::{Align, Fmt, Rgb, model, parse_color}; /// A CSS length (or font-size keyword) in points; `None` when it is not one. pub fn css_len_pt(v: &str) -> Option { @@ -88,7 +88,398 @@ pub(super) fn css_unescape(s: &str) -> String { o } -/// Apply a `style` attribute to formatting / block properties. +/// Maximum number of tokens parsed in a CSS background shorthand declaration to prevent DOS. +const MAX_CSS_SHORTHAND_TOKENS: usize = 64; + +/// Returns true if `c` is a CSS whitespace character according to CSS Syntax Level 3 § 4.2. +/// +/// Only U+0020 (space), U+0009 (tab), U+000A (LF), U+000C (FF), and U+000D (CR) are CSS whitespace. +/// Non-breaking space (U+00A0) and other Unicode whitespace characters are not CSS whitespace. +fn is_css_whitespace(c: char) -> bool { + matches!(c, ' ' | '\t' | '\n' | '\x0C' | '\r') +} + +/// Trims leading and trailing CSS whitespace from a string slice according to CSS Syntax Level 3 § 4.2. +fn trim_css_whitespace(s: &str) -> &str { + s.trim_matches(is_css_whitespace) +} + +/// Check whether a token is a valid CSS length or percentage value. +/// +/// Returns `true` for `"0"` or numeric quantities ending in valid CSS length units +/// (`px`, `pt`, `em`, `rem`, `%`, `in`, `cm`, `mm`, `vw`, `vh`, `vmin`, `vmax`, `pc`, `ch`, `ex`). +fn is_length_or_percentage(s: &str) -> bool { + let s = trim_css_whitespace(s); + if s.parse::().is_ok_and(|x| x == 0.0) { + return true; + } + let units = ["px", "pt", "em", "rem", "%", "in", "cm", "mm", "vw", "vh", "vmin", "vmax", "pc", "ch", "ex"]; + for unit in units { + if let Some(num_str) = s.strip_suffix(unit) + && trim_css_whitespace(num_str).parse::().is_ok_and(|x| x.is_finite()) + { + return true; + } + } + false +} + +/// Represents a parsed CSS background layer containing its tokens and depth-zero slash count. +struct BgLayer<'a> { + /// Tokens belonging to this layer, trimmed of CSS whitespace. + tokens: Vec<&'a str>, + /// Number of slashes occurring at parenthesis depth 0 in this layer. + depth_zero_slashes: usize, +} + +/// Push a sliced and trimmed token to the layer's token list, enforcing the shorthand token limit. +fn push_shorthand_token<'a>(val: &'a str, start: &mut Option, end: usize, tokens: &mut Vec<&'a str>, total_tokens: &mut usize) -> Option<()> { + if let Some(s) = start.take() + && let Some(token) = val.get(s..end) + { + let trimmed = trim_css_whitespace(token); + if !trimmed.is_empty() { + if *total_tokens >= MAX_CSS_SHORTHAND_TOKENS { + return None; + } + tokens.push(trimmed); + *total_tokens = total_tokens.saturating_add(1); + } + } + Some(()) +} + +/// Parse CSS background shorthand value into comma-separated layers and tokens. +/// +/// Respects quotes and parenthesis depth. Rejects and returns `None` if the token +/// limit `MAX_CSS_SHORTHAND_TOKENS` is exceeded (indicating hostile or truncated input), +/// or if quotes or parentheses are unbalanced. +fn parse_bg_layers(val: &str) -> Option>> { + let mut layers = Vec::new(); + let mut current_tokens = Vec::new(); + let mut current_slashes = 0usize; + let mut total_tokens = 0usize; + + let mut start = None; + let mut paren_depth = 0usize; + let mut in_quote = None; + let mut escaped = false; + let mut in_raw_url = false; + + let mut byte_idx = 0; + while byte_idx < val.len() { + let Some(c) = val[byte_idx..].chars().next() else { break }; + let char_len = c.len_utf8(); + let i = byte_idx; + byte_idx += char_len; + + if escaped { + escaped = false; + continue; + } + if c == '\\' { + escaped = true; + if start.is_none() { + start = Some(i); + } + continue; + } + if let Some(q) = in_quote { + if c == q { + in_quote = None; + } + } else if c == '\'' || c == '"' { + in_quote = Some(c); + if start.is_none() { + start = Some(i); + } + } else if !in_raw_url && val[i..].starts_with("/*") { + // CSS comments outside strings and URLs are consumed before delimiter classification + if paren_depth == 0 { + push_shorthand_token(val, &mut start, i, &mut current_tokens, &mut total_tokens)?; + } + if let Some(end_offset) = val[i + 2..].find("*/") { + byte_idx = i + 2 + end_offset + 2; + } else { + byte_idx = val.len(); + } + continue; + } else if c == '(' { + if in_quote.is_none() + && let Some(s) = start + && val.get(s..i).is_some_and(|prefix| trim_css_whitespace(prefix).eq_ignore_ascii_case("url")) + { + in_raw_url = true; + } + paren_depth = paren_depth.saturating_add(1); + if start.is_none() { + start = Some(i); + } + } else if c == ')' { + if paren_depth == 0 { + return None; + } + paren_depth -= 1; + if paren_depth == 0 { + in_raw_url = false; + } + } else if paren_depth == 0 { + if c == '/' { + current_slashes = current_slashes.saturating_add(1); + push_shorthand_token(val, &mut start, i, &mut current_tokens, &mut total_tokens)?; + if total_tokens >= MAX_CSS_SHORTHAND_TOKENS { + return None; + } + if let Some(slash_token) = val.get(i..i + 1) { + current_tokens.push(slash_token); + total_tokens = total_tokens.saturating_add(1); + } + } else if c == ',' { + push_shorthand_token(val, &mut start, i, &mut current_tokens, &mut total_tokens)?; + if current_tokens.is_empty() { + return None; + } + layers.push(BgLayer { tokens: std::mem::take(&mut current_tokens), depth_zero_slashes: current_slashes }); + current_slashes = 0; + } else if is_css_whitespace(c) { + push_shorthand_token(val, &mut start, i, &mut current_tokens, &mut total_tokens)?; + } else if start.is_none() { + start = Some(i); + } + } else if start.is_none() { + start = Some(i); + } + } + + if escaped || paren_depth != 0 || in_quote.is_some() { + return None; + } + + push_shorthand_token(val, &mut start, val.len(), &mut current_tokens, &mut total_tokens)?; + + if current_tokens.is_empty() { + return None; + } + + layers.push(BgLayer { tokens: current_tokens, depth_zero_slashes: current_slashes }); + + Some(layers) +} + +fn is_valid_rgb_component(s: &str) -> bool { + let s = trim_css_whitespace(s); + if s.eq_ignore_ascii_case("none") { + return true; + } + if let Some(p) = s.strip_suffix('%') { + trim_css_whitespace(p).parse::().is_ok_and(|v| v.is_finite()) + } else { + s.parse::().is_ok_and(|v| v.is_finite()) + } +} + +fn is_valid_hue_component(s: &str) -> bool { + let s = trim_css_whitespace(s); + if s.eq_ignore_ascii_case("none") { + return true; + } + let num_str = if let Some(deg) = s.strip_suffix("deg") { + deg + } else if let Some(rad) = s.strip_suffix("rad") { + rad + } else if let Some(turn) = s.strip_suffix("turn") { + turn + } else { + s + }; + trim_css_whitespace(num_str).parse::().is_ok_and(|v| v.is_finite()) +} + +fn is_valid_zero_alpha(a: &str) -> bool { + let a = trim_css_whitespace(a); + if a.eq_ignore_ascii_case("none") || a == "0" || a == "0%" || a == "0.0" { + return true; + } + if let Some(p) = a.strip_suffix('%') { + trim_css_whitespace(p).parse::().is_ok_and(|v| v <= 0.0) + } else { + a.parse::().is_ok_and(|v| v <= 0.0) + } +} + +/// Returns true if a CSS color expression specifies a fully transparent color (alpha = 0). +fn is_zero_alpha_color(s: &str) -> bool { + let s = trim_css_whitespace(s).to_ascii_lowercase(); + if s == "transparent" { + return true; + } + if let Some(h) = s.strip_prefix('#') { + if h.len() == 4 && h.ends_with('0') && h.bytes().all(|b| b.is_ascii_hexdigit()) { + return true; + } + if h.len() == 8 && h.ends_with("00") && h.bytes().all(|b| b.is_ascii_hexdigit()) { + return true; + } + return false; + } + if let Some(inner) = s.strip_prefix("rgb(").or_else(|| s.strip_prefix("rgba(")) { + let Some(inner) = inner.strip_suffix(')') else { return false }; + let (rgb_part, alpha_part) = inner.split_once('/').map_or((inner, None), |(a, b)| (a, Some(b))); + let (parts, alpha_str) = match alpha_part { + Some(a) => { + let parts: Vec<&str> = if rgb_part.contains(',') { rgb_part.split(',').collect() } else { rgb_part.split_whitespace().collect() }; + (parts, a) + } + None => { + let parts: Vec<&str> = if inner.contains(',') { inner.split(',').collect() } else { inner.split_whitespace().collect() }; + if parts.len() == 4 { + (parts[..3].to_vec(), parts[3]) + } else { + return false; + } + } + }; + return parts.len() == 3 && parts.iter().all(|&p| is_valid_rgb_component(p)) && is_valid_zero_alpha(alpha_str); + } + if let Some(inner) = s.strip_prefix("hsl(").or_else(|| s.strip_prefix("hsla(")) { + let Some(inner) = inner.strip_suffix(')') else { return false }; + let (hsl_part, alpha_part) = inner.split_once('/').map_or((inner, None), |(a, b)| (a, Some(b))); + let (parts, alpha_str) = match alpha_part { + Some(a) => { + let parts: Vec<&str> = if hsl_part.contains(',') { hsl_part.split(',').collect() } else { hsl_part.split_whitespace().collect() }; + (parts, a) + } + None => { + let parts: Vec<&str> = if inner.contains(',') { inner.split(',').collect() } else { inner.split_whitespace().collect() }; + if parts.len() == 4 { + (parts[..3].to_vec(), parts[3]) + } else { + return false; + } + } + }; + return parts.len() == 3 + && is_valid_hue_component(parts[0]) + && is_valid_rgb_component(parts[1]) + && is_valid_rgb_component(parts[2]) + && is_valid_zero_alpha(alpha_str); + } + false +} + +/// Returns true if a lowercase token represents a recognized CSS image function. +fn is_valid_image_function(ltok: &str) -> bool { + if !ltok.ends_with(')') { + return false; + } + ltok.starts_with("url(") + || ltok.starts_with("image(") + || ltok.starts_with("image-set(") + || ltok.starts_with("-webkit-image-set(") + || ltok.starts_with("cross-fade(") + || ltok.starts_with("element(") + || ltok.starts_with("paint(") + || ltok.starts_with("linear-gradient(") + || ltok.starts_with("radial-gradient(") + || ltok.starts_with("conic-gradient(") + || ltok.starts_with("repeating-linear-gradient(") + || ltok.starts_with("repeating-radial-gradient(") + || ltok.starts_with("repeating-conic-gradient(") + || ltok.starts_with("-webkit-linear-gradient(") + || ltok.starts_with("-webkit-radial-gradient(") + || ltok.starts_with("-webkit-gradient(") + || ltok.starts_with("-moz-linear-gradient(") + || ltok.starts_with("-moz-radial-gradient(") +} + +/// Returns true if a lowercase token represents a recognized CSS math or environment function. +fn is_valid_math_or_value_function(ltok: &str) -> bool { + if !ltok.ends_with(')') { + return false; + } + ltok.starts_with("calc(") + || ltok.starts_with("min(") + || ltok.starts_with("max(") + || ltok.starts_with("clamp(") + || ltok.starts_with("var(") + || ltok.starts_with("env(") +} + +/// Check whether a token is a valid CSS background position component (`top`, `bottom`, `left`, `right`, `center`, length, percentage, or math function). +fn is_valid_pos_token(s: &str) -> bool { + let ls = s.to_ascii_lowercase(); + matches!(ls.as_str(), "top" | "bottom" | "left" | "right" | "center") || is_length_or_percentage(&ls) || is_valid_math_or_value_function(&ls) +} + +/// Check whether a token is a valid CSS background size component (`auto`, length, percentage, or math function). +fn is_valid_size_component(s: &str) -> bool { + let ls = s.to_ascii_lowercase(); + ls == "auto" || is_length_or_percentage(&ls) || is_valid_math_or_value_function(&ls) +} + +/// Check whether a token is a valid CSS background property token outside of position-and-size slash expressions. +/// +/// Recognizes color names/hex codes, images, repeat styles, attachments, and box keywords. +/// Standalone size keywords (`cover`, `contain`, `auto`) and slashes are rejected unless positioned in a valid slash layer. +fn is_valid_non_slash_bg_token(tok: &str) -> bool { + let ltok = tok.to_ascii_lowercase(); + if is_valid_image_function(<ok) || is_valid_math_or_value_function(<ok) { + return true; + } + if is_zero_alpha_color(tok) || parse_color(tok).is_some() || ltok == "transparent" { + return true; + } + match ltok.as_str() { + "none" | "repeat" | "no-repeat" | "repeat-x" | "repeat-y" | "space" | "round" | "scroll" | "fixed" | "local" | "border-box" + | "padding-box" | "content-box" | "top" | "bottom" | "left" | "right" | "center" => true, + _ => is_length_or_percentage(<ok), + } +} + +/// Validate that a single CSS background shorthand layer satisfies the position-and-size grammar. +/// +/// If depth-zero slashes are present, exactly one slash must separate a valid `` from a valid ``. +/// Background size keywords `cover` and `contain` are rejected unless preceded by a valid position and slash (#1786). +fn is_valid_bg_layer(layer: &BgLayer<'_>) -> bool { + if layer.depth_zero_slashes > 1 { + return false; + } + if layer.depth_zero_slashes == 0 { + return layer.tokens.iter().all(|t| is_valid_non_slash_bg_token(t)); + } + + let Some(slash_idx) = layer.tokens.iter().position(|&t| t == "/") else { + return false; + }; + let before_tokens = &layer.tokens[..slash_idx]; + let after_tokens = &layer.tokens[slash_idx + 1..]; + + let Some(&last_before) = before_tokens.last() else { + return false; + }; + if !is_valid_pos_token(last_before) { + return false; + } + if !before_tokens[..before_tokens.len().saturating_sub(1)].iter().all(|t| is_valid_non_slash_bg_token(t)) { + return false; + } + + if after_tokens.is_empty() { + return false; + } + let first_after = after_tokens[0]; + let remaining_after = if first_after.eq_ignore_ascii_case("cover") || first_after.eq_ignore_ascii_case("contain") { + &after_tokens[1..] + } else if is_valid_size_component(first_after) { + if after_tokens.len() > 1 && is_valid_size_component(after_tokens[1]) { &after_tokens[2..] } else { &after_tokens[1..] } + } else { + return false; + }; + + remaining_after.iter().all(|t| is_valid_non_slash_bg_token(t)) +} + +/// Apply CSS `style` declarations to formatting and block properties, updating character and block attributes. pub(super) fn apply_style( css: &str, f: &mut Fmt, @@ -96,6 +487,7 @@ pub(super) fn apply_style( preserve: &mut bool, page_break: &mut bool, page_break_after: &mut bool, + parent_bg: Option, ) { for (k, v) in decls(css) { let lv = v.to_ascii_lowercase(); @@ -119,11 +511,78 @@ pub(super) fn apply_style( f.color = Some(c); } } - "background-color" | "background" => { - if let Some(c) = v.split_whitespace().find_map(parse_color) { + "background-color" => { + let trimmed = trim_css_whitespace(v); + let lv = trimmed.to_ascii_lowercase(); + if lv == "transparent" || lv == "none" || lv == "initial" || lv == "unset" || is_zero_alpha_color(trimmed) { + f.background = None; + } else if lv == "inherit" { + f.background = parent_bg; + } else if let Some(c) = parse_color(trimmed) { f.background = Some(c); } } + "background" => { + let Some(layers) = parse_bg_layers(v) else { + continue; + }; + + // CSS-wide keywords (inherit, initial, unset) must be the sole value of the declaration. + if layers.len() == 1 && layers[0].tokens.len() == 1 { + let first = layers[0].tokens[0].to_ascii_lowercase(); + match first.as_str() { + "inherit" => { + f.background = parent_bg; + continue; + } + "initial" | "unset" | "none" | "transparent" => { + f.background = None; + continue; + } + _ => {} + } + } else if layers.iter().any(|l| l.tokens.iter().any(|t| matches!(t.to_ascii_lowercase().as_str(), "inherit" | "initial" | "unset"))) { + // Invalid CSS: CSS-wide keywords cannot be combined with other values. + continue; + } + + // In CSS background shorthand: + // 1. Each layer may have at most one slash separating position and size. + // 2. All layers must satisfy the grammar (e.g. `cover` requires position and slash). + // 3. Only the final layer may specify a background color. + if !layers.iter().all(is_valid_bg_layer) { + continue; + } + + // Only the final layer can specify background-color. If any earlier layer has a color, + // the entire declaration is invalid CSS. + let earlier_has_color = layers[..layers.len().saturating_sub(1)] + .iter() + .any(|l| l.tokens.iter().any(|t| is_zero_alpha_color(t) || parse_color(t).is_some())); + if earlier_has_color { + continue; + } + + // Extract background color from the final layer. + let final_layer = &layers[layers.len().saturating_sub(1)]; + let color_tokens: Vec<_> = + final_layer.tokens.iter().copied().filter(|t| is_zero_alpha_color(t) || parse_color(t).is_some()).collect(); + if color_tokens.len() > 1 { + // Invalid CSS: multiple background colors in a single layer. + continue; + } + if let Some(&tok) = color_tokens.first() { + if is_zero_alpha_color(tok) { + f.background = None; + } else if let Some(c) = parse_color(tok) { + f.background = Some(c); + } + } else { + // A valid background shorthand without a color (such as background: url(...) or none repeat) + // resets background-color to transparent. + f.background = None; + } + } "font-size" => { if let Some(p) = css_len_pt(v).filter(|p| *p >= 1.0 && *p <= 1638.0) { f.size = Some(p); diff --git a/crates/html/src/doc/export.rs b/crates/html/src/doc/export.rs index 78f6d9ae8..9fb861d85 100644 --- a/crates/html/src/doc/export.rs +++ b/crates/html/src/doc/export.rs @@ -183,18 +183,70 @@ pub fn inlines_html(inlines: &[Inline]) -> String { o } +/// Formatted code inline spans inside `
`: preserves formatting tags while keeping
+/// raw whitespace semantics (spaces and tabs are preserved, not converted to ` ` or `
`). +fn code_inlines_html(inlines: &[Inline]) -> String { + let mut o = String::new(); + for i in inlines { + match i { + Inline::Text(t, f) => { + let (open, close) = fmt_tags(f); + o.push_str(&open); + o.push_str(&esc(t)); + for c in close.iter().rev() { + o.push_str(c); + } + } + Inline::Ruby { base, ruby, fmt } => { + let (open, close) = fmt_tags(fmt); + o.push_str(&open); + o.push_str(&format!("{}{}", esc(base), esc(ruby))); + for c in close.iter().rev() { + o.push_str(c); + } + } + Inline::Anchor(a) => o.push_str(&format!("", esc(a))), + Inline::Image(img) => { + o.push_str(&format!( + "\"{}\"", + mime_of(&img.ext), + base64_encode(&img.data), + esc(&img.alt), + (img.w / 0.75).round(), + (img.h / 0.75).round() + )); + } + Inline::Field { result, fmt, .. } | Inline::Control { text: result, fmt, .. } => { + let (open, close) = fmt_tags(fmt); + o.push_str(&open); + o.push_str(&esc(result)); + for c in close.iter().rev() { + o.push_str(c); + } + } + Inline::Figure(alt) | Inline::Chart(craft_flow::Chart { alt, .. }) => o.push_str(&format!("\"{}\"", esc(alt))), + Inline::Equation { linear, display } => o.push_str(&craft_math::mathml::linear_to_mathml(linear, *display)), + _ => {} + } + } + o +} + fn trim_num(v: f32) -> String { let s = format!("{:.2}", v); s.trim_end_matches('0').trim_end_matches('.').to_string() } fn para_attrs(p: &Para) -> String { - let mut css: Vec<&str> = Vec::new(); + let mut css: Vec = Vec::new(); if let Some(a) = align_css(p.align) { - css.push(a); + css.push(a.to_string()); } if p.page_break { - css.push("break-before:page;page-break-before:always"); + css.push("break-before:page;page-break-before:always".to_string()); + } + if let Some(bg) = p.extra.as_ref().and_then(|x| x.shading) { + css.push(format!("background-color:#{}", bg.hex())); } if css.is_empty() { String::new() } else { format!(" style=\"{}\"", css.join(";")) } } @@ -240,7 +292,11 @@ fn table_html(t: &FTable, out: &mut String, depth: usize) { css.push(format!("background-color:#{}", s.hex())); } let single = match c.blocks.as_slice() { - [FBlock::Para(p)] if p.kind == Kind::Normal && p.list.is_none() && !p.page_break => Some(p), + [FBlock::Para(p)] + if p.kind == Kind::Normal && p.list.is_none() && !p.page_break && p.extra.as_ref().and_then(|x| x.shading).is_none() => + { + Some(p) + } _ => None, }; if let Some(a) = single.and_then(|p| align_css(p.align)) { @@ -310,17 +366,20 @@ fn blocks_html(blocks: &[FBlock], out: &mut String, depth: usize) { out.push('\n'); } FBlock::Para(p) if p.kind == Kind::Code => { - out.push_str("
");
+                // One `
` per run of code paragraphs whose attributes match: they share the
+                // `
`'s shading, so a different background starts a new block.
+                let attrs = para_attrs(p);
+                out.push_str(&format!(""));
                 let mut first = true;
                 while let Some(FBlock::Para(q)) = blocks.get(i) {
-                    if q.kind != Kind::Code || q.list.is_some() {
+                    if q.kind != Kind::Code || q.list.is_some() || para_attrs(q) != attrs {
                         break;
                     }
                     if !first {
                         out.push('\n');
                     }
                     first = false;
-                    out.push_str(&esc(&q.text()));
+                    out.push_str(&code_inlines_html(&q.inlines));
                     i += 1;
                 }
                 out.push_str("
\n"); @@ -357,14 +416,14 @@ fn close_list(stack: &mut Vec<(bool, bool)>, out: &mut String) { /// A complete HTML document. pub fn export(doc: &Document) -> String { - let flow = model::from_doc(doc); + let flow = model::from_doc_with(doc, model::FlowOpts { paras: true, ..Default::default() }); export_flow(&flow, doc.styles.default_chr.lang.as_deref().unwrap_or("en")) } /// `doc`'s content as an HTML fragment (no head or style sheet): what a copy puts on the system /// clipboard beside its text, equations as MathML (#816). pub fn export_fragment(doc: &Document) -> String { - let flow = model::from_doc(doc); + let flow = model::from_doc_with(doc, model::FlowOpts { paras: true, ..Default::default() }); let mut out = String::from(""); blocks_html(&flow.blocks, &mut out, 0); out diff --git a/crates/html/src/doc/tests.rs b/crates/html/src/doc/tests.rs index 640ab07d0..c0b00084b 100644 --- a/crates/html/src/doc/tests.rs +++ b/crates/html/src/doc/tests.rs @@ -767,3 +767,834 @@ fn hostile_style_sheets_never_panic() { let _ = parse_in(&format!("

x

y"), &|_| None, true); } } + +/// Ensure container elements (such as `div` and `p`) with background colors do not leak +/// character shading onto their child text runs (#1786). +#[test] +fn container_background_color_does_not_leak_into_character_shading() { + let html = r#"
code
"#; + let doc = import(html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert!(!p.runs.is_empty(), "expected nonempty runs"); + assert_eq!(&p.text, "code"); + assert_eq!(p.props.shading, Some(craft_wordmodel::Rgb(0x1e, 0x1e, 0x1e)), "container div background is preserved as paragraph shading"); + for r in &p.runs { + assert_eq!(r.props.shading, None, "character should have no shading from container div"); + } +} + +/// Verify that table background colors cascade down to cell shading through implicit or explicit +/// row groups (`tbody`, `thead`, `tfoot`), but do not leak into cell character shading. +#[test] +fn table_background_inherits_through_row_groups() { + let html = r#"
cell1
+
cell2
+
head
"#; + let doc = import(html); + let tables: Vec<_> = doc + .body + .iter() + .filter_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t), + _ => None, + }) + .collect(); + assert_eq!(tables.len(), 3); + for (t, want_hex) in tables.iter().zip(["e8f0fa", "d0e0f0", "c0d0e0"]) { + let cell = &t.rows[0].cells[0]; + assert_eq!( + cell.props.shading.map(|c| c.hex().to_ascii_lowercase()), + Some(want_hex.to_string()), + "cell should inherit shading from table or row group" + ); + let p = &cell.blocks[0]; + let craft_wordmodel::Block::Para(p) = &**p else { + panic!("expected table cell block to be a paragraph"); + }; + assert!(!p.runs.is_empty(), "expected nonempty runs"); + for r in &p.runs { + assert_eq!(r.props.shading, None, "cell text should have no character shading"); + } + } +} + +/// Verify that block-level container backgrounds (`p`, `pre`, `div`) are preserved as paragraph +/// shading on paragraphs rather than character shading on individual runs (#1786). +#[test] +fn block_element_backgrounds_preserve_paragraph_shading() { + let html = r#"

text

code

inner

"#; + let doc = import(html); + assert_eq!(doc.body.len(), 3); + let craft_wordmodel::Block::Para(p1) = &*doc.body[0] else { panic!("expected Para") }; + let craft_wordmodel::Block::Para(p2) = &*doc.body[1] else { panic!("expected Para") }; + let craft_wordmodel::Block::Para(p3) = &*doc.body[2] else { panic!("expected Para") }; + assert_eq!(p1.props.shading, Some(craft_wordmodel::Rgb(0x1e, 0x1e, 0x1e))); + assert_eq!(p2.props.shading, Some(craft_wordmodel::Rgb(0x2a, 0x2a, 0x2a))); + assert_eq!(p3.props.shading, Some(craft_wordmodel::Rgb(0x3a, 0x3a, 0x3a))); + assert_eq!(&p1.text, "text"); + assert_eq!(&p2.text, "code"); + assert_eq!(&p3.text, "inner"); + assert!(!p1.runs.is_empty()); + assert!(!p2.runs.is_empty()); + assert!(!p3.runs.is_empty()); + for r in &p1.runs { + assert_eq!(r.props.shading, None, "character should have no shading from paragraph background"); + } + for r in &p2.runs { + assert_eq!(r.props.shading, None, "character should have no shading from pre background"); + } + for r in &p3.runs { + assert_eq!(r.props.shading, None, "character should have no shading from container div background"); + } +} + +/// Verify that paragraph shading created by a container background survives an HTML round trip (#1786). +#[test] +fn paragraph_shading_survives_an_html_round_trip() { + let html = r#"

code

pre
"#; + let doc = import(html); + let out = export(&doc); + assert!(out.contains("background-color:#1E1E1E"), "paragraph shading is exported: {out}"); + assert!(out.contains("background-color:#2A2A2A"), "code block shading is exported: {out}"); + + let back = import(&out); + let craft_wordmodel::Block::Para(p1) = &*back.body[0] else { panic!("expected Para") }; + let craft_wordmodel::Block::Para(p2) = &*back.body[1] else { panic!("expected Para") }; + assert_eq!(p1.props.shading, Some(craft_wordmodel::Rgb(0x1e, 0x1e, 0x1e))); + assert_eq!(p2.props.shading, Some(craft_wordmodel::Rgb(0x2a, 0x2a, 0x2a))); +} + +/// Verify that paragraph shading inside a single-paragraph table cell survives an HTML round trip (#1786). +#[test] +fn table_cell_paragraph_shading_survives_an_html_round_trip() { + let html = r#"

text

"#; + let doc = import(html); + let out = export(&doc); + assert!(out.contains("background-color:#123456"), "paragraph shading is exported: {out}"); + + let back = import(&out); + let table = back + .body + .iter() + .find_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t), + _ => None, + }) + .expect("expected table"); + let cell = &table.rows[0].cells[0]; + assert_eq!(cell.props.shading, None, "paragraph shading must not become cell shading"); + let craft_wordmodel::Block::Para(p) = &*cell.blocks[0] else { panic!("expected Para") }; + assert_eq!(p.props.shading, Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56))); +} + +/// Verify that consecutive code paragraphs with different backgrounds export their own `
`.
+#[test]
+fn consecutive_code_blocks_keep_their_own_shading() {
+    let html = r#"
a
b
"#; + let out = export(&import(html)); + assert!(out.contains("
a
"), "{out}"); + assert!(out.contains("
b
"), "{out}"); +} + +/// Verify that paragraph shading inherited from a paragraph style is exported (#1786). +#[test] +fn paragraph_shading_from_a_style_survives_html_export() { + let mut doc = Document::new(); + std::sync::Arc::make_mut(&mut doc.styles).styles.push(craft_wordmodel::Style { + id: "Shaded".into(), + name: "Shaded".into(), + para: craft_wordmodel::props::ParaProps { shading: Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56)), ..Default::default() }, + ..Default::default() + }); + let mut p = craft_wordmodel::Paragraph::with_text("text", craft_wordmodel::CharProps::default()); + p.props.style = Some("Shaded".into()); + doc.body = vec![craft_wordmodel::para_block(p)]; + + let out = export(&doc); + assert!(out.contains("background-color:#123456"), "style shading is exported: {out}"); +} + +/// A closing parenthesis without an opening one invalidates the declaration (#1786). +#[test] +fn background_shorthand_unbalanced_closing_paren_is_ignored() { + let html = r#"text"#; + let doc = import(html); + let craft_wordmodel::Block::Para(p) = &*doc.body[0] else { panic!("expected Para") }; + assert_eq!(p.runs[0].props.shading, Some(craft_wordmodel::Rgb(0xff, 0x00, 0x00)), "invalid shorthand must not clear inherited shading"); +} + +/// A shaded paragraph keeps its shading on both sides of an internal page break (#1786). +#[test] +fn paragraph_shading_survives_an_internal_page_break() { + let mut p = craft_wordmodel::Paragraph::with_text("before\u{000C}after", craft_wordmodel::CharProps::default()); + p.props.shading = Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56)); + let mut doc = Document::new(); + doc.body = vec![craft_wordmodel::para_block(p)]; + let out = export(&doc); + assert_eq!(out.matches("background-color:#123456").count(), 2, "{out}"); +} + +/// Verify that CSS-escaped quote characters in background shorthand URLs remain part of the URL +/// content and do not cause the shorthand declaration to be rejected. +#[test] +fn background_shorthand_escaped_quotes_in_url() { + let doc = import(r#"

text

"#); + let craft_wordmodel::Block::Para(p) = &*doc.body[0] else { panic!("expected Para") }; + assert_eq!(&p.text, "text"); + assert!(!p.runs.is_empty()); + assert_eq!(p.runs[0].props.shading, Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56))); +} + +/// Verify that valid multi-token CSS background shorthands without a color (such as `none repeat`) +/// reset character shading, while invalid declarations are ignored. +#[test] +fn background_shorthand_without_color_resets_background() { + let html = r#"plain"#; + let doc = import(html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p.runs[0].props.shading, None); + + let html_invalid = r#"shaded"#; + let doc_invalid = import(html_invalid); + let p_invalid = match &*doc_invalid.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_invalid.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); +} + +/// Verify that CSS `background: inherit` keeps inherited character shading instead of removing it (#1786). +#[test] +fn background_inherit_retains_inline_shading() { + let html = r#"shaded"#; + let doc = import(html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0)), "background: inherit should retain inherited character shading"); + + // Also verify background-color: inherit retains shading. + let html_color = r#"shaded"#; + let doc_color = import(html_color); + let p_color = match &*doc_color.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!( + p_color.runs[0].props.shading, + Some(craft_wordmodel::Rgb(255, 0, 0)), + "background-color: inherit should retain inherited character shading" + ); + + // CSS-wide keyword inherit mixed with other values is invalid and ignored. + let html_mixed = r#"green"#; + let doc_mixed = import(html_mixed); + let p_mixed = match &*doc_mixed.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!( + p_mixed.runs[0].props.shading, + Some(craft_wordmodel::Rgb(0, 255, 0)), + "invalid shorthand mixing inherit with values should be ignored" + ); +} + +/// Verify that hostile background declarations with deeply nested slashes do not cause stack overflow (#1786). +#[test] +fn hostile_background_slashes_never_stack_overflow() { + let slashes = "/".repeat(20_000); + let html = format!(r#"hostile"#); + let doc = import(&html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p.runs[0].props.shading, None); +} + +/// Verify that non-breaking space (U+00A0) is not treated as CSS whitespace when splitting tokens (#1786). +#[test] +fn background_whitespace_preserves_nbsp() { + let html = "shaded"; + let doc = import(html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!( + p.runs[0].props.shading, + Some(craft_wordmodel::Rgb(255, 0, 0)), + "non-breaking space is not CSS whitespace and should not clear shading" + ); +} + +/// Verify that background shorthands exceeding the token limit are rejected and unapplied (#1786). +#[test] +fn background_shorthand_truncated_rejects_unapplied() { + let mut layers = String::new(); + for i in 0..64 { + layers.push_str(&format!("url(img{i}.png), ")); + } + layers.push_str("#00ff00"); + let html = format!(r#"retained"#); + let doc = import(&html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!( + p.runs[0].props.shading, + Some(craft_wordmodel::Rgb(255, 0, 0)), + "truncated shorthand should be rejected and leave inherited background untouched" + ); +} + +/// Verify that shorthands with image-set or calc functions parse and preserve colors (#1786). +#[test] +fn background_shorthand_valid_functions_preserve_color() { + let html_image_set = r#"image-set"#; + let doc = import(html_image_set); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p.runs[0].props.shading, Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56))); + + let html_calc = r#"calc"#; + let doc_calc = import(html_calc); + let p_calc = match &*doc_calc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_calc.runs[0].props.shading, Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56))); +} + +/// Verify that multi-layer background shorthands validate slashes per layer and preserve final-layer color (#1786). +#[test] +fn background_shorthand_multi_layer_slashes_apply_color() { + let html = r#"multi-layer"#; + let doc = import(html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p.runs[0].props.shading, Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56))); + + // Color in a non-final layer is invalid CSS and must be ignored. + let html_invalid_color = r#"invalid"#; + let doc_invalid_color = import(html_invalid_color); + let p_invalid_color = match &*doc_invalid_color.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_invalid_color.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); + + // Multiple slashes in a single layer makes the declaration invalid. + let html_multi_slash = + r#"invalid"#; + let doc_multi_slash = import(html_multi_slash); + let p_multi_slash = match &*doc_multi_slash.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_multi_slash.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); +} + +/// Verify that background shorthands with empty layers (leading, trailing, or double commas) are rejected (#1786). +#[test] +fn background_shorthand_rejects_empty_layers() { + // Leading comma + let html_leading = r#"leading"#; + let doc_leading = import(html_leading); + let p_leading = match &*doc_leading.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_leading.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); + + // Trailing comma + let html_trailing = r#"trailing"#; + let doc_trailing = import(html_trailing); + let p_trailing = match &*doc_trailing.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_trailing.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); + + // Double comma + let html_double = r#"double"#; + let doc_double = import(html_double); + let p_double = match &*doc_double.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_double.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); +} + +/// Verify that zero-alpha colors in background shorthands or declarations remain transparent (#1786). +#[test] +fn background_zero_alpha_colors_are_transparent() { + for decl in ["rgb(0 0 0 / 0)", "rgba(0, 0, 0, 0)", "#0000", "#00000000", "#ffffff00", "hsla(120, 100%, 50%, 0)", "hsl(120 100% 50% / 0)"] { + let html = format!(r#"transparent"#); + let doc = import(&html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p.runs[0].props.shading, None, "zero-alpha color `{decl}` must clear background rather than composite over white"); + } +} + +/// Verify that ancestor table shading is preserved beneath transparent table layers (#1786). +#[test] +fn transparent_table_layers_preserve_ancestor_table_shading() { + let html = r#" + + + + + + +
transparent_layersexplicit_cell
"#; + let doc = import(html); + let table = doc + .body + .iter() + .find_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t), + _ => None, + }) + .unwrap(); + assert_eq!( + table.rows[0].cells[0].props.shading, + Some(craft_wordmodel::Rgb(0xe8, 0xf0, 0xfa)), + "table background must show through transparent tbody, tr, and td" + ); + assert_eq!( + table.rows[0].cells[1].props.shading, + Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56)), + "cell with explicit background must override table background" + ); +} + +/// Verify that block-level container background is available to immediate inline children using explicit `inherit` (#1786). +#[test] +fn block_background_explicit_inherit() { + // When the immediate parent

has no background, an inline span inheriting background gets transparent (None): + let html_indirect = r#"

text

"#; + let doc_indirect = import(html_indirect); + let p_indirect = match &*doc_indirect.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_indirect.runs[0].props.shading, None); + + // When the span is an immediate child of the styled div, it inherits the div's computed background: + let html_direct = r#"
text
"#; + let doc_direct = import(html_direct); + let p_direct = match &*doc_direct.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_direct.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); + + let html_shorthand = r#"
text
"#; + let doc_shorthand = import(html_shorthand); + let p_shorthand = match &*doc_shorthand.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_shorthand.runs[0].props.shading, Some(craft_wordmodel::Rgb(0, 255, 0))); +} + +/// Verify that CSS-escaped quotes inside background URLs do not close the quote or drop declaration colors (#1786). +#[test] +fn background_escaped_quote_url() { + let html = r#"text"#; + let doc = import(html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p.runs[0].props.shading, Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56))); + + let html_single = r#"text"#; + let doc_single = import(html_single); + let p_single = match &*doc_single.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_single.runs[0].props.shading, Some(craft_wordmodel::Rgb(0x65, 0x43, 0x21))); +} + +/// Verify that invalid hex color declarations like `#ggg0` do not clear inherited shading (#1786). +#[test] +fn background_invalid_hex_retains_shading() { + let html = r#"text"#; + let doc = import(html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); +} + +/// Verify that background size keywords (`cover`, `contain`) without preceding position and slash are invalid and retain shading (#1786). +#[test] +fn background_cover_without_slash_invalid() { + let html_cover = r#"text"#; + let doc_cover = import(html_cover); + let p_cover = match &*doc_cover.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_cover.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); + + let html_contain = r#"text"#; + let doc_contain = import(html_contain); + let p_contain = match &*doc_contain.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_contain.runs[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); + + let html_valid = r#"text"#; + let doc_valid = import(html_valid); + let p_valid = match &*doc_valid.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p_valid.runs[0].props.shading, None); +} + +/// Verify that table backgrounds declared on thead or tbody are applied to cells (#1786). +#[test] +fn table_row_group_background_inheritance() { + let html = r#" + + + + + + +
head
body
"#; + let doc = import(html); + let table = doc + .body + .iter() + .find_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t), + _ => None, + }) + .unwrap(); + assert_eq!(table.rows[0].cells[0].props.shading, Some(craft_wordmodel::Rgb(0, 255, 0))); + assert_eq!(table.rows[1].cells[0].props.shading, Some(craft_wordmodel::Rgb(0, 0, 255))); +} + +/// Verify that background shorthand with slashes inside URL functions correctly identifies the position/size slash (#1786). +#[test] +fn background_url_with_slashes_and_position_size() { + let html = r#"text"#; + let doc = import(html); + let p = match &*doc.body[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p.runs[0].props.shading, Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56))); +} + +/// Verify that a table inside an inline element with background shading does not turn character shading into table/cell background (#1786). +#[test] +fn table_inside_inline_element_does_not_inherit_character_shading() { + let html = r#"
cell
"#; + let doc = import(html); + let table = doc + .body + .iter() + .find_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t), + _ => None, + }) + .unwrap(); + assert_eq!(table.rows[0].cells[0].props.shading, None); +} + +/// Verify that a child with `background: inherit` inside an unstyled cell in a shaded table does not inherit the table fallback (#1786). +#[test] +fn cell_inherit_uses_cell_background_not_table_fallback() { + let html = r#"
text
"#; + let doc = import(html); + let table = doc + .body + .iter() + .find_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t), + _ => None, + }) + .unwrap(); + assert_eq!(table.rows[0].cells[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); + let p = match &*table.rows[0].cells[0].blocks[0] { + craft_wordmodel::Block::Para(p) => p, + _ => panic!("expected paragraph"), + }; + assert_eq!(p.runs[0].props.shading, None); +} + +/// Verify that CSS `background: transparent` overrides HTML `bgcolor` presentational attribute (#1786). +#[test] +fn bgcolor_overridden_by_css_transparent() { + let html = r##"
cell
"##; + let doc = import(html); + let table = doc + .body + .iter() + .find_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t), + _ => None, + }) + .unwrap(); + assert_eq!(table.rows[0].cells[0].props.shading, None); +} + +/// Verify that nested container shading is preserved when merging list continuation paragraphs (#1786). +#[test] +fn list_continuation_preserves_nested_container_shading() { + let html = r#"
  • before
    inside
    after
"#; + let flow = parse(html); + assert_eq!(flow.blocks.len(), 1); + let FBlock::Para(p) = &flow.blocks[0] else { panic!("expected Para") }; + assert!(p.list.is_some(), "expected list item"); + let dark = Some(craft_wordmodel::Rgb(0x11, 0x11, 0x11)); + let inside = p + .inlines + .iter() + .find_map(|i| match i { + Inline::Text(t, fmt) if t.contains("inside") => Some(fmt.background), + _ => None, + }) + .expect("inside text inline"); + assert_eq!(inside, dark, "nested container shading should be preserved on merged run"); + + let doc = import(html); + let craft_wordmodel::Block::Para(p_doc) = &*doc.body[0] else { panic!("expected Para") }; + let mut offset = 0usize; + let mut inside_shading = None; + for r in &p_doc.runs { + let text_slice = &p_doc.text[offset..offset + r.len]; + if text_slice.contains("inside") { + inside_shading = Some(r.props.shading); + } else if text_slice.contains("before") || text_slice.contains("after") { + assert_eq!(r.props.shading, None); + } + offset += r.len; + } + assert_eq!(inside_shading, Some(dark)); +} + +/// Verify that starting a new row group implicitly closes any preceding sibling row group so +/// cell shading is not inherited from an omitted-end-tag preceding group (#1786). +#[test] +fn consecutive_row_groups_with_omitted_end_tag_do_not_leak_shading() { + let html = r#"
a
b
"#; + let doc = import(html); + let table = doc + .body + .iter() + .find_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t), + _ => None, + }) + .unwrap(); + assert_eq!(table.rows.len(), 2); + assert_eq!(table.rows[0].cells[0].props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); + assert_eq!(table.rows[1].cells[0].props.shading, None, "second cell should not inherit shading from closed tbody"); +} + +/// Verify that a list item with a shaded container followed by unshaded text preserves separate +/// background regions so the trailing text does not inherit the container's background (#1786). +#[test] +fn shaded_container_first_in_list_item_preserves_unshaded_trailing_text() { + let html = r#"
  • inside
    after
"#; + let doc = import(html); + assert_eq!(doc.body.len(), 1); + let craft_wordmodel::Block::Para(p) = &*doc.body[0] else { panic!("expected Para") }; + assert_eq!(p.props.shading, None, "list paragraph as a whole should have no background when regions differ"); + let dark = Some(craft_wordmodel::Rgb(0x11, 0x11, 0x11)); + let mut offset = 0usize; + let mut inside_shading = None; + let mut after_shading = None; + for r in &p.runs { + let text_slice = &p.text[offset..offset + r.len]; + if text_slice.contains("inside") { + inside_shading = Some(r.props.shading); + } else if text_slice.contains("after") { + after_shading = Some(r.props.shading); + } + offset += r.len; + } + assert_eq!(inside_shading, Some(dark)); + assert_eq!(after_shading, Some(None), "trailing text should have no shading"); +} + +/// Verify that container backgrounds behind tables are preserved on table cells (#1786). +#[test] +fn container_background_behind_table_preserved_on_cells() { + let html = r#"
text
"#; + let doc = import(html); + let table = doc + .body + .iter() + .find_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t), + _ => None, + }) + .unwrap(); + assert_eq!(table.rows[0].cells[0].props.shading, Some(craft_wordmodel::Rgb(0x11, 0x11, 0x11))); + + // Nested table inside an unshaded cell stops at the cell boundary: + let nested_html = r#"
nested
"#; + let nested_doc = import(nested_html); + let outer_table = nested_doc + .body + .iter() + .find_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t), + _ => None, + }) + .unwrap(); + assert_eq!(outer_table.rows[0].cells[0].props.shading, Some(craft_wordmodel::Rgb(0x11, 0x11, 0x11))); + let inner_table = match &*outer_table.rows[0].cells[0].blocks[0] { + craft_wordmodel::Block::Table(t) => t, + _ => panic!("expected nested Table"), + }; + assert_eq!(inner_table.rows[0].cells[0].props.shading, None, "nested table in unshaded cell must stop at cell boundary"); +} + +/// Verify that page imports preserve root (body/html) backgrounds while pasted fragments do not (#1786). +#[test] +fn root_background_preserved_on_page_import_only() { + let html = r#"

text

"#; + let page_doc = import_page(html, &|_| None); + let craft_wordmodel::Block::Para(p_page) = &*page_doc.body[0] else { panic!("expected Para") }; + assert_eq!(p_page.props.shading, Some(craft_wordmodel::Rgb(0x11, 0x11, 0x11)), "page import must preserve body background on paragraphs"); + assert_eq!( + p_page.runs[0].props.color, + Some(craft_wordmodel::TextColor::Rgb(craft_wordmodel::Rgb(0xff, 0xff, 0xff))), + "page import keeps the root foreground with its background" + ); + + let frag_doc = import(html); + let craft_wordmodel::Block::Para(p_frag) = &*frag_doc.body[0] else { panic!("expected Para") }; + assert_eq!(p_frag.props.shading, None, "fragment paste must not turn body background into paragraph shading"); + assert_eq!(p_frag.runs[0].props.color, None, "fragment paste drops the root foreground with its background"); +} + +/// Verify that an inline child with `background: inherit` does not receive character shading from a pasted body background (#1786). +#[test] +fn pasted_body_background_not_inherited_by_inline_child() { + let html = r#"text"#; + let frag_doc = import(html); + let craft_wordmodel::Block::Para(p_frag) = &*frag_doc.body[0] else { panic!("expected Para") }; + assert_eq!(p_frag.runs[0].props.shading, None, "inline child in pasted fragment must not inherit character shading from body background"); + + let page_doc = import_page(html, &|_| None); + let craft_wordmodel::Block::Para(p_page) = &*page_doc.body[0] else { panic!("expected Para") }; + assert_eq!( + p_page.runs[0].props.shading, + Some(craft_wordmodel::Rgb(0x11, 0x11, 0x11)), + "inline child in page import inherits body background via inherit" + ); +} + +#[test] +fn root_background_on_html_and_foreground_on_body() { + let html = r#"

text

"#; + let frag_doc = import(html); + let craft_wordmodel::Block::Para(p_frag) = &*frag_doc.body[0] else { panic!("expected Para") }; + assert_eq!(p_frag.props.shading, None, "fragment paste drops html background"); + assert_eq!(p_frag.runs[0].props.color, None, "fragment paste drops body foreground when html supplied suppressed background"); + + let page_doc = import_page(html, &|_| None); + let craft_wordmodel::Block::Para(p_page) = &*page_doc.body[0] else { panic!("expected Para") }; + assert_eq!(p_page.props.shading, Some(craft_wordmodel::Rgb(0x11, 0x11, 0x11))); + assert_eq!(p_page.runs[0].props.color, Some(craft_wordmodel::TextColor::Rgb(craft_wordmodel::Rgb(0xff, 0xff, 0xff)))); +} + +#[test] +fn background_unitless_zero_lengths() { + let html = r#"

text

"#; + let doc = import(html); + let craft_wordmodel::Block::Para(p) = &*doc.body[0] else { panic!("expected Para") }; + assert_eq!(p.props.shading, Some(craft_wordmodel::Rgb(0x12, 0x34, 0x56))); + + let html2 = r#"

text

"#; + let doc2 = import(html2); + let craft_wordmodel::Block::Para(p2) = &*doc2.body[0] else { panic!("expected Para") }; + assert_eq!(p2.props.shading, Some(craft_wordmodel::Rgb(0x65, 0x43, 0x21))); +} + +#[test] +fn background_comments_skipped_outside_strings() { + let html = r#"

text

"#; + let doc = import(html); + let craft_wordmodel::Block::Para(p) = &*doc.body[0] else { panic!("expected Para") }; + assert_eq!(p.props.shading, Some(craft_wordmodel::Rgb(0x11, 0x11, 0x11))); + + let html2 = r#"

text

"#; + let doc2 = import(html2); + let craft_wordmodel::Block::Para(p2) = &*doc2.body[0] else { panic!("expected Para") }; + assert_eq!(p2.props.shading, Some(craft_wordmodel::Rgb(0x22, 0x22, 0x22))); +} + +#[test] +fn invalid_color_does_not_clear_preceding_background() { + let html = r#"

text

"#; + let doc = import(html); + let craft_wordmodel::Block::Para(p) = &*doc.body[0] else { panic!("expected Para") }; + assert_eq!(p.props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); + + let html2 = r#"

text

"#; + let doc2 = import(html2); + let craft_wordmodel::Block::Para(p2) = &*doc2.body[0] else { panic!("expected Para") }; + assert_eq!(p2.props.shading, Some(craft_wordmodel::Rgb(255, 0, 0))); +} + +#[test] +fn code_block_export_preserves_foreground_color() { + let html = r#"
const x = 1;
"#; + let doc = import_page(html, &|_| None); + let exported = export(&doc); + assert!(exported.contains("style=\"background-color:#000000\""), "exported pre must keep background: {}", exported); + assert!(exported.contains("color:#FFFFFF"), "exported code inlines must keep foreground: {}", exported); + assert!(exported.contains("const x = 1;"), "exported code text preserved: {}", exported); +} + +#[test] +fn background_comments_inside_functions() { + let html = r#"

text

"#; + let doc = import(html); + let craft_wordmodel::Block::Para(p) = &*doc.body[0] else { panic!("expected Para") }; + assert_eq!(p.props.shading, Some(craft_wordmodel::Rgb(0x11, 0x11, 0x11))); + assert_eq!(p.runs[0].props.color, Some(craft_wordmodel::TextColor::Rgb(craft_wordmodel::Rgb(0xff, 0xff, 0xff)))); +} + +#[test] +fn zero_alpha_colors_with_none_channels() { + let html = r#"

text

"#; + let doc = import(html); + let craft_wordmodel::Block::Para(p) = &*doc.body[0] else { panic!("expected Para") }; + assert_eq!(p.props.shading, None); + + let html2 = r#"

text

"#; + let doc2 = import(html2); + let craft_wordmodel::Block::Para(p2) = &*doc2.body[0] else { panic!("expected Para") }; + assert_eq!(p2.props.shading, None); +} From cfad8f0bcca6900ddd88361220fb5ed432ce817e Mon Sep 17 00:00:00 2001 From: el-j Date: Tue, 17 Nov 2026 03:30:57 +0100 Subject: [PATCH 27/64] craft-captions: PJS, RealText and JACOsub subtitle formats (#1557) (#1788) --- crates/captions/src/jacosub.rs | 242 +++++++++++++++++ crates/captions/src/lib.rs | 50 +++- crates/captions/src/pjs.rs | 102 ++++++++ crates/captions/src/realtext.rs | 247 ++++++++++++++++++ crates/captions/src/text.rs | 46 ++++ crates/captions/tests/it/main.rs | 1 + .../captions/tests/it/pjs_realtext_jacosub.rs | 174 ++++++++++++ 7 files changed, 860 insertions(+), 2 deletions(-) create mode 100644 crates/captions/src/jacosub.rs create mode 100644 crates/captions/src/pjs.rs create mode 100644 crates/captions/src/realtext.rs create mode 100644 crates/captions/tests/it/pjs_realtext_jacosub.rs diff --git a/crates/captions/src/jacosub.rs b/crates/captions/src/jacosub.rs new file mode 100644 index 000000000..30233b6f1 --- /dev/null +++ b/crates/captions/src/jacosub.rs @@ -0,0 +1,242 @@ +//! JACOsub (`.jss`, `.js`): multi-feature scriptable subtitle format. +//! +//! ```text +//! # JACOsub file +//! #TimeRes 100 +//! 0:00:01.00 0:00:03.00 D0 First line\nsecond line +//! ``` +//! +//! Lines beginning with `#` are comments or header directives. Timed caption lines begin with +//! `START STOP [DIRECTIVE] Text`, where timestamps are `H:MM:SS.FF` (or `@units`) relative to +//! the declared `#TimeRes` (default 30). Inside the text, `\n` represents a newline. + +use crate::text::{escape_markup, ms_to_tick, plain_text, tick_to_ms}; +use crate::{Cue, Document, Error, Result}; + +/// Parse a JACOsub timestamp `H:MM:SS.FF` or `@units` into milliseconds. +pub(crate) fn parse_time(s: &str, time_res: i64) -> Option { + let s = s.trim(); + if s.is_empty() { + return None; + } + + if let Some(units_str) = s.strip_prefix('@') { + let units: i64 = units_str.trim().parse().ok()?; + let time_res = if time_res > 0 { time_res } else { 30 }; + return Some(units.saturating_mul(1000) / time_res); + } + + let (h_str, rest) = s.split_once(':')?; + let (m_str, rest) = rest.split_once(':')?; + let (s_str, f_str) = rest.split_once('.')?; + + let h: i64 = h_str.trim().parse().ok()?; + let m: i64 = m_str.trim().parse().ok()?; + let sec: i64 = s_str.trim().parse().ok()?; + let frac: i64 = f_str.trim().parse().ok()?; + + let time_res = if time_res > 0 { time_res } else { 30 }; + let frac_ms = frac.saturating_mul(1000) / time_res; + + let total_secs = h.saturating_mul(3600).saturating_add(m.saturating_mul(60)).saturating_add(sec); + Some(total_secs.saturating_mul(1000).saturating_add(frac_ms)) +} + +/// Format milliseconds into JACOsub timestamp string `H:MM:SS.cc` (at 100 centiseconds/sec). +pub(crate) fn format_time(ms: i64) -> String { + let ms = ms.max(0); + let total_secs = ms / 1000; + let centis = (ms % 1000) / 10; + let hours = total_secs / 3600; + let mins = (total_secs % 3600) / 60; + let secs = total_secs % 60; + + format!("{hours}:{mins:02}:{secs:02}.{centis:02}") +} + +/// Check if a line is a JACOsub timed caption line: `H:MM:SS.FF H:MM:SS.FF ...` or `@units @units ...`. +pub(crate) fn is_timed_line(line: &str) -> bool { + let line = line.trim(); + if line.starts_with('#') { + return false; + } + let mut parts = line.split_whitespace(); + let Some(t0) = parts.next() else { return false }; + let Some(t1) = parts.next() else { return false }; + (t0.contains(':') && t0.contains('.') && t1.contains(':') && t1.contains('.')) || (t0.starts_with('@') && t1.starts_with('@')) +} + +pub fn parse(text: &str) -> Result { + let mut doc = Document::default(); + let mut time_res: i64 = 30; // standard default + let mut shift_ms: i64 = 0; + let mut found = false; + + for (n, line) in text.lines().enumerate() { + let line = line.trim(); + if line.is_empty() { + continue; + } + + if let Some(cmd) = line.strip_prefix('#') { + let cmd_lower = cmd.to_ascii_lowercase(); + if cmd_lower.starts_with("timeres") || cmd_lower.starts_with('t') { + let parts: Vec<&str> = cmd.split_whitespace().collect(); + if parts.len() >= 2 + && let Ok(res) = parts[1].parse::() + && res > 0 + { + time_res = res; + } + } else if cmd_lower.starts_with("shift") || cmd_lower.starts_with('s') { + let parts: Vec<&str> = cmd.split_whitespace().collect(); + if parts.len() >= 2 { + let s_val = parts[1].trim(); + let (neg, s_raw) = if let Some(stripped) = s_val.strip_prefix('-') { + (true, stripped) + } else if let Some(stripped) = s_val.strip_prefix('+') { + (false, stripped) + } else { + (false, s_val) + }; + if let Some(ms) = parse_time(s_raw, time_res) { + shift_ms = if neg { -ms } else { ms }; + } + } + } + continue; + } + + if !is_timed_line(line) { + continue; + } + + let mut parts = line.split_whitespace(); + let Some(start_str) = parts.next() else { continue }; + let Some(end_str) = parts.next() else { continue }; + + let start_ms = match parse_time(start_str, time_res) { + Some(ms) => ms.saturating_add(shift_ms).max(0), + None => { + doc.warnings.push(format!("line {}: invalid start timestamp, skipped", n + 1)); + continue; + } + }; + let end_ms = match parse_time(end_str, time_res) { + Some(ms) => ms.saturating_add(shift_ms).max(0), + None => { + doc.warnings.push(format!("line {}: invalid end timestamp, skipped", n + 1)); + continue; + } + }; + + found = true; + + // Skip to after the end timestamp in the original line to preserve exact spaces + let after_end_pos = match line.find(end_str) { + Some(idx) => idx + end_str.len(), + None => continue, + }; + let remainder = &line[after_end_pos..]; + let trimmed_rem = remainder.trim_start(); + + // Check if there is a directive prefix: either [Directive] or a single non-space word starting with D + let text_part = if let Some(stripped) = trimmed_rem.strip_prefix('[') { + match stripped.find(']') { + Some(end_bracket) => stripped[end_bracket + 1..].trim_start(), + None => trimmed_rem, + } + } else if let Some(space_idx) = trimmed_rem.find(' ') { + let first_token = &trimmed_rem[..space_idx]; + if first_token.starts_with('D') && first_token[1..].chars().all(|c| c.is_ascii_digit()) { + trimmed_rem[space_idx + 1..].trim_start() + } else { + trimmed_rem + } + } else { + trimmed_rem + }; + + // Text parsing: `\n` represents newline + let raw_lines: Vec<&str> = text_part.split(r"\n").map(str::trim).filter(|l| !l.is_empty()).collect(); + let lines: Vec = raw_lines.into_iter().map(escape_markup).collect(); + + let start = ms_to_tick(start_ms); + let end = ms_to_tick(end_ms); + if end <= start || lines.is_empty() { + doc.warnings.push(format!("line {}: empty or ends before it starts; skipped", n + 1)); + continue; + } + + doc.cues.push(Cue { start, end, text: lines.join("\n"), ..Default::default() }); + } + + if !found && !text.trim().is_empty() { + return Err(Error::NotFormat("JACOsub")); + } + + Ok(doc) +} + +pub fn write(doc: &Document) -> String { + let mut out = String::new(); + out.push_str("# JACOsub file\n"); + out.push_str("#TimeRes 100\n\n"); + + for c in &doc.cues { + let start_ms = tick_to_ms(c.start); + let end_ms = tick_to_ms(c.end).max(start_ms + 10); + let raw_lines = plain_text(&c.text); + let lines: Vec<&str> = raw_lines.lines().map(str::trim).filter(|l| !l.is_empty()).collect(); + + if !lines.is_empty() { + let text = lines.join(r"\n"); + out.push_str(&format!("{} {} D0 {}\n", format_time(start_ms), format_time(end_ms), text)); + } + } + + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parse_and_write_roundtrip() { + let jss = "# JACOsub file\n#TimeRes 100\n\n0:00:01.00 0:00:03.00 D0 First line\\nsecond line\n0:00:04.50 0:00:06.00 D0 Second cue\n"; + let doc = parse(jss).expect("parse"); + assert_eq!(doc.cues.len(), 2); + assert_eq!(doc.cues[0].start, ms_to_tick(1000)); + assert_eq!(doc.cues[0].end, ms_to_tick(3000)); + assert_eq!(doc.cues[0].text, "First line\nsecond line"); + assert_eq!(doc.cues[1].start, ms_to_tick(4500)); + assert_eq!(doc.cues[1].end, ms_to_tick(6000)); + assert_eq!(doc.cues[1].text, "Second cue"); + + let written = write(&doc); + assert_eq!(written, jss); + } + + #[test] + fn parse_bracketed_directive() { + let jss = "#TimeRes 100\n0:00:01.00 0:00:03.00 [Style1] Bracketed style text\n"; + let doc = parse(jss).expect("parse"); + assert_eq!(doc.cues.len(), 1); + assert_eq!(doc.cues[0].text, "Bracketed style text"); + } + + #[test] + fn negative_shift_under_one_hour() { + let jss = "#TimeRes 100\n#Shift -0:00:01.00\n0:00:02.00 0:00:04.00 D0 Shifted line\n"; + let doc = parse(jss).expect("parse"); + assert_eq!(doc.cues.len(), 1); + assert_eq!(doc.cues[0].start, ms_to_tick(1000)); + assert_eq!(doc.cues[0].end, ms_to_tick(3000)); + } + + #[test] + fn rejects_non_jacosub() { + assert!(parse("1\n00:00:01,000 --> 00:00:02,000\nHello\n").is_err()); + } +} diff --git a/crates/captions/src/lib.rs b/crates/captions/src/lib.rs index e8a492722..ca99dba43 100644 --- a/crates/captions/src/lib.rs +++ b/crates/captions/src/lib.rs @@ -34,7 +34,10 @@ struct ReadmeExamples; pub mod ass; pub mod cea608; +pub mod jacosub; pub mod mcc; +pub mod pjs; +pub mod realtext; pub mod scc; pub mod srt; pub mod stl; @@ -72,10 +75,28 @@ pub enum Format { Dfxp, /// Advanced SubStation Alpha (also reads SubStation Alpha). Ass, + /// Phoenix Japanimation Society (PJS) subtitles. + Pjs, + /// RealText streaming timed text markup. + RealText, + /// JACOsub scriptable subtitles. + JacoSub, } impl Format { - pub const ALL: [Format; 8] = [Format::Srt, Format::WebVtt, Format::Scc, Format::Mcc, Format::Stl, Format::Ttml, Format::Dfxp, Format::Ass]; + pub const ALL: [Format; 11] = [ + Format::Srt, + Format::WebVtt, + Format::Scc, + Format::Mcc, + Format::Stl, + Format::Ttml, + Format::Dfxp, + Format::Ass, + Format::Pjs, + Format::RealText, + Format::JacoSub, + ]; pub fn name(self) -> &'static str { match self { Format::Srt => "SubRip (SRT)", @@ -86,6 +107,9 @@ impl Format { Format::Ttml => "TTML (IMSC1)", Format::Dfxp => "DFXP (TTML1)", Format::Ass => "Advanced SubStation Alpha (ASS)", + Format::Pjs => "PJS", + Format::RealText => "RealText", + Format::JacoSub => "JACOsub", } } pub fn extension(self) -> &'static str { @@ -98,6 +122,9 @@ impl Format { Format::Ttml => "ttml", Format::Dfxp => "dfxp", Format::Ass => "ass", + Format::Pjs => "pjs", + Format::RealText => "rt", + Format::JacoSub => "jss", } } pub fn from_name(s: &str) -> Option { @@ -110,6 +137,9 @@ impl Format { "ttml" | "imsc" | "imsc1" | "xml" => Some(Format::Ttml), "dfxp" => Some(Format::Dfxp), "ass" | "ssa" => Some(Format::Ass), + "pjs" => Some(Format::Pjs), + "rt" | "realtext" => Some(Format::RealText), + "jss" | "js" | "jacosub" => Some(Format::JacoSub), _ => None, } } @@ -260,6 +290,16 @@ pub fn detect(bytes: &[u8], ext: Option<&str>) -> Option { if head.starts_with("[Script Info]") { return Some(Format::Ass); } + if realtext::is_realtext(head) { + return Some(Format::RealText); + } + let first_lines: Vec<&str> = head.lines().map(str::trim).filter(|l| !l.is_empty()).take(3).collect(); + if first_lines.first().is_some_and(|l| pjs::split_cue(l).is_some()) { + return Some(Format::Pjs); + } + if first_lines.iter().any(|l| jacosub::is_timed_line(l)) || (head.starts_with('#') && (head.contains("TimeRes") || head.contains("#T"))) { + return Some(Format::JacoSub); + } let ext = ext.map(|e| e.trim_start_matches('.').to_ascii_lowercase()); if (head.starts_with('<') && (head.contains("") || head.contains(":tt "))) && (head.contains("ns/ttml") || head.contains("ttaf1")) @@ -271,7 +311,7 @@ pub fn detect(bytes: &[u8], ext: Option<&str>) -> Option { match ext.as_deref() { Some("srt") if has_arrow_timing || head.is_empty() => Some(Format::Srt), Some("vtt") if has_arrow_timing => Some(Format::WebVtt), - Some("srt" | "vtt" | "scc" | "mcc" | "stl" | "ttml" | "dfxp" | "xml" | "ass" | "ssa") => None, + Some("srt" | "vtt" | "scc" | "mcc" | "stl" | "ttml" | "dfxp" | "xml" | "ass" | "ssa" | "pjs" | "rt" | "jss" | "js") => None, _ if has_arrow_timing => Some(Format::Srt), _ => None, } @@ -306,6 +346,9 @@ fn parse_unbounded(bytes: &[u8], format: Format) -> Result { Format::Mcc => mcc::parse(&text), Format::Ttml | Format::Dfxp => ttml::parse(&text), Format::Ass => ass::parse(&text), + Format::Pjs => pjs::parse(&text), + Format::RealText => realtext::parse(&text), + Format::JacoSub => jacosub::parse(&text), Format::Stl => stl::parse(bytes), } } @@ -344,6 +387,9 @@ pub fn write(doc: &Document, format: Format, opts: WriteOptions) -> Vec { Format::Ttml => ttml::write(doc, ttml::Flavor::Imsc1, opts.rate, doc.language.as_deref().unwrap_or("")).into_bytes(), Format::Dfxp => ttml::write(doc, ttml::Flavor::Dfxp, opts.rate, doc.language.as_deref().unwrap_or("")).into_bytes(), Format::Ass => ass::write(doc).into_bytes(), + Format::Pjs => pjs::write(doc).into_bytes(), + Format::RealText => realtext::write(doc).into_bytes(), + Format::JacoSub => jacosub::write(doc).into_bytes(), } } diff --git a/crates/captions/src/pjs.rs b/crates/captions/src/pjs.rs new file mode 100644 index 000000000..91874941b --- /dev/null +++ b/crates/captions/src/pjs.rs @@ -0,0 +1,102 @@ +//! Phoenix Japanimation Society (PJS) subtitles (`.pjs`): times in tenths of a second. +//! +//! ```text +//! 10,50,"First line" +//! 60,120,"Second line|with break" +//! ``` +//! +//! Lines are comma-separated `start,end,"text"` with times in deciseconds (tenths of a second). +//! Inside the quotes, `|` breaks a line. + +use crate::text::{escape_markup, ms_to_tick, number, plain_lines, tick_to_ms}; +use crate::{Cue, Document, Error, Result}; + +/// `start,end,"text"` as its parts. +pub(crate) fn split_cue(line: &str) -> Option<(i64, i64, &str)> { + let (start_str, rest) = line.split_once(',')?; + let (end_str, text_str) = rest.split_once(',')?; + let start = number(start_str.trim())?; + let end = number(end_str.trim())?; + let text = text_str.trim(); + let text = if let Some(stripped) = text.strip_prefix('"').and_then(|t| t.strip_suffix('"')) { stripped } else { text }; + Some((start, end, text)) +} + +/// Parse a PJS subtitle document. +pub fn parse(text: &str) -> Result { + let mut doc = Document::default(); + let mut found = false; + for (n, line) in text.lines().enumerate() { + let line = line.trim(); + if line.is_empty() { + continue; + } + let Some((start_ds, end_ds, raw)) = split_cue(line) else { + doc.warnings.push(format!("line {}: not a PJS cue, skipped", n + 1)); + continue; + }; + found = true; + let mut lines = Vec::new(); + for l in raw.split('|') { + let trimmed = l.trim(); + if !trimmed.is_empty() { + let unquoted = trimmed.replace("\"\"", "\""); + lines.push(escape_markup(&unquoted)); + } + } + let start = ms_to_tick(start_ds.saturating_mul(100)); + let end = ms_to_tick(end_ds.saturating_mul(100)); + if end <= start || lines.is_empty() { + doc.warnings.push(format!("line {}: empty or ends before it starts; skipped", n + 1)); + continue; + } + doc.cues.push(Cue { start, end, text: lines.join("\n"), ..Default::default() }); + } + if !found && !text.trim().is_empty() { + return Err(Error::NotFormat("PJS")); + } + Ok(doc) +} + +/// Serialize a document into PJS format. +pub fn write(doc: &Document) -> String { + let mut out = String::new(); + let ds = |t| (tick_to_ms(t) + 50) / 100; + for c in &doc.cues { + let start = ds(c.start); + let end = ds(c.end).max(start + 1); + let lines: Vec = + plain_lines(&c.text).into_iter().map(|l| l.replace('"', "\"\"").replace('|', "|")).filter(|l| !l.is_empty()).collect(); + if !lines.is_empty() { + out.push_str(&format!("{start},{end},\"{}\"\n", lines.join("|"))); + } + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parse_and_write_roundtrip() { + let pjs = "10,50,\"First line\"\n60,120,\"Second line|with break\"\n130,150,\"Say \"\"Hi\"\"\"\n"; + let doc = parse(pjs).expect("parse"); + assert_eq!(doc.cues.len(), 3); + assert_eq!(doc.cues[0].start, ms_to_tick(1000)); + assert_eq!(doc.cues[0].end, ms_to_tick(5000)); + assert_eq!(doc.cues[0].text, "First line"); + assert_eq!(doc.cues[1].start, ms_to_tick(6000)); + assert_eq!(doc.cues[1].end, ms_to_tick(12000)); + assert_eq!(doc.cues[1].text, "Second line\nwith break"); + assert_eq!(doc.cues[2].text, "Say \"Hi\""); + + let written = write(&doc); + assert_eq!(written, pjs); + } + + #[test] + fn rejects_non_pjs() { + assert!(parse("1\n00:00:01,000 --> 00:00:02,000\nHello\n").is_err()); + } +} diff --git a/crates/captions/src/realtext.rs b/crates/captions/src/realtext.rs new file mode 100644 index 000000000..1c4328a3b --- /dev/null +++ b/crates/captions/src/realtext.rs @@ -0,0 +1,247 @@ +//! RealText (`.rt`): streaming HTML-like timed text markup. +//! +//! ```text +//! +//! +//! ``` +//! +//! RealText documents encapsulate timed text inside a `` container with `