diff --git a/.cargo/config.toml b/.cargo/config.toml deleted file mode 100644 index 873f4f7aa..000000000 --- a/.cargo/config.toml +++ /dev/null @@ -1,2 +0,0 @@ -[lints] -cargo.unused_workspace_dependencies = "allow" diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 8840199b2..02935bac6 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -90,7 +90,7 @@ and the exact transfer revision are recorded in each vendored crate's SOURCE.jso | `crates/psd/tests/fixtures/atn/*.atn` (seven synthetic action sets, encoded field by field; `crates/psd/tests/fixtures/atn/README.md`) | PhotoCraft contributors | [PhotoCraft `crates/psd/tests/fixtures/atn`](https://github.com/storytold/photocraft/tree/63b641b55e54bf8f5c83efd977fdb16a2c255431/crates/psd/tests/fixtures/atn) | MIT OR Apache-2.0 | | `crates/lottie/tests/fixtures/` | EffectCraft contributors (original work: four hand-written Lottie JSON documents, written from the public Lottie format description; not exported from any Adobe product or third-party file) | [EffectCraft `crates/lottie/tests/fixtures`](https://github.com/storytold/effectcraft/tree/e18f48fb/crates/lottie/tests/fixtures) | MIT OR Apache-2.0 | | `crates/pkcs7/tests/data/` | PdfCraft contributors (original work: throw-away test keys and certificates made with OpenSSL 3 for these tests, as seven PKCS #12 files with the password `test` and two PEM certificates; they protect nothing; commands in `crates/pkcs7/tests/data/README.md`) | [PdfCraft `crates/sign/tests/data`](https://github.com/storytold/pdfcraft/tree/1d7a9f9f/crates/sign/tests/data) | MIT OR Apache-2.0 | -| `crates/affinity/tests/support/corpus.tsv`, `crates/affinity/tests/support/affinity3-signatures.txt` (manifest and measured signatures only; the 51 documents are not bundled, `scripts/fetch-affinity-corpus.sh` downloads them outside the checkout) | The authors of each document: samuel-etver (vector-art), Seth A. Robinson (Patchy fixtures), Nick Beeuwsaert (AFDesignLoad), Jeremy Cantu (Branding), eviltwo (AssetStoreTemplate), Square (leakcanary) | each file's pinned upstream URL and SHA-256 in the manifest; list carried over from [VectorCraft `xtask/src/affinity_corpus.rs`](https://github.com/storytold/vectorcraft/blob/6e873b806c9d5b3f2b55f651df57bd97933b579a/xtask/src/affinity_corpus.rs) | CC0-1.0, MIT or Apache-2.0 (per file, in the manifest) | +| `crates/affinity/tests/support/corpus.tsv`, `crates/affinity/tests/support/affinity3-signatures.txt` (manifest and measured signatures only; the 113 files, 90 of them documents, are not bundled, `scripts/fetch-affinity-corpus.sh` downloads them outside the checkout) | The authors of each document: samuel-etver (vector-art), satoshoe-dev (affinity-samples), Seth A. Robinson (Patchy fixtures), Nick Beeuwsaert (AFDesignLoad), Jeremy Cantu (Branding), eviltwo (AssetStoreTemplate), Square (leakcanary) | each file's pinned upstream URL and SHA-256 in the manifest; every name from [VectorCraft `xtask/src/affinity_corpus.rs`](https://github.com/storytold/vectorcraft/blob/bada8e17103db9917de44e40a1cead5a7fc71c3c/xtask/src/affinity_corpus.rs) and [PhotoCraft `xtask/affinity-corpus.sha256`](https://github.com/storytold/photocraft/blob/629751503165118d5fec5f70e64fe2d6592f7b53/xtask/affinity-corpus.sha256) | CC0-1.0, MIT or Apache-2.0 (per file, in the manifest) | | `crates/raw/docs/coverage/adobe-cameras.tsv` | Facts (maker, model, extension, profile, minimum Camera Raw version) parsed by LightCraft contributors from Adobe's published list | [Adobe Camera Raw supported cameras](https://helpx.adobe.com/camera-raw/desktop/dng-and-file-formats/camera-raw-plug-supported-cameras.html), Wayback capture 20261003133011; moved from [LightCraft `docs/raw`](https://github.com/storytold/lightcraft/tree/5ff567a4a2e067bef1b6bce152c11e7f727ccbaf/docs/raw) | Facts, not copyrightable expression; the file is MIT OR Apache-2.0 | | `crates/raw/docs/coverage/{coverage,coverage-sweep,evidence,usage-weights}.tsv`, `coverage.py` | LightCraft contributors | [LightCraft `docs/raw`](https://github.com/storytold/lightcraft/tree/5ff567a4a2e067bef1b6bce152c11e7f727ccbaf/docs/raw) | MIT OR Apache-2.0 | | `crates/raw/docs/raf-corpus.sha256` (hashes only; the files are not bundled) | The photographers who contributed each file to raw.pixls.us | [raw.pixls.us](https://raw.pixls.us/) | CC0-1.0 | @@ -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/Cargo.lock b/Cargo.lock index ef82f1afa..74732b6d6 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -502,7 +502,7 @@ dependencies = [ "log", "num-rational", "num-traits", - "pastey", + "pastey 0.1.1", "rayon", "thiserror 2.0.21", "v_frame", @@ -568,6 +568,12 @@ version = "1.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "fd307490d624467aa6f74b0eabb77633d1f758a7b25f12bceb0b22e08d9726f6" +[[package]] +name = "base64" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e1b586273c5702936fe7b7d6896644d8be71e6314cfe09d3167c95f712589e8" + [[package]] name = "base64" version = "0.22.1" @@ -992,6 +998,64 @@ dependencies = [ "cipher 0.4.4", ] +[[package]] +name = "candle-core" +version = "0.9.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c15b675b80d994b2eadb20a4bbe434eabeb454eac3ee5e2b4cf6f147ee9be091" +dependencies = [ + "byteorder", + "float8", + "gemm", + "half", + "libm", + "memmap2", + "num-traits", + "num_cpus", + "rand 0.9.5", + "rand_distr", + "rayon", + "safetensors", + "thiserror 2.0.21", + "yoke", + "zip 7.4.0", +] + +[[package]] +name = "candle-nn" +version = "0.9.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3045fa9e7aef8567d209a27d56b692f60b96f4d0569f4c3011f8ca6715c65e03" +dependencies = [ + "candle-core", + "half", + "libc", + "num-traits", + "rayon", + "safetensors", + "serde", + "thiserror 2.0.21", +] + +[[package]] +name = "candle-transformers" +version = "0.9.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b538ec4aa807c416a2ddd3621044888f188827862e2a6fcacba4738e89795d01" +dependencies = [ + "byteorder", + "candle-core", + "candle-nn", + "fancy-regex 0.17.0", + "num-traits", + "rand 0.9.5", + "rayon", + "serde", + "serde_json", + "serde_plain", + "tracing", +] + [[package]] name = "cap-primitives" version = "4.0.3" @@ -1025,6 +1089,15 @@ dependencies = [ "cipher 0.4.4", ] +[[package]] +name = "castaway" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dec551ab6e7578819132c713a93c022a05d60159dc86e7a7050223577484c55a" +dependencies = [ + "rustversion", +] + [[package]] name = "cbc" version = "0.2.1" @@ -1260,6 +1333,21 @@ dependencies = [ "memchr", ] +[[package]] +name = "compact_str" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9dfdd1c2274d9aa354115b09dc9a901d6c5576818cdf70d14cae2bdb47df00ab" +dependencies = [ + "castaway", + "cfg-if", + "itoa", + "rustversion", + "ryu", + "serde", + "static_assertions", +] + [[package]] name = "concurrent-queue" version = "2.5.0" @@ -1296,6 +1384,35 @@ dependencies = [ "unicode-segmentation", ] +[[package]] +name = "cookie" +version = "0.18.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a373e3602691c3cdea496d2f0ee5935151e6168fe87739483c463db1b2f2f87" +dependencies = [ + "percent-encoding", + "time", + "version_check", +] + +[[package]] +name = "cookie_store" +version = "0.22.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "15b2c103cf610ec6cae3da84a766285b42fd16aad564758459e6ecf128c75206" +dependencies = [ + "cookie", + "document-features", + "idna", + "indexmap", + "log", + "serde", + "serde_derive", + "serde_json", + "time", + "url", +] + [[package]] name = "core-foundation" version = "0.9.4" @@ -1411,6 +1528,23 @@ dependencies = [ "sha2 0.10.9", ] +[[package]] +name = "craft-ai" +version = "0.1.0" +dependencies = [ + "candle-core", + "candle-nn", + "candle-transformers", + "dirs", + "serde", + "serde_json", + "sha2 0.11.1", + "sysinfo", + "tempfile", + "tokenizers", + "ureq", +] + [[package]] name = "craft-ai-core" version = "0.1.0" @@ -1574,7 +1708,7 @@ dependencies = [ "serde", "serde_json", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -1645,7 +1779,7 @@ dependencies = [ "craft-zip", "serde_json", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -1669,7 +1803,7 @@ dependencies = [ "thiserror 2.0.21", "unicode-bidi", "zeroize", - "zip", + "zip 9.1.3", ] [[package]] @@ -1744,7 +1878,7 @@ dependencies = [ "craft-xml", "craft-zip", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -1787,7 +1921,7 @@ dependencies = [ "ruzstd", "serde_json", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -1798,7 +1932,7 @@ dependencies = [ "serde", "serde_json", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -2059,7 +2193,7 @@ dependencies = [ "craft-xml", "craft-zip", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -2183,7 +2317,7 @@ dependencies = [ "craft-xml", "craft-zip", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -2298,6 +2432,9 @@ dependencies = [ [[package]] name = "craft-media-testkit" version = "0.1.0" +dependencies = [ + "craft-testkit", +] [[package]] name = "craft-menu" @@ -2390,7 +2527,7 @@ dependencies = [ "sha2 0.11.1", "thiserror 2.0.21", "zeroize", - "zip", + "zip 9.1.3", ] [[package]] @@ -2427,7 +2564,7 @@ dependencies = [ "craft-zip", "log", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -2452,7 +2589,7 @@ dependencies = [ "craft-xml", "craft-zip", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -2546,7 +2683,7 @@ dependencies = [ "serde", "serde_json", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -2661,6 +2798,16 @@ dependencies = [ "ttf-parser", ] +[[package]] +name = "craft-press-print" +version = "0.1.0" +dependencies = [ + "craft-cms", + "craft-prepress", + "craft-print", + "thiserror 2.0.21", +] + [[package]] name = "craft-print" version = "0.1.0" @@ -2725,6 +2872,7 @@ dependencies = [ name = "craft-pst" version = "0.1.0" dependencies = [ + "craft-pst", "proptest", ] @@ -2849,7 +2997,7 @@ dependencies = [ "kurbo 0.13.1", "serde_json", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -2968,6 +3116,10 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-testkit" +version = "0.1.0" + [[package]] name = "craft-text" version = "0.1.0" @@ -2989,6 +3141,7 @@ version = "0.1.0" dependencies = [ "bytemuck", "dds", + "half", "rayon", "thiserror 2.0.21", ] @@ -3083,7 +3236,7 @@ dependencies = [ "verifysign", "winreg", "winsafe", - "zip", + "zip 9.1.3", ] [[package]] @@ -3223,6 +3376,7 @@ version = "0.1.0" dependencies = [ "craft-cfb", "craft-sheet", + "craft-xls", "md-5 0.10.6", "miniz_oxide 0.9.1", "sha1 0.10.7", @@ -3236,6 +3390,7 @@ dependencies = [ "craft-drawingml", "craft-opc", "craft-sheet", + "craft-xlsx", "craft-xml", "thiserror 2.0.21", ] @@ -3249,6 +3404,15 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-xtask" +version = "0.1.0" +dependencies = [ + "craft-atomic", + "serde_json", + "tempfile", +] + [[package]] name = "craft-y4m" version = "0.1.0" @@ -3269,7 +3433,7 @@ dependencies = [ "serde", "serde_json", "thiserror 2.0.21", - "zip", + "zip 9.1.3", ] [[package]] @@ -3535,6 +3699,15 @@ dependencies = [ "syn 2.0.119", ] +[[package]] +name = "dary_heap" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8b1e3a325bc115f096c8b77bbf027a7c2592230e70be2d985be950d3d5e60ebe" +dependencies = [ + "serde", +] + [[package]] name = "data-encoding" version = "2.11.1" @@ -3854,6 +4027,22 @@ version = "1.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813" +[[package]] +name = "dyn-stack" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c4713e43e2886ba72b8271aa66c93d722116acf7a75555cce11dcde84388fe8" +dependencies = [ + "bytemuck", + "dyn-stack-macros", +] + +[[package]] +name = "dyn-stack-macros" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1d926b4d407d372f141f93bb444696142c29d32962ccbd3531117cf3aa0bfa9" + [[package]] name = "eax" version = "0.5.0" @@ -4209,6 +4398,18 @@ version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "66b7e2430c6dff6a955451e2cfc438f09cea1965a9d6f87f7e3b90decc014099" +[[package]] +name = "enum-as-inner" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1e6a265c649f3f5979b601d26f1d05ada116434c87741c9493cb56218f76cbc" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "enum-map" version = "3.1.0" @@ -4329,6 +4530,12 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "esaxx-rs" +version = "0.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d817e038c30374a4bcb22f94d0a8a0e216958d4c3dcde369b1439fec4bdda6e6" + [[package]] name = "euclid" version = "0.22.14" @@ -4380,6 +4587,17 @@ version = "0.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "af9673d8203fcb076b19dfd17e38b3d4ae9f44959416ea532ce72415a6020365" +[[package]] +name = "fancy-regex" +version = "0.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72cf461f865c862bb7dc573f643dd6a2b6842f7c30b07882b56bd148cc2761b8" +dependencies = [ + "bit-set 0.8.0", + "regex-automata", + "regex-syntax", +] + [[package]] name = "fancy-regex" version = "0.19.2" @@ -4504,6 +4722,18 @@ dependencies = [ "num-traits", ] +[[package]] +name = "float8" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "719a903cc23e4a89e87962c2a80fdb45cdaad0983a89bd150bb57b4c8571a7d5" +dependencies = [ + "half", + "num-traits", + "rand 0.9.5", + "rand_distr", +] + [[package]] name = "fluent-uri" version = "0.4.1" @@ -4762,6 +4992,125 @@ dependencies = [ "slab", ] +[[package]] +name = "gemm" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aa0673db364b12263d103b68337a68fbecc541d6f6b61ba72fe438654709eacb" +dependencies = [ + "dyn-stack", + "gemm-c32", + "gemm-c64", + "gemm-common", + "gemm-f16", + "gemm-f32", + "gemm-f64", + "num-complex", + "num-traits", + "paste", + "raw-cpuid", + "seq-macro", +] + +[[package]] +name = "gemm-c32" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "086936dbdcb99e37aad81d320f98f670e53c1e55a98bee70573e83f95beb128c" +dependencies = [ + "dyn-stack", + "gemm-common", + "num-complex", + "num-traits", + "paste", + "raw-cpuid", + "seq-macro", +] + +[[package]] +name = "gemm-c64" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20c8aeeeec425959bda4d9827664029ba1501a90a0d1e6228e48bef741db3a3f" +dependencies = [ + "dyn-stack", + "gemm-common", + "num-complex", + "num-traits", + "paste", + "raw-cpuid", + "seq-macro", +] + +[[package]] +name = "gemm-common" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "88027625910cc9b1085aaaa1c4bc46bb3a36aad323452b33c25b5e4e7c8e2a3e" +dependencies = [ + "bytemuck", + "dyn-stack", + "half", + "libm", + "num-complex", + "num-traits", + "once_cell", + "paste", + "pulp", + "raw-cpuid", + "rayon", + "seq-macro", + "sysctl", +] + +[[package]] +name = "gemm-f16" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3df7a55202e6cd6739d82ae3399c8e0c7e1402859b30e4cb780e61525d9486e" +dependencies = [ + "dyn-stack", + "gemm-common", + "gemm-f32", + "half", + "num-complex", + "num-traits", + "paste", + "raw-cpuid", + "rayon", + "seq-macro", +] + +[[package]] +name = "gemm-f32" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "02e0b8c9da1fbec6e3e3ab2ce6bc259ef18eb5f6f0d3e4edf54b75f9fd41a81c" +dependencies = [ + "dyn-stack", + "gemm-common", + "num-complex", + "num-traits", + "paste", + "raw-cpuid", + "seq-macro", +] + +[[package]] +name = "gemm-f64" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "056131e8f2a521bfab322f804ccd652520c79700d81209e9d9275bbdecaadc6a" +dependencies = [ + "dyn-stack", + "gemm-common", + "num-complex", + "num-traits", + "paste", + "raw-cpuid", + "seq-macro", +] + [[package]] name = "generic-array" version = "0.14.7" @@ -5051,9 +5400,12 @@ version = "2.7.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b" dependencies = [ + "bytemuck", "cfg-if", "crunchy", "num-traits", + "rand 0.9.5", + "rand_distr", "zerocopy", ] @@ -5100,6 +5452,8 @@ dependencies = [ "allocator-api2", "equivalent", "foldhash 0.2.0", + "serde", + "serde_core", ] [[package]] @@ -5958,7 +6312,7 @@ dependencies = [ "bytecount", "data-encoding", "email_address", - "fancy-regex", + "fancy-regex 0.19.2", "fraction", "getrandom 0.3.4", "idna", @@ -6464,6 +6818,22 @@ dependencies = [ "crc", ] +[[package]] +name = "macro_rules_attribute" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b3ae8f6d608c795738406608304d30a2dfbdc8e58e44f7ba43236da5208ded3c" +dependencies = [ + "macro_rules_attribute-proc_macro", + "pastey 0.2.3", +] + +[[package]] +name = "macro_rules_attribute-proc_macro" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc04a4c58212d57930a24bf47d3fa87485264a3a054e9c10e042eb373573ad3c" + [[package]] name = "maybe-owned" version = "0.3.4" @@ -6513,6 +6883,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "6b0ca1155a9ecc25aa12e8313a119f32edf0255fea2f44839c4ac0a12b2ac157" dependencies = [ "libc", + "stable_deref_trait", ] [[package]] @@ -6583,6 +6954,28 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "monostate" +version = "0.1.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3341a273f6c9d5bef1908f17b7267bbab0e95c9bf69a0d4dcf8e9e1b2c76ef67" +dependencies = [ + "monostate-impl", + "serde", + "serde_core", +] + +[[package]] +name = "monostate-impl" +version = "0.1.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e4db6d5580af57bf992f59068d4ea26fd518574ff48d7639b255a36f9de6e7e9" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "moxcms" version = "0.8.1" @@ -6765,6 +7158,15 @@ version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0676bb32a98c1a483ce53e500a81ad9c3d5b3f7c920c28c24e9cb0980d0b5bc8" +[[package]] +name = "ntapi" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3b335231dfd352ffb0f8017f3b6027a4917f7df785ea2143d8af2adc66980ae" +dependencies = [ + "winapi", +] + [[package]] name = "nu-ansi-term" version = "0.50.3" @@ -6827,6 +7229,7 @@ version = "0.4.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495" dependencies = [ + "bytemuck", "num-traits", ] @@ -6887,6 +7290,16 @@ dependencies = [ "libm", ] +[[package]] +name = "num_cpus" +version = "1.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "91df4bbde75afed763b708b7eee1e8e7651e02d97f6d5dd763e89367e957b23b" +dependencies = [ + "hermit-abi", + "libc", +] + [[package]] name = "num_enum" version = "0.7.6" @@ -7087,6 +7500,16 @@ dependencies = [ "objc2-core-foundation", ] +[[package]] +name = "objc2-io-kit" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33fafba39597d6dc1fb709123dfa8289d39406734be322956a69f0931c73bb15" +dependencies = [ + "libc", + "objc2-core-foundation", +] + [[package]] name = "objc2-io-surface" version = "0.3.2" @@ -7134,6 +7557,17 @@ dependencies = [ "objc2-foundation 0.3.2", ] +[[package]] +name = "objc2-open-directory" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb82bed227edf5201dfedf072bba4015a33d3d4a98519837295a90f0a23f676d" +dependencies = [ + "objc2 0.6.5", + "objc2-core-foundation", + "objc2-foundation 0.3.2", +] + [[package]] name = "objc2-quartz-core" version = "0.2.2" @@ -7264,6 +7698,28 @@ version = "1.21.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" +[[package]] +name = "onig" +version = "6.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0cc3cbf698f9438986c11a880c90a6d04b9de27575afd28bbf45b154b6c709e2" +dependencies = [ + "bitflags 2.13.2", + "libc", + "once_cell", + "onig_sys", +] + +[[package]] +name = "onig_sys" +version = "69.9.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e68317604e77e53b85896388e1a803c1d21b74c899ec9e5e1112db90735edd7" +dependencies = [ + "cc", + "pkg-config", +] + [[package]] name = "oorandom" version = "11.1.5" @@ -7479,6 +7935,12 @@ version = "0.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "35fb2e5f958ec131621fdd531e9fc186ed768cbe395337403ae56c17a74c68ec" +[[package]] +name = "pastey" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4" + [[package]] name = "pbkdf2" version = "0.13.0" @@ -8072,6 +8534,29 @@ dependencies = [ "unarray", ] +[[package]] +name = "pulp" +version = "0.22.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "046aa45b989642ec2e4717c8e72d677b13edd831a4d3b6cf37d9a3e54912496a" +dependencies = [ + "bytemuck", + "cfg-if", + "libm", + "num-complex", + "paste", + "pulp-wasm-simd-flag", + "raw-cpuid", + "reborrow", + "version_check", +] + +[[package]] +name = "pulp-wasm-simd-flag" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1d8f70e07b9c3962945a74e59ca1c511bba65b6419468acc217c457d93f3c740" + [[package]] name = "pxfm" version = "0.1.30" @@ -8277,6 +8762,16 @@ version = "0.10.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69" +[[package]] +name = "rand_distr" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6a8615d50dcf34fa31f7ab52692afec947c4dd0ab803cc87cb3b0b4570ff7463" +dependencies = [ + "num-traits", + "rand 0.9.5", +] + [[package]] name = "rand_pcg" version = "0.10.2" @@ -8351,6 +8846,15 @@ dependencies = [ "rgb", ] +[[package]] +name = "raw-cpuid" +version = "11.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "498cd0dc59d73224351ee52a95fee0f1a617a2eae0e7d9d720cc622c73a54186" +dependencies = [ + "bitflags 2.13.2", +] + [[package]] name = "raw-window-handle" version = "0.6.2" @@ -8379,6 +8883,17 @@ dependencies = [ "rayon-core", ] +[[package]] +name = "rayon-cond" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2964d0cf57a3e7a06e8183d14a8b527195c706b7983549cd5462d5aa3747438f" +dependencies = [ + "either", + "itertools 0.14.0", + "rayon", +] + [[package]] name = "rayon-core" version = "1.13.0" @@ -8467,6 +8982,12 @@ dependencies = [ "yoke", ] +[[package]] +name = "reborrow" +version = "0.5.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "03251193000f4bd3b042892be858ee50e8b3719f2b08e5833ac4353724632430" + [[package]] name = "recvmsg" version = "1.0.0" @@ -9029,6 +9550,17 @@ version = "1.0.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "04d056b875a9d2e6cb9a61d127afee9ac5999b9f87bcb32079d1318e505be714" +[[package]] +name = "safetensors" +version = "0.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "675656c1eabb620b921efea4f9199f97fc86e36dd6ffd1fbbe48d0f59a4987f5" +dependencies = [ + "hashbrown 0.16.1", + "serde", + "serde_json", +] + [[package]] name = "same-file" version = "1.0.6" @@ -9127,6 +9659,12 @@ version = "0.6.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cd0b0ec5f1c1ca621c432a25813d8d60c88abe6d3e08a3eb9cf37d97a0fe3d73" +[[package]] +name = "seq-macro" +version = "0.3.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc" + [[package]] name = "serde" version = "1.0.229" @@ -9181,6 +9719,15 @@ dependencies = [ "serde_json", ] +[[package]] +name = "serde_plain" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ce1fc6db65a611022b23a0dec6975d63fb80a302cb3388835ff02c097258d50" +dependencies = [ + "serde", +] + [[package]] name = "serde_repr" version = "0.1.21" @@ -9712,6 +10259,18 @@ dependencies = [ "der 0.8.3", ] +[[package]] +name = "spm_precompiled" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5851699c4033c63636f7ea4cf7b7c1f1bf06d0cc03cfb42e711de5a5c46cf326" +dependencies = [ + "base64 0.13.1", + "nom 7.1.3", + "serde", + "unicode-segmentation", +] + [[package]] name = "sponge-cursor" version = "0.1.0" @@ -10097,6 +10656,35 @@ dependencies = [ "web-sys", ] +[[package]] +name = "sysctl" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "01198a2debb237c62b6826ec7081082d951f46dbb64b0e8c7649a452230d1dfc" +dependencies = [ + "bitflags 2.13.2", + "byteorder", + "enum-as-inner", + "libc", + "thiserror 1.0.69", + "walkdir", +] + +[[package]] +name = "sysinfo" +version = "0.39.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2071df9448915b71c4fe6d25deaf1c22f12bd234f01540b77312bb8e41361e6" +dependencies = [ + "libc", + "memchr", + "ntapi", + "objc2-core-foundation", + "objc2-io-kit", + "objc2-open-directory", + "windows", +] + [[package]] name = "system-configuration" version = "0.7.0" @@ -10346,6 +10934,39 @@ dependencies = [ "syn 2.0.119", ] +[[package]] +name = "tokenizers" +version = "0.22.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b238e22d44a15349529690fb07bd645cf58149a1b1e44d6cb5bd1641ff1a6223" +dependencies = [ + "ahash", + "aho-corasick", + "compact_str", + "dary_heap", + "derive_builder", + "esaxx-rs", + "getrandom 0.3.4", + "itertools 0.14.0", + "log", + "macro_rules_attribute", + "monostate", + "onig", + "paste", + "rand 0.9.5", + "rayon", + "rayon-cond", + "regex", + "regex-syntax", + "serde", + "serde_json", + "spm_precompiled", + "thiserror 2.0.21", + "unicode-normalization-alignments", + "unicode-segmentation", + "unicode_categories", +] + [[package]] name = "tokio" version = "1.53.2" @@ -10559,6 +11180,12 @@ dependencies = [ "rustc-hash 2.1.3", ] +[[package]] +name = "typed-path" +version = "0.12.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "54ec2755506471f54baf5e4bb5499d8e510cc1caf271270e778a736bd2d7336c" + [[package]] name = "typed-path" version = "0.13.0" @@ -10633,6 +11260,15 @@ dependencies = [ "tinyvec", ] +[[package]] +name = "unicode-normalization-alignments" +version = "0.1.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "43f613e4fa046e69818dd287fdc4bc78175ff20331479dab6e1b0f98d57062de" +dependencies = [ + "smallvec", +] + [[package]] name = "unicode-properties" version = "0.1.4" @@ -10669,6 +11305,12 @@ version = "0.2.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853" +[[package]] +name = "unicode_categories" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39ec24b3121d976906ece63c9daad25b85969647682eee313cb5779fdd69e14e" + [[package]] name = "universal-hash" version = "0.5.1" @@ -10698,12 +11340,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cde93ff05758a36a851a398a772b0b79a82fbe3c186a46f2696baaeaf84c966b" dependencies = [ "base64 0.23.1", + "cookie_store", "flate2", "log", "percent-encoding", "rustls", "rustls-pki-types", "rustls-platform-verifier", + "serde", + "serde_json", "ureq-proto", "utf8-zero", "webpki-roots", @@ -11652,6 +12297,22 @@ version = "1.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "72069c3113ab32ab29e5584db3c6ec55d416895e60715417b5b883a357c3e471" +[[package]] +name = "winapi" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419" +dependencies = [ + "winapi-i686-pc-windows-gnu", + "winapi-x86_64-pc-windows-gnu", +] + +[[package]] +name = "winapi-i686-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" + [[package]] name = "winapi-util" version = "0.1.11" @@ -11661,6 +12322,12 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "winapi-x86_64-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" + [[package]] name = "windows" version = "0.62.2" @@ -12410,6 +13077,18 @@ dependencies = [ "syn 3.0.6", ] +[[package]] +name = "zip" +version = "7.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc12baa6db2b15a140161ce53d72209dacea594230798c24774139b54ecaa980" +dependencies = [ + "crc32fast", + "indexmap", + "memchr", + "typed-path 0.12.4", +] + [[package]] name = "zip" version = "9.1.3" @@ -12422,7 +13101,7 @@ dependencies = [ "indexmap", "memchr", "nix", - "typed-path", + "typed-path 0.13.0", "windows-sys 0.61.2", ] diff --git a/Cargo.toml b/Cargo.toml index c8ae36287..72ae0083a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -26,6 +26,7 @@ craft-plist = { path = "crates/plist" } craft-platform = { path = "crates/platform" } craft-aep = { path = "crates/aep" } craft-affinity = { path = "crates/affinity" } +craft-ai = { path = "crates/ai" } craft-ai-core = { path = "crates/ai-core" } craft-anicraft-format = { path = "crates/anicraft-format" } craft-pdf = { path = "crates/pdf", version = "=0.1.0" } @@ -48,6 +49,7 @@ craft-gzip = { path = "crates/gzip" } craft-gridcraft-format = { path = "crates/gridcraft-format" } craft-aaf = { path = "crates/aaf" } craft-atomic = { path = "crates/atomic" } +craft-xtask = { path = "crates/xtask" } craft-captions = { path = "crates/captions" } craft-cfb = { path = "crates/cfb" } craft-codepage = { path = "crates/codepage" } @@ -142,6 +144,7 @@ craft-pcraft-bundle = { path = "crates/pcraft-bundle" } craft-pkcs7 = { path = "crates/pkcs7" } craft-plotter = { path = "crates/plotter" } craft-prepress = { path = "crates/prepress" } +craft-press-print = { path = "crates/press-print" } craft-print = { path = "crates/print" } craft-proof = { path = "crates/proof" } craft-raster-codecs = { path = "crates/raster-codecs" } @@ -163,6 +166,7 @@ craft-stencilcraft-format = { path = "crates/stencilcraft-format" } craft-stencilcraft-document = { path = "crates/stencilcraft-document" } craft-svg-paths = { path = "crates/svg-paths" } craft-stream-codecs = { path = "crates/stream-codecs" } +craft-testkit = { path = "crates/testkit" } craft-text = { path = "crates/text" } craft-tcraft = { path = "crates/tcraft" } craft-texture = { path = "crates/texture" } @@ -210,6 +214,9 @@ chrono = { version = "0.4.45", default-features = false, features = ["std"] } unsafe_code = "forbid" unexpected_cfgs = { level = "warn", check-cfg = ["cfg(craft_pdf_unicode_fixtures)"] } +[workspace.lints.cargo] +unused_workspace_dependencies = "allow" + [workspace.lints.clippy] cognitive_complexity = "deny" too_many_arguments = "deny" diff --git a/NOTICE b/NOTICE index c3cdbabc8..35085dcb3 100644 --- a/NOTICE +++ b/NOTICE @@ -254,11 +254,10 @@ applications retain their own document-font selection and licensing policy. linesweeper linesweeper 0.5.0 (https://crates.io/crates/linesweeper/0.5.0), MIT OR Apache-2.0, is stored in -vendor/linesweeper with its upstream license files and local patches, to src/sweep/sweep_line.rs and -docs/sweep.typ. Its manifest names Joe Neeman as author, and its LICENSE-MIT reads "Copyright (c) 2018 -Raph Levien". See vendor/linesweeper/README.craft.md and vendor/linesweeper/SOURCE.json for -provenance, the local patches -and the files left out. +vendor/linesweeper with its upstream license files and local patches, to src/sweep/sweep_line.rs, +src/curve/mod.rs, src/curve/line.rs and docs/sweep.typ. Its manifest names Joe Neeman as author, and +its LICENSE-MIT reads "Copyright (c) 2018 Raph Levien". See vendor/linesweeper/README.craft.md and +vendor/linesweeper/SOURCE.json for provenance, the local patches and the files left out. Platform lifecycle source provenance diff --git a/README.md b/README.md index a3373f3a3..5650bb932 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,7 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit - [`craft-assuan`](crates/assuan/README.md): the Assuan protocol and gpg-agent's operations (key lookup, signing a digest, decrypting a session key) over any `Read + Write` stream, with a bounded canonical S-expression reader. No sockets; everything the agent sends is capped. - [`craft-affinity`](crates/affinity/README.md): bounded reader for native Affinity documents (`.af`, `.afdesign`, `.afphoto`, `.afpub`): archive, object stream and a neutral document model with layers, artboards, vectors, text, tables, images and masks. Read only; mapping onto an app's document stays in the app. - [`craft-atomic`](crates/atomic/README.md): Crash-safe atomic file writing and replacement with same-directory staging, directory fsync, Apple `F_FULLFSYNC` fallback, transient lock backoff, and fault injection for the Craft suite. +- [`craft-xtask`](crates/xtask/README.md): a library for the apps' `cargo xtask` binaries: the gate's step runner (steps in order, stop at the first failure, the ok, FAIL and skip summary, workspace tests that exclude the running xtask package), an optional slot lock held across processes and an optional per-step JSON report. Each app keeps its step list and its own policy. Planned for DesignCraft and LightCraft. - [`craft-captions`](crates/captions/README.md): caption and subtitle files behind one neutral model (cues with exact tick times): SubRip, WebVTT, Scenarist SCC, MacCaption MCC, EBU STL and TTML / IMSC1 / DFXP readers and writers, and CEA-608 / CEA-708 byte-pair coding. Carved from @@ -286,9 +287,8 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit stay in each app. - [`craft-mesh`](crates/mesh/README.md): 3D mesh file formats behind one neutral model (meshes of polygons with per-corner indices, materials, a node hierarchy): STL, OBJ with MTL, PLY, - glTF 2.0 / GLB and 3MF, one feature each. Readers are bounded by `Limits`, never open a file themselves - glTF 2.0 / GLB and FBX, one feature each. Readers are bounded by `Limits`, never open a file themselves - and never panic. Carved from EffectCraft, SolidCraft, TextureCraft and MaterialCraft. + glTF 2.0 / GLB, FBX and 3MF, one feature each. Readers are bounded by `Limits`, never open a file + themselves and never panic. Carved from EffectCraft, SolidCraft, TextureCraft and MaterialCraft. - [`craft-midi`](crates/midi/README.md): Standard MIDI Files: a bounded reader for formats 0, 1 and 2 and a format-1 writer, over a neutral model of notes and channel events in ticks at 960 per quarter note. From SoundCraft. @@ -326,6 +326,9 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit - [`craft-pptx`](crates/pptx/README.md): PresentationML, the model of a `.pptx` presentation: masters, layouts, slides, shapes, placeholders and their inheritance, transitions and animations, comments, sections, media and kept parts. From DeckCraft. DrawingML comes from `craft-drawingml`. +- [`craft-press-print`](crates/press-print/README.md): press-accurate printing: a PDF page separated + into plates by `craft-prepress`, composited into the printer's RGB profile and printed through + `craft-print`'s RGB transport, application-managed. - [`craft-print`](crates/print/README.md): PDF submission to CUPS and Windows, printer discovery, duplex/copies/colour and driver preferences. PDF generation stays in each app. - [`craft-proof`](crates/proof/README.md): proofing per language (spelling, suggestions, grammar, @@ -364,6 +367,13 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit check for drawing a tree with resvg. Apps take usvg from here, not as their own dependency. - [`craft-svg-paths`](crates/svg-paths/src/lib.rs): the former name of `craft-svg`'s `paths`, `color` and `write`; re-exports them for existing users. +- [`craft-testkit`](crates/testkit/README.md): test support for the apps' own tests. Its `guards` module + reports source patterns that broke platforms before: muda's predefined Quit item, WGSL float literals + out of range, and `std::time::Instant` in code the web build runs. Its `deadline` module fails a test + whose body runs past a limit, or whose condition does not hold in time; a variable the caller names + replaces each limit. Its `hostile` module runs a parser on every truncation and on seeded damaged + copies of a valid input, and fails the test with the case that panicked or did not finish. Not + published. - [`craft-text`](crates/text/README.md): text processing below the composer. Its `hyphen` module finds hyphenation points, with a bundled US English dictionary and patterns and optional hypher patterns for 47 more languages (one cargo feature each). @@ -371,6 +381,7 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit nearest and bilinear sampling that repeats or clamps, resizing and display conversion. Sizes are bounded by `Limits`. From MaterialCraft. - [`craft-ui`](crates/ui/README.md): SVG catalogs, icon buttons, tabs, pane controls, transactional docking, print settings and theme helpers for egui frontends; +- [`craft-ai`](crates/ai/README.md) *(spec)*: AI provider abstraction — BYO API keys (OpenAI-compatible) and one-click curated local models with capability probing, resumable checksummed downloads, and document segmentation that protects markup while translating prose; assets, themes, localization and command handling stay in each app. Requires Rust 1.95 or later. - [`craft-vcard`](crates/vcard/README.md): vCard contacts, from MailCraft: vCard 2.1, 3.0 and 4.0 read (legacy character sets, quoted-printable, labels and Apple label groups, `KEY` certificates and diff --git a/crates/affinity/README.md b/crates/affinity/README.md index 8567507e8..4a15037a5 100644 --- a/crates/affinity/README.md +++ b/crates/affinity/README.md @@ -115,11 +115,15 @@ text-frame fixture. against the limits below: grids of 16 million cells, grids and stories shared by many layers, 200 000 paragraphs, a document embedded hundreds of times, compounds that fan out or contain themselves, lists of a million null slots linked many times. -* `scripts/fetch-affinity-corpus.sh` fetches 51 public CC0/MIT/Apache-2.0 documents at pinned - commits, SHA-256 verified against `tests/support/corpus.tsv` (which names each file's source and - licence), with the upstream licence notices. Of these, 33 are current `.af`: four CC0 vector - illustrations and 28 original Affinity 3.2.3 feature probes plus one separately identified - derived regression input from [SethRobinson/Patchy](https://github.com/SethRobinson/Patchy) +* `scripts/fetch-affinity-corpus.sh` fetches 113 files at pinned commits, SHA-256 verified + against `tests/support/corpus.tsv` (which names each file's source and license): 90 public + CC0/MIT/Apache-2.0 documents, the 21 PNG files published with the + [satoshoe-dev/affinity-samples](https://github.com/satoshoe-dev/affinity-samples) documents, and + two upstream license notices. The manifest holds every name from the PhotoCraft and VectorCraft + corpus lists, so 21 files are fetched under two names. Of the documents, 55 are current `.af`: + four CC0 vector illustrations (each under two names), 18 CC0 Affinity 3.1.0 samples from + satoshoe-dev/affinity-samples, and 28 original Affinity 3.2.3 feature probes plus one separately + identified derived regression input from [SethRobinson/Patchy](https://github.com/SethRobinson/Patchy) (MIT). Only document data and provenance notices were inspected, never that project's importer or authoring scripts. The files are never committed. @@ -129,11 +133,14 @@ text-frame fixture. ``` Without `AFFINITY_CORPUS` the corpus tests are skipped. `AFFINITY_SAMPLES` names any other - folder of documents to parse. -* `tests/it/real_files.rs` parses every file and freezes the modelled features of all 33 current - `.af` files (`tests/support/affinity3-signatures.txt`: counts, fonts, artboards, warnings and a - CRC of the whole model). Native raster tests compare decoded pixels with independent embedded - images; text tests assert Unicode run boundaries, fallback fonts and feature retention. + folder of documents to parse. A corpus folder fetched for an older manifest fails the tests + until the script is run on it again. +* `tests/it/real_files.rs` checks the shape of every manifest row (four fields, a SHA-256, a + relative name listed once, a license and an `https` URL), parses every file and freezes the + modeled features of all 55 `.af` files (`tests/support/affinity3-signatures.txt`: counts, + fonts, artboards, warnings and a CRC of the whole model). Native raster tests compare decoded + pixels with independent embedded images; text tests assert Unicode run boundaries, fallback + fonts and feature retention. * `fuzz/` has `cargo-fuzz` targets for the whole reader (`container`) and the object stream (`stream`): diff --git a/crates/affinity/tests/it/real_files.rs b/crates/affinity/tests/it/real_files.rs index 18228bfc2..673173c80 100644 --- a/crates/affinity/tests/it/real_files.rs +++ b/crates/affinity/tests/it/real_files.rs @@ -22,8 +22,55 @@ fn files(dir: &Path, out: &mut Vec) { } fn samples() -> Option { - let pinned = corpus::pinned(); - std::env::var_os("AFFINITY_SAMPLES").map(PathBuf::from).or(pinned) + folder(std::env::var_os("AFFINITY_SAMPLES"), corpus::pinned) +} + +/// The `AFFINITY_SAMPLES` folder when one is given, without reading the pinned corpus; otherwise +/// the pinned corpus. +fn folder(samples: Option, pinned: impl FnOnce() -> Option) -> Option { + samples.map(PathBuf::from).or_else(pinned) +} + +#[test] +fn a_samples_folder_is_used_without_the_pinned_corpus() { + assert_eq!(folder(Some("samples".into()), || panic!("the pinned corpus was read")), Some(PathBuf::from("samples"))); + assert_eq!(folder(None, || Some(PathBuf::from("pinned"))), Some(PathBuf::from("pinned"))); + assert_eq!(folder(None, || None), None); +} + +#[test] +fn the_pinned_manifest_is_well_formed() { + let rows = corpus::rows(corpus::MANIFEST).unwrap(); + assert!(rows.iter().filter(|r| r.name.ends_with(".af")).count() >= 4); +} + +#[test] +fn the_manifest_check_rejects_malformed_rows() { + let digest = "0".repeat(64); + let url = "https://example.com/a.af"; + let row = |name: &str| format!("{digest}\t{name}\tMIT\t{url}\n"); + // Two names may share a digest. + assert!(corpus::rows(&(row("a.af") + &row("dir/b.af"))).is_ok()); + for (bad, why) in [ + (row("a.af") + &row("a.af"), "listed twice"), + (format!("{digest}\ta.af\tMIT\n"), "four tab-separated fields"), + (format!("{digest}\ta.af\tMIT\t{url}\textra\n"), "four tab-separated fields"), + (format!("{}\ta.af\tMIT\t{url}\n", "0".repeat(63)), "invalid SHA-256"), + (format!("{}\ta.af\tMIT\t{url}\n", "A".repeat(64)), "invalid SHA-256"), + (row("../a.af"), "relative path"), + (row("/a.af"), "relative path"), + (row("dir//a.af"), "relative path"), + (row("dir\\a.af"), "relative path"), + (row("C:a.af"), "relative path"), + (format!("{digest}\ta.af\t \t{url}\n"), "no license"), + (format!("{digest}\ta.af\tMIT\thttp://example.com/a.af\n"), "https"), + (format!("{digest}\ta.af\tMIT\thttps://\n"), "https"), + ] { + match corpus::rows(&bad) { + Ok(_) => panic!("accepted {bad:?}"), + Err(e) => assert!(e.contains(why), "{bad:?}: {e}"), + } + } } #[test] diff --git a/crates/affinity/tests/support/affinity3-signatures.txt b/crates/affinity/tests/support/affinity3-signatures.txt index 79ed6df5e..f6b20d056 100644 --- a/crates/affinity/tests/support/affinity3-signatures.txt +++ b/crates/affinity/tests/support/affinity3-signatures.txt @@ -1,3 +1,21 @@ +affinity-samples/01-layer-effects.af dpi=72;spreads=1;model_crc32=9a2e65d6;counts={"depth": 2, "fills": 13, "gradients": 0, "layers": 12, "nodes": 38, "segments": 51, "shapes": 13, "strokes": 0, "subpaths": 13, "text_chars": 166, "text_runs": 13, "texts": 13};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["blur effects (left out)", "layer effects of other kinds (left out) (2×)", "paragraph leading of an unknown kind (imported as automatic) (13×)", "unknown layers attached to other layers (imported without them) (2×)"] +affinity-samples/02-adjustment-layers.af dpi=72;spreads=1;model_crc32=fc8b239f;counts={"depth": 2, "fills": 17, "gradients": 16, "layers": 8, "nodes": 42, "segments": 51, "shapes": 17, "strokes": 0, "subpaths": 17, "text_chars": 96, "text_runs": 9, "texts": 9, "unsupported": 8};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["adjustment layers (8×)", "paragraph leading of an unknown kind (imported as automatic) (9×)"] +affinity-samples/03-brush-strokes.af dpi=72;spreads=1;model_crc32=a492c413;counts={"depth": 1, "fills": 1, "gradients": 0, "hidden": 4, "images": 2, "nodes": 14, "segments": 15, "shapes": 7, "strokes": 6, "subpaths": 7, "text_chars": 107, "text_runs": 5, "texts": 5};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (5×)"] +affinity-samples/04-master-page.af dpi=300;spreads=3;model_crc32=ba260d8d;counts={"depth": 3, "fills": 1, "gradients": 0, "layers": 6, "master_instances": 3, "nodes": 30, "segments": 18, "shapes": 9, "strokes": 0, "subpaths": 9, "text_chars": 31, "text_runs": 3, "texts": 3, "unsupported": 9};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (3×)", "text fields such as page numbers (left out of the text)", "text whose story could not be read (master-page text, or an unknown layout) (9×)"] +affinity-samples/05-symbols.af dpi=72;spreads=1;model_crc32=fe74faa6;counts={"depth": 2, "fills": 5, "gradients": 0, "groups": 1, "layers": 3, "nodes": 40, "segments": 129, "shapes": 32, "strokes": 1, "subpaths": 32, "text_chars": 179, "text_runs": 4, "texts": 4};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (4×)"] +affinity-samples/06-special-shapes.af dpi=72;spreads=1;model_crc32=7e9a9eb3;counts={"depth": 1, "fills": 17, "gradients": 0, "nodes": 50, "segments": 268, "shapes": 33, "strokes": 16, "subpaths": 34, "text_chars": 182, "text_runs": 17, "texts": 17};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (17×)"] +affinity-samples/07-transparency.af dpi=72;spreads=1;model_crc32=6595042f;counts={"depth": 1, "fills": 18, "gradients": 1, "nodes": 26, "opacity": 1, "segments": 57, "shapes": 19, "strokes": 0, "subpaths": 19, "text_chars": 151, "text_runs": 7, "texts": 7};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["bitmap and pattern fills (left empty)", "paragraph leading of an unknown kind (imported as automatic) (7×)", "transparency gradients (imported without them) (2×)"] +affinity-samples/08-gradients.af dpi=72;spreads=1;model_crc32=5638db4d;counts={"depth": 1, "fills": 7, "gradients": 6, "nodes": 14, "segments": 27, "shapes": 7, "strokes": 0, "subpaths": 7, "text_chars": 97, "text_runs": 7, "texts": 7};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (7×)"] +affinity-samples/09-corners-stars.af dpi=72;spreads=1;model_crc32=e3528065;counts={"depth": 2, "fills": 9, "gradients": 0, "layers": 8, "nodes": 26, "segments": 81, "shapes": 9, "strokes": 0, "subpaths": 9, "text_chars": 122, "text_runs": 9, "texts": 9};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (9×)"] +affinity-samples/10-multiple-fills.af dpi=72;spreads=1;model_crc32=07d2e434;counts={"depth": 2, "fills": 7, "gradients": 3, "layers": 6, "nodes": 20, "segments": 21, "shapes": 7, "strokes": 3, "subpaths": 7, "text_chars": 140, "text_runs": 7, "texts": 7};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (7×)", "several fills or strokes on one object (only the active one is imported) (6×)"] +affinity-samples/11-text.af dpi=72;spreads=1;model_crc32=de077247;counts={"depth": 2, "fills": 13, "gradients": 0, "groups": 1, "layers": 1, "nodes": 28, "segments": 198, "shapes": 13, "strokes": 0, "subpaths": 18, "text_chars": 452, "text_runs": 11, "texts": 11, "unsupported": 2};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (10×)", "text fields such as page numbers (left out of the text) (2×)", "text frames with several columns (imported as one column)", "unknown layers (2×)"] +affinity-samples/12-cmyk8.af dpi=72;spreads=1;model_crc32=f40c0d8e;counts={"depth": 1, "fills": 31, "gradients": 1, "nodes": 41, "segments": 93, "shapes": 31, "strokes": 8, "subpaths": 31, "text_chars": 148, "text_runs": 10, "texts": 10};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (10×)"] +affinity-samples/12-grey8.af dpi=72;spreads=1;model_crc32=f40c0d8e;counts={"depth": 1, "fills": 31, "gradients": 1, "nodes": 41, "segments": 93, "shapes": 31, "strokes": 8, "subpaths": 31, "text_chars": 148, "text_runs": 10, "texts": 10};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (10×)"] +affinity-samples/12-lab16.af dpi=72;spreads=1;model_crc32=f40c0d8e;counts={"depth": 1, "fills": 31, "gradients": 1, "nodes": 41, "segments": 93, "shapes": 31, "strokes": 8, "subpaths": 31, "text_chars": 148, "text_runs": 10, "texts": 10};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (10×)"] +affinity-samples/12-rgb16.af dpi=72;spreads=1;model_crc32=f40c0d8e;counts={"depth": 1, "fills": 31, "gradients": 1, "nodes": 41, "segments": 93, "shapes": 31, "strokes": 8, "subpaths": 31, "text_chars": 148, "text_runs": 10, "texts": 10};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (10×)"] +affinity-samples/12-rgb32.af dpi=72;spreads=1;model_crc32=a9aeb9ab;counts={"depth": 1, "fills": 31, "gradients": 1, "nodes": 41, "segments": 93, "shapes": 31, "strokes": 8, "subpaths": 31, "text_chars": 148, "text_runs": 10, "texts": 10};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (10×)"] +affinity-samples/12-rgb8.af dpi=72;spreads=1;model_crc32=f40c0d8e;counts={"depth": 1, "fills": 31, "gradients": 1, "nodes": 41, "segments": 93, "shapes": 31, "strokes": 8, "subpaths": 31, "text_chars": 148, "text_runs": 10, "texts": 10};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (10×)"] +affinity-samples/13-blend-modes.af dpi=72;spreads=1;model_crc32=13f9c6d7;counts={"depth": 2, "fills": 13, "gradients": 6, "layers": 6, "nodes": 26, "segments": 45, "shapes": 13, "strokes": 0, "subpaths": 13, "text_chars": 169, "text_runs": 7, "texts": 7};boards=[];fonts={"Fira Sans:FiraSans-Regular:400:false"};warnings=["paragraph leading of an unknown kind (imported as automatic) (7×)"] affinity3-mexican-guy.af dpi=300;spreads=1;model_crc32=32b7cf3f;counts={"depth": 8, "fills": 169, "gradients": 0, "groups": 23, "nodes": 283, "opacity": 1, "segments": 1491, "shapes": 260, "strokes": 114, "subpaths": 264};boards=[];fonts={};warnings=["blur effects (left out) (156×)"] affinity3-mexican-man.af dpi=300;spreads=1;model_crc32=c10daaea;counts={"depth": 7, "fills": 277, "gradients": 2, "groups": 29, "nodes": 903, "segments": 3225, "shapes": 874, "strokes": 540, "subpaths": 881};boards=[];fonts={};warnings=["blur effects (left out) (244×)"] affinity3-mexican-woman.af dpi=300;spreads=1;model_crc32=3bc13374;counts={"depth": 9, "fills": 527, "gradients": 0, "groups": 28, "nodes": 595, "segments": 3562, "shapes": 567, "strokes": 60, "subpaths": 570};boards=[];fonts={};warnings=["blur effects (left out) (278×)"] @@ -31,3 +49,7 @@ patchy-text-runs.af dpi=72;spreads=1;model_crc32=7820b881;counts={"depth": 1, "n patchy-transform.af dpi=72;spreads=1;model_crc32=8d56df84;counts={"depth": 1, "images": 1, "nodes": 1};boards=[];fonts={};warnings=[] patchy-vector-mask.af dpi=72;spreads=1;model_crc32=80ca946a;counts={"depth": 1, "fills": 2, "gradients": 0, "nodes": 2, "segments": 7, "shapes": 2, "strokes": 0, "subpaths": 2, "vector_masks": 1};boards=[];fonts={};warnings=["unknown layers attached to other layers (imported without them)"] patchy-vector.af dpi=72;spreads=1;model_crc32=3b16c7ed;counts={"depth": 1, "fills": 3, "gradients": 0, "nodes": 4, "segments": 17, "shapes": 4, "strokes": 2, "subpaths": 5};boards=[];fonts={};warnings=[] +vector-art/mexican-guy.af dpi=300;spreads=1;model_crc32=32b7cf3f;counts={"depth": 8, "fills": 169, "gradients": 0, "groups": 23, "nodes": 283, "opacity": 1, "segments": 1491, "shapes": 260, "strokes": 114, "subpaths": 264};boards=[];fonts={};warnings=["blur effects (left out) (156×)"] +vector-art/mexican-man.af dpi=300;spreads=1;model_crc32=c10daaea;counts={"depth": 7, "fills": 277, "gradients": 2, "groups": 29, "nodes": 903, "segments": 3225, "shapes": 874, "strokes": 540, "subpaths": 881};boards=[];fonts={};warnings=["blur effects (left out) (244×)"] +vector-art/mexican-woman.af dpi=300;spreads=1;model_crc32=3bc13374;counts={"depth": 9, "fills": 527, "gradients": 0, "groups": 28, "nodes": 595, "segments": 3562, "shapes": 567, "strokes": 60, "subpaths": 570};boards=[];fonts={};warnings=["blur effects (left out) (278×)"] +vector-art/playing-cards.af dpi=300;spreads=1;model_crc32=bc0c838d;counts={"depth": 5, "fills": 363, "gradients": 0, "groups": 758, "nodes": 1350, "segments": 4864, "shapes": 592, "strokes": 17, "subpaths": 656};boards=[];fonts={};warnings=["blur effects (left out) (309×)", "brush strokes (imported as plain strokes)"] diff --git a/crates/affinity/tests/support/corpus.rs b/crates/affinity/tests/support/corpus.rs index 21458a6f8..425aa7632 100644 --- a/crates/affinity/tests/support/corpus.rs +++ b/crates/affinity/tests/support/corpus.rs @@ -10,9 +10,56 @@ use sha2::{Digest, Sha256}; /// `sha256 name licence url` rows. pub const MANIFEST: &str = include_str!("corpus.tsv"); +/// One manifest row. +pub struct Row<'a> { + pub digest: &'a str, + pub name: &'a str, + pub license: &'a str, + pub url: &'a str, +} + +/// The rows of `manifest`. A row has exactly four tab-separated fields: a lowercase hexadecimal +/// SHA-256, a relative `/`-separated name without empty, `.` or `..` parts, a license and an +/// `https://` URL. Each name is listed once; several names may share a digest. +pub fn rows(manifest: &str) -> Result>, String> { + let mut seen = std::collections::BTreeSet::new(); + let mut rows = Vec::new(); + for line in manifest.lines().filter(|l| !l.trim().is_empty()) { + let cols: Vec<&str> = line.split('\t').collect(); + let &[digest, name, license, url] = cols.as_slice() else { + return Err(format!("corpus row needs four tab-separated fields: {line}")); + }; + if digest.len() != 64 || !digest.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) { + return Err(format!("{name}: invalid SHA-256 {digest:?}")); + } + if name.starts_with('/') + || name.contains(['\\', ':']) + || name.chars().any(char::is_control) + || name.split('/').any(|part| part.is_empty() || part == "." || part == "..") + { + return Err(format!("{name:?}: the name must be a relative path inside the corpus folder")); + } + if license.trim().is_empty() { + return Err(format!("{name}: no license")); + } + if !url.starts_with("https://") || url.len() == "https://".len() { + return Err(format!("{name}: the URL must use https: {url:?}")); + } + if !seen.insert(name) { + return Err(format!("{name}: listed twice")); + } + rows.push(Row { digest, name, license, url }); + } + Ok(rows) +} + +fn manifest() -> Vec> { + rows(MANIFEST).unwrap_or_else(|e| panic!("malformed corpus.tsv: {e}")) +} + /// The names of the pinned files. pub fn names() -> impl Iterator { - MANIFEST.lines().filter_map(|l| l.split('\t').nth(1)) + manifest().into_iter().map(|row| row.name) } pub fn pinned() -> Option { @@ -21,10 +68,7 @@ pub fn pinned() -> Option { return None; }; let mut count = 0; - for line in MANIFEST.lines().filter(|l| !l.trim().is_empty()) { - let mut cols = line.split('\t'); - let (Some(digest), Some(name)) = (cols.next(), cols.next()) else { panic!("malformed corpus row: {line}") }; - assert_eq!(digest.len(), 64, "invalid SHA256 for {name}"); + for Row { digest, name, .. } in manifest() { let bytes = std::fs::read(dir.join(name)).unwrap_or_else(|e| panic!("missing pinned Affinity file {name}: {e}")); let hex: String = Sha256::digest(&bytes).iter().map(|b| format!("{b:02x}")).collect(); assert_eq!(hex, digest, "{name}: pinned corpus modified; run scripts/fetch-affinity-corpus.sh"); diff --git a/crates/affinity/tests/support/corpus.tsv b/crates/affinity/tests/support/corpus.tsv index bf6bc4e22..2fab83b8f 100644 --- a/crates/affinity/tests/support/corpus.tsv +++ b/crates/affinity/tests/support/corpus.tsv @@ -7,10 +7,59 @@ e56c35f876277b101790ff4384cfde103a093ed6c81790a2d62176de21da339f afdesignload-re 08946c60c0da1c8aeea92d65acfb244721eeb3b480ed358609f4a48bbecfc5b9 afdesignload-shape_test.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/shape_test.afdesign 7306ab4fcbdc225d816f32a0d2aca15ac887053f60170459ac947e70f4ef343d afdesignload-slice_test.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/slice_test.afdesign e5d04bac0235af9386aea251cdd6903ed7810d335fdb6194d0483ea30b14e24a afdesignload-test_path.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/test_path.afdesign +cc8ca0db0d8fc545eb29153be900f153fa6b7b7eac068d05e54a502aba1264fe afdesignload/color.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/color.afdesign +9a17f500d09fb3b1a70d24aabdc2882955ec3eac3700a474549e6100be3a8484 afdesignload/layer_mode.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/layer_mode.afdesign +77ae60c02749224fe2c52691c951568138eaed5f8584ebc5da83715fae0234dd afdesignload/layer_test.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/layer_test.afdesign +04944918ff8e29c5c1b466b7e43c232f7ab80db15fb934080bbcd7baaf093e22 afdesignload/margins.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/margins.afdesign +35afa31b89f2b9970eb3701ee64e2a19476383637e8b07689334d6ffe556b593 afdesignload/raster_test.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/raster_test.afdesign +e56c35f876277b101790ff4384cfde103a093ed6c81790a2d62176de21da339f afdesignload/revision_test.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/revision_test.afdesign +08946c60c0da1c8aeea92d65acfb244721eeb3b480ed358609f4a48bbecfc5b9 afdesignload/shape_test.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/shape_test.afdesign +7306ab4fcbdc225d816f32a0d2aca15ac887053f60170459ac947e70f4ef343d afdesignload/slice_test.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/slice_test.afdesign +e5d04bac0235af9386aea251cdd6903ed7810d335fdb6194d0483ea30b14e24a afdesignload/test_path.afdesign MIT https://raw.githubusercontent.com/NickBeeuwsaert/AFDesignLoad/a18dd50a7079fb861a28835eeefa0d015f03f4a1/testDesigns/test_path.afdesign +5f5b98f0ab2121f75f24362792c00cd5b610767820eb754b5660668f478b0c86 affinity-samples/01-layer-effects.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/01-layer-effects.af +33c1ad5022abc14e6136f4cb9fa0751c9778a0a564bc3abc2e0e6b051f7e00bb affinity-samples/01-layer-effects.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/01-layer-effects.png +4d19e95abe3423692f5bdfd0ede5bf3aebdd4bf16c32eaa304cead91a7a2e9b7 affinity-samples/02-adjustment-layers.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/02-adjustment-layers.af +726b7939e23a745f7578fa84188b56c2eb845cde28493499f1b18b4ede9b8a6e affinity-samples/02-adjustment-layers.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/02-adjustment-layers.png +c6ca86439c89d83ba43c76e9d783865ac09ca0ff524d5b347caa77f473caac98 affinity-samples/03-brush-strokes.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/03-brush-strokes.af +e57e36ffffdd88d3a62ebdb142435d7d3056286b22130f459c404a3ef529f61f affinity-samples/03-brush-strokes.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/03-brush-strokes.png +e3bf04f7cc02e1d49ec79503f2b4044f385de1e890bd461013a5a6fca09b5223 affinity-samples/04-master-page.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/04-master-page.af +246279f00d1f08917409b34e60359bd3bba158bcf4e8d5847a806f575d8eb98f affinity-samples/04-master-page_1.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/04-master-page_1.png +0e023792ce89f724b1dfedb6360556348309e483c23e32b91d87afab5d64c9cc affinity-samples/04-master-page_2.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/04-master-page_2.png +f431b15027e20ab760c4d241aa6981130560409cb270bbc6d4dd9241d1883f0a affinity-samples/04-master-page_3.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/04-master-page_3.png +ef779b58a6721001ee961b42eacb96fb47dcaa35ccb7e6ccf2ec6f33106070b2 affinity-samples/05-symbols.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/05-symbols.af +6675fc4a1563f61b7fcaa64978447e0fa6e1b0bb8073b4e63f958db1cf726fef affinity-samples/05-symbols.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/05-symbols.png +9e463b4d1ca8e7a1b67b3c30351a28af8ed05b9cd11f3cea2159319c9974bc67 affinity-samples/06-special-shapes.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/06-special-shapes.af +a897c607631acbea31c5a926af6ca20c0acb2744636003b8c9ef07861752d947 affinity-samples/06-special-shapes.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/06-special-shapes.png +3aba0d83055f09da4dba465a3abf66c77d4362dc6060548e54db943029b3996e affinity-samples/07-transparency.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/07-transparency.af +3b73945b7302627caf679a961053f30a9593bab7d709e27acb1df54dadc53968 affinity-samples/07-transparency.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/07-transparency.png +4292c1571b6c8c19b80c530602ca21d5996df7b99221639a4cde76d8307ffbcb affinity-samples/08-gradients.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/08-gradients.af +f6fb427c9715ea193e595d0c441b462224971fcda2aa2b4d8b71631d0f59f992 affinity-samples/08-gradients.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/08-gradients.png +c913882b3bea7a4218aa88e96890181cdc08ce37f0859196a1ad1828be78b347 affinity-samples/09-corners-stars.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/09-corners-stars.af +068bcc7599336a174d7ce87962da414ccf429d549484ccbe8f68f669779d84d0 affinity-samples/09-corners-stars.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/09-corners-stars.png +f03e797d6dbf8a31eab9d0b9cf9a8bddcc8440c6003863f31d97fe23c195c4b2 affinity-samples/10-multiple-fills.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/10-multiple-fills.af +e1951aa6d8acdbeccc281b6a20a03df9b257c0d739aa5f6aec27c105151fef3f affinity-samples/10-multiple-fills.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/10-multiple-fills.png +6da8b59b40d0e082435c5a2004c50fa90e3c4f15c3a02763b8edf84b8b9f4506 affinity-samples/11-text.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/11-text.af +bb2040cda017cb753d0594416ac0501a1049bc333a7cf2c1c832356e2bbe1a45 affinity-samples/11-text.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/11-text.png +0c13cfe0f716902199775251b0983f28d60a64c1f79d3c6f496f2c019365bdb5 affinity-samples/12-cmyk8.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-cmyk8.af +cfef257c50201968121332e8ae12a7fe2ecdcc3bce1faeb5e581751662098c05 affinity-samples/12-cmyk8.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-cmyk8.png +03d4cfe5ce4b80833d83de89848e88639056e8984c049865c8f29b9ef41b40e5 affinity-samples/12-grey8.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-grey8.af +855e4f08f21c60f1d2080c9533b98f99c7a635c5804abf8ec9d6ee1a29029cef affinity-samples/12-grey8.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-grey8.png +9adc0d4242b5448ac84aef886bd7afc165e1959015125ce21bf402ddb65caba1 affinity-samples/12-lab16.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-lab16.af +6c30cef8304fd08539d631988280a6b3bc8570db3f1425fa771d83c1591dfc8d affinity-samples/12-lab16.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-lab16.png +26b47861275b2f83517e7d42ec051efc3cd22956440784b6df0bc016ecb0e008 affinity-samples/12-rgb16.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-rgb16.af +967ba0cb7d93496a7e454dcc37013c1b19089cc283c7e08f2dea7023ad330e80 affinity-samples/12-rgb16.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-rgb16.png +36e62b0de8488712c04831ba3ef466da68bf080ec3caf9fbe6646905d3fb87e8 affinity-samples/12-rgb32.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-rgb32.af +0ebcf7211447d64158c21c27eeb19b8737cb2cdcc708dcdf3b4fed5041b449e9 affinity-samples/12-rgb32.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-rgb32.png +4d210ce4724409fb6c9715046ad9efa0049442f8324a21174068a02c6df10632 affinity-samples/12-rgb8.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-rgb8.af +4e4dda966c337119165ba5d88cb3d4af10bf6507b9a69986d33060a8eeb37c21 affinity-samples/12-rgb8.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/12-rgb8.png +b84815dbb5e3a7f7842d860acb888f93dbd1f949bcb6a3bf858515b85ea3c3b7 affinity-samples/13-blend-modes.af CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/13-blend-modes.af +a49d2fe6043002aef4f4c6b8cf64a04838d21cf29795324c02fb1772d5519a21 affinity-samples/13-blend-modes.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/13-blend-modes.png +b73eceb73a45df1a424d60164b7e1b521b9f01f56fe86159e477b49c9cd90f78 affinity-samples/source/07-texture.png CC0-1.0 https://raw.githubusercontent.com/satoshoe-dev/affinity-samples/96aca6bd86bbe7a677f1cf0630bd832d23943be8/source/07-texture.png c499cf3ca73cf7cd3e2e65bed048d1b8ecf03e7167b74d54f0ae6db31868cab8 affinity3-mexican-guy.af CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/mexican-guy.af 730e3fae51d9044ada58f51c7b5f9327d99e8d62376453bc251d0d26cda47743 affinity3-mexican-man.af CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/mexican-man.af 5f5fccc0bd8be2bb3b2a07461ec77a012a61eef1883485d7c80f72d4383231ce affinity3-mexican-woman.af CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/mexican-woman.af 0a52bb923c949c566a4339b996bce1a67b683f61def1a73dfefb910effaa450d affinity3-playing-cards.af CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/playing-cards.af +e1b121d7c3d02356baa5dea512f5aa1fe77249c28d7b227e29cab2bc67ec323a asset-store-template/AssetStore.aftemplate MIT https://raw.githubusercontent.com/eviltwo/AssetStoreTemplate/f671981ee89d15526285b3cc87b4393d3defe644/AssetStoreTemplate/AssetStore.aftemplate 87a7bd93de16c404f6c6dd9cdebff96ec47832a3b342d2ce0af73d9a87e209e0 designer-beer.afdesign CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/beer.afdesign 09ba790c428e8e09dc0b9ddebb4f3db6daefaa2af1da492ee34e73fba1b8af69 designer-cactus.afdesign CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/cactus.afdesign c3bcd0395b407493bc9d2877d424029b70f0e4c817a56e893f7ac74973df52e5 designer-car.afdesign CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/car.afdesign @@ -19,6 +68,8 @@ c3bcd0395b407493bc9d2877d424029b70f0e4c817a56e893f7ac74973df52e5 designer-car.af e1b121d7c3d02356baa5dea512f5aa1fe77249c28d7b227e29cab2bc67ec323a eviltwo-AssetStore.aftemplate MIT https://raw.githubusercontent.com/eviltwo/AssetStoreTemplate/f671981ee89d15526285b3cc87b4393d3defe644/AssetStoreTemplate/AssetStore.aftemplate fbb196e918e302c16f8de9f2e6dffaef70ab3c317b32a9f44607fd4b2ead0206 jac21-SimpleLogo.afdesign MIT https://raw.githubusercontent.com/Jac21/Branding/57ae3f45bf4637f6927c0b07de25b922c55f944f/Logos/JC/DesignerFiles/Affinity/SimpleLogo.afdesign 9d874245936483de3ec04cca48b383028d33666801dff1814246a44e695e29b8 jac21-SimpleLogoBanner.afdesign MIT https://raw.githubusercontent.com/Jac21/Branding/57ae3f45bf4637f6927c0b07de25b922c55f944f/Logos/JC/DesignerFiles/Affinity/SimpleLogoBanner.afdesign +fbb196e918e302c16f8de9f2e6dffaef70ab3c317b32a9f44607fd4b2ead0206 jac21/SimpleLogo.afdesign MIT https://raw.githubusercontent.com/Jac21/Branding/57ae3f45bf4637f6927c0b07de25b922c55f944f/Logos/JC/DesignerFiles/Affinity/SimpleLogo.afdesign +9d874245936483de3ec04cca48b383028d33666801dff1814246a44e695e29b8 jac21/SimpleLogoBanner.afdesign MIT https://raw.githubusercontent.com/Jac21/Branding/57ae3f45bf4637f6927c0b07de25b922c55f944f/Logos/JC/DesignerFiles/Affinity/SimpleLogoBanner.afdesign ec1072cb03fcd0ed7ac1dfc7e087f4920df545fe9c84a386a7dac2fd33fbbe1f leakcanary-vector_icon.afdesign Apache-2.0 https://raw.githubusercontent.com/square/leakcanary/00880a8fb66eb4046a0124bff8303a04874bc07e/docs/assets/vector_icon.afdesign bbc50c8c376e0e5980939be7df6769feed1a30289c7efc6391b204dfb15de88d patchy-LICENSE.txt MIT https://raw.githubusercontent.com/SethRobinson/Patchy/de84eab550758b30fa062e479f5778cce7693b73/LICENSE 150e423be0c5eb22f252a38c2de68ab3ccec7e20bfba166f7ddd622ac243d8f4 patchy-NOTICE.txt MIT https://raw.githubusercontent.com/SethRobinson/Patchy/de84eab550758b30fa062e479f5778cce7693b73/NOTICE-THIRD-PARTY.md @@ -51,3 +102,12 @@ a5ccb62ee8d7e36d1a19a037aba989a5ba0232767e9f3305f7d9f7d4603291dd patchy-text-rot 87e1dee23769932b7e414116233063a8d68726cbffdebb975b3cd0ef447c602a patchy-transform.af MIT https://raw.githubusercontent.com/SethRobinson/Patchy/de84eab550758b30fa062e479f5778cce7693b73/test-fixtures/af/tiny-transform.af fa5dd80f44ae0712a9888c62953fd442a28119034d343db93b7892d5d2a61328 patchy-vector-mask.af MIT https://raw.githubusercontent.com/SethRobinson/Patchy/de84eab550758b30fa062e479f5778cce7693b73/test-fixtures/af/tiny-vector-mask.af 8ab1995ecbd9306ebcb7a4d2cd81701f34401e67f08b242f14dc3e3d04c94803 patchy-vector.af MIT https://raw.githubusercontent.com/SethRobinson/Patchy/de84eab550758b30fa062e479f5778cce7693b73/test-fixtures/af/tiny-vector.af +87a7bd93de16c404f6c6dd9cdebff96ec47832a3b342d2ce0af73d9a87e209e0 vector-art/beer.afdesign CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/beer.afdesign +09ba790c428e8e09dc0b9ddebb4f3db6daefaa2af1da492ee34e73fba1b8af69 vector-art/cactus.afdesign CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/cactus.afdesign +c3bcd0395b407493bc9d2877d424029b70f0e4c817a56e893f7ac74973df52e5 vector-art/car.afdesign CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/car.afdesign +112562bc91e7cccf003d34364430544208373c4fb4bb4ab9acdaf27cf0125047 vector-art/flowers.afdesign CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/flowers.afdesign +023531b8216f2d4da24ab715e3b313506712e50d5f5bf7da927f434def1d0ea2 vector-art/lion-track.afdesign CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/lion-track.afdesign +c499cf3ca73cf7cd3e2e65bed048d1b8ecf03e7167b74d54f0ae6db31868cab8 vector-art/mexican-guy.af CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/mexican-guy.af +730e3fae51d9044ada58f51c7b5f9327d99e8d62376453bc251d0d26cda47743 vector-art/mexican-man.af CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/mexican-man.af +5f5fccc0bd8be2bb3b2a07461ec77a012a61eef1883485d7c80f72d4383231ce vector-art/mexican-woman.af CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/mexican-woman.af +0a52bb923c949c566a4339b996bce1a67b683f61def1a73dfefb910effaa450d vector-art/playing-cards.af CC0-1.0 https://raw.githubusercontent.com/samuel-etver/vector-art/255f8add3c8f0740196e22bd59502b811b532f0b/simple/playing-cards.af diff --git a/crates/ai/Cargo.toml b/crates/ai/Cargo.toml new file mode 100644 index 000000000..cca808c9c --- /dev/null +++ b/crates/ai/Cargo.toml @@ -0,0 +1,32 @@ +[package] +name = "craft-ai" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +description = "AI provider abstraction for the Craft suite — BYO API keys and one-click local models" + +[lints] +workspace = true + +[dependencies] +serde = { version = "1", features = ["derive"] } +serde_json = "1" + +[target.'cfg(not(target_arch = "wasm32"))'.dependencies] +dirs = "7" +sysinfo = "0.39" +ureq = { version = "3", features = ["json"] } +sha2 = "0.11" +candle-core = { version = "0.9", optional = true } +candle-nn = { version = "0.9", optional = true } +candle-transformers = { version = "0.9", optional = true } +tokenizers = { version = "0.22", optional = true, default-features = false, features = ["onig"] } + +[features] +# Local GGUF inference on candle. Heavy dependency tree; apps opt in. +local = ["dep:candle-core", "dep:candle-nn", "dep:candle-transformers", "dep:tokenizers"] + +[dev-dependencies] +tempfile = "3" diff --git a/crates/ai/README.md b/crates/ai/README.md new file mode 100644 index 000000000..90170c8eb --- /dev/null +++ b/crates/ai/README.md @@ -0,0 +1,145 @@ +# craft-ai — AI providers for the Craft suite + +Shared AI abstraction for every Craft app: translation, rewriting, summaries, +vision captions — one crate, one settings store, one model cache. + +Status: **spec** — this file is the contract; implementation follows. + +## The feature this powers + +A per-app **AI tab** offering document-wide operations — the flagship being +"translate this whole document" — backed by either: + +1. **BYOT** — the user's own API token against an OpenAI-compatible endpoint + (OpenAI, Azure, Ollama, LM Studio, any compatible proxy), or +2. **Local model** — a one-click download of a curated open model, chosen for + the machine it's running on. + +The user experience is deliberately *informed*: every step reports what is +happening, why this model was picked, what it will cost in disk/RAM, and that +nothing leaves the machine in local mode. + +## Modules + +### `probe` — capability detection + +Runs once, caches the result: + +| Signal | Source | +| --- | --- | +| Total/free RAM | `sysinfo` or `std::alloc`-safe OS calls | +| CPU threads + features | `std::thread`, `is_x86_feature_detected!` (AVX2 gates Q4 speed) | +| GPU + VRAM | `wgpu` adapter info (apps already link wgpu — reuse, don't re-probe) | +| Free disk at the model cache dir | `fs2`/`std::fs` | +| Network reachability | optional HEAD to the model host, skipped offline | + +Output: `MachineCaps { ram_gb, vram_gb, threads, avx2, disk_free_gb }`. + +### `registry` — the curated model list + +A small hand-maintained table (Rust consts, not runtime-fetched — supply +chain stays auditable). Each entry: `id`, display name, HF repo + file, +`sha256`, size, min RAM, recommended RAM, license id, quality tier, +languages covered. + +Curation rule — **permissive licenses only** (the suite is MIT OR Apache-2.0 +and commercial users run it): + +- ✅ Qwen2.5-0.5B / 1.5B / 3B Instruct (Apache-2.0) +- ✅ SmolLM2-1.7B (Apache-2.0) +- ✅ Gemma-3 (Gemma Terms — allowed, flag in UI) +- ✅ Helsinki-NLP opus-mt-* per-language pairs (CC-BY/MIT) +- ❌ NLLB-200, M2M-100 — CC-BY-NC, excluded +- ❌ Llama-* — custom license acceptable? default: exclude until reviewed + +`registry::suggest(&caps)` picks the best fitting model: prefers 3B when +VRAM ≥ 6 GB or RAM ≥ 16 GB, falls to 1.5B at 8 GB, 0.5B below. Always shows +alternatives — the suggestion is a default, not a cage. + +### `provider` — inference backends + +```rust +trait Provider { + fn name(&self) -> &str; + fn complete(&self, prompt: &str, opts: &GenOpts) -> Result; + fn test(&self) -> Result; +} +``` + +- `OpenAiCompat` — POST `/v1/chat/completions`, configurable endpoint+token+ + model. Covers OpenAI, Ollama (`http://localhost:11434/v1`), LM Studio, + Groq, OpenRouter… Token stored via the OS keyring (`keyring` crate) or a + 0600-permissioned config file — never in project files, never logged. +- `LocalGguf` — GGUF inference. First implementation target: **candle** + (pure Rust, Apache/MIT — keeps the no-C++ toolchain rule). `llama-cpp-2` + stays a possible perf upgrade later, gated behind a feature flag. + +### `fetch` — one-click download + +- Resumable HTTP GET (range requests), streamed to `*.part` then renamed — + a half-downloaded GGUF can never be mistaken for a valid one. +- SHA-256 checked against the registry entry; mismatch = hard fail, delete. +- Progress events (`Download { bytes_done, bytes_total, bytes_per_sec }`) + feed the UI's live status line. +- Cache dir is **shared across the suite**: + `%LOCALAPPDATA%\artcraft\models` (Windows), `~/Library/Application + Support/artcraft/models` (macOS), `~/.cache/artcraft/models` (Linux). + +### `translate` — document segmentation + +The model is the easy part; the hard part is *what not to touch*. The +translator walks the document as segments, not raw text: + +- **Protected**: LaTeX commands/envs/math (`\cite{…}`, `$…$`), code fences, + placeholders (`{count}`), URLs, citation keys, markup tags. +- **Translated**: prose runs, captions, headings, table cells. +- Per-app adapters declare the grammar: TexCraft protects `\command{…}` and + math mode; WordCraft protects field codes; MatCraft protects code. +- Batch-friendly: segments → prompt with numbered items → parse numbered + output; verify count matches, retry split halves on mismatch. +- Deterministic options: temperature 0-ish, glossary hook (`HashMap`) applied post-hoc. + +## The AI tab (per app, `ui-egui/src/ai.rs`) + +First-open flow — the "smooth informed" sequence: + +1. Two cards: **Use an API provider** / **Run on this PC**. +2. BYOT card: endpoint, token, model fields + **Test connection** → green + check with model list echo. +3. Local card: **Detect this PC** → probe runs → + `Suggested: Qwen2.5-1.5B-Instruct (Q4_K_M, 1.1 GB) — fits your 16 GB RAM; + est. ~8 tok/s` with an "Other models ▸" disclosure showing the registry. +4. **Download** → progress bar with MB/%/speed → `Verifying checksum…` → + `Loading…` → `Ready — local, offline, nothing leaves this PC`. +5. Then the operations: "Translate document to [language ▾]", "Summarize + selection", custom prompt box. Status line narrates each step; + expandable activity log for the curious. +6. Language detected vs document language → gentle offer chip: + `This document is French — translate to English?` + +## Non-negotiables + +- **Honesty**: the UI always says which provider is active, what model, + and "cloud — your document text is sent to the endpoint" vs "local — + nothing leaves this PC". No silent cloud calls; AI is strictly opt-in. +- **No crash**: model load failures, corrupt GGUFs, OOM — all `Result`, + all surfaced as messages. +- **Rust only**: candle over llama.cpp bindings preserves the wasm story + (local inference on wasm is future-possible with `candle` + WGPU backend). +- **Licensing**: registry carries SPDX ids; the UI shows them; CC-BY-NC and + unreviewed custom licenses are excluded by policy. +- **Everything is a command**: `ai.translate_doc`, `ai.status`, + `ai.models.list`, `ai.model.download`, `ai.provider.test` — reachable + from the app's control channel and MCP, same as every Craft convention. + +## Milestones + +| # | Deliverable | Done when | +| --- | --- | --- | +| A1 | `probe` + `registry` + `fetch` | CLI-free test: probe reports real caps; `suggest` picks sanely per fixture; a tiny model downloads + sha256 verifies | +| A2 | `OpenAiCompat` provider | `translate` a string through Ollama/OpenAI with mocked HTTP tests | +| A3 | `LocalGguf` on candle | Qwen2.5-0.5B loads and answers on CPU in a test (model fixture fetched in-test, skipped without network) | +| A4 | `translate` segmentation | LaTeX/code/placeholder round-trip tests — protected spans byte-identical | +| A5 | AI tab in one pilot app (suggest TexCraft or WordCraft) | download → translate document end-to-end, live status UX | +| A6 | Commands + MCP surface | `ai.*` commands reachable via control channel | diff --git a/crates/ai/src/error.rs b/crates/ai/src/error.rs new file mode 100644 index 000000000..5955b260c --- /dev/null +++ b/crates/ai/src/error.rs @@ -0,0 +1,52 @@ +//! The crate's error type: everything fails with `Result`, never a panic. + +use std::fmt; + +/// Every failure a caller can act on: the variant says what went wrong, +/// the message says why. +#[derive(Debug)] +pub enum AiError { + /// The HTTP layer failed (DNS, TLS, status code, body). + Http(String), + /// A downloaded file's SHA-256 did not match the expected digest. + Checksum { expected: String, got: String }, + /// The local disk refused us (permissions, full, vanished mid-write). + Io(std::io::Error), + /// The provider returned a response we could not parse. + BadResponse(String), + /// The provider rejected the request (bad token, quota, model name). + Rejected(String), + /// No provider is configured — the UI should route to setup. + NotConfigured, + /// Local model inference failed (load, OOM, bad GGUF). + Inference(String), + /// The operation was cancelled by the user. + Cancelled, + /// The same cache entry is already being downloaded by another + /// caller — only one may hold the `.part` file at a time. + Busy, +} + +impl fmt::Display for AiError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::Http(m) => write!(f, "network error: {m}"), + Self::Checksum { expected, got } => write!(f, "checksum mismatch: expected {expected}, got {got}"), + Self::Io(e) => write!(f, "disk error: {e}"), + Self::BadResponse(m) => write!(f, "unreadable response: {m}"), + Self::Rejected(m) => write!(f, "provider rejected the request: {m}"), + Self::NotConfigured => write!(f, "no AI provider configured"), + Self::Inference(m) => write!(f, "local model error: {m}"), + Self::Cancelled => write!(f, "cancelled"), + Self::Busy => write!(f, "a download of this model is already in progress"), + } + } +} + +impl std::error::Error for AiError {} + +impl From for AiError { + fn from(e: std::io::Error) -> Self { + Self::Io(e) + } +} diff --git a/crates/ai/src/fetch.rs b/crates/ai/src/fetch.rs new file mode 100644 index 000000000..d725127a2 --- /dev/null +++ b/crates/ai/src/fetch.rs @@ -0,0 +1,338 @@ +//! One-click model download: resumable, `.part`-suffixed while in flight +//! (a half-downloaded GGUF is never mistaken for a valid one), SHA-256 +//! verified, then atomically renamed. + +use std::fs::{self, File, OpenOptions}; +use std::io::{Read, Write}; +use std::path::{Path, PathBuf}; +use std::time::{Duration, Instant}; + +use sha2::Digest; + +use crate::error::AiError; +use crate::registry::ModelEntry; + +/// Progress + lifecycle events, fed to the UI's status line. +#[derive(Clone, Debug)] +pub enum Event { + /// We know the total; download is starting or resuming. + Started { total: u64, resumed_from: u64 }, + /// Bytes on disk so far. `bytes_per_sec` is a running average. + Progress { done: u64, total: u64, bytes_per_sec: u64 }, + /// Body finished; hashing the file before we trust it. + Verifying, + /// Download is complete. `verified` is false when no reference digest + /// existed anywhere (registry table and the host's ETag) — the file is + /// kept but the UI should say "unverified" rather than pretend. + Done { verified: bool }, +} + +/// A handle to abort a download: `cancel` returns false → `AiError::Cancelled`. +pub type Cancel<'a> = &'a dyn Fn() -> bool; + +/// ureq's `timeout_recv_body` is a *total* budget, not a stall timer, so a +/// single fixed cap would kill slow-but-alive downloads of multi-GB models. +/// Instead the GET's body deadline scales with the registry's declared +/// size: a floor rate of 256 KiB/s, between 5 min and 6 h. A dead +/// connection can therefore never block the read loop indefinitely, and a +/// retry still resumes from the `.part` file. +const MIN_BODY_RATE: u64 = 256 * 1024; +const BODY_BUDGET_MIN: Duration = Duration::from_secs(5 * 60); +const BODY_BUDGET_MAX: Duration = Duration::from_secs(6 * 60 * 60); + +fn body_agent(remaining_bytes: u64) -> ureq::Agent { + let budget = Duration::from_secs(remaining_bytes / MIN_BODY_RATE).clamp(BODY_BUDGET_MIN, BODY_BUDGET_MAX); + ureq::Agent::config_builder() + .timeout_connect(Some(Duration::from_secs(15))) + .timeout_send_request(Some(Duration::from_secs(30))) + .timeout_recv_response(Some(Duration::from_secs(60))) + .timeout_recv_body(Some(budget)) + .build() + .into() +} + +/// OS-level lock guarding one cache entry against concurrent downloads; +/// released automatically on close/process exit, so no stale lock files. +fn lock_entry(part_path: &Path) -> Result { + let mut lock_name = part_path.as_os_str().to_os_string(); + lock_name.push(".lock"); + let lock = OpenOptions::new().write(true).create(true).truncate(false).open(PathBuf::from(lock_name))?; + match lock.try_lock() { + Ok(()) => Ok(lock), + Err(std::fs::TryLockError::WouldBlock) => Err(AiError::Busy), + Err(std::fs::TryLockError::Error(e)) => Err(AiError::Io(e)), + } +} + +/// Download `entry` into `cache_dir`, calling `on` with progress events. +/// Resumes an existing `*.part` via HTTP Range. Returns the final path. +pub fn download(entry: &ModelEntry, cache_dir: &Path, on: impl Fn(&Event), cancel: Option>) -> Result { + if cancel.is_some_and(|c| !c()) { + return Err(AiError::Cancelled); + } + fs::create_dir_all(cache_dir)?; + let final_path = cache_dir.join(entry.file); + if final_path.is_file() { + // Already on disk — verify once, reuse if good. + on(&Event::Verifying); + if let Some(expected) = expected_sha256(entry)? { + let got = sha256_file(&final_path)?; + if got.eq_ignore_ascii_case(&expected) { + on(&Event::Done { verified: true }); + return Ok(final_path); + } + return Err(AiError::Checksum { expected, got }); + } + on(&Event::Done { verified: false }); + return Ok(final_path); + } + + let part_path = cache_dir.join(format!("{}.part", entry.file)); + // One downloader per cache entry: two concurrent calls would read the + // same resume offset and append the same bytes twice, corrupting the + // `.part`. The lock is held through the final rename. + let _entry_lock = lock_entry(&part_path)?; + let mut resumed_from = part_path.metadata().map_or(0, |m| m.len()); + + let expected = expected_sha256(entry)?; + + let get = |range_from: u64| { + // Budget for the *full* size, not the remainder: a 200 that + // ignores Range means we re-download the whole model. + let mut req = body_agent(entry.size_mb.saturating_mul(1 << 20)).get(entry.url); + if range_from > 0 { + req = req.header("Range", &format!("bytes={range_from}-")); + } + req.call() + }; + let mut resp = match get(resumed_from) { + Ok(r) => r, + // A 416 means the server found our resume offset unsatisfiable — + // the common cause is a `.part` that already holds the complete + // file (cancelled between the last byte and the rename). If it + // verifies, finish the job; otherwise restart from scratch. + Err(ureq::Error::StatusCode(416)) if resumed_from > 0 => { + if let Some(expected) = &expected + && sha256_file(&part_path).is_ok_and(|got| got.eq_ignore_ascii_case(expected)) + { + on(&Event::Verifying); + fs::rename(&part_path, &final_path)?; + on(&Event::Done { verified: true }); + return Ok(final_path); + } + fs::remove_file(&part_path)?; + resumed_from = 0; + get(0).map_err(http_err)? + } + Err(e) => return Err(http_err(e)), + }; + + // A 200 to a Range request means the server ignored resume — truncate. + let honored_resume = resumed_from > 0 && resp.status() == 206; + let total = content_length(&resp).map(|len| if honored_resume { len + resumed_from } else { len }); + + on(&Event::Started { total: total.unwrap_or(0), resumed_from: if honored_resume { resumed_from } else { 0 } }); + + let mut file = if honored_resume { OpenOptions::new().append(true).open(&part_path)? } else { File::create(&part_path)? }; + + let mut body = resp.body_mut().as_reader(); + let mut buf = vec![0u8; 256 * 1024]; + let mut done = if honored_resume { resumed_from } else { 0 }; + let started = Instant::now(); + loop { + if cancel.is_some_and(|c| !c()) { + return Err(AiError::Cancelled); + } + let n = match body.read(&mut buf) { + Ok(0) => break, + Ok(n) => n, + Err(e) => return Err(AiError::Io(e)), + }; + file.write_all(&buf[..n])?; + done += n as u64; + let secs = started.elapsed().as_secs_f64().max(0.001); + on(&Event::Progress { done, total: total.unwrap_or(0), bytes_per_sec: (done.saturating_sub(resumed_from) as f64 / secs) as u64 }); + } + file.flush()?; + drop(file); + + // A short read means the connection dropped mid-body — keep the .part + // for resume and report it as an HTTP failure, not a success. + if let Some(t) = total + && done < t + { + return Err(AiError::Http(format!("connection dropped at {done}/{t} bytes — retry to resume"))); + } + + on(&Event::Verifying); + let verified = if let Some(expected) = expected { + let got = sha256_file(&part_path)?; + if !got.eq_ignore_ascii_case(&expected) { + // A corrupt download is deleted — it can never silently pass. + let _ = fs::remove_file(&part_path); + return Err(AiError::Checksum { expected, got }); + } + true + } else { + false + }; + + fs::rename(&part_path, &final_path)?; + on(&Event::Done { verified }); + Ok(final_path) +} + +/// The digest we hold this file to: our registry hash if pinned, else the +/// ETag of the resolved URL (Hugging Face serves the LFS sha256 there). +fn expected_sha256(entry: &ModelEntry) -> Result, AiError> { + if let Some(s) = entry.sha256 { + return Ok(Some(s.to_string())); + } + // No redirects: HF serves the LFS sha256 in `x-linked-etag` on the + // 302 itself; following it would return the CDN's own etag instead. + let agent: ureq::Agent = ureq::Agent::config_builder() + .max_redirects(0) + .timeout_connect(Some(Duration::from_secs(15))) + .timeout_recv_response(Some(Duration::from_secs(30))) + .build() + .into(); + match agent.head(entry.url).call() { + Ok(resp) => Ok(etag(&resp)), + // HEAD unsupported/unreachable → proceed without verification. + Err(_) => Ok(None), + } +} + +fn etag(resp: &ureq::http::Response) -> Option { + // Prefer the redirect target's etag (the LFS object), fall back to + // the response's own. Quotes stripped; weak etags ("W/…") ignored. + for name in ["x-linked-etag", "etag"] { + if let Some(v) = resp.headers().get(name).and_then(|v| v.to_str().ok()) { + let v = v.trim().trim_matches('"'); + if !v.starts_with("W/") && v.len() == 64 && v.bytes().all(|b| b.is_ascii_hexdigit()) { + return Some(v.to_string()); + } + } + } + None +} + +fn content_length(resp: &ureq::http::Response) -> Option { + resp.headers() + .get("content-length") + .and_then(|v| v.to_str().ok()) + .and_then(|v| v.trim().parse().ok()) + // A redirect's own length is meaningless; only trust it after + // ureq followed redirects (it does — so the final body length). + .filter(|&n: &u64| n > 0) +} + +fn sha256_file(path: &Path) -> Result { + let mut file = File::open(path)?; + let mut hasher = sha2::Sha256::new(); + let mut buf = vec![0u8; 256 * 1024]; + loop { + let n = file.read(&mut buf)?; + if n == 0 { + break; + } + hasher.update(&buf[..n]); + } + Ok(hasher.finalize().iter().map(|b| format!("{b:02x}")).collect()) +} + +fn http_err(e: ureq::Error) -> AiError { + match e { + ureq::Error::StatusCode(code) => AiError::Rejected(format!("HTTP {code}")), + other => AiError::Http(other.to_string()), + } +} + +/// Where a model would land once downloaded. +pub fn model_path(entry: &ModelEntry, cache_dir: &Path) -> PathBuf { + cache_dir.join(entry.file) +} + +/// Is `entry` already fully downloaded? +pub fn is_downloaded(entry: &ModelEntry, cache_dir: &Path) -> bool { + cache_dir.join(entry.file).is_file() +} + +/// `tokenizer.json` beside the GGUF: `.tokenizer.json`. +pub fn tokenizer_path(entry: &ModelEntry, cache_dir: &Path) -> PathBuf { + cache_dir.join(format!("{}.tokenizer.json", entry.file)) +} + +/// The companion tokenizer — small (a few MB), so no resume loop, but the +/// same `.part`-then-rename rule applies. +pub fn download_tokenizer(entry: &ModelEntry, cache_dir: &Path) -> Result { + let dest = tokenizer_path(entry, cache_dir); + if dest.is_file() { + return Ok(dest); + } + let tmp = dest.with_extension("part"); + let mut resp = body_agent(32 * 1024 * 1024).get(entry.tokenizer_url).call().map_err(http_err)?; + let bytes = resp.body_mut().read_to_vec().map_err(|e| AiError::Http(e.to_string()))?; + fs::write(&tmp, bytes)?; + fs::rename(&tmp, &dest)?; + Ok(dest) +} + +/// Remove `entry`'s file (and any `.part` remnant). Missing is fine; +/// other failures (permissions, locked) are surfaced to the caller. +pub fn delete(entry: &ModelEntry, cache_dir: &Path) -> Result<(), AiError> { + for p in [cache_dir.join(entry.file), cache_dir.join(format!("{}.part", entry.file))] { + match fs::remove_file(&p) { + Ok(()) => {} + Err(e) if e.kind() == std::io::ErrorKind::NotFound => {} + Err(e) => return Err(AiError::Io(e)), + } + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::registry::Arch; + + fn entry() -> &'static ModelEntry { + static E: ModelEntry = ModelEntry { + id: "t", + name: "t", + url: "", + file: "m.gguf", + tokenizer_url: "", + sha256: None, + size_mb: 1, + min_ram_gb: 0.0, + rec_ram_gb: 0.0, + license: "MIT", + quality: crate::registry::Quality::Tiny, + arch: Arch::Llama, + langs: "", + }; + &E + } + + #[test] + fn second_lock_on_same_entry_is_busy() { + let dir = tempfile::tempdir().expect("tempdir"); + let part = dir.path().join("m.gguf.part"); + let _lock = lock_entry(&part).expect("first lock"); + assert!(matches!(lock_entry(&part), Err(AiError::Busy))); + // Releasing lets the next caller in. + drop(_lock); + assert!(lock_entry(&part).is_ok()); + } + + #[test] + fn delete_reports_failures_beyond_not_found() { + let dir = tempfile::tempdir().expect("tempdir"); + // Absent paths are fine. + delete(entry(), dir.path()).expect("missing ok"); + // A directory where the file would be fails removal on every OS. + fs::create_dir(dir.path().join("m.gguf")).expect("mkdir"); + assert!(matches!(delete(entry(), dir.path()), Err(AiError::Io(_)))); + } +} diff --git a/crates/ai/src/lib.rs b/crates/ai/src/lib.rs new file mode 100644 index 000000000..b180040bc --- /dev/null +++ b/crates/ai/src/lib.rs @@ -0,0 +1,27 @@ +//! craft-ai — AI provider abstraction for the Craft suite. +//! +//! See `README.md` for the design: BYO API provider (OpenAI-compatible) + +//! one-click local models with capability detection. +#![forbid(unsafe_code)] +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +mod error; +mod provider; +mod registry; +mod translate; + +#[cfg(not(target_arch = "wasm32"))] +pub mod fetch; +#[cfg(not(target_arch = "wasm32"))] +#[cfg(feature = "local")] +pub mod local; +// `MachineCaps` is portable data the registry needs on every target; only +// the OS probe itself is native-only. +pub mod probe; + +pub use error::AiError; +#[cfg(not(target_arch = "wasm32"))] +pub use provider::OpenAiCompat; +pub use provider::{GenOpts, Provider, ProviderInfo}; +pub use registry::{Arch, MODELS, ModelEntry, Quality, by_id, fits, suggest}; +pub use translate::{PdfGrammar, Segment, TranslateGrammar, is_protected_token, segment, translate_segments}; diff --git a/crates/ai/src/local.rs b/crates/ai/src/local.rs new file mode 100644 index 000000000..6c42aabae --- /dev/null +++ b/crates/ai/src/local.rs @@ -0,0 +1,144 @@ +//! Local GGUF inference on candle (pure Rust — keeps the no-C++ rule and +//! the door open for wasm later). CPU only for now; GPU comes from the +//! app's wgpu adapter in a later milestone. +//! +//! Both supported architectures speak ChatML — one prompt template covers +//! Qwen2.5 and SmolLM2. + +use std::fs::File; +use std::path::Path; + +use candle_core::quantized::gguf_file; +use candle_core::{Device, IndexOp, Tensor}; +use candle_transformers::generation::LogitsProcessor; +use candle_transformers::models::{quantized_llama, quantized_qwen2}; +use tokenizers::Tokenizer; + +use crate::error::AiError; +use crate::provider::{GenOpts, Provider, ProviderInfo}; +use crate::registry::{Arch, ModelEntry}; + +enum Weights { + Qwen2(quantized_qwen2::ModelWeights), + Llama(quantized_llama::ModelWeights), +} + +impl Weights { + fn forward(&mut self, ids: &Tensor, pos: usize) -> Result { + match self { + Self::Qwen2(w) => w.forward(ids, pos), + Self::Llama(w) => w.forward(ids, pos), + } + } +} + +/// A downloaded GGUF loaded and ready. Construction is the expensive +/// part; `complete` is then just a forward loop. +pub struct LocalGguf { + weights: Weights, + tokenizer: Tokenizer, + device: Device, + eos: u32, + entry: &'static ModelEntry, +} + +const SEED: u64 = 0xC0FFEE; + +impl LocalGguf { + /// Load the GGUF + tokenizer.json of `entry` from the model cache. + /// All failures are `Inference` errors — a corrupt file, an OOM, a + /// wrong-arch GGUF, all land in the status line, never in a panic. + pub fn load(entry: &'static ModelEntry, gguf_path: &Path, tokenizer_path: &Path) -> Result { + let device = Device::Cpu; + let mut file = File::open(gguf_path).map_err(AiError::Io)?; + // Malformed GGUF metadata (e.g. `general.alignment = 0`) makes + // candle's parser panic on a division — hostile input must come + // back as an error, not a crash. + // Malformed GGUF metadata (e.g. `general.alignment = 0`, or a + // zero `attention.head_count` reaching a division in the weight + // constructors) makes candle panic — hostile input must come + // back as an error, not a crash. The guard covers parsing *and* + // weight construction. + let weights = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| -> Result { + let content = gguf_file::Content::read(&mut file).map_err(|e| AiError::Inference(format!("bad GGUF: {e}")))?; + match entry.arch { + Arch::Qwen2 => Ok(Weights::Qwen2( + quantized_qwen2::ModelWeights::from_gguf(content, &mut file, &device) + .map_err(|e| AiError::Inference(format!("cannot load {}: {e}", entry.file)))?, + )), + Arch::Llama => Ok(Weights::Llama( + quantized_llama::ModelWeights::from_gguf(content, &mut file, &device) + .map_err(|e| AiError::Inference(format!("cannot load {}: {e}", entry.file)))?, + )), + } + })) + .map_err(|_| AiError::Inference("GGUF loader panicked on malformed metadata".to_owned()))??; + let tokenizer = Tokenizer::from_file(tokenizer_path).map_err(|e| AiError::Inference(format!("bad tokenizer.json: {e}")))?; + let eos = tokenizer.token_to_id("<|im_end|>").ok_or_else(|| AiError::Inference("tokenizer has no EOS token".into()))?; + Ok(Self { weights, tokenizer, device, eos, entry }) + } + + /// ChatML wrap — Qwen2.5 and SmolLM2 both ship this template. + fn chat(prompt: &str) -> String { + format!( + "<|im_start|>system\nYou are a precise translation engine. Follow the instructions exactly.<|im_end|>\n<|im_start|>user\n{prompt}<|im_end|>\n<|im_start|>assistant\n", + ) + } + + fn generate(&mut self, prompt: &str, opts: &GenOpts) -> Result { + let text = Self::chat(prompt); + let encoding = self.tokenizer.encode(text, true).map_err(|e| AiError::Inference(format!("encode failed: {e}")))?; + let mut tokens: Vec = encoding.get_ids().to_vec(); + + let temp = if opts.temperature <= 0.02 { None } else { Some(f64::from(opts.temperature)) }; + let mut sampler = LogitsProcessor::new(SEED, temp, None); + + let mut pos = 0usize; + let mut generated: Vec = Vec::with_capacity(opts.max_tokens.min(4096) as usize); + let mut hit_eos = false; + for _ in 0..opts.max_tokens { + let input_len = tokens.len() - pos; + let input = + Tensor::new(&tokens[pos..], &self.device).and_then(|t| t.reshape((1, t.dims1()?))).map_err(|e| AiError::Inference(e.to_string()))?; + let logits = self.weights.forward(&input, pos).map_err(|e| AiError::Inference(e.to_string()))?; + pos += input_len; + // `forward` already returns the last sequence position's + // logits [batch, vocab] — index the batch row only. + let logits = logits.i(0).map_err(|e| AiError::Inference(e.to_string()))?; + let next = sampler.sample(&logits).map_err(|e| AiError::Inference(e.to_string()))?; + if next == self.eos { + hit_eos = true; + break; + } + tokens.push(next); + generated.push(next); + } + // No EOS inside the budget → the reply was cut mid-translation; + // partial output would silently truncate the document. + if !hit_eos { + return Err(AiError::Inference(format!("generation hit max_tokens ({}) without EOS", opts.max_tokens))); + } + // Decode the generated ids through the tokenizer: byte-level BPE + // vocab strings can't be concatenated (spaces/newlines/non-ASCII + // bytes stay encoded, and UTF-8 can split across tokens). + self.tokenizer.decode(&generated, true).map_err(|e| AiError::Inference(format!("decode failed: {e}"))) + } +} + +impl Provider for LocalGguf { + fn name(&self) -> String { + format!("local: {}", self.entry.name) + } + + fn complete(&mut self, prompt: &str, opts: &GenOpts) -> Result { + self.generate(prompt, opts).map(|s| s.trim().to_string()) + } + + fn test(&mut self) -> Result { + Ok(ProviderInfo { label: format!("loaded: {}", self.entry.name), models: vec![self.entry.id.to_string()] }) + } + + fn is_local(&self) -> bool { + true + } +} diff --git a/crates/ai/src/probe.rs b/crates/ai/src/probe.rs new file mode 100644 index 000000000..23c948b37 --- /dev/null +++ b/crates/ai/src/probe.rs @@ -0,0 +1,82 @@ +//! Machine capability detection — runs once, cache the result. +//! +//! GPU/VRAM is deliberately *not* probed here: apps already link wgpu, so +//! they read their own adapter info and fill `MachineCaps::vram_gb` after +//! calling [`probe`]. Re-probing the GPU would double the surface for a +//! bug that reports nonsense VRAM on hybrid laptops. + +/// What this machine can comfortably run. +#[derive(Clone, Debug, PartialEq)] +pub struct MachineCaps { + /// Total physical RAM, in GiB. + pub ram_gb: f32, + /// Free space on the volume holding the model cache, in GiB. + pub disk_free_gb: f32, + /// Logical CPU threads. + pub threads: usize, + /// AVX2 detected — without it quantized GGUF inference crawls. + pub avx2: bool, + /// Dedicated VRAM in GiB, when the app supplied it from its wgpu adapter. + /// `None` means "unknown or no discrete GPU" — never guessed. + pub vram_gb: Option, +} + +impl MachineCaps { + /// Rough throughput hint for a model of `size_mb`: tokens/sec on CPU. + /// Deliberately conservative — an honest underestimate beats an + /// optimistic one that makes the app look slow. + pub fn est_tokens_per_sec(&self, size_mb: u64) -> f32 { + let base = if self.avx2 { 6.0 } else { 1.2 }; + // ~0.5B params ≈ 350 MiB Q4; speed scales inversely with size. + let scale = 350.0 / (size_mb.max(1) as f32); + let thread_boost = (self.threads as f32 / 4.0).min(1.5); + (base * scale * thread_boost).max(0.3) + } +} + +/// Probe the real machine once. `cache_dir` is the future model-cache +/// location — disk space is measured on *its* volume, which may not be +/// the OS volume. +#[cfg(not(target_arch = "wasm32"))] +pub fn probe(cache_dir: &std::path::Path) -> MachineCaps { + let mut sys = sysinfo::System::new(); + sys.refresh_memory(); + let ram_gb = sys.total_memory() as f32 / (1 << 30) as f32; + + let disk_free_gb = disk_free(cache_dir); + + MachineCaps { ram_gb, disk_free_gb, threads: std::thread::available_parallelism().map_or(1, |n| n.get()), avx2: avx2(), vram_gb: None } +} + +#[cfg(all(not(target_arch = "wasm32"), any(target_arch = "x86_64", target_arch = "x86")))] +fn avx2() -> bool { + std::arch::is_x86_feature_detected!("avx2") +} + +#[cfg(all(not(target_arch = "wasm32"), not(any(target_arch = "x86_64", target_arch = "x86"))))] +fn avx2() -> bool { + // AArch64 NEON is mandatory, so the honest answer is "fast enough". + true +} + +/// Free bytes on the volume containing `dir`, walking up to the nearest +/// existing ancestor if `dir` doesn't exist yet (the common case). +#[cfg(not(target_arch = "wasm32"))] +fn disk_free(dir: &std::path::Path) -> f32 { + // Canonicalize the existing ancestor: a relative or symlinked + // `cache_dir` must still match an absolute mount point. + let probe: std::path::PathBuf = + dir.ancestors().find(|p| p.exists()).and_then(|p| p.canonicalize().ok()).unwrap_or_else(|| std::path::PathBuf::from(".")); + let disks = sysinfo::Disks::new_with_refreshed_list(); + // The longest mount point that prefixes our dir owns it. + let best = disks.iter().filter(|d| probe.starts_with(d.mount_point())).max_by_key(|d| d.mount_point().as_os_str().len()); + best.map_or(0.0, |d| d.available_space() as f32 / (1 << 30) as f32) +} + +/// The suite-shared model cache (`%LOCALAPPDATA%\artcraft\models` etc.). +/// `None` on platforms without a cache dir — the caller should refuse +/// local models rather than splashing files into the cwd. +#[cfg(not(target_arch = "wasm32"))] +pub fn models_dir() -> Option { + dirs::cache_dir().map(|d| d.join("artcraft").join("models")) +} diff --git a/crates/ai/src/provider.rs b/crates/ai/src/provider.rs new file mode 100644 index 000000000..ae7bd757d --- /dev/null +++ b/crates/ai/src/provider.rs @@ -0,0 +1,196 @@ +//! Inference backends behind one trait. Apps hold a `Box` +//! and never care whether the bytes went to OpenAI, Ollama or a local GGUF. + +use crate::error::AiError; + +/// Generation parameters — kept minimal on purpose; the UI exposes +/// "translate", not a sampler playground. +#[derive(Clone, Debug)] +pub struct GenOpts { + /// Max tokens to generate. + pub max_tokens: u32, + /// Sampling temperature; translation wants ~0. + pub temperature: f32, +} + +impl Default for GenOpts { + fn default() -> Self { + Self { max_tokens: 2048, temperature: 0.1 } + } +} + +/// What `test()` learned about a provider — shown next to the green check. +#[derive(Clone, Debug)] +pub struct ProviderInfo { + /// Human label, e.g. "Ollama at http://localhost:11434". + pub label: String, + /// Model ids the endpoint advertised (may be empty if it doesn't say). + pub models: Vec, +} + +/// An AI backend the suite can use. `Send` so apps can move a loaded +/// provider onto a worker thread for long generations. +pub trait Provider: Send { + /// Short name for the status line ("local: Qwen2.5 1.5B", "OpenAI-compatible"). + fn name(&self) -> String; + /// One completion. Prompt construction is the caller's job — this + /// trait is deliberately text-in/text-out so every consumer (translate, + /// summarize, custom prompt) shares one path. + fn complete(&mut self, prompt: &str, opts: &GenOpts) -> Result; + /// Can we reach it? Never sends document text — just a handshake. + fn test(&mut self) -> Result; + /// True when document text stays on this machine. + fn is_local(&self) -> bool; +} + +/// Any OpenAI-compatible `/v1/chat/completions` endpoint: OpenAI, Azure, +/// Ollama (`http://localhost:11434/v1`), LM Studio, Groq, OpenRouter… +/// The token is a plain string — storage (OS keyring, settings file) is +/// the app's choice, and it is never logged or echoed into errors. +#[cfg(not(target_arch = "wasm32"))] +pub struct OpenAiCompat { + /// Base URL ending at the API root, e.g. `https://api.openai.com/v1`. + pub endpoint: String, + /// Bearer token; `None` for unauthenticated local endpoints (Ollama). + pub token: Option, + /// Model id sent in every request. + pub model: String, +} + +#[cfg(not(target_arch = "wasm32"))] +impl OpenAiCompat { + pub fn new(endpoint: impl Into, token: Option, model: impl Into) -> Self { + Self { endpoint: endpoint.into(), token, model: model.into() } + } + + fn url(&self, path: &str) -> String { + format!("{}/{}", self.endpoint.trim_end_matches('/'), path) + } + + /// ureq sets no timeouts by default — an endpoint that accepts the + /// socket and never replies would block the caller forever, so every + /// request goes through an agent with finite deadlines. The response + /// budgets are generous: a non-streamed chat completion only sends + /// headers once generation is done, which can take minutes. + fn agent() -> ureq::Agent { + ureq::Agent::config_builder() + .timeout_connect(Some(std::time::Duration::from_secs(15))) + .timeout_send_request(Some(std::time::Duration::from_secs(30))) + .timeout_send_body(Some(std::time::Duration::from_secs(60))) + .timeout_recv_response(Some(std::time::Duration::from_secs(300))) + .timeout_recv_body(Some(std::time::Duration::from_secs(300))) + .build() + .into() + } + + fn auth(&self, req: ureq::RequestBuilder) -> ureq::RequestBuilder { + match &self.token { + Some(t) if !t.is_empty() => req.header("Authorization", format!("Bearer {t}")), + _ => req, + } + } +} + +#[cfg(not(target_arch = "wasm32"))] +impl Provider for OpenAiCompat { + fn name(&self) -> String { + format!("{} ({})", self.model, self.endpoint) + } + + fn complete(&mut self, prompt: &str, opts: &GenOpts) -> Result { + if self.endpoint.trim().is_empty() { + return Err(AiError::NotConfigured); + } + let body = serde_json::json!({ + "model": self.model, + "messages": [{"role": "user", "content": prompt}], + "temperature": opts.temperature, + "max_tokens": opts.max_tokens, + }); + let mut resp = + self.auth(Self::agent().post(self.url("chat/completions"))).header("Content-Type", "application/json").send_json(body).map_err(|e| { + match e { + ureq::Error::StatusCode(401 | 403) => AiError::Rejected("authentication failed — check the API token".into()), + ureq::Error::StatusCode(404) => AiError::Rejected("model or endpoint not found — check both fields".into()), + ureq::Error::StatusCode(c) => AiError::Rejected(format!("HTTP {c}")), + other => AiError::Http(other.to_string()), + } + })?; + let v: serde_json::Value = resp.body_mut().read_json().map_err(|e| AiError::BadResponse(e.to_string()))?; + // A completion cut off at max_tokens ("length") or aborted is not + // a translation — returning it would silently truncate the doc. + match v.pointer("/choices/0/finish_reason").and_then(serde_json::Value::as_str) { + Some("stop") | Some("tool_calls") | None => {} + Some(reason) => return Err(AiError::BadResponse(format!("incomplete completion (finish_reason={reason})"))), + } + v.pointer("/choices/0/message/content") + .and_then(serde_json::Value::as_str) + .map(str::to_string) + .ok_or_else(|| AiError::BadResponse("no choices[0].message.content in response".into())) + } + + fn test(&mut self) -> Result { + if self.endpoint.trim().is_empty() { + return Err(AiError::NotConfigured); + } + // GET /v1/models — a handshake only, no user text leaves the app. + let mut req = Self::agent().get(self.url("models")); + if let Some(t) = &self.token + && !t.is_empty() + { + req = req.header("Authorization", format!("Bearer {t}")); + } + let mut resp = req.call().map_err(|e| match e { + ureq::Error::StatusCode(401 | 403) => AiError::Rejected("authentication failed — check the API token".into()), + ureq::Error::StatusCode(c) => AiError::Rejected(format!("HTTP {c}")), + other => AiError::Http(other.to_string()), + })?; + let v: serde_json::Value = resp.body_mut().read_json().map_err(|e| AiError::BadResponse(e.to_string()))?; + let models = v + .get("data") + .and_then(serde_json::Value::as_array) + .map(|arr| arr.iter().filter_map(|m| m.get("id").and_then(serde_json::Value::as_str).map(str::to_string)).collect()) + .unwrap_or_default(); + Ok(ProviderInfo { label: format!("reachable: {}", self.endpoint), models }) + } + + fn is_local(&self) -> bool { + // Local endpoints keep text on the machine; we can't verify a + // remote URL's forwarding, so honesty means: loopback → local. + // Parse the authority properly — a prefix match would call + // `localhost.example.com` or `127.0.0.1.example.com` "local" + // while document text leaves the machine. + let e = self.endpoint.trim(); + let after_scheme = e.split_once("://").map_or(e, |(_, rest)| rest); + let authority = after_scheme.split(['/', '?', '#']).next().unwrap_or(""); + let host_port = authority.rsplit('@').next().unwrap_or(""); // strip userinfo + let host = if let Some(rest) = host_port.strip_prefix('[') { + rest.split(']').next().unwrap_or("") + } else { + host_port.split(':').next().unwrap_or("") + }; + host.eq_ignore_ascii_case("localhost") || host.parse::().is_ok_and(|ip| ip.is_loopback()) + } +} + +#[cfg(all(test, not(target_arch = "wasm32")))] +mod tests { + use super::*; + + #[test] + fn is_local_accepts_only_real_loopback() { + let local = |ep: &str| OpenAiCompat::new(ep, None, "m").is_local(); + assert!(local("http://localhost:11434/v1")); + assert!(local("https://localhost/v1")); + assert!(local("http://127.0.0.1:8080/v1")); + assert!(local("http://127.99.0.1/v1")); // whole 127/8 is loopback + assert!(local("http://[::1]:11434/v1")); + // Lookalike hostnames must NOT report local — document text would + // leave the machine while the UI promises it stays. + assert!(!local("https://localhost.example.com/v1")); + assert!(!local("https://127.0.0.1.example.com/v1")); + assert!(!local("https://localhost.evil.io/v1")); + assert!(!local("https://api.openai.com/v1")); + assert!(!local("https://example.com/localhost/v1")); + } +} diff --git a/crates/ai/src/registry.rs b/crates/ai/src/registry.rs new file mode 100644 index 000000000..2035ab836 --- /dev/null +++ b/crates/ai/src/registry.rs @@ -0,0 +1,138 @@ +//! The curated model registry — a hand-maintained table, compiled in. +//! Runtime-fetching this list would make our supply chain un-auditable. +//! +//! Curation rule: **permissive licenses only** (the suite is MIT OR +//! Apache-2.0 and commercial users run it). CC-BY-NC models like NLLB-200 +//! are excluded by policy; their absence is deliberate. +//! +//! `sha256` may be `None`: Hugging Face serves the LFS digest in the +//! `X-Linked-ETag` header of the resolve redirect, which [`crate::fetch`] +//! uses as the expected checksum. We only hard-code a hash when we've +//! verified it ourselves — never a guessed one. + +use crate::probe::MachineCaps; + +/// Model quality tier — higher is better output, bigger download. +#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)] +pub enum Quality { + Tiny, + Small, + Medium, +} + +/// Which candle architecture loads the GGUF. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Arch { + Qwen2, + Llama, +} + +/// One downloadable model. +#[derive(Clone, Copy, Debug)] +pub struct ModelEntry { + /// Stable identifier stored in settings (`"qwen2.5-1.5b-q4km"`). + pub id: &'static str, + /// Display name for the picker. + pub name: &'static str, + /// Canonical download URL (Hugging Face `resolve` endpoint). + pub url: &'static str, + /// Filename inside the model cache. + pub file: &'static str, + /// Companion tokenizer (needed by local inference; the GGUF ships + /// vocab only, not the chat-time tokenizer.json). + pub tokenizer_url: &'static str, + /// Verified SHA-256 of the GGUF, when we have one. + pub sha256: Option<&'static str>, + /// Download size, MiB — shown to the user before they commit. + pub size_mb: u64, + /// Below this RAM the model is refused outright. + pub min_ram_gb: f32, + /// Recommended RAM for comfortable use. + pub rec_ram_gb: f32, + /// SPDX license id, displayed in the UI. + pub license: &'static str, + pub quality: Quality, + pub arch: Arch, + /// Human-readable language coverage for the picker. + pub langs: &'static str, +} + +/// The registry, smallest first. +pub static MODELS: &[ModelEntry] = &[ + ModelEntry { + id: "qwen2.5-0.5b-q4km", + name: "Qwen2.5 0.5B Instruct (Q4_K_M)", + url: "https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q4_k_m.gguf", + file: "qwen2.5-0.5b-instruct-q4_k_m.gguf", + tokenizer_url: "https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct/resolve/main/tokenizer.json", + sha256: None, + size_mb: 389, + min_ram_gb: 2.0, + rec_ram_gb: 4.0, + license: "Apache-2.0", + quality: Quality::Tiny, + arch: Arch::Qwen2, + langs: "29+ languages incl. EN/ZH/FR/DE/ES/JA/KO/RU", + }, + ModelEntry { + id: "smollm2-1.7b-q4km", + name: "SmolLM2 1.7B Instruct (Q4_K_M)", + url: "https://huggingface.co/bartowski/SmolLM2-1.7B-Instruct-GGUF/resolve/main/SmolLM2-1.7B-Instruct-Q4_K_M.gguf", + file: "SmolLM2-1.7B-Instruct-Q4_K_M.gguf", + tokenizer_url: "https://huggingface.co/HuggingFaceTB/SmolLM2-1.7B-Instruct/resolve/main/tokenizer.json", + sha256: None, + size_mb: 1033, + min_ram_gb: 4.0, + rec_ram_gb: 8.0, + license: "Apache-2.0", + quality: Quality::Small, + arch: Arch::Llama, + langs: "primarily EN/FR/DE/ES/IT", + }, + ModelEntry { + id: "qwen2.5-1.5b-q4km", + name: "Qwen2.5 1.5B Instruct (Q4_K_M)", + url: "https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF/resolve/main/qwen2.5-1.5b-instruct-q4_k_m.gguf", + file: "qwen2.5-1.5b-instruct-q4_k_m.gguf", + tokenizer_url: "https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct/resolve/main/tokenizer.json", + sha256: None, + size_mb: 986, + min_ram_gb: 4.0, + rec_ram_gb: 8.0, + license: "Apache-2.0", + quality: Quality::Small, + arch: Arch::Qwen2, + langs: "29+ languages incl. EN/ZH/FR/DE/ES/JA/KO/RU", + }, + // NOTE: Qwen2.5-3B was removed — its `qwen-research` license is + // non-commercial and breaks the permissive-only rule above. No + // permissively-licensed Medium-tier candidate is currently curated. +]; + +/// Look up a model by stable id. +pub fn by_id(id: &str) -> Option<&'static ModelEntry> { + MODELS.iter().find(|m| m.id == id) +} + +/// Whether `entry` can run at all on this machine. +pub fn fits(caps: &MachineCaps, entry: &ModelEntry) -> bool { + let ram_ok = caps.ram_gb >= entry.min_ram_gb; + let disk_ok = caps.disk_free_gb >= entry.size_mb as f32 / 1024.0 * 1.3; // file + headroom + ram_ok && disk_ok +} + +/// The default suggestion for `caps`: best quality that fits, preferring +/// 3B on roomy machines, 1.5B mid-range, 0.5B on small ones. Returns +/// `None` when nothing fits — the UI then says so honestly instead of +/// offering a download that can't run. +pub fn suggest(caps: &MachineCaps) -> Option<&'static ModelEntry> { + let capable: Vec<&ModelEntry> = MODELS.iter().filter(|m| fits(caps, m)).collect(); + let best_allowed = if caps.vram_gb.is_some_and(|v| v >= 6.0) || caps.ram_gb >= 16.0 { + Quality::Medium + } else if caps.ram_gb >= 8.0 { + Quality::Small + } else { + Quality::Tiny + }; + capable.into_iter().filter(|m| m.quality <= best_allowed).max_by_key(|m| m.quality) +} diff --git a/crates/ai/src/translate.rs b/crates/ai/src/translate.rs new file mode 100644 index 000000000..a5de0622c --- /dev/null +++ b/crates/ai/src/translate.rs @@ -0,0 +1,525 @@ +//! Document translation as *segments*, never raw text: the model sees +//! only translatable runs, and protected spans (URLs, placeholders, +//! markup, numbers-only runs) come back byte-identical because we never +//! sent them. +//! +//! Each app declares its grammar via [`TranslateGrammar`]; the default +//! [`PdfGrammar`] suits extracted PDF text. + +use crate::error::AiError; +use crate::provider::{GenOpts, Provider}; + +/// A unit of text the translator decided on. +#[derive(Clone, Debug, PartialEq)] +pub enum Segment { + /// Sent to the model; replace with the translation. + Text(String), + /// Never sent; re-inserted verbatim. + Protected(String), +} + +impl Segment { + /// The source text, translated or not. + pub fn source(&self) -> &str { + match self { + Self::Text(s) | Self::Protected(s) => s, + } + } +} + +/// Which runs of a document's text must never be translated. +pub trait TranslateGrammar { + /// True when `token` (already delimited — a word, symbol, or + /// whitespace-free run) is structural and must survive verbatim. + fn is_protected(&self, token: &str) -> bool; +} + +/// Grammar for text extracted from a PDF: protects URLs, e-mail +/// addresses, `{placeholders}`, ``, and runs with no letters +/// (page furniture, digits, punctuation). +pub struct PdfGrammar; + +impl TranslateGrammar for PdfGrammar { + fn is_protected(&self, token: &str) -> bool { + is_protected_token(token) + } +} + +/// Shared protected-token test, useful to other apps' grammars. +pub fn is_protected_token(token: &str) -> bool { + let t = token.trim(); + if t.is_empty() { + return true; + } + if !t.chars().any(|c| c.is_alphabetic()) { + return true; // numbers, punctuation, symbols + } + let lower = t.to_ascii_lowercase(); + lower.starts_with("http://") + || lower.starts_with("https://") + || lower.starts_with("www.") + || lower.contains('@') && lower.contains('.') && !lower.contains(' ') + || (t.starts_with('{') && t.ends_with('}')) + || (t.starts_with('<') && t.ends_with('>')) +} + +/// Split `text` into segments on whitespace boundaries, grouping +/// consecutive protected or translatable tokens. `` spans are +/// carved out first — a tag with attributes contains whitespace, and a +/// whole `Hello` run must keep "Hello" translatable while the +/// tags themselves stay byte-identical. +pub fn segment(text: &str, grammar: &dyn TranslateGrammar) -> Vec { + fn flush(out: &mut Vec, buf: &mut String, protected: bool) { + if buf.is_empty() { + return; + } + let seg = if protected { Segment::Protected(std::mem::take(buf)) } else { Segment::Text(std::mem::take(buf)) }; + out.push(seg); + } + + let mut out: Vec = Vec::new(); + let mut buf = String::new(); + let mut buf_protected = false; + let mut started = false; + + for (token, is_tag) in split_tokens(text) { + let ws = token.chars().all(char::is_whitespace); + // Whitespace glues to whatever the current run is; markup tags + // are always protected. + let this_protected = if ws { buf_protected } else { is_tag || grammar.is_protected(token) }; + if started && this_protected != buf_protected { + flush(&mut out, &mut buf, buf_protected); + } + buf_protected = this_protected; + started = true; + buf.push_str(token); + } + flush(&mut out, &mut buf, buf_protected); + out +} + +/// Tokenize into `(slice, is_tag)`: markup tags are whole `<…>` spans +/// (attributes included), everything else alternates between maximal +/// whitespace and non-whitespace runs. +fn split_tokens(text: &str) -> Vec<(&str, bool)> { + let mut out = Vec::new(); + let mut pos = 0usize; + let bytes = text.as_bytes(); + while pos < bytes.len() { + if bytes[pos] == b'<' + && let Some(tag_len) = tag_len(&text[pos..]) + { + out.push((&text[pos..pos + tag_len], true)); + pos += tag_len; + continue; + } + // Advance a non-tag run up to the next '<' that starts a tag; + // bare '<' characters just stay inside the run. + let mut scan = pos; + let mut run_end = bytes.len(); + while let Some(lt) = bytes[scan..].iter().position(|&b| b == b'<') { + let at = scan + lt; + if tag_len(&text[at..]).is_some() { + run_end = at; + break; + } + scan = at + 1; + } + for piece in split_words_ws(&text[pos..run_end]) { + out.push((piece, false)); + } + pos = run_end; + } + out +} + +/// Length of a `<…>` tag starting at `s[0]`, or `None` when `<` does not +/// begin markup (bare `<`, `<3`, `< hello`). Tags start `` before any `<` or newline; +/// the scan is capped so pathological input can't stall it. +fn tag_len(s: &str) -> Option { + const MAX_TAG: usize = 512; + let second = s.as_bytes().get(1)?; + let opener_ok = second.is_ascii_alphabetic() || matches!(second, b'/' | b'!' | b'?'); + if !opener_ok { + return None; + } + s.char_indices().skip(2).take(MAX_TAG).find(|(_, c)| matches!(c, '>' | '<' | '\n')).and_then(|(i, c)| (c == '>').then_some(i + 1)) +} + +/// Split into alternating word/whitespace runs (like `split_inclusive` +/// but grouping every maximal run of whitespace or non-whitespace). +fn split_words_ws(text: &str) -> Vec<&str> { + let mut out = Vec::new(); + let mut start = 0usize; + let mut prev_ws: Option = None; + for (i, c) in text.char_indices() { + let ws = c.is_whitespace(); + if let Some(p) = prev_ws + && p != ws + { + out.push(&text[start..i]); + start = i; + } + prev_ws = Some(ws); + } + if start < text.len() { + out.push(&text[start..]); + } + out +} + +/// How many segments one prompt carries — keeps responses snappy and +/// makes a numbering slip cheap to retry. +const BATCH: usize = 20; +/// …and how many bytes one prompt carries. A document with no protected +/// tokens is one `Text` segment of arbitrary length — without a size +/// bound the request can exceed `max_tokens` and come back truncated +/// (which providers must reject, not return as success). +const BATCH_BYTES: usize = 4 * 1024; +/// A single `Text` run larger than this is chopped into pieces before +/// batching, so no one request is unbounded. +const RUN_BYTES: usize = 3 * 1024; + +/// A translatable piece of one segment: the whitespace-stripped `core` +/// is sent to the model, `lead`/`trail` are restored verbatim around the +/// translation so `Visitez` never glues to `https://a.io`. +struct Run<'a> { + seg: usize, + lead: &'a str, + core: &'a str, + trail: &'a str, + /// False for whitespace-only pieces: never sent to the model, but + /// still reassembled into the segment. + send: bool, +} + +/// `(leading ws, core, trailing ws)` of `s`, all on char boundaries. +fn ws_edges(s: &str) -> (&str, &str, &str) { + let lead = s.len() - s.trim_start().len(); + let tail = s.len() - s.trim_end().len(); + if lead + tail >= s.len() { + return (s, "", ""); // all-whitespace run: nothing to translate + } + (&s[..lead], &s[lead..s.len() - tail], &s[s.len() - tail..]) +} + +/// Chop `s` into ≤ `max`-byte pieces on whitespace boundaries (the last +/// ws before the limit; a run with no ws is hard-cut at the limit). The +/// boundary whitespace stays inside the pieces — nothing is lost. +fn split_run(s: &str, max: usize) -> Vec<&str> { + let mut out = Vec::new(); + let mut rest = s; + while rest.len() > max { + let mut ws_cut = None; + let mut boundary = 0usize; + for (i, c) in rest.char_indices() { + if i >= max { + break; + } + boundary = i + c.len_utf8(); + if c.is_whitespace() { + ws_cut = Some(i); // cut *before* the ws — it leads the next piece + } + } + let cut = match ws_cut.filter(|w| *w > max / 4) { + Some(w) => w, + None => boundary.max(1), + }; + out.push(&rest[..cut]); + rest = &rest[cut..]; + } + if !rest.is_empty() { + out.push(rest); + } + out +} + +/// Translate every `Text` segment to `target_lang`, leaving `Protected` +/// untouched. Batched with numbered items; a count mismatch retries the +/// offending half rather than misaligning the whole document. +pub fn translate_segments(provider: &mut dyn Provider, segs: &[Segment], target_lang: &str) -> Result, AiError> { + // Source whitespace never reaches the model: each Text segment is + // split edge-to-edge, and oversized runs are chopped further. + let mut runs: Vec> = Vec::new(); + for (i, s) in segs.iter().enumerate() { + let Segment::Text(src) = s else { continue }; + for piece in split_run(src, RUN_BYTES) { + let (lead, core, trail) = ws_edges(piece); + // Pure-whitespace pieces (possible after a long run is chopped) + // keep their bytes in the output but skip the provider. + runs.push(Run { seg: i, lead, core, trail, send: !core.is_empty() }); + } + } + let run_segs: std::collections::HashSet = runs.iter().map(|r| r.seg).collect(); + + let mut out: Vec = segs.iter().map(|s| s.source().to_string()).collect(); + for &i in &run_segs { + out[i].clear(); // rebuilt from translated runs below + } + let mut i = 0; + while i < runs.len() { + // Whitespace-only pieces restore verbatim, in order, and never + // reach the model. + while i < runs.len() && !runs[i].send { + let r = &runs[i]; + out[r.seg].push_str(r.lead); + out[r.seg].push_str(r.trail); + i += 1; + } + // A batch is bounded by item count *and* total prompt bytes. + let mut bytes = 0usize; + let start = i; + while i < runs.len() && runs[i].send && i - start < BATCH && bytes + runs[i].core.len() <= BATCH_BYTES { + bytes += runs[i].core.len(); + i += 1; + } + if i == start { + if i < runs.len() { + i += 1; // never spin on an oversized single item + } + continue; + } + let chunk = &runs[start..i]; + let translated = translate_batch(provider, chunk, target_lang)?; + for (run, t) in chunk.iter().zip(translated) { + out[run.seg].push_str(run.lead); + out[run.seg].push_str(&t); + out[run.seg].push_str(run.trail); + } + } + Ok(out) +} + +/// One numbered batch; splits recursively on count mismatch so a single +/// malformed reply can't corrupt neighbors. +fn translate_batch(provider: &mut dyn Provider, runs: &[Run<'_>], lang: &str) -> Result, AiError> { + if runs.len() == 1 { + return Ok(vec![translate_one(provider, runs[0].core, lang)?]); + } + let prompt = numbered_prompt(&runs.iter().map(|r| r.core.to_string()).collect::>(), lang); + let reply = provider.complete(&prompt, &GenOpts::default())?; + match parse_numbered(&reply, runs.len()) { + Some(v) => Ok(v), + None => { + let mid = runs.len() / 2; + let mut a = translate_batch(provider, &runs[..mid], lang)?; + let b = translate_batch(provider, &runs[mid..], lang)?; + a.extend(b); + Ok(a) + } + } +} + +fn translate_one(provider: &mut dyn Provider, source: &str, lang: &str) -> Result { + let prompt = format!("Translate the following text to {lang}. Reply with ONLY the translation, no quotes, no notes.\n\n{source}"); + Ok(provider.complete(&prompt, &GenOpts::default())?.trim().to_string()) +} + +/// `"1. …"`-style numbered prompt — models follow it far more reliably +/// than delimiter schemes. +fn numbered_prompt(sources: &[String], lang: &str) -> String { + let mut p = format!( + "Translate each numbered item to {lang}. Keep the numbering. \ + Preserve all formatting, placeholders like {{name}}, URLs and markup verbatim. \ + Reply with ONLY the numbered translations.\n\n" + ); + for (i, s) in sources.iter().enumerate() { + p.push_str(&format!("{}. {}\n", i + 1, s.replace('\n', " "))); + } + p +} + +/// Parse `"1. …\n2. …"` back into items; `None` when the reply is +/// malformed — duplicates, out-of-range numbers, or a missing item all +/// mean the numbering slipped, and the caller retries/splits rather +/// than accepting corrupted text. Non-numbered lines after an item are +/// continuations of it; non-numbered chatter before item 1 is rejected +/// the same way, so nothing is silently dropped. +fn parse_numbered(reply: &str, want: usize) -> Option> { + let mut out = vec![String::new(); want]; + let mut seen = vec![false; want]; + let mut current: Option = None; + for line in reply.lines() { + let line = line.trim(); + if line.is_empty() { + continue; + } + match numbered_line(line) { + Some(idx) if idx >= 1 && idx <= want => { + if seen[idx - 1] { + return None; // "1. un\n2. deux\n1. trois" overwrites — reject + } + seen[idx - 1] = true; + let rest = line.split_once(['.', ')']).map_or("", |(_, r)| r).trim().to_string(); + out[idx - 1] = rest; + current = Some(idx - 1); + } + Some(_) => return None, // numbered but out of range — malformed reply + // A wrapped/multi-line item: keep the continuation, not + // "1. Première phrase.\nSuite" dropping "Suite". Unnumbered + // preamble is rejected — not our format. + None => { + let i = current?; + out[i].push('\n'); + out[i].push_str(line); + } + } + } + (seen.iter().all(|s| *s) && out.iter().all(|s| !s.is_empty())).then_some(out) +} + +/// `Some(idx)` when `line` opens as `"12."` / `"12)"` — a 1-3 digit +/// number followed by `'.'` or `')'`. Anything else is `None`, so +/// "Section 2. notes" is a continuation, not item 2. +fn numbered_line(line: &str) -> Option { + let line = line.trim_start(); + let digits = line.bytes().take_while(|b| b.is_ascii_digit()).count(); + if digits == 0 || digits > 3 || !matches!(line.as_bytes().get(digits), Some(b'.' | b')')) { + return None; + } + line.get(..digits)?.parse().ok() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn split_words_ws_groups_runs() { + assert_eq!(split_words_ws("a b\tc"), vec!["a", " ", "b", "\t", "c"]); + } + + #[test] + fn pdf_grammar_protects() { + let g = PdfGrammar; + assert!(g.is_protected("https://x.io/a")); + assert!(g.is_protected("{count}")); + assert!(g.is_protected("42.5")); + assert!(!g.is_protected("Bonjour")); + } + + #[test] + fn segmentation_glues_whitespace_and_protects_spans() { + let segs = segment("Visit https://a.io now {n} times", &PdfGrammar); + // "Visit " text, protected url, " now " text, protected {n}, " times" text + let texts: Vec<&Segment> = segs.iter().filter(|s| matches!(s, Segment::Text(_))).collect(); + assert!(segs.iter().any(|s| matches!(s, Segment::Protected(p) if p.trim() == "https://a.io"))); + assert!(segs.iter().any(|s| matches!(s, Segment::Protected(p) if p.trim() == "{n}"))); + assert!(texts.iter().any(|s| s.source().contains("Visit"))); + } + + #[test] + fn numbered_parse_roundtrip() { + let r = "1. un\n2. deux\n3. trois"; + assert_eq!(parse_numbered(r, 3), Some(vec!["un".into(), "deux".into(), "trois".into()])); + assert_eq!(parse_numbered("1. un\n3. trois", 3), None); + } + + #[test] + fn numbered_parse_rejects_duplicates_and_overflow() { + assert_eq!(parse_numbered("1. un\n2. deux\n1. trois", 2), None); + assert_eq!(parse_numbered("1. un\n2. deux\n3. trois", 2), None); + assert_eq!(parse_numbered("0. zero\n1. un\n2. deux", 2), None); + } + + #[test] + fn numbered_parse_keeps_continuation_lines() { + let r = "1. Première phrase.\nSuite du paragraphe\n2. Deuxième élément."; + assert_eq!(parse_numbered(r, 2), Some(vec!["Première phrase.\nSuite du paragraphe".into(), "Deuxième élément.".into()])); + // Preamble chatter that isn't a numbered item is rejected, not + // silently dropped. + assert_eq!(parse_numbered("Sure, here you go:\n1. un\n2. deux", 2), None); + // "Section 2. notes" looks numbered but isn't → continuation. + let r2 = "1. un\nSection 2. notes\n2. deux"; + assert_eq!(parse_numbered(r2, 2), Some(vec!["un\nSection 2. notes".into(), "deux".into()])); + } + + #[test] + fn markup_tags_split_from_their_text() { + let segs = segment("Hello world", &PdfGrammar); + assert!(segs.iter().any(|s| matches!(s, Segment::Protected(p) if p == ""))); + assert!(segs.iter().any(|s| matches!(s, Segment::Protected(p) if p.trim() == ""))); + assert!(segs.iter().any(|s| matches!(s, Segment::Text(t) if t.contains("Hello")))); + assert!(segs.iter().any(|s| matches!(s, Segment::Text(t) if t.contains("world")))); + // Tags containing spaces stay whole and protected. + let segs = segment("link", &PdfGrammar); + assert!(segs.iter().any(|s| matches!(s, Segment::Protected(p) if p == ""))); + // A bare '<' is text, not a tag opener — words around it stay + // translatable (the lone '<' itself is protected as punctuation). + let segs = segment("a < b and <3 hearts", &PdfGrammar); + assert!(segs.iter().any(|s| matches!(s, Segment::Text(t) if t.contains("hearts")))); + assert!(!segs.iter().any(|s| matches!(s, Segment::Protected(p) if p.contains('<') && p.contains('>')))); + } + + #[test] + fn ws_edges_and_split_run_preserve_every_byte() { + assert_eq!(ws_edges(" héllo \n"), (" ", "héllo", " \n")); + assert_eq!(ws_edges(" "), (" ", "", "")); + let s = "alpha beta gamma delta epsilon"; + let pieces = split_run(s, 12); + assert!(pieces.iter().all(|p| p.len() <= 12)); + assert_eq!(pieces.concat(), s); // boundary whitespace survives + // A run with no whitespace is hard-cut at a char boundary. + let long = "x".repeat(50); + let pieces = split_run(&long, 20); + assert!(pieces.iter().all(|p| p.len() <= 20)); + assert_eq!(pieces.concat(), long); + } + + /// A provider that echoes numbered replies — exercises the batching, + /// whitespace restore and reassembly end to end without a network. + struct Echo; + + impl Provider for Echo { + fn name(&self) -> String { + "echo".into() + } + + fn complete(&mut self, prompt: &str, _opts: &GenOpts) -> Result { + if prompt.starts_with("Translate each numbered item") { + // Parse our own prompt's numbering and echo each item. + let body = prompt.split("\n\n").nth(1).unwrap_or(""); + let mut out = String::new(); + for line in body.lines() { + out.push_str(line); + out.push('\n'); + } + return Ok(out); + } + Ok(prompt.rsplit("\n\n").next().unwrap_or(prompt).to_string()) + } + + fn test(&mut self) -> Result { + Ok(crate::provider::ProviderInfo { label: "echo".into(), models: vec![] }) + } + + fn is_local(&self) -> bool { + true + } + } + + #[test] + fn numbered_parse_accepts_paren_markers() { + // "1) …" replies contain sentence-ending periods inside items — + // the leading delimiter must be picked before inspecting text. + let r = "1) Première phrase.\nSuite.\n2) Deuxième élément."; + assert_eq!(parse_numbered(r, 2), Some(vec!["Première phrase.\nSuite.".into(), "Deuxième élément.".into()])); + } + + #[test] + fn whitespace_only_pieces_survive_reconstruction() { + let segs = vec![Segment::Text(format!("{}Hello", " ".repeat(RUN_BYTES)))]; + let mut echo = Echo; + let out = translate_segments(&mut echo, &segs, "fr").unwrap_or_default(); + assert_eq!(out.concat(), format!("{}Hello", " ".repeat(RUN_BYTES))); + } + + #[test] + fn translate_restores_whitespace_around_protected_spans() { + let segs = segment("Visit https://a.io now", &PdfGrammar); + let mut echo = Echo; + let out = translate_segments(&mut echo, &segs, "fr").unwrap_or_default(); + assert_eq!(out.concat(), "Visit https://a.io now"); + } +} diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index fe28cec3f..607fb00b9 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`). @@ -58,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`). @@ -92,10 +98,18 @@ 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"] +[[test]] +name = "sbc_oracle" +required-features = ["sbc"] + [[example]] name = "info" required-features = ["decode"] 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..8aa3af36d 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; @@ -56,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/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"); +} 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}"); +} 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 `
`: 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); +} diff --git a/crates/image-codecs/README.md b/crates/image-codecs/README.md index f96672817..0fb86e31c 100644 --- a/crates/image-codecs/README.md +++ b/crates/image-codecs/README.md @@ -353,8 +353,16 @@ Rec. 2020 RGB as 16-bit BT.2100 PQ, with measured content-light levels and the r * Adam7 PNG against progressive PNG and against the `image` crate as an oracle; * limit enforcement. -If `corpus/pngsuite/*.png` exists at the repo root, every file in it is compared against the -`image` crate's decoder. Without it, that test is skipped. +With the `corpus` feature, the PngSuite tests read `corpus/pngsuite/` at the repo root. They +take the PNGs that `tests/it/common/pngsuite.tsv` lists (one `sha256name` row per file), +check each file's SHA-256 before decoding it, and compare it against the `image` crate's +decoder. A listed PNG that is missing or changed fails the tests; a file the list does not name is +not read. To fill the folder, download +[PngSuite-2017jul19.tgz](http://www.schaik.com/pngsuite/PngSuite-2017jul19.tgz) from the +[PngSuite page](http://www.schaik.com/pngsuite/), check that its SHA-256 is +`0294b244c95a8342c01b00010cf34abdcabc7c6a34fd0fe1bd963917537bfdc8`, and extract it into +`corpus/pngsuite/`. No PngSuite file is committed here; the list links the suite's +[terms](http://www.schaik.com/pngsuite/PngSuite.LICENSE). With the `corpus` feature, the deep EXR test reads `11.deep.exr`, `42.deep.exr`, `64.deep.exr`, `multivariate.deep.exr` and `objectid.deep.exr` from `corpus/exr/` at the repo root. These are the diff --git a/crates/image-codecs/tests/it/common/mod.rs b/crates/image-codecs/tests/it/common/mod.rs index 6b03752f3..10960bbc9 100644 --- a/crates/image-codecs/tests/it/common/mod.rs +++ b/crates/image-codecs/tests/it/common/mod.rs @@ -2,6 +2,7 @@ //! image generators, comparison metrics. #![allow(dead_code)] +pub mod pngsuite; pub mod tiffgen; use craft_image_codecs::*; diff --git a/crates/image-codecs/tests/it/common/pngsuite.rs b/crates/image-codecs/tests/it/common/pngsuite.rs new file mode 100644 index 000000000..c8944ba9c --- /dev/null +++ b/crates/image-codecs/tests/it/common/pngsuite.rs @@ -0,0 +1,94 @@ +//! The pinned PngSuite. `pngsuite.tsv` lists every file of the suite as a `sha256name` row, +//! with `#` comment lines; further tab-separated columns are allowed and ignored. The corpus tests +//! read only the listed PNGs from `corpus/pngsuite/` at the repo root, and only after each file's +//! SHA-256 matches its row. A file the list does not name is never read. + +use std::collections::BTreeMap; +use std::io::Read; +use std::path::{Path, PathBuf}; + +use sha2::{Digest, Sha256}; + +/// The pinned list. +pub const MANIFEST: &str = include_str!("pngsuite.tsv"); + +/// The largest file read from the corpus folder. The suite's largest file is under 5 KiB. +pub const MAX_FILE_BYTES: u64 = 4 * 1024 * 1024; + +/// `corpus/pngsuite` at the repo root. +pub fn dir() -> PathBuf { + Path::new(env!("CARGO_MANIFEST_DIR")).join("../../corpus/pngsuite") +} + +/// The rows of `manifest` as name to lowercase hex SHA-256. A row needs a 64-digit lowercase hex +/// digest and a plain file name (ASCII letters, digits, `.`, `_` and `-`, not starting with `.`), +/// and each name may appear once. +pub fn parse(manifest: &str) -> Result, String> { + let mut rows = BTreeMap::new(); + for (number, line) in manifest.lines().enumerate().map(|(i, l)| (i + 1, l)) { + if line.is_empty() || line.starts_with('#') { + continue; + } + let mut cols = line.split('\t'); + let (Some(digest), Some(name)) = (cols.next(), cols.next()) else { + return Err(format!("line {number}: expected a SHA-256, a tab and a name")); + }; + if digest.len() != 64 || !digest.bytes().all(|c| matches!(c, b'0'..=b'9' | b'a'..=b'f')) { + return Err(format!("line {number}: invalid SHA-256 for {name:?}")); + } + if name.is_empty() || name.starts_with('.') || !name.bytes().all(|c| c.is_ascii_alphanumeric() || b"._-".contains(&c)) { + return Err(format!("line {number}: invalid file name {name:?}")); + } + if rows.insert(name, digest).is_some() { + return Err(format!("line {number}: {name} is listed twice")); + } + } + if rows.is_empty() { + return Err("the manifest lists no files".into()); + } + Ok(rows) +} + +/// The lowercase hex SHA-256 of `bytes`. +pub fn sha256_hex(bytes: &[u8]) -> String { + Sha256::digest(bytes).iter().map(|b| format!("{b:02x}")).collect() +} + +/// Reads a regular file of at most `limit` bytes. A symbolic link, a folder or a larger file is an +/// error, and a file that grows during the read is cut off at `limit + 1` bytes and refused. +fn read_file(path: &Path, limit: u64) -> Result, String> { + let meta = std::fs::symlink_metadata(path).map_err(|e| format!("{}: {e}", path.display()))?; + if !meta.is_file() || meta.len() > limit { + return Err(format!("{}: expected a regular file of at most {limit} bytes", path.display())); + } + let mut bytes = Vec::new(); + std::fs::File::open(path).and_then(|f| f.take(limit + 1).read_to_end(&mut bytes)).map_err(|e| format!("{}: {e}", path.display()))?; + if bytes.len() as u64 > limit { + return Err(format!("{}: exceeds {limit} bytes", path.display())); + } + Ok(bytes) +} + +/// Every `.png` that `manifest` lists, read from `dir` in name order with its bytes. A listed PNG +/// that is missing, is not a regular file or does not match its SHA-256 is an error. +pub fn pinned_pngs(dir: &Path, manifest: &str) -> Result)>, String> { + let rows = parse(manifest)?; + let mut out = Vec::new(); + for (name, digest) in rows.into_iter().filter(|(name, _)| name.ends_with(".png")) { + let bytes = read_file(&dir.join(name), MAX_FILE_BYTES)?; + let got = sha256_hex(&bytes); + if got != digest { + return Err(format!("{name}: SHA-256 {got} does not match the pinned {digest}")); + } + out.push((name.to_string(), bytes)); + } + Ok(out) +} + +/// The pinned PNGs of `corpus/pngsuite/`. A missing or changed file fails the calling test. +pub fn pngs() -> Vec<(String, Vec)> { + let dir = dir(); + pinned_pngs(&dir, MANIFEST).unwrap_or_else(|e| { + panic!("{}: {e}; extract the archive named in tests/it/common/pngsuite.tsv into this folder (see the crate README)", dir.display()) + }) +} diff --git a/crates/image-codecs/tests/it/common/pngsuite.tsv b/crates/image-codecs/tests/it/common/pngsuite.tsv new file mode 100644 index 000000000..e7906feac --- /dev/null +++ b/crates/image-codecs/tests/it/common/pngsuite.tsv @@ -0,0 +1,186 @@ +# PngSuite original PNGs and redistribution notice +# Source: https://github.com/lunapaint/pngsuite/tree/8cd768dd0d0063195174d0d01cacbd5a7d1e5605 +# Archive: http://www.schaik.com/pngsuite/PngSuite-2017jul19.tgz +# Archive SHA-256: 0294b244c95a8342c01b00010cf34abdcabc7c6a34fd0fe1bd963917537bfdc8 +# Terms: http://www.schaik.com/pngsuite/PngSuite.LICENSE +# LICENSE holds the same bytes as the archive's PngSuite.LICENSE. +# sha256 name +71e1f5bf865131b5d9996e76a78372146283e5089e50f900ae927a6458b62101 LICENSE +71e1f5bf865131b5d9996e76a78372146283e5089e50f900ae927a6458b62101 PngSuite.LICENSE +a2853f2be68e460dcb9992819125b74503a01383e79f79a04b971ffa9d248544 PngSuite.README +6cf3bcd1757bfad2a7ce9c9659d4f609297a0828cafc7c9eddee18c5576ba9e9 PngSuite.png +9bf1c4610280efecc291361e2b7b026d602d03a7137f476ff84af626bb7b3a62 basi0g01.png +50ed4ff9c1c80578ae58ead6fb28ea2e44016b5b56a7b3e95c235ec86f97c0d8 basi0g02.png +0cce4212157dae7c0f71f5f72cef39cecab3347de455da0ace7de83eebd47849 basi0g04.png +b9300750e7414c9fed68cc7f4f531f5e2cdd2724f50142e8aa3a0070836bece9 basi0g08.png +d354026bdd0aa6ed7bedea7c92e5eef2ebbd4854848b8a0a48f562cc71bfe80f basi0g16.png +b2690d4475cdc39faf5a7d2de20de4e14eb96c6360fa791ec2003b4085ecacde basi2c08.png +ae13eba5fabbf7cbe8c01ec4458cdaa7e6bfdfcbd5109e831efaac9f39096027 basi2c16.png +8e1edfbc0382e0b545c70209271cedead2d530df1ce40f5296f0749226b36006 basi3p01.png +85f304eaaf6831b2bcc2c08892b947fef52f06337aaf23312d6326e367d73f77 basi3p02.png +78890ee2c4da71e460b5a1527efe7dc17d673ebe997f49ca1b4dcd7347d21e56 basi3p04.png +ca103eef7a7c50abc7af9d5ec0dc9fdc07668e2f030adbce226e050dcec9eea3 basi3p08.png +dfae01a4548e30519157bb51ce29d4de3b35b74288e9568b4d5911de01c6048b basi4a08.png +ef7df23ccd912309a4f89ca3c3094bf5ab55add25218e571e51cc6cb11cfad9e basi4a16.png +fe70ea20c8447e82abb7bc9dd05344a61a4631cc69e0974378df8f6263af0337 basi6a08.png +7fdd6bf08f04692bcf06b5c4262e7f76c49d8adb992789fd3f05aa0435645cd8 basi6a16.png +c8b1364d7771dd2f5a1b2d7d633abcf3f48dafee608558ecd2e5fc98f61894cd basn0g01.png +ca172e92d179c77b3d321ad501e452a59bdaafafde8ebd74fd0669c4eae58efc basn0g02.png +fb2d42c4c8f5c51590e675994a9b0c718fbf71c80e28142f231cfa7c5b0e26e8 basn0g04.png +268d061075d1dd2eeec62b31303d09f6998549e1bfb447a5f09c80a2b0978ac3 basn0g08.png +1a1fe155f40c11d79350b3f84c7eb2b29719037e57073cb7ae2ab9e8323f9360 basn0g16.png +c90e86090a625661b19960cafdde6e347d6e32d73837aaae533f66dd3f099506 basn2c08.png +1e1c28ec0ee5da6224404b4005076dd30e2335a1a80c0ca722046a245c4a2b3b basn2c16.png +c2d7cd682df5f74506b33a5d70c344aaee248fda79fdfef8e873426fd6f2b75b basn3p01.png +0466bb7ed9984cf03b70704564bcffab1df8ec0e8167473ba0f75e4fedce5a8f basn3p02.png +e1fc7be978d3149b98533d0076245ae64353b7967290f4204c1282ecb4ec1aba basn3p04.png +d58256cd2eb16b5740d4c1403d25ce43d8dd03e270627ab709d2fb141e3d904c basn3p08.png +7be24b618bfd437b921ae0caf9341d112338c6290cc62466deb19d2c7a512968 basn4a08.png +1c92ffd11d2fc89a36f170d0239668436407f5c8e3f8d93483fb3fc6bca361d7 basn4a16.png +559c594166eb156f461c9beff0f053196730dc998fdb0d2b801c89e6680860a5 basn6a08.png +8f9d81060aebf4576461403c5057de7f23f73157016b659402b906df805845aa basn6a16.png +dfae01a4548e30519157bb51ce29d4de3b35b74288e9568b4d5911de01c6048b bgai4a08.png +ef7df23ccd912309a4f89ca3c3094bf5ab55add25218e571e51cc6cb11cfad9e bgai4a16.png +559c594166eb156f461c9beff0f053196730dc998fdb0d2b801c89e6680860a5 bgan6a08.png +8f9d81060aebf4576461403c5057de7f23f73157016b659402b906df805845aa bgan6a16.png +71d041df5c8949ce07d5e93b3c9f752cefc75ef7326c49df05ae73915f1a755f bgbn4a08.png +c45de44d3442bd33072d68456541b10e0cc57c5d8bfc809208995d939091eb2d bggn4a16.png +2da3c3efa01bf166958852a104ece92daaede8ffb5e0452a55d40526258a8bf5 bgwn6a08.png +875bc2b44a4355551c51260def9664da68be1af8c14b82f76173aaf01ddb1929 bgyn6a16.png +c88909e74e039dd3df829bf24144b487171e53b17f5c5c07cbc08688247d24b5 ccwn2c08.png +dc365b39d49c287669d837872dd59aef30763a611dfc8c046c481e35e49a390a ccwn3p08.png +438018f19c85e582cb586ac7cca2220008ecb7fc70ce50e8f2a76b494c128a20 cdfn2c08.png +a068eaf1f7040490e08eda3259befb6689849dd0ff8bb4cc03c705d117cb2b9f cdhn2c08.png +ee08dfa303a3c09171280fc1821180dc0a4c3591af7e9077e8ce0435642c76d2 cdsn2c08.png +a849d89ba3d92146940d7c56d2fe74c9c3ec96725c7f24eefaf44160a6304de2 cdun2c08.png +587a8624228d3f605f475bd751a1f3a97f0bbab590c0ff518bce5da3abcb6f2b ch1n3p04.png +e3cace549047c6e5e693b9b135d53f7f9ca5b1088bf30cc408634598ba53758a ch2n3p08.png +79ccaf4abe5091e1f65f8a61496363ed3312ebb9ea1aaa98affadac3d98507de cm0n0g04.png +127bb50d224ac3ebff36160482a03b9e6686072e86c8ff4cd43e3ce2271b2315 cm7n0g04.png +774b384d0ad73698e7d93fc5a29976b332c619045e5966276c609b11459a4152 cm9n0g04.png +bc812de2b83abc9ae2a6d1ae01e91f9090214b9ed8fee1d56cdfea58f4f259d0 cs3n2c16.png +267104dced0858dd828cdd41edc0e87042c7094c77191565192a67045064b23f cs3n3p08.png +028fa49fbba3954c2eba27a4c3607196e87c1dae74192df3b3ad7afe5e0a3f0c cs5n2c08.png +a7a4021983d6b22685529cbafb65cd087c9e1af1c5d205c2e13e3efc4ae87b6a cs5n3p08.png +d90ddab7313e4e1fd7f20f16a6c546b449697fbcac1a7776298a74896f4662da cs8n2c08.png +5bffdb88e307a851f8e85b137a69c59e557a881db816e990061934c0155c894c cs8n3p08.png +081d1ec26b4157fbc032b76dc716321420f2d032a425de046557c7842766826d ct0n0g04.png +259116f8ecf849d83d824688eb02b4575aed11980f02ab6fb123281c25a6459d ct1n0g04.png +4583e63d1bdfa18b6abb47439dee9a73bed311ed1b0a71d22bed75fe4767832b cten0g04.png +d0607280c3539a8934c5cfd22788b382cdc31321cdedc75ae8a29e3948580ba6 ctfn0g04.png +5f4c87f5a8f589d029a908050880ac5d6aed3810e55e75444802d6d3fb27cf33 ctgn0g04.png +8ef799e59871755578e563c5b411bc3895c2f7112c115aaa921b6c04fe255bf2 cthn0g04.png +ca91332ecc04e5faac1f39ca4df4996b072a93f3e574e7f4b50d52aafbfe67b6 ctjn0g04.png +c0765e635a6423ec64f0314400c3df20745c4a4469ffcc323c7b00ba66b4aceb ctzn0g04.png +d04140d74bc60597c47b5aac371a3553d3add9354437bbd8c57007d94e197809 exif2c08.png +d055cc0bb505b37c6ecf88a808d71675eca5dd0ee683d70ebc9c0be0e1bb8e57 f00n0g08.png +0fe92b2aa2da04c885d1dbd85c834716f6cdd946364d97dcd597bb79d9e14427 f00n2c08.png +956ddaf133e6d9a8d36f1e00604d87fbc2d0295e933bb8caaef517e7d87e5342 f01n0g08.png +ef072ec6815ebf9b33e0553d2e4e4e7ed6911860a2512c67bcd10a9f0f09b9de f01n2c08.png +1f5b49c06ecc2a1756f0423b3de936bd18497866d035ac8eded78a6f17408a2c f02n0g08.png +ca4b937b3c587d5c007f193a2eec14dc96b0d23ff7d6aa9004e3badd1af9fe8f f02n2c08.png +d0563ae30c6ce7a01eae7a5cdc0ef780175bfa7653888ed93f17bef5fe4b2107 f03n0g08.png +2d101e3ef4f78a69437034671e93fe11faac0cfc4d44210dcca1b944caa886f7 f03n2c08.png +fec1a3c53833d0ddefa4486a98934c393cb4335b2dc31da70e6540a4686f1457 f04n0g08.png +c365c24153cb69fd3c162f00b296ae23a71a1595645d1aeb0ad23af680d7b4be f04n2c08.png +8ac0f095d2a943157e820fa121bccde08d5230af1b5830c3041d5f4da3524eba f99n0g04.png +3494b914dd1b094afa9a74a89bfa75219030e21af6fca3ed66c9d45032a047e9 g03n0g16.png +abce774b9624952c2d0c57ff681790ba620cf5616fe7e0ef0600600cdce3c22a g03n2c08.png +541389db0c72721c6c49501e1dbf6e32df41b4fcfa318676955e278f3f4332b3 g03n3p04.png +72350a2d9db2df09b626f1f1dd48061e9c749d471bf19814d2c5c10acbf007e5 g04n0g16.png +bfd3edfc4d85a43383556a51023533fa3888184aa53a6b43769910782beebfce g04n2c08.png +5ea85ebefb58b2ab113fc05bf1cb79ffb068359e3a5620843590a0a7b59bd49a g04n3p04.png +be19721d28e0b268af1e29e8190c952b94315bd08899383ae2c91e6dc8c4f889 g05n0g16.png +74ab5b8477992d65e220eeaff8df466522c1b392fa90c6f9935da5bdb7113c9d g05n2c08.png +2f46afd7ec15836b523cbce6965f34d89833b8d777afffaf0f53bce620d5f65e g05n3p04.png +9070f843981f765cc8e26a63751be5d58631d85a8a7b4e826358f80e8a679d03 g07n0g16.png +ca4cd32d222f65fb7beb7c9f40d8b6833b36d552b830ff1a1d67dae73b8ed0d8 g07n2c08.png +b8e7abeabcfd50b71cca78b6cdff7372310cfc179cd63304c3e904f469b333cb g07n3p04.png +a22486acb74ee5f947db3a20b1f314a9dd8aca3339840049ee559f4d676a6b5c g10n0g16.png +4ac23729aea109e8f6b1e831448115cf02dcd97559e9403847cbe6dd7e5c7347 g10n2c08.png +36cc2ea4b5b33cd18e0a01c7de85dbcaf7161d258cd0f2265a90cd835b15cf6d g10n3p04.png +1fae707d809296d2cf0d6aa653bead6199644fb1c859558ec7d2d69e709a423a g25n0g16.png +9b128cfa1bb417dd99251914d729062621fcea9f346168549b16a75fe030b0f6 g25n2c08.png +4197a0a25c4f74d42c2285d75b9fabe1eedbed45bc224ff1ec1784f5797e9dbf g25n3p04.png +1a1fe155f40c11d79350b3f84c7eb2b29719037e57073cb7ae2ab9e8323f9360 oi1n0g16.png +1e1c28ec0ee5da6224404b4005076dd30e2335a1a80c0ca722046a245c4a2b3b oi1n2c16.png +142bc4b1e9f8a9e3b0ba3d2c2025e485bf7e76df88f914bf8c9041b4562cc080 oi2n0g16.png +2c523f138e0ade1bed8f31d59ec0f34b82660b192d6af8b8f395f82b9ba9dabb oi2n2c16.png +aa2d77723ba44f654a41a2ab97e01271fe942fecd2f299c0a81da90acb2887ac oi4n0g16.png +661220a0ed03ca6d63ec8dcaac738d4a9fd089b491c40dd896267ffb6cf5015d oi4n2c16.png +ae70c9effd0d9957a0d42771bc987529a1f3715e068057fae63f0c7e50d5c53a oi9n0g16.png +fef98e9bebe6c4046c29f2568f7a735305c8661aa01f9c37a718135e5bc4f941 oi9n2c16.png +72406b6173ec20dd059e8cea594ef5bc8f81bac5e416e2b53058d2debd51d195 pp0n2c16.png +d5a6f964a601a5e1815525117c12c32b61e2aa09fd6040776d35f2f7115b7110 pp0n6a08.png +b321b9ac8f2aa641475b6936365954181726dcb8662dbf641284d82a83cc22a5 ps1n0g08.png +6c59d673032fe2d04dbd2ea91cc9bc7bebe7d5ab84911f00e36fb28994793576 ps1n2c16.png +bd2ae1b45fd771aaa8c57dccd183f3834fc9742f6dfc692606865049efb116e5 ps2n0g08.png +120c62ce9d014f7772c4b38a446991b5bbe6a22ef5ea59239d32e023bc167585 ps2n2c16.png +235eb82f1337e3fcefbdca566a53af3d3523db7588ba3cd7fa5dab19afe48a41 s01i3p01.png +6a4f6da9fe36d195219ad2beeac1a0423e2ee6de03dfb064a3b6fa31623eb230 s01n3p01.png +e7d26ab4b31e7066b0674a4374c093967a9f1761b96836aa3dbe624acd73ab52 s02i3p01.png +f4b324f2b1d013ee77f632e42129c7cd3eca55da846e775e744a1f224ad1efcd s02n3p01.png +4513dec80f54ffd04a28834b114254d6e6d66e52e32e0059174474f2fb15d6bc s03i3p01.png +4dee297bd7f747f87488509af11a1e1e0531fa67e6e8d0f8ab7f4df7940f0ff3 s03n3p01.png +918f94f3557e10de91efa680df507c8eafc347fa5023af43037701398128ad0f s04i3p01.png +e73c52f764b684ec5133cce11f7f18cc60065acdd308e2c3d871e0a792a1080e s04n3p01.png +77fe040e17167f9656afe46cf0031832e635745e4e7f19ba12dee32f5ec03d96 s05i3p02.png +1b9e244a5c1d6cc9830391fff4eac565ada026d000e60faf7525c8add6bdc726 s05n3p02.png +cf8d5fdb34c0afd38b1b4745bed6167771767ccdfe847c4d8766f7fcc5c41176 s06i3p02.png +5caabfc4b147fad5e49e558143faaab91888324240acf45e5db8fc49f7a7f667 s06n3p02.png +d9874bfad10353a9ea2876ee388c3e7f81f697ed141d0d79c5c2019d62a7a698 s07i3p02.png +e7d447394f5fa64c27353216af387352a77a1fb534922a2d974e60d965d4e414 s07n3p02.png +62adf855c6b1e3a007f9dcf3ce2ba244616c089269a511dd939e89a4b0853453 s08i3p02.png +544fdd476e566e8aef4c98604124ae05acef48be20d1aebb9b6674b08b2abbb6 s08n3p02.png +f2cf5b3109690704d106a0b22ea079e36064cc6077e1fb9a1ba87397d0bbcca1 s09i3p02.png +6be8f58b638e7f7114750f5796f66f650db8fb7242a36183850f02117f4eaa65 s09n3p02.png +a27e0dbf923ef868e7399560b76c23a50b2d8926cddd9775e2bc4e050273f205 s32i3p04.png +c80d9fc7ded0b7834ec11d0e324540c7be74016b61bc302a1d167218fa35fbf9 s32n3p04.png +cc6ad98dcf686d92f1165d951f90fac70e568cedb1fcbba33e8890d0e6cdad4d s33i3p04.png +998d08e084e3eea288984475bfed0d48ee2d8250e20b96755898b59152e36a34 s33n3p04.png +83eb2e82eb14ae3c608833ef371a6f472c4c6e63b7e9f4f92f5472f975793b97 s34i3p04.png +a25451168c0b03ab8f52dcc60c6b9c12bc5df5d55afabe1892b87d0a856bb4a0 s34n3p04.png +db5988c27ad577de1e494cb50229dc2772678531adde2db84493907eae003e54 s35i3p04.png +cd99fc4cc69bda1ff8e8697d8b423ae8d9e84a58ba1d2b480751953b6869e3b3 s35n3p04.png +a36b40927b730a31d60c7818fb4a32e67ace06393cdaa26edc09520b6cee066d s36i3p04.png +ebc08f6a1e0918c5d3a9a08e184c23019a3cf90d8843e4b71bf2ae16040b1a84 s36n3p04.png +565c79404c4b9e46c27edb2f93d7b26b93ec0a0481ab7a21fc405152a21f53ba s37i3p04.png +964078b1f3f472268b8ac97a8976b4d1cdb6a47e6243d67eddcb0205e65b9f61 s37n3p04.png +b107f120ffaffcb949ac4547e0f91555ac681f78c7e68c724e7ceddfd8e5387b s38i3p04.png +045b0f5ea35874741bf6cac40f2e63ec8726450ab241475df4b7e9303c39e339 s38n3p04.png +4b5a6d8c04c8c70e1de3bcb6f7b5cc3ba359b13e28de6f52e21a291d4bc8a937 s39i3p04.png +2115b6cad0140ea97fe6ec056b47307ef1e8b5c00db5f08707a0572b165e5f08 s39n3p04.png +48a3f19b5c3b2f7eca17fd34765a2a3e385d770f24c357bc66bd74417eb60a5a s40i3p04.png +c4598ea73b1ec015bef7dcfd7f67bc7bfc41546619953d1a92cd9b8657a7033a s40n3p04.png +c5e7eeaffa677bfac002ee968a0423e0fea3be7701d39ccd6a015df1d2d85e40 tbbn0g04.png +8fcfd031a5b716201854fdab25691feed6cd3ed7b713a51b94e1f43fc63fe0c1 tbbn2c16.png +8eb43a6020fda8ed7c8c9b88b974ef794ee8452db29212ae7e5c11003bfd76a3 tbbn3p08.png +49711ee271f96099521b83b75d58ed2f76d42ed46cb3c06656fde2cad697cf59 tbgn2c16.png +6f798628935a021fe446dce3d62861d1f7369aaf01bad10daa4917c5abccad7d tbgn3p08.png +8223d8b0c5f84b149f0c1f0e1f658346e07fcbd03ffc02b2e9eeea1481eb19bf tbrn2c08.png +01e86f108b244bdee4d72e384aced8a62369965ca2993ee6ef88f131c647f7d1 tbwn0g16.png +978b28cec43bd219517083b63661bb30a7b9cdf9fd4476ab4e70844565980d51 tbwn3p08.png +7b4eb64b4bd7eb36417752873ddaca027ce77a07f474b2af569f4eea1e984111 tbyn3p08.png +f05e317f64a038123faf96fdbd6fc3ab3eec14e1fc1eb87fd7da4d996be63526 tm3n3p02.png +a253e055d8cd94049cd95e9392e7aa60f3d5c922a8f0cccb84762b0c5f547545 tp0n0g08.png +5dced3fde56b950e61ce86f4ad54458336f66389ce8ca68524d4fd8ec546ff5b tp0n2c08.png +da40ddb18bd45db32ed03dc89e2250b096d808efe975a88477e4f5a91a4677c9 tp0n3p08.png +50bc927fe6cf1816454a7c27f8c743734be8db45e37e5ee3ede540f4e895e6c5 tp1n3p08.png +4059f7e6a1c5bac1801f70e09f9ec1e1297dcdce34055c13ab2703d6d9613c7e xc1n0g08.png +e252a0e7df3e794e52ce4a831edafef76e7043d0d8d84019db0f7fd0b30e20f4 xc9n2c08.png +3c0c2a68dd416a7be79400e0e2ceb358ba3191d5309d4bad9dd04b32ff6d5b60 xcrn0g04.png +71e4b2826f61556eda39f3a93c8769b14d3ac90f135177b9373061199dbef39a xcsn0g01.png +c1287690808e809dc5d4fb89d8a7fd69ed93521f290abd42021ca00a061a1ba4 xd0n2c08.png +00b53c3bbd0641454521b982bc6f6bcfda7c91f1874cefb3a9bac37d80a1a269 xd3n2c08.png +16e5b40fb2600db1af20fb79ff715c2869255e2d4bef20702f16534e5dd6a847 xd9n2c08.png +f9d1fb2a708703518368c392c74765a6e3e5b49dbb9717df3974452291032df9 xdtn0g01.png +318864720c8fc0dbe4884035f2183cc3bd3d92ec60d447879982942600e9fe2e xhdn0g08.png +968fd21abb8acf40fbca90676de3abcb3a6e35b01ba7a3b9190184eafb99c83d xlfn0g04.png +776701227c7094dd10b78f508430b8ea4f03471d072096382cbcca628dea1d2b xs1n0g01.png +9dd7e93ba9211f0caee09d8f12e37742936c469f45fcad21e577c9f0640cf99e xs2n0g01.png +166c8633d116d1c26631cb98f3a75340cf4385fa7ae6a67913bc78e709bcb30d xs4n0g01.png +7a380568beeac969908196ac89cd2347c96ac2f26fdc2b8e0314b62c59f0e308 xs7n0g01.png +e4767d3259e1b331c9ece9fb07fc30f385879ac12b3cd0e1cb923f3bfac81dcf z00n2c08.png +939abfc6e0a3e349bb5bcd8c4e427a6cdb2c7e0c23a773aefa1c4fc9f07e4cb4 z03n2c08.png +21652fe42f472acd83dcb207806add5737db0020b21d6b38b0a00be3e9e37990 z06n2c08.png +98d90a7e61aa1a9ac9d99af44dd25c70cd5a7b4a11a85da60f82923e18a78f9f z09n2c08.png diff --git a/crates/image-codecs/tests/it/png_jpeg.rs b/crates/image-codecs/tests/it/png_jpeg.rs index 98a134121..38b40a674 100644 --- a/crates/image-codecs/tests/it/png_jpeg.rs +++ b/crates/image-codecs/tests/it/png_jpeg.rs @@ -490,37 +490,103 @@ fn png_rows_fail_like_decode_on_damaged_files() { } // --------------------------------------------------------------------------- -// PngSuite corpus (repo-root corpus/pngsuite/*.png; feature `corpus`, fetched by -// `cargo xtask corpus --all`; missing = failure) +// PngSuite corpus (repo-root corpus/pngsuite/; feature `corpus`). The tests read the PNGs that +// tests/it/common/pngsuite.tsv lists, each checked against its SHA-256 first; a missing or changed +// listed file fails the test, and an unlisted file is not read. // --------------------------------------------------------------------------- #[cfg(feature = "corpus")] #[test] fn pngsuite_corpus_matches_oracle() { - let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../corpus/pngsuite"); - let Ok(entries) = std::fs::read_dir(&dir) else { - panic!("{} is missing: run `cargo xtask corpus --all`", dir.display()); - }; let mut checked = 0; - for e in entries.flatten() { - let p = e.path(); - if p.extension().and_then(|s| s.to_str()) != Some("png") { - continue; - } - let bytes = std::fs::read(&p).unwrap(); + for (name, bytes) in common::pngsuite::pngs() { let oracle = image::load_from_memory_with_format(&bytes, image::ImageFormat::Png); let ours = decode(&bytes); match (ours, oracle) { (Ok(a), Ok(b)) => { - assert_eq!(a.to_rgba16(), b.into_rgba16().into_raw(), "{}", p.display()); + assert_eq!(a.to_rgba16(), b.into_rgba16().into_raw(), "{name}"); checked += 1; } - (Err(e), Ok(_)) => panic!("{}: we failed but oracle decoded: {e}", p.display()), + (Err(e), Ok(_)) => panic!("{name}: we failed but oracle decoded: {e}"), _ => {} } } eprintln!("pngsuite: {checked} files compared"); - assert!(checked > 100, "{}: only {checked} PNGs compared: run `cargo xtask corpus --all`", dir.display()); + assert!(checked > 100, "only {checked} PNGs compared"); +} + +/// The pinned list names the 178 files of the 2017 archive and `LICENSE`, a copy of the archive's +/// `PngSuite.LICENSE` with the same SHA-256: 179 names, 176 of them PNGs, every name once. +#[test] +fn pngsuite_manifest_lists_the_whole_suite() { + use common::pngsuite::{MANIFEST, parse}; + let rows = parse(MANIFEST).unwrap(); + assert_eq!(rows.len(), 179); + assert_eq!(rows.keys().filter(|n| n.ends_with(".png")).count(), 176); + assert_eq!(rows["LICENSE"], rows["PngSuite.LICENSE"]); + for name in ["PngSuite.README", "PngSuite.png", "basn0g01.png", "xs7n0g01.png", "z09n2c08.png"] { + assert!(rows.contains_key(name), "{name}"); + } + assert_eq!(MANIFEST.lines().filter(|l| l.starts_with('#')).count(), 7); +} + +/// A row with a bad digest, a path, a hidden name or a repeated name is refused, and so is a list +/// with no rows. Extra columns, blank lines and comments are accepted. +#[test] +fn pngsuite_manifest_refuses_bad_rows() { + use common::pngsuite::parse; + let d = "a".repeat(64); + assert_eq!(parse(&format!("# note\n\n{d}\tx.png\tCC0-1.0\thttps://example.com/x.png\n")).unwrap().len(), 1); + for bad in [ + format!("{d}\tx.png\n{d}\tx.png\n"), + format!("{d}\t../x.png\n"), + format!("{d}\tdir/x.png\n"), + format!("{d}\tdir\\x.png\n"), + format!("{d}\t.x.png\n"), + format!("{d}\t\n"), + format!("{d} x.png\n"), + format!("{}\tx.png\n", "a".repeat(63)), + format!("{}\tx.png\n", "A".repeat(64)), + format!("{}\tx.png\n", "g".repeat(64)), + "# only a comment\n".to_string(), + String::new(), + ] { + assert!(parse(&bad).is_err(), "{bad:?}"); + } +} + +/// The corpus reader returns every listed PNG with its bytes and nothing else: an unlisted PNG in +/// the folder is not read, and a listed PNG that is missing, changed or not a regular file fails. +#[test] +fn pngsuite_reader_takes_only_listed_files_that_match() { + use common::pngsuite::{pinned_pngs, sha256_hex}; + let dir = std::env::temp_dir().join(format!("craft-image-codecs-pngsuite-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + let a = encode(&synth(5, 4, ChannelLayout::Rgb, SampleType::U8, 1, 0.5), Format::Png, &EncodeOptions::default()).unwrap(); + let b = encode(&synth(3, 7, ChannelLayout::Gray, SampleType::U16, 2, 0.5), Format::Png, &EncodeOptions::default()).unwrap(); + std::fs::write(dir.join("a.png"), &a).unwrap(); + std::fs::write(dir.join("b.png"), &b).unwrap(); + std::fs::write(dir.join("unlisted.png"), &a).unwrap(); + let manifest = format!("# test\n{}\ta.png\n{}\tb.png\n{}\tnotes.txt\n", sha256_hex(&a), sha256_hex(&b), "0".repeat(64)); + + let got = pinned_pngs(&dir, &manifest).unwrap(); + assert_eq!(got, vec![("a.png".to_string(), a.clone()), ("b.png".to_string(), b.clone())]); + + let mut changed = b.clone(); + let last = changed.len() - 1; + changed[last] ^= 1; + std::fs::write(dir.join("b.png"), &changed).unwrap(); + let err = pinned_pngs(&dir, &manifest).unwrap_err(); + assert!(err.contains("b.png") && err.contains("does not match"), "{err}"); + std::fs::write(dir.join("b.png"), &b).unwrap(); + + std::fs::remove_file(dir.join("a.png")).unwrap(); + assert!(pinned_pngs(&dir, &manifest).unwrap_err().contains("a.png")); + std::fs::create_dir(dir.join("a.png")).unwrap(); + assert!(pinned_pngs(&dir, &manifest).unwrap_err().contains("regular file")); + + std::fs::remove_dir_all(&dir).unwrap(); } /// The preflight charges the decoded layout's bytes per pixel: a 1000×1000 Gray8 PNG (1 MB) fits a @@ -539,21 +605,12 @@ fn png_preflight_uses_the_output_layout() { #[cfg(feature = "corpus")] #[test] fn png_rows_equal_decode_on_the_pngsuite_corpus() { - let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../corpus/pngsuite"); - let Ok(entries) = std::fs::read_dir(&dir) else { - panic!("{} is missing: run `cargo xtask corpus --all`", dir.display()); - }; let mut checked = 0; - for e in entries.flatten() { - let p = e.path(); - if p.extension().and_then(|s| s.to_str()) != Some("png") { - continue; - } - let bytes = std::fs::read(&p).unwrap(); - assert_steps_equal_decode(&bytes, &p.display().to_string()); + for (name, bytes) in common::pngsuite::pngs() { + assert_steps_equal_decode(&bytes, &name); checked += 1; } - assert!(checked > 100, "{}: only {checked} PNGs compared: run `cargo xtask corpus --all`", dir.display()); + assert!(checked > 100, "only {checked} PNGs compared"); } /// Row-by-row decoding gives `decode`'s pixels and metadata for every PngSuite file it takes (all @@ -561,18 +618,9 @@ fn png_rows_equal_decode_on_the_pngsuite_corpus() { #[cfg(feature = "corpus")] #[test] fn pngsuite_corpus_rows_match_the_whole_decode() { - let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../corpus/pngsuite"); - let Ok(entries) = std::fs::read_dir(&dir) else { - panic!("{} is missing: run `cargo xtask corpus --all`", dir.display()); - }; let opts = DecodeOptions { keep_orientation: true, ..Default::default() }; let (mut streamed, mut refused, mut skipped) = (0, 0, 0); - for e in entries.flatten() { - let p = e.path(); - if p.extension().and_then(|s| s.to_str()) != Some("png") { - continue; - } - let bytes = std::fs::read(&p).unwrap(); + for (name, bytes) in common::pngsuite::pngs() { // The importer only streams files `detect` takes for PNG. if detect(&bytes) != Some(Format::Png) { skipped += 1; @@ -596,24 +644,23 @@ fn pngsuite_corpus_rows_match_the_whole_decode() { match (whole, rows) { (Ok(img), Ok(Some(x))) => { let h = header.unwrap(); - assert_eq!((img.width(), img.height(), img.layout(), img.sample_type()), (h.width, h.height, h.layout, h.sample), "{}", p.display()); - assert!(img.data() == data, "{}: pixels", p.display()); + assert_eq!((img.width(), img.height(), img.layout(), img.sample_type()), (h.width, h.height, h.layout, h.sample), "{name}"); + assert!(img.data() == data, "{name}: pixels"); assert_eq!( (&img.icc, &img.meta.exif, &img.meta.text, &img.meta.xmp, &img.warnings), (&x.icc, &x.meta.exif, &x.meta.text, &x.meta.xmp, &x.warnings), - "{}", - p.display() + "{name}" ); - assert_eq!(img.meta.dpi, x.meta.dpi, "{}", p.display()); + assert_eq!(img.meta.dpi, x.meta.dpi, "{name}"); streamed += 1; } (Ok(_), Ok(None)) => refused += 1, - (Err(a), Err(b)) => assert_eq!(a.to_string(), b.to_string(), "{}", p.display()), - (a, b) => panic!("{}: whole {:?}, rows {:?}", p.display(), a.map(|_| ()), b.map(|r| r.map(|_| ()))), + (Err(a), Err(b)) => assert_eq!(a.to_string(), b.to_string(), "{name}"), + (a, b) => panic!("{name}: whole {:?}, rows {:?}", a.map(|_| ()), b.map(|r| r.map(|_| ()))), } } eprintln!("pngsuite: {streamed} streamed, {refused} refused (interlaced), {skipped} skipped (not detected as PNG)"); - assert!(streamed > 100, "only {streamed} PNGs streamed: run `cargo xtask corpus --all`"); + assert!(streamed > 100, "only {streamed} PNGs streamed"); } /// Streaming a PNG's rows a group at a time gives the pixels and metadata `decode` gives, holds diff --git a/crates/keymap/src/ui/view.rs b/crates/keymap/src/ui/view.rs index 6922d0aca..53ce22a85 100644 --- a/crates/keymap/src/ui/view.rs +++ b/crates/keymap/src/ui/view.rs @@ -426,7 +426,7 @@ impl Draw<'_, '_> { .inner .labelled_by(label.id); self.tag(|| format!("shortcuts.{salt}"), r.rect, title); - if natural > width { r.on_hover_text(full) } else { r } + r } fn filter_combo(&mut self, ui: &mut Ui) { 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}") { diff --git a/crates/media-testkit/Cargo.toml b/crates/media-testkit/Cargo.toml index 827d2ae6b..d69a88bf1 100644 --- a/crates/media-testkit/Cargo.toml +++ b/crates/media-testkit/Cargo.toml @@ -8,5 +8,8 @@ rust-version.workspace = true repository.workspace = true publish = false +[dependencies] +craft-testkit = { workspace = true } + [lints] workspace = true diff --git a/crates/media-testkit/src/hostile.rs b/crates/media-testkit/src/hostile.rs index 1051d0405..f40021986 100644 --- a/crates/media-testkit/src/hostile.rs +++ b/crates/media-testkit/src/hostile.rs @@ -1,89 +1,26 @@ -//! Deterministic hostile-input hammer: truncations, bit flips and extreme-value overwrites of a -//! valid seed, each run under `catch_unwind` with a time budget. No dependencies, no `unsafe`. +//! Deterministic hostile-input hammer, from [`craft_testkit::hostile`]: [`hammer`] runs a parser on +//! a valid seed, every truncation of it and seeded damage of it, one case after another on a worker +//! thread with a time limit for each case. [`Rng`], [`mutations`] and the other names here are +//! `craft_testkit`'s. -use std::fmt::Write as _; -use std::panic::{AssertUnwindSafe, catch_unwind}; -use std::time::{Duration, Instant}; +#[cfg(not(target_arch = "wasm32"))] +pub use craft_testkit::hostile::{HammerConfig, HammerError}; +pub use craft_testkit::hostile::{MAX_CASES, Mutation, Mutations, Rng, mutations}; -/// xorshift64* PRNG. -pub struct Rng(pub u64); +/// The variable that multiplies [`hammer`]'s iterations. +#[cfg(not(target_arch = "wasm32"))] +const MULTIPLIER_VARIABLE: &str = "CRAFT_MEDIA_HOSTILE_MULT"; -impl Rng { - /// The next value. - pub fn next_u64(&mut self) -> u64 { - self.0 ^= self.0 >> 12; - self.0 ^= self.0 << 25; - self.0 ^= self.0 >> 27; - self.0.wrapping_mul(0x2545_F491_4F6C_DD1D) - } - /// A value below `n` (0 for `n` = 0). - pub fn below(&mut self, n: usize) -> usize { - (self.next_u64() % n.max(1) as u64) as usize - } -} - -const EXTREMES: [u64; 8] = [0, 1, 0x7F, 0x80, 0xFF, 0xFFFF, 0x8000_0000, u64::MAX]; - -fn run_one(name: &str, what: &str, data: &[u8], run: &dyn Fn(&[u8])) { - let t = Instant::now(); - let r = catch_unwind(AssertUnwindSafe(|| run(data))); - let el = t.elapsed(); - assert!(r.is_ok(), "{name}: PANIC on {what} (len {})", data.len()); - assert!(el < Duration::from_secs(5), "{name}: HANG/slow ({el:?}) on {what} (len {})", data.len()); -} - -/// Run `run` over every truncation of `seed` (stepped beyond 4096 lengths), then `iters` random -/// mutations (bit flips, random bytes, 1/2/4/8-byte extreme-value overwrites in both -/// endiannesses, deletions, truncation). Panics, naming the mutation, on the first panic or on -/// a run slower than 5 s. -pub fn hammer(name: &str, seed: &[u8], iters: usize, run: impl Fn(&[u8])) { - run_one(name, "the unmodified seed", seed, &run); - let step = (seed.len() / 4096).max(1); - for n in (0..seed.len()).step_by(step) { - run_one(name, &format!("truncation to {n}"), &seed[..n], &run); - } - let mut rng = Rng((0x5EED_F00D ^ seed.len() as u64) | 1); - // CRAFT_MEDIA_HOSTILE_MULT=10 runs ten times the iterations (soak runs). - let mult = std::env::var("CRAFT_MEDIA_HOSTILE_MULT").ok().and_then(|v| v.parse::().ok()).unwrap_or(1); - for _ in 0..iters.saturating_mul(mult) { - let mut d = seed.to_vec(); - let mut what = String::new(); - for _ in 0..1 + rng.below(4) { - if d.is_empty() { - break; - } - let pos = rng.below(d.len()); - match rng.below(7) { - 0 => { - let b = rng.below(8); - d[pos] ^= 1 << b; - let _ = write!(what, "flip[{pos}].{b} "); - } - 1 => { - d[pos] = rng.next_u64() as u8; - let _ = write!(what, "set[{pos}]={:#x} ", d[pos]); - } - 2..=4 => { - let w = [1usize, 2, 4, 8][rng.below(4)]; - let v = EXTREMES[rng.below(EXTREMES.len())]; - let be = rng.below(2) == 0; - let bytes = if be { v.to_be_bytes()[8 - w..].to_vec() } else { v.to_le_bytes()[..w].to_vec() }; - let end = (pos + w).min(d.len()); - d[pos..end].copy_from_slice(&bytes[..end - pos]); - let _ = write!(what, "put{w}{}[{pos}]={v:#x} ", if be { "be" } else { "le" }); - } - 5 => { - let n = 1 + rng.below(16); - let end = (pos + n).min(d.len()); - d.drain(pos..end); - let _ = write!(what, "del[{pos}..{end}] "); - } - _ => { - d.truncate(pos); - let _ = write!(what, "trunc{pos} "); - } - } - } - run_one(name, &what, &d, &run); - } +/// Run `run` over `seed`, every truncation of it, then `iters` random mutations (bit flips, random +/// bytes, 1/2/4/8-byte extreme-value overwrites in both endiannesses, deletions, truncation). The +/// cases run on a worker thread with a limit of 5 s each, which `CRAFT_TEST_TIMEOUT_SECS` replaces. +/// Panics on the first case that panics or does not finish, naming `name`, the case, its length and +/// the panic's message. +/// +/// `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times the iterations (soak runs). A value that is not a +/// whole number above zero panics, naming the variable, before `run` is called. +#[cfg(not(target_arch = "wasm32"))] +#[track_caller] +pub fn hammer(name: &str, seed: &[u8], iters: usize, run: impl Fn(&[u8]) + Send + Sync + 'static) { + craft_testkit::hostile::hammer(&HammerConfig::new(name, iters).with_multiplier_variable(MULTIPLIER_VARIABLE), seed, run); } diff --git a/crates/media-testkit/src/lib.rs b/crates/media-testkit/src/lib.rs index 6d3a75525..4eba224e0 100644 --- a/crates/media-testkit/src/lib.rs +++ b/crates/media-testkit/src/lib.rs @@ -11,8 +11,9 @@ //! Fixtures are generated into `$CRAFT_MEDIA_FIXTURES_DIR` or `/target/fixtures`, one //! directory per crate or format, and never committed. //! -//! [`hostile::hammer`] runs a parser over truncations and mutations of a valid input and fails on -//! a panic or a slow run; `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times the iterations. +//! [`hostile::hammer`] runs a parser over every truncation and mutations of a valid input and fails +//! on a panic or a case that does not finish in time; `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times +//! the iterations. It and [`with_deadline`] call `craft_testkit`. //! //! Failing loudly is what a test helper is for: a wrong `CRAFT_MEDIA_*` setting or an unwritable //! fixture directory panics, which fails the test that asked. @@ -216,35 +217,19 @@ pub fn set_progress(label: &str) { eprintln!("PROGRESS: {label}"); } -/// Run closure with an execution deadline, terminating with a panic if the limit is exceeded. -#[allow(clippy::panic)] +/// Run closure with an execution deadline of `secs` seconds, which `CRAFT_TEST_TIMEOUT_SECS` +/// replaces, through [`craft_testkit::with_deadline`]. Panics when the closure does not finish in +/// time, when `secs` is zero, or when the variable is not a whole number of seconds above zero. +#[cfg(not(target_arch = "wasm32"))] +#[track_caller] pub fn with_deadline(secs: u64, f: F) { - let timeout_secs = std::env::var("CRAFT_TEST_TIMEOUT_SECS").ok().and_then(|s| s.parse().ok()).unwrap_or(secs); - with_timeout(timeout_secs, f); + with_limit(craft_testkit::DeadlineLimit::new(std::time::Duration::from_secs(secs)), f); } -#[allow(clippy::panic)] -fn with_timeout(timeout_secs: u64, f: F) { - let (tx, rx) = std::sync::mpsc::channel(); - let handle = std::thread::spawn(move || { - f(); - let _ = tx.send(()); - }); - match rx.recv_timeout(std::time::Duration::from_secs(timeout_secs)) { - Ok(()) => { - if let Err(payload) = handle.join() { - std::panic::resume_unwind(payload); - } - } - Err(std::sync::mpsc::RecvTimeoutError::Timeout) => { - panic!("test exceeded execution deadline of {timeout_secs} seconds"); - } - Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => { - if let Err(payload) = handle.join() { - std::panic::resume_unwind(payload); - } - } - } +#[cfg(not(target_arch = "wasm32"))] +#[track_caller] +fn with_limit(limit: craft_testkit::DeadlineLimit<'_>, f: F) { + craft_testkit::with_deadline(limit, "the test body", f); } /// Return fixture directory for a crate/category, creating it if needed. @@ -339,10 +324,31 @@ Encoders: } #[test] - #[should_panic(expected = "test exceeded execution deadline")] + #[should_panic(expected = "the test body did not finish within 1s")] fn with_deadline_times_out() { - with_timeout(1, || { - std::thread::sleep(std::time::Duration::from_secs(3)); + let (_keep, rx) = std::sync::mpsc::channel::<()>(); + let limit = craft_testkit::DeadlineLimit::new(std::time::Duration::from_secs(1)).with_variable("CRAFT_MEDIA_TESTKIT_UNSET_IN_TESTS"); + with_limit(limit, move || { + let _ = rx.recv(); }); } + + #[test] + #[should_panic(expected = "the default limit is zero")] + fn with_deadline_of_zero_fails() { + with_deadline(0, || {}); + } + + #[test] + fn with_deadline_names_a_bad_timeout_variable() { + let out = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "tests::with_deadline_completes", "--nocapture", "--test-threads=1"]) + .env("CRAFT_TEST_TIMEOUT_SECS", "soon") + .output() + .unwrap(); + let printed = format!("{}{}", String::from_utf8_lossy(&out.stdout), String::from_utf8_lossy(&out.stderr)); + assert!(printed.contains("running 1 test"), "the child did not run the test:\n{printed}"); + assert!(!out.status.success(), "the child passed:\n{printed}"); + assert!(printed.contains(r#"CRAFT_TEST_TIMEOUT_SECS="soon" is not a whole number of seconds"#), "{printed}"); + } } diff --git a/crates/media-testkit/tests/hostile.rs b/crates/media-testkit/tests/hostile.rs new file mode 100644 index 000000000..8e34cd5af --- /dev/null +++ b/crates/media-testkit/tests/hostile.rs @@ -0,0 +1,93 @@ +//! `hostile::hammer` as the media crates' tests call it. + +use std::collections::BTreeSet; +use std::process::Command; +use std::sync::{Arc, Mutex}; +use std::time::Duration; + +use craft_media_testkit::hostile::hammer; + +/// Set only in the child processes of `run_child`: the value names what `child_hammer` does. +const CHILD_VARIABLE: &str = "CRAFT_MEDIA_TESTKIT_HOSTILE_CHILD"; + +/// Overrides the two-minute limit on each child process of `run_child`. The limit does not read +/// `CRAFT_TEST_TIMEOUT_SECS`, which `a_hang_fails_at_the_deadline` sets for the child. +const WATCHDOG_VARIABLE: &str = "CRAFT_MEDIA_TESTKIT_CHILD_WATCHDOG_SECS"; + +/// Runs `child_hammer` in a child process with `vars` set, and returns what it printed. The child +/// must fail. A child that never returns fails the test after two minutes. +fn run_child(vars: &'static [(&'static str, &'static str)]) -> String { + let limit = craft_testkit::DeadlineLimit::new(Duration::from_secs(120)).with_variable(WATCHDOG_VARIABLE); + craft_testkit::with_deadline(limit, "the child test", move || { + let out = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "child_hammer", "--nocapture", "--test-threads=1"]) + .envs(vars.iter().copied()) + .output() + .unwrap(); + let printed = format!("{}{}", String::from_utf8_lossy(&out.stdout), String::from_utf8_lossy(&out.stderr)); + assert!(printed.contains("running 1 test"), "the child did not run the test:\n{printed}"); + assert!(!out.status.success(), "the child passed:\n{printed}"); + printed + }) +} + +/// Runs in the child processes of `run_child`. Without `CHILD_VARIABLE` it hammers a small seed and +/// passes; with `hang`, its parser never returns. +#[test] +fn child_hammer() { + if std::env::var_os(CHILD_VARIABLE).is_some_and(|v| v == "hang") { + hammer("hang", &[1, 2, 3], 0, |_| { + loop { + std::thread::park(); + } + }); + } else { + hammer("small", &[1, 2, 3], 10, |_| {}); + } +} + +#[test] +fn a_hang_fails_at_the_deadline() { + let printed = run_child(&[(CHILD_VARIABLE, "hang"), ("CRAFT_TEST_TIMEOUT_SECS", "1")]); + assert!(printed.contains("hang: the unmodified seed (len 3) did not finish within 1s, set by CRAFT_TEST_TIMEOUT_SECS"), "{printed}"); +} + +#[test] +fn a_bad_multiplier_names_the_variable() { + let printed = run_child(&[("CRAFT_MEDIA_HOSTILE_MULT", "ten")]); + assert!(printed.contains(r#"small: CRAFT_MEDIA_HOSTILE_MULT="ten" is not a whole number written in digits"#), "{printed}"); +} + +#[test] +fn a_panic_keeps_its_message() { + let payload = std::panic::catch_unwind(|| hammer("demo", &[9, 8, 7, 6], 0, |d| assert!(d.len() != 2, "boom at {}", d.len()))).unwrap_err(); + let message = payload.downcast_ref::().cloned().unwrap_or_default(); + assert!(message.starts_with("demo: truncation to 2 (len 2): the parser panicked: "), "{message}"); + assert!(message.contains("boom at 2"), "{message}"); +} + +#[test] +fn every_truncation_of_a_large_seed_runs() { + let seed: Vec = (0..8_192u32).map(|i| i as u8).collect(); + let lengths = Arc::new(Mutex::new(BTreeSet::new())); + let record = Arc::clone(&lengths); + hammer("large", &seed, 0, move |d| { + record.lock().unwrap().insert(d.len()); + }); + // The seed and its 8,192 truncations. + assert_eq!(lengths.lock().unwrap().len(), 8_193); +} + +#[test] +fn the_child_timeout_variable_does_not_set_the_watchdog() { + // `a_hang_fails_at_the_deadline` sets `CRAFT_TEST_TIMEOUT_SECS` for its child. Run it with a value + // that `with_deadline` rejects; it passes only if `run_child`'s watchdog reads another variable. + let out = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "a_hang_fails_at_the_deadline", "--nocapture", "--test-threads=1"]) + .env("CRAFT_TEST_TIMEOUT_SECS", "not a number") + .output() + .unwrap(); + let printed = format!("{}{}", String::from_utf8_lossy(&out.stdout), String::from_utf8_lossy(&out.stderr)); + assert!(printed.contains("running 1 test"), "the test did not run:\n{printed}"); + assert!(out.status.success(), "{printed}"); +} diff --git a/crates/media/src/mpegts/tests/hostile.rs b/crates/media/src/mpegts/tests/hostile.rs index ff1784fc8..97bba47d0 100644 --- a/crates/media/src/mpegts/tests/hostile.rs +++ b/crates/media/src/mpegts/tests/hostile.rs @@ -89,7 +89,8 @@ fn elementary_stream_frame_parsers_never_panic() { ac3.extend([1u8; 60]); let seeds = [adts_frame(3), mp2_frame(1), ac3, mpeg2_frame(1, 0, false, 64), vec![0x56, 0xE0, 0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70, 0x80]]; for (i, s) in seeds.iter().enumerate() { - craft_media_testkit::hostile::hammer(&format!("es seed {i}"), s, 40_000, |d| { + let codecs = codecs.clone(); + craft_media_testkit::hostile::hammer(&format!("es seed {i}"), s, 40_000, move |d| { for c in &codecs { let _ = frame_bytes(c, d); let _ = frame_info(c, d); diff --git a/crates/mesh/Cargo.toml b/crates/mesh/Cargo.toml index 861c19239..ef860114f 100644 --- a/crates/mesh/Cargo.toml +++ b/crates/mesh/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "craft-mesh" -description = "3D mesh file formats behind one neutral model: STL, Wavefront OBJ/MTL, PLY and glTF 2.0 / GLB readers and writers and FBX and 3MF readers, bounded on hostile input" +description = "3D mesh file formats behind one neutral model: STL and Wavefront OBJ/MTL readers and writers, a glTF 2.0 / GLB reader and GLB writer, and PLY, FBX and 3MF readers, bounded on hostile input" version.workspace = true edition.workspace = true license.workspace = true diff --git a/crates/mesh/README.md b/crates/mesh/README.md index 3b57208fa..8c0cdec00 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, @@ -127,27 +127,17 @@ mutations of every byte of good files. | `max_vertices` | 20 000 000 | entries per attribute pool (OBJ: each of `v`, `vt`, `vn`, counting unused ones; glTF: vertices over all meshes; 3MF: vertices, colours and texture coordinates of the file together) | | `max_triangles` | 20 000 000 | triangles after fanning polygons, strips and fans | | `max_face_corners` | 4096 | corners of one face; PLY list lengths | -| `max_meshes` | 100 000 | OBJ objects, glTF meshes, 3MF objects | -| `max_parts` | 100 000 | groups, material runs, glTF primitives | +| `max_meshes` | 100 000 | OBJ objects, glTF meshes, 3MF objects, FBX meshes | +| `max_parts` | 100 000 | groups, material runs, glTF primitives, material slots of an FBX mesh | | `max_materials` | 100 000 | materials; images; OBJ material libraries; 3MF base materials and textures together | | `max_nodes` | 100 000 | nodes, and node visits when the hierarchy is walked (ends cycles); 3MF placed objects, build items and components | | `max_depth` | 64 | node nesting; 3MF component nesting (ends cycles) | -| `max_data_bytes` | 1 GiB | buffers and material libraries taken from the resolver; embedded image bytes; skin and animation values; the binary chunk `write_glb` builds; what a 3MF package inflates to, and its textures | +| `max_data_bytes` | 1 GiB | buffers and material libraries taken from the resolver; embedded image bytes; skin and animation values; the binary chunk `write_glb` builds; what a 3MF package inflates to, and its textures; an FBX file's meshes, image bytes and parsed values (binary: 8 bytes per array element, and other values are not counted; ASCII: `size_of::()` per value, each array element included, plus string bytes; record names and the overhead of records and their containers are not counted) | | `max_extras` | 10 000 | skins, animations, cameras, lights, buffers (each); channels of one animation | Fixed bounds: a PLY header of 1 MiB, 64 elements and 256 properties per element; 2^24 components -for glTF accessors without a buffer view, over the whole file; 10 000 parts in a 3MF package. -| `max_meshes` | 100 000 | OBJ objects, glTF meshes, FBX meshes | -| `max_parts` | 100 000 | groups, material runs, glTF primitives, material slots of an FBX mesh | -| `max_materials` | 100 000 | materials; images; OBJ material libraries | -| `max_nodes` | 100 000 | nodes, and node visits when the hierarchy is walked (ends cycles) | -| `max_depth` | 64 | node nesting | -| `max_data_bytes` | 1 GiB | buffers and material libraries taken from the resolver; embedded image bytes; skin and animation values; the binary chunk `write_glb` builds; everything an FBX file keeps (parsed values at 8 bytes per array element, meshes, image bytes) | -| `max_extras` | 10 000 | skins, animations, cameras, lights, buffers (each); channels of one animation | - -Fixed bounds: a PLY header of 1 MiB, 64 elements and 256 properties per element; 2^24 components -for glTF accessors without a buffer view, over the whole file; FBX records nested 64 deep and -arrays of 1 GiB. +for glTF accessors without a buffer view, over the whole file; 10 000 parts in a 3MF package; FBX +records nested 64 deep and arrays of 1 GiB. **External files.** No reader opens a file. A reader that needs another file to parse (an OBJ material library, a glTF buffer) asks the caller's `Resolver` for it by the name the file writes; diff --git a/crates/mesh/src/fbx.rs b/crates/mesh/src/fbx.rs index 5c7eaab42..054754ae3 100644 --- a/crates/mesh/src/fbx.rs +++ b/crates/mesh/src/fbx.rs @@ -41,9 +41,12 @@ //! //! Not read: FBX 5 and older, animation stacks, skin deformers, blend shapes, lights, NURBS and patches. //! -//! [`Limits::max_data_bytes`] bounds what one file may keep in memory: its parsed values (an -//! array element counts 8 bytes whatever its type in the file), the meshes built from them and -//! the image bytes. +//! [`Limits::max_data_bytes`] is the budget the reader charges for one file: its parsed values, +//! the meshes built from them and the image bytes. A binary file is charged 8 bytes per array +//! element whatever its type in the file; its scalar, string and raw values are not counted. An +//! ASCII file is charged `size_of::()` for every value, each array element included, plus +//! the bytes of its strings. Neither form is charged for record names or for the overhead of +//! records and their containers, so the reader keeps those even with a budget of 0. use std::cell::Cell; use std::collections::{HashMap, HashSet}; 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, }; 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()); + } +} diff --git a/crates/odf/src/text/body.rs b/crates/odf/src/text/body.rs index 1b2793258..565c0f764 100644 --- a/crates/odf/src/text/body.rs +++ b/crates/odf/src/text/body.rs @@ -106,6 +106,10 @@ pub(super) struct Body<'a> { depth: usize, /// The markup being read (`content.xml`), for keeping paragraphs' own (empty: none kept). pub(super) raw: &'a [u8], + /// The markup being read, body's or a header's, and where the start tag being read ends in it: + /// for looking into a picture before reading it (empty: not known). + pub(super) markup: &'a [u8], + pub(super) tag_end: usize, /// The paragraph whose markup is being kept (see [`KeptOpen`]). kept_open: Option, /// The body table whose markup is being kept (its `done`: the container's length before it). @@ -257,6 +261,8 @@ impl<'a> Body<'a> { skip: 0, depth: 0, raw: &[], + markup: &[], + tag_end: 0, kept_open: None, kept_table: None, kept_index: None, @@ -455,6 +461,7 @@ impl<'a> Body<'a> { /// whole and refers to nothing outside itself keeps its markup (`Para::kept`), so a save /// that doesn't change it writes it as it was (see `craft_wordmodel::kept`). pub(super) fn feed_at(&mut self, ev: Ev, at: (usize, usize)) { + self.tag_end = at.1; self.hide_read(); self.hidden_section(&ev); // A body index, kept whole: its settings and templates, which WordCraft writes its own. @@ -1468,10 +1475,33 @@ impl Body<'_> { } } + /// Whether the `draw:image` just started holds any text, read from its markup as the rest of + /// the file is read (`xml::holds_words`); `true` when the markup isn't known, so nothing in + /// it is skipped unread. + fn picture_holds_words(&self) -> bool { + let Some(before) = self.markup.get(..self.tag_end) else { return true }; + if before.is_empty() { + return true; + } + if before.ends_with(b"/>") { + return false; + } + super::xml::holds_words(self.markup, self.tag_end) + } + /// Part of a frame: its picture, embedded object, description or contour. fn frame_part(&mut self, q: &str, a: &Attrs) { match local(q) { "image" => { + // What a picture holds (§10.4.4 lets it hold text; LibreOffice writes an empty + // paragraph in one it draws as a shape, as it does every picture in a group) isn't + // the text's: read as a paragraph, it ended the one around the frame. An empty one + // isn't read. Words in one still are, as a paragraph of their own (which still ends + // the one around it): skipped, they'd be lost on the paragraph's first edit or a + // save to another format. + if q == "draw:image" && !self.picture_holds_words() { + self.skip = 1; + } // A chart's replacement picture (what readers that can't draw it show): kept with // the chart as read, written back with it while it is unchanged. if let Some(href) = get(a, "xlink:href") diff --git a/crates/odf/src/text/frames.rs b/crates/odf/src/text/frames.rs index 2a2beee2f..0ab079db7 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/import.rs b/crates/odf/src/text/import.rs index a438c10c5..8154875c7 100644 --- a/crates/odf/src/text/import.rs +++ b/crates/odf/src/text/import.rs @@ -940,6 +940,7 @@ fn parse_tracked(bytes: &[u8], paper: (f32, f32)) -> Result { (body.entries, body.manifest) = (objects.0, Some(objects.1)); body.raw = &content; + body.markup = &content; body.spaces_left = spaces_left; super::xml::events_at(&content, |ev, at| body.feed_at(ev, at)); let mut blocks = body.take_blocks(); diff --git a/crates/odf/src/text/package.rs b/crates/odf/src/text/package.rs index b435d7271..ab3dee9e1 100644 --- a/crates/odf/src/text/package.rs +++ b/crates/odf/src/text/package.rs @@ -1591,32 +1591,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/odf/src/text/page_parts.rs b/crates/odf/src/text/page_parts.rs index 6a67da3af..a484ae44d 100644 --- a/crates/odf/src/text/page_parts.rs +++ b/crates/odf/src/text/page_parts.rs @@ -4,7 +4,8 @@ use std::collections::HashSet; use craft_wordmodel::{Document, PartKind}; -use super::{Body, Ev, FBlock, Pages, SectionProps, Styles, events, get, model}; +use super::xml::events_at; +use super::{Body, Ev, FBlock, Pages, SectionProps, Styles, get, model}; /// Most XML events kept for all headers and footers together; a slot past it is left out. const MAX_EVENTS: usize = 1 << 20; @@ -79,13 +80,13 @@ pub(super) fn read( objects: (&[String], &std::collections::HashMap), spaces_left: &mut usize, ) -> Parts { - let mut found: Vec<(String, Slot, Vec)> = Vec::new(); + let mut found: Vec<(String, Slot, Vec<(Ev, usize)>)> = Vec::new(); let mut master: Option = None; // The slot being read, its nesting depth and whether it is kept. let mut slot: Option<(usize, bool)> = None; let mut seen = HashSet::new(); let mut room = MAX_EVENTS; - events(xml, |ev| { + events_at(xml, |ev, at| { if let Some((depth, keep)) = &mut slot { match &ev { Ev::End(_) if *depth == 0 => { @@ -102,7 +103,7 @@ pub(super) fn read( } if *keep && let Some((.., evs)) = found.last_mut() { room -= 1; - evs.push(ev); + evs.push((ev, at.1)); } return; } @@ -130,7 +131,9 @@ pub(super) fn read( reader.in_text = true; (reader.entries, reader.manifest) = (objects.0, Some(objects.1)); reader.spaces_left = *spaces_left; - for ev in evs { + reader.markup = xml; + for (ev, end) in evs { + reader.tag_end = end; reader.feed(ev); } *spaces_left = reader.spaces_left; 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/kept.rs b/crates/odf/src/text/tests_more/kept.rs index 88d271142..2efbad997 100644 --- a/crates/odf/src/text/tests_more/kept.rs +++ b/crates/odf/src/text/tests_more/kept.rs @@ -159,6 +159,170 @@ fn a_file_a_kept_definition_names_is_written_with_it() { assert!(m.contains(r#"manifest:full-path="Pictures/paper.png""#), "{m}"); } +/// A picture as LibreOffice writes one it draws as a shape: a frame with a text style, and in its +/// `draw:image` an empty paragraph (ODF 1.3 §10.4.4 lets a picture hold text). +const SHAPE_PICTURE: &str = r#""#; +const AFTER_PICTURE: &str = r#"Text after it."#; + +/// A package whose text is `body`, with the styles and the picture [`SHAPE_PICTURE`] names. +fn shape_picture_doc(body: &str) -> (Vec, Vec) { + let png = [b"\x89PNG\r\n\x1a\n".as_slice(), &[5u8; 64]].concat(); + let content = format!( + r#"{body}"# + ); + (crate::text::tests::zip_of(&[("content.xml", content.as_bytes()), ("Pictures/x.png", &png)]), png) +} + +#[test] +fn a_picture_holding_an_empty_paragraph_stays_in_its_own() { + let first = format!(r#"{SHAPE_PICTURE}"#); + let (pkg, png) = shape_picture_doc(&format!("{first}{AFTER_PICTURE}")); + let d = import(&pkg).unwrap(); + // Two paragraphs, as written: the picture in the first, the text in the second. The picture's + // own paragraph used to end the one around it, and the picture joined the next one. + assert_eq!(d.body.len(), 2); + let (a, b) = (d.body[0].as_para().unwrap(), d.body[1].as_para().unwrap()); + assert_eq!(a.objects.len(), 1, "the picture is in the first paragraph"); + assert!(b.objects.is_empty()); + assert_eq!(b.text, "Text after it."); + + let saved = export(&d).unwrap(); + let c = content_of(&saved); + assert!(c.contains(&format!("{first}\n{AFTER_PICTURE}")), "as read: {c}"); + for def in [r#"style:name="P1""#, r#"style:name="P2""#, r#"style:name="gr1""#] { + assert!(c.contains(def), "{def}: {c}"); + } + let mut z = zip::ZipArchive::new(std::io::Cursor::new(saved.clone())).unwrap(); + let mut got = Vec::new(); + std::io::Read::read_to_end(&mut z.by_name("Pictures/x.png").unwrap(), &mut got).unwrap(); + assert_eq!(got, png); + // Saved again, still as read. + assert!(content_of(&export(&import(&saved).unwrap()).unwrap()).contains(&format!("{first}\n{AFTER_PICTURE}"))); +} + +#[test] +fn a_grouped_picture_holding_an_empty_paragraph_stays_in_its_own() { + // LibreOffice writes every picture in a group this way. + let member = SHAPE_PICTURE.replace(r#" text:anchor-type="paragraph" draw:z-index="0""#, ""); + let first = format!( + r#"{member}"# + ); + let (pkg, _) = shape_picture_doc(&format!("{first}{AFTER_PICTURE}")); + let d = import(&pkg).unwrap(); + assert_eq!(d.body.len(), 2); + assert_eq!(d.body[0].as_para().unwrap().objects.len(), 1, "the group is in the first paragraph"); + assert_eq!(d.body[1].as_para().unwrap().text, "Text after it."); + let c = content_of(&export(&d).unwrap()); + assert!(c.contains(&format!("{first}\n{AFTER_PICTURE}")), "{c}"); +} + +#[test] +fn a_picture_holding_a_paragraph_in_a_cell_or_a_text_box_stays_in_its_own() { + let inner = format!(r#"Before {SHAPE_PICTURE} after."#); + let cell = + format!(r#"{inner}"#); + let boxed = format!( + r#"{inner}"# + ); + let (pkg, _) = shape_picture_doc(&format!("{cell}{boxed}")); + let d = import(&pkg).unwrap(); + let craft_wordmodel::Block::Table(t) = &*d.body[0] else { panic!("a table: {:?}", d.body[0]) }; + let in_cell = &t.rows[0].cells[0].blocks; + assert_eq!(in_cell.len(), 1); + assert_eq!(in_cell[0].as_para().unwrap().text, "Before \u{FFFC} after."); + let saved = content_of(&export(&d).unwrap()); + assert_eq!(saved.matches(inner.as_str()).count(), 2, "as read: {saved}"); +} + +/// All the text of `blocks`, paragraph by paragraph. +fn texts(blocks: &[std::sync::Arc]) -> Vec { + blocks.iter().filter_map(|b| b.as_para()).map(|p| p.text.clone()).collect() +} + +#[test] +fn words_in_a_picture_are_not_lost() { + // LibreOffice draws them on the picture. Skipped like an empty paragraph, they were only in the + // paragraph's markup as read: gone once the paragraph was edited, or saved to another format. + let held = SHAPE_PICTURE.replace("", r#"Words on it"#); + let first = format!(r#"{held}"#); + let (pkg, _) = shape_picture_doc(&format!("{first}{AFTER_PICTURE}")); + let mut d = import(&pkg).unwrap(); + assert!(texts(&d.body).iter().any(|t| t.contains("Words on it")), "{:?}", texts(&d.body)); + assert!(d.plain_text(craft_wordmodel::StoryRef::Body).contains("Words on it")); + d.kept.clear(); + assert!(content_of(&export(&d).unwrap()).contains("Words on it")); +} + +#[test] +fn a_picture_in_a_header_holding_an_empty_paragraph_stays_in_its_own_and_words_stay() { + let header = |held: &str| { + let styles = format!( + r#"Head {held} line"# + ); + let png = [b"\x89PNG\r\n\x1a\n".as_slice(), &[5u8; 64]].concat(); + let content = format!( + r#"Body"# + ); + let pkg = crate::text::tests::zip_of(&[("content.xml", content.as_bytes()), ("styles.xml", styles.as_bytes()), ("Pictures/x.png", &png)]); + let d = import(&pkg).unwrap(); + let part = d.parts.values().find(|p| p.kind == craft_wordmodel::PartKind::Header).expect("a header"); + texts(&part.blocks) + }; + // An empty paragraph in the picture doesn't end the header's. + assert_eq!(header(SHAPE_PICTURE), vec!["Head \u{FFFC} line".to_string()]); + // Words in one are read. + let held = SHAPE_PICTURE.replace("", "Words on it"); + assert!(header(&held).iter().any(|t| t.contains("Words on it")), "{:?}", header(&held)); +} + +/// The paragraphs of a document whose first paragraph holds [`SHAPE_PICTURE`] with `inside` in +/// place of its empty paragraph, followed by [`AFTER_PICTURE`]. +fn with_in_picture(inside: &str) -> craft_wordmodel::Document { + let held = SHAPE_PICTURE.replace("", inside); + let (pkg, _) = shape_picture_doc(&format!(r#"A {held} B{AFTER_PICTURE}"#)); + import(&pkg).unwrap() +} + +#[test] +fn words_in_a_picture_written_as_cdata_or_after_a_comment_are_not_lost() { + // Read as the parser reads them, not as the bytes look: CDATA is text, and a comment naming + // the picture's end doesn't end it. + for inside in ["", "Words on it"] { + let mut d = with_in_picture(inside); + assert!(texts(&d.body).iter().any(|t| t.contains("Words on it")), "{inside}: {:?}", texts(&d.body)); + assert!(d.plain_text(craft_wordmodel::StoryRef::Body).contains("Words on it"), "{inside}"); + d.kept.clear(); + assert!(content_of(&export(&d).unwrap()).contains("Words on it"), "{inside}"); + } +} + +#[test] +fn an_empty_picture_with_a_greater_than_sign_in_its_markup_stays_in_its_own() { + // A `>` in an attribute or a comment isn't a word. + for inside in [r#""#, "", ""] { + let d = with_in_picture(inside); + assert_eq!(texts(&d.body), ["A \u{FFFC} B", "Text after it."], "{inside}"); + } +} + +#[test] +fn many_pictures_without_their_ends_are_read_in_linear_time() { + // Each picture's contents are looked at only so far: a picture whose end is far off, or never + // comes, isn't looked through to the end of the file once for every picture. + let run = |n: usize| { + let stray = "".repeat(n); + let open = "".repeat(n); + let (pkg, _) = shape_picture_doc(&format!( + r#"{stray}{open}"# + )); + let t = std::time::Instant::now(); + assert!(import(&pkg).is_ok()); + t.elapsed() + }; + let took = run(20_000); + assert!(took.as_secs_f32() < 3.0, "{took:?}"); +} + #[test] fn the_files_font_declarations_are_kept() { // A reader without a font picks its substitute by how the file declares it. WordCraft's own 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 115dd9b02..8d7576acc 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/odf/src/text/xml.rs b/crates/odf/src/text/xml.rs index 706056270..d0e80e60b 100644 --- a/crates/odf/src/text/xml.rs +++ b/crates/odf/src/text/xml.rs @@ -35,6 +35,16 @@ pub(super) enum Ev { Text(String), } +/// No limit but the input's own size (each part is at most a package entry). +const LIMITS: craft_xml::Limits = craft_xml::Limits { + max_input: usize::MAX, + max_depth: usize::MAX, + max_nodes: usize::MAX, + max_elements: usize::MAX, + max_attrs: usize::MAX, + max_attrs_total: usize::MAX, +}; + /// Stream XML events (empty elements become start + end). Malformed XML ends the stream. pub(super) fn events(xml: &[u8], mut f: impl FnMut(Ev)) { events_at(xml, |ev, _| f(ev)); @@ -43,17 +53,8 @@ pub(super) fn events(xml: &[u8], mut f: impl FnMut(Ev)) { /// [`events`], each with the byte range of `xml` its markup takes (an empty element's start /// and end both take the whole element). pub(super) fn events_at(xml: &[u8], mut f: impl FnMut(Ev, (usize, usize))) { - // Names and attributes as written; no limit but the input's own size (each part is at most a - // package entry), and at most 128 attributes kept per element. - let limits = craft_xml::Limits { - max_input: usize::MAX, - max_depth: usize::MAX, - max_nodes: usize::MAX, - max_elements: usize::MAX, - max_attrs: usize::MAX, - max_attrs_total: usize::MAX, - }; - let opts = craft_xml::Options::default().with_limits(limits); + // Names and attributes as written, and at most 128 attributes kept per element. + let opts = craft_xml::Options::default().with_limits(LIMITS); let mut events = opts.events(xml); // Malformed XML ends the stream. while let Ok(Some(ev)) = events.next() { @@ -71,6 +72,58 @@ pub(super) fn events_at(xml: &[u8], mut f: impl FnMut(Ev, (usize, usize))) { } } +/// Most events, and bytes, [`holds_words`] looks at: an element still open past them counts as +/// holding words (an empty one LibreOffice writes is a handful of events). +const LOOK_EVENTS: usize = 64; +const LOOK_BYTES: usize = 4096; + +/// Whether the element whose start tag ends at `from` in `xml` holds any words before its end, +/// read as [`events`] reads them: text, CDATA or a reference that isn't only whitespace (comments +/// and processing instructions hold none). Any end at its own depth ends it, as in [`events`]. +/// `true` when that can't be told within [`LOOK_EVENTS`] events and [`LOOK_BYTES`] bytes, or +/// the markup is malformed, so nothing in it is taken for empty unread. +pub(super) fn holds_words(xml: &[u8], from: usize) -> bool { + let Some(rest) = xml.get(from..from.saturating_add(LOOK_BYTES).min(xml.len())) else { return true }; + // The reader skips an end tag with nothing open, so the contents are read inside a stand-in + // start tag, which the element's own end (any end at its depth) closes. + const OPEN: &[u8] = b"<_>"; + let mut wrapped = Vec::with_capacity(OPEN.len().saturating_add(rest.len())); + wrapped.extend_from_slice(OPEN); + wrapped.extend_from_slice(rest); + // An unknown entity is an error rather than left out, so that it counts as words. + let opts = craft_xml::Options { unknown_entity: craft_xml::UnknownEntity::Error, ..craft_xml::Options::default().with_limits(LIMITS) }; + let mut r = opts.events(&wrapped); + if !matches!(r.next(), Ok(Some(craft_xml::Event::Start { .. }))) { + return true; + } + let mut depth = 0usize; + let mut looked = 0usize; + // An empty element's start and end are one piece of markup (one span): counted once. + let mut last = 0..0; + while looked < LOOK_EVENTS { + let ev = match r.next() { + Ok(Some(ev)) => ev, + Ok(None) | Err(_) => return true, + }; + let span = r.span(); + if span != last { + looked = looked.saturating_add(1); + } + let markup = wrapped.get(span.clone()).unwrap_or_default(); + last = span; + match ev { + craft_xml::Event::Start { .. } => depth = depth.saturating_add(1), + craft_xml::Event::End { .. } if depth == 0 => return false, + craft_xml::Event::End { .. } => depth = depth.saturating_sub(1), + // A reference, resolved: words whatever it stands for. + craft_xml::Event::Text(_) if markup.starts_with(b"&") => return true, + craft_xml::Event::Text(t) | craft_xml::Event::CData(t) if t.bytes().any(|b| !b.is_ascii_whitespace()) => return true, + _ => {} + } + } + true +} + /// Rewrite only the first interpreted draw:z-index value in each start tag. /// Event spans exclude comments/CDATA and retain the reader's first-128-attribute /// policy. All bytes outside changed values (including unknown markup) survive. diff --git a/crates/ods/README.md b/crates/ods/README.md index eb255349a..0246578b7 100644 --- a/crates/ods/README.md +++ b/crates/ods/README.md @@ -35,3 +35,9 @@ expanded; blank padding past the grid's edge is clipped, data past it is an erro `craft-xml`'s depth and attribute limits. At most 1024 tables. `Options::only_sheet` keeps one sheet's cells and lists the others by name. + +`Options::truncate_text` keeps the cells read before the text passes `max_text`, leaves out +every cell after that point and sets `Workbook::text_truncated`, so the caller can warn instead +of failing. Rows and cells after the cell that passes it are not read. The one-cell limit still +applies to every cell read, that cell included; the cell and merged-range limits count the cells +kept. diff --git a/crates/ods/src/content.rs b/crates/ods/src/content.rs index b8e2e2ab9..c4d5e252a 100644 --- a/crates/ods/src/content.rs +++ b/crates/ods/src/content.rs @@ -187,15 +187,17 @@ impl Import<'_> { let name = self.attr(attrs, "table:name")?.unwrap_or_default(); self.sheet = Some(SheetDraft { sheet: Sheet { name, ..Sheet::default() }, depth, row: 0, keep }); } + // Once the text is cut short, nothing after it is kept: its rows and cells are not read. Tag::Row - if self - .sheet - .as_ref() - .is_some_and(|s| s.keep && self.stack.get(s.depth + 1..).is_some_and(|p| p.iter().all(|t| *t == Tag::Rows))) => + if !self.wb.text_truncated + && self + .sheet + .as_ref() + .is_some_and(|s| s.keep && self.stack.get(s.depth + 1..).is_some_and(|p| p.iter().all(|t| *t == Tag::Rows))) => { self.row = Some(RowDraft { depth, repeat: self.count(attrs, "table:number-rows-repeated", u32::MAX)?, col: 0, cells: vec![] }); } - Tag::Cell | Tag::Covered if self.row.as_ref().is_some_and(|r| depth == r.depth + 1) => { + Tag::Cell | Tag::Covered if !self.wb.text_truncated && self.row.as_ref().is_some_and(|r| depth == r.depth + 1) => { let value_type = if self.attr(attrs, "calcext:value-type")?.as_deref() == Some("error") { Some(ValueType::Error) } else { @@ -320,6 +322,24 @@ impl Import<'_> { Ok(()) } + /// With [`Options::truncate_text`], how many of `copies` copies of `each` bytes of text fit + /// in what is left of `max_text`; fewer than `copies` marks the workbook truncated, and none + /// fit once it is. + fn fit(&mut self, copies: u32, each: u64) -> u32 { + if self.wb.text_truncated { + return 0; + } + if each == 0 { + return copies; + } + let room = self.options.max_text.saturating_sub(self.text) / each; + if room < u64::from(copies) { + self.wb.text_truncated = true; + return u32::try_from(room).unwrap_or(0); + } + copies + } + fn charge_text(&mut self, bytes: u64) -> Result<(), Error> { self.text = self.text.saturating_add(bytes); if self.text > self.options.max_text { @@ -342,9 +362,13 @@ impl Import<'_> { row.col = end; if kept { let len = draft.cell.text.len() + draft.cell.raw.as_ref().map_or(0, String::len); - self.charge_text(u64::from(draft.repeat).saturating_mul(len as u64))?; + let repeat = if self.options.truncate_text { self.fit(draft.repeat, len as u64) } else { draft.repeat }; + if repeat == 0 { + return Ok(()); + } + self.charge_text(u64::from(repeat).saturating_mul(len as u64))?; if let Some(row) = self.row.as_mut() { - row.cells.push(RepeatedCell { col: start, repeat: draft.repeat, width, height, cell: draft.cell }); + row.cells.push(RepeatedCell { col: start, repeat, width, height, cell: draft.cell }); } } Ok(()) @@ -360,44 +384,71 @@ impl Import<'_> { }; let first_row = sheet.row; sheet.row = end; - for entry in row.cells { - let count = u64::from(entry.repeat) * u64::from(row.repeat); - if !entry.cell.is_blank() { - self.cells = self.cells.saturating_add(count); - let len = entry.cell.text.len() + entry.cell.raw.as_ref().map_or(0, String::len); - // The first row's copies were charged with the cell. - self.text = self.text.saturating_add(count.saturating_sub(u64::from(entry.repeat)).saturating_mul(len as u64)); + // The first copy of the row was charged cell by cell. With truncation, keep the further + // copies whose text fits, then the cells of the next copy that fit. + let row_repeat = row.repeat; + let mut partial = vec![]; + let repeat = if self.options.truncate_text && row.repeat > 1 && !self.wb.text_truncated { + let each = row.cells.iter().map(|e| u64::from(e.repeat).saturating_mul(charged(&e.cell))).fold(0u64, u64::saturating_add); + let full = 1 + self.fit(row.repeat - 1, each); + if full < row.repeat { + let room = self.options.max_text.saturating_sub(self.text).saturating_sub(each.saturating_mul(u64::from(full - 1))); + partial = cells_that_fit(&row.cells, room); } - let merged = entry.width > 1 || entry.height > 1; - if merged { - self.merges = self.merges.saturating_add(count); + full + } else if self.options.truncate_text && self.wb.text_truncated { + 1 + } else { + row.repeat + }; + let kept_end = first_row.saturating_add(repeat).min(end); + // The first copy's text was charged in `finish_cell`; the partial copy's was not. + for (cells, rows, first_charged) in [(row.cells, first_row..kept_end, true), (partial, kept_end..kept_end + 1, false)] { + for entry in cells { + self.place(&entry, rows.clone(), first_charged, end, row_repeat)?; } - if self.cells > self.options.max_cells || self.merges > self.options.max_merges || self.text > self.options.max_text { - return Err(Error::TooLarge(format!( - "more than {} cells, {} merged ranges or {} MiB of text", - self.options.max_cells, - self.options.max_merges, - self.options.max_text >> 20 - ))); - } - let last_col = entry.col.checked_add(entry.repeat - 1).and_then(|c| c.checked_add(entry.width - 1)); - let last_row = end.checked_add(entry.height - 1); - if last_col.is_none_or(|c| c >= MAX_COLS) || last_row.is_none_or(|r| r > MAX_ROWS) { - return Err(Error::TooLarge("a merged cell reaches outside the grid".into())); - } - if merged && ((entry.repeat > 1 && entry.width > 1) || (row.repeat > 1 && entry.height > 1)) { - return Err(Error::Invalid("repeated cells have overlapping merges".into())); - } - let Some(sheet) = self.sheet.as_mut() else { return Ok(()) }; - for r in first_row..end { - for c in entry.col..entry.col + entry.repeat { - let at = CellRef::new(r, c); - if !entry.cell.is_blank() { - sheet.sheet.cells.insert(at, entry.cell.clone()); - } - if merged { - sheet.sheet.merges.push(Range::new(at, CellRef::new(r + entry.height - 1, c + entry.width - 1))); - } + } + Ok(()) + } + + /// Counts, checks and stores one cell entry over `rows`. + fn place(&mut self, entry: &RepeatedCell, rows: std::ops::Range, first_charged: bool, end: u32, row_repeat: u32) -> Result<(), Error> { + let count = u64::from(entry.repeat) * u64::from(rows.end.saturating_sub(rows.start)); + if !entry.cell.is_blank() { + self.cells = self.cells.saturating_add(count); + // The first row's copies were charged with the cell. + let copies = if first_charged { count.saturating_sub(u64::from(entry.repeat)) } else { count }; + self.text = self.text.saturating_add(copies.saturating_mul(charged(&entry.cell))); + } + let merged = entry.width > 1 || entry.height > 1; + if merged { + self.merges = self.merges.saturating_add(count); + } + if self.cells > self.options.max_cells || self.merges > self.options.max_merges || self.text > self.options.max_text { + return Err(Error::TooLarge(format!( + "more than {} cells, {} merged ranges or {} MiB of text", + self.options.max_cells, + self.options.max_merges, + self.options.max_text >> 20 + ))); + } + let last_col = entry.col.checked_add(entry.repeat - 1).and_then(|c| c.checked_add(entry.width - 1)); + let last_row = end.checked_add(entry.height - 1); + if last_col.is_none_or(|c| c >= MAX_COLS) || last_row.is_none_or(|r| r > MAX_ROWS) { + return Err(Error::TooLarge("a merged cell reaches outside the grid".into())); + } + if merged && ((entry.repeat > 1 && entry.width > 1) || (row_repeat > 1 && entry.height > 1)) { + return Err(Error::Invalid("repeated cells have overlapping merges".into())); + } + let Some(sheet) = self.sheet.as_mut() else { return Ok(()) }; + for r in rows { + for c in entry.col..entry.col + entry.repeat { + let at = CellRef::new(r, c); + if !entry.cell.is_blank() { + sheet.sheet.cells.insert(at, entry.cell.clone()); + } + if merged { + sheet.sheet.merges.push(Range::new(at, CellRef::new(r + entry.height - 1, c + entry.width - 1))); } } } @@ -405,6 +456,30 @@ impl Import<'_> { } } +/// Bytes of text a kept cell is charged: its displayed text and its value attribute. +fn charged(cell: &Cell) -> u64 { + if cell.is_blank() { 0 } else { (cell.text.len() + cell.raw.as_ref().map_or(0, String::len)) as u64 } +} + +/// The leading entries of a row copy whose text fits in `room` bytes, the last one with only +/// the repeats that fit. +fn cells_that_fit(cells: &[RepeatedCell], mut room: u64) -> Vec { + let mut out = vec![]; + for e in cells { + let len = charged(&e.cell); + let n = room.checked_div(len).map_or(e.repeat, |fit| u32::try_from(fit).unwrap_or(u32::MAX).min(e.repeat)); + if n == 0 { + break; + } + room -= u64::from(n) * len; + out.push(RepeatedCell { col: e.col, repeat: n, width: e.width, height: e.height, cell: e.cell.clone() }); + if n < e.repeat { + break; + } + } + out +} + fn push_text(out: &mut String, text: &str, max: usize) -> Result<(), Error> { if out.len().saturating_add(text.len()) > max { return Err(Error::TooLarge(format!("a cell's text is longer than {max} bytes"))); diff --git a/crates/ods/src/lib.rs b/crates/ods/src/lib.rs index e96e22df2..c816905a9 100644 --- a/crates/ods/src/lib.rs +++ b/crates/ods/src/lib.rs @@ -19,7 +19,7 @@ //! //! ``` //! # fn main() -> Result<(), craft_ods::Error> { -//! # let bytes = craft_ods::testing::spreadsheet(r#"Tea"#); +//! # let bytes = craft_ods::testing::spreadsheet(r#"Tea"#)?; //! let book = craft_ods::read(&bytes, &craft_ods::Options::default())?; //! let sheet = &book.sheets[0]; //! assert_eq!(sheet.name, "Prices"); @@ -73,6 +73,11 @@ pub struct Options { pub max_merges: u64, /// Bytes of cell text, repeats expanded, over all sheets. pub max_text: u64, + /// When the text would pass `max_text`, keep the cells read before that point and stop + /// keeping cells, with [`Workbook::text_truncated`] set, instead of refusing the document. + /// Rows and cells after the cell that passes it are not read. `max_cell_text` still applies + /// to every cell read, that cell included; `max_cells` and `max_merges` count the cells kept. + pub truncate_text: bool, /// Bytes of one cell's text, and of one attribute value. pub max_cell_text: usize, /// Keep the cells of this sheet only (by position); the others are listed by name, empty. @@ -86,6 +91,7 @@ impl Default for Options { max_cells: 1_000_000, max_merges: 100_000, max_text: 64 << 20, + truncate_text: false, max_cell_text: 1 << 20, only_sheet: None, } diff --git a/crates/ods/src/model.rs b/crates/ods/src/model.rs index 5c0fb14d1..d9c428b9b 100644 --- a/crates/ods/src/model.rs +++ b/crates/ods/src/model.rs @@ -105,6 +105,9 @@ pub struct Sheet { #[derive(Clone, Debug, Default, PartialEq, Eq)] pub struct Workbook { pub sheets: Vec, + /// [`Options::truncate_text`](crate::Options::truncate_text) cut the text short: the cells + /// after the point where it passed `max_text` were left out. + pub text_truncated: bool, } fn digits(s: &str) -> Option<&str> { diff --git a/crates/ods/src/testing.rs b/crates/ods/src/testing.rs index a8a663d77..fb73d9d25 100644 --- a/crates/ods/src/testing.rs +++ b/crates/ods/src/testing.rs @@ -10,14 +10,39 @@ pub fn content(tables: &str) -> String { ) } -/// An `.ods` package around [`content`]. -pub fn spreadsheet(tables: &str) -> Vec { +/// An `.ods` package around [`content`]. A package that cannot be written returns the writer's +/// error. +pub fn spreadsheet(tables: &str) -> Result, craft_odf::Error> { package(content(tables).as_bytes()) } -/// An `.ods` package with this `content.xml`. -pub fn package(content: &[u8]) -> Vec { +/// An `.ods` package with this `content.xml`. A package that cannot be written returns the +/// writer's error. +pub fn package(content: &[u8]) -> Result, craft_odf::Error> { + files(&[("content.xml", content)]) +} + +/// An `.ods` package with these XML files, in order. +fn files(files: &[(&str, &[u8])]) -> Result, craft_odf::Error> { let mut w = craft_odf::PackageWriter::new(craft_odf::mime::SPREADSHEET); - w.file("content.xml", "text/xml", content); - w.finish().unwrap_or_default() + for (path, data) in files { + w.file(path, "text/xml", data); + } + w.finish() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_package_that_cannot_be_written_returns_the_writer_error() { + let xml = content(""); + let twice = files(&[("content.xml", xml.as_bytes()), ("content.xml", xml.as_bytes())]); + match twice { + Err(craft_odf::Error::Zip(message)) => assert!(message.contains("content.xml"), "{message}"), + other => panic!("expected the writer's error, got {other:?}"), + } + assert!(crate::is_ods(&package(xml.as_bytes()).unwrap())); + } } diff --git a/crates/ods/tests/read.rs b/crates/ods/tests/read.rs index e53b19e6b..530177b4c 100644 --- a/crates/ods/tests/read.rs +++ b/crates/ods/tests/read.rs @@ -5,7 +5,7 @@ use craft_ods::testing::{content, package, spreadsheet}; use craft_ods::{CellRef, Error, Options, Range, Sheet, Value, ValueType, Workbook, read}; fn ods(tables: &str) -> Vec { - spreadsheet(tables) + spreadsheet(tables).unwrap() } fn row(cells: &str) -> Vec { ods(&format!(r#"{cells}"#)) @@ -28,8 +28,8 @@ fn a_namespace_declaration_bomb_is_refused() { content(r#""#) .replacen("kept"#, )) @@ -166,7 +166,7 @@ fn bad_packages_encryption_and_bad_xml_are_refused() { let mut w = craft_odf::PackageWriter::new("application/zip"); w.file("content.xml", "text/xml", xml.as_bytes()); assert!(matches!(open(&w.finish().unwrap()), Err(Error::Invalid(_)))); - assert!(craft_ods::is_ods(&package(xml.as_bytes()))); + assert!(craft_ods::is_ods(&package(xml.as_bytes()).unwrap())); let mut w = craft_odf::PackageWriter::new(craft_odf::mime::SPREADSHEET); w.file("content.xml", "text/xml", xml.as_bytes()); if let Some(e) = w.manifest_mut().entries.iter_mut().find(|e| e.path == "content.xml") { @@ -182,10 +182,10 @@ fn bad_packages_encryption_and_bad_xml_are_refused() { xml.replace("Data", "&custom;"), content(""), ] { - assert!(open(&package(bad.as_bytes())).is_err(), "{bad}"); + assert!(open(&package(bad.as_bytes()).unwrap()).is_err(), "{bad}"); } let deep = content(&format!("{}{}", "".repeat(300), "".repeat(300))); - assert!(open(&package(deep.as_bytes())).is_err()); + assert!(open(&package(deep.as_bytes()).unwrap()).is_err()); } #[test] @@ -214,7 +214,7 @@ fn expansion_bounds_stop_small_repeat_bombs() { // One row of cells each just under the 1 MiB cell limit, past 64 MiB in all: refused while // the row is read. The row's end is never reached. let long = format!(r#""#, "x".repeat(1024 * 1024 - 1)); - let cells = package(content(&format!(r#"{}"#, long.repeat(65))).as_bytes()); + let cells = package(content(&format!(r#"{}"#, long.repeat(65))).as_bytes()).unwrap(); assert!(matches!(open(&cells), Err(Error::TooLarge(_)))); // A row repeated once more than its cells' text allows is refused, and one that fits reads. let cell = format!(r#""#, "y".repeat(1024)); @@ -240,6 +240,67 @@ fn expansion_bounds_stop_small_repeat_bombs() { )); } +#[test] +fn text_past_the_limit_can_be_cut_short_instead_of_refused() { + let cut = Options { truncate_text: true, ..Options::default() }; + // A repeated row past 64 MiB keeps the copies that fit. + let cell = format!(r#""#, "y".repeat(1024)); + let rows = + ods(&format!(r#"{cell}"#)); + assert!(matches!(open(&rows), Err(Error::TooLarge(_)))); + let wb = read(&rows, &cut).unwrap(); + assert!(wb.text_truncated); + assert_eq!(wb.sheets[0].cells.len(), 65_536); + assert!(wb.sheets[0].cells.contains_key(&CellRef::new(65_535, 0))); + assert!( + !open(&ods(&format!(r#"{cell}"#))).unwrap().text_truncated + ); + // Repeated columns keep the copies that fit, and nothing after them is kept: not a later + // cell that would fit, not the row's further copies, not later rows or sheets. + let small = Options { max_text: 10, ..cut }; + let bytes = ods(r#" + + + + + "#); + assert!(matches!(read(&bytes, &Options { max_text: 10, ..Options::default() }), Err(Error::TooLarge(_)))); + let wb = read(&bytes, &small).unwrap(); + assert!(wb.text_truncated); + assert_eq!(wb.sheets.iter().map(|s| s.name.as_str()).collect::>(), ["A", "B"]); + assert_eq!(wb.sheets[0].cells.keys().copied().collect::>(), [CellRef::new(0, 0), CellRef::new(0, 1)]); + assert_eq!(shown(&wb.sheets[0], CellRef::new(0, 1)), text("abcd")); + assert!(wb.sheets[0].merges.is_empty() && wb.sheets[1].cells.is_empty()); + // A repeated row keeps the cells of its next copy that fit. + let bytes = ods( + r#""#, + ); + let wb = read(&bytes, &Options { max_text: 12, ..cut }).unwrap(); + assert!(wb.text_truncated); + assert_eq!(wb.sheets[0].cells.keys().copied().collect::>(), [CellRef::new(0, 0), CellRef::new(0, 1), CellRef::new(1, 0)]); + // Cells after the cut are not read, so their own size limit does not refuse the document. + let small = Options { max_text: 4, max_cell_text: 10, ..cut }; + let bytes = ods(r#" + + more than ten bytes + "#); + assert!(matches!(read(&bytes, &Options { truncate_text: false, ..small }), Err(Error::TooLarge(_)))); + assert_eq!(read(&bytes, &small).unwrap().sheets[0].cells.keys().copied().collect::>(), [CellRef::new(0, 0)]); + // The cell that passes the limit is read whole first, so its own size limit still applies. + let over = row(r#""#); + assert!(matches!(read(&over, &small), Err(Error::TooLarge(_)))); + // The other limits refuse the cells kept, and do not count the cells left out. + let few = Options { max_cells: 1, ..cut }; + let after = row( + r#""#, + ); + assert!(read(&after, &Options { max_text: 1, ..few }).unwrap().sheets[0].cells.is_empty()); + assert!(matches!( + read(&row(r#""#), &few), + Err(Error::TooLarge(_)) + )); +} + #[test] fn an_error_result_never_reads_as_its_placeholder_zero() { let wb = open(&row( 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/pdf/Cargo.toml b/crates/pdf/Cargo.toml index a04f030c1..f4c2d0b23 100644 --- a/crates/pdf/Cargo.toml +++ b/crates/pdf/Cargo.toml @@ -27,6 +27,8 @@ cos = ["crypt", "filters", "dep:chrono", "dep:js-sys", "dep:wasm-bindgen"] # tokenizer ends them. content = ["cos", "dep:hayro-syntax"] crypt = ["dep:aes", "dep:md-5", "dep:sha2", "dep:stringprep", "dep:zeroize", "dep:thiserror"] +# `testing`: a builder of small synthetic PDF files, for the tests of crates that read them. +test-support = ["cos"] [dependencies] hayro-syntax = { workspace = true, optional = true } @@ -72,6 +74,10 @@ proptest = { workspace = true } [target.'cfg(target_arch = "wasm32")'.dev-dependencies] wasm-bindgen-test = "0.3" +[[test]] +name = "testing_pdf" +required-features = ["test-support"] + [[example]] name = "cos_info" required-features = ["cos"] diff --git a/crates/pdf/README.md b/crates/pdf/README.md index b9e0129d3..f1de94d17 100644 --- a/crates/pdf/README.md +++ b/crates/pdf/README.md @@ -16,6 +16,7 @@ No feature is enabled by default. | `filters` | The `/Filter` chain for editing and writing PDF files: decode and encode, with limits and accounting. No reader or writer dependency | | `crypt` | The standard security handler: decrypt, encrypt and create encryption. No reader or writer dependency | | `cos` | `crypt` and `filters` plus the object layer: open, edit and save PDF files (incremental and full saves). No reader or writer dependency | +| `test-support` | `cos` plus `testing::Pdf`, a builder of small synthetic PDF files for tests | | `content` | `cos` plus `cos::content`: parse content streams into operators with source spans, write them back, and the matrix arithmetic. Uses hayro-syntax's tokenizer for inline images | ## Reading and rendering @@ -136,7 +137,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 @@ -160,8 +165,9 @@ The code comes from PdfCraft's `pdfcraft-cos` crate (revision comments. Its test helpers come along: `src/cos/testkit.rs` (synthetic files, from `pdfcraft-testkit`) and `tests/cos/oracle.rs` (qpdf runs, from `pdfcraft-oracle`; a missing `qpdf` skips those tests, or fails them when `CRAFT_PDF_ORACLES_REQUIRED` is set). Tests: -`cargo test -p craft-pdf --no-default-features --features cos`. Examples: `cos_info` and -`cos_protect` (`--features cos`). +`cargo test -p craft-pdf --no-default-features --features cos`. Other crates' tests use the +builder as `craft_pdf::testing::Pdf` by enabling `test-support` in their dev-dependency on +`craft-pdf`. Examples: `cos_info` and `cos_protect` (`--features cos`). ## Stream filters diff --git a/crates/pdf/src/cos.rs b/crates/pdf/src/cos.rs index d67543041..cedd5eb35 100644 --- a/crates/pdf/src/cos.rs +++ b/crates/pdf/src/cos.rs @@ -23,7 +23,7 @@ mod parser; mod security; mod writer; -#[cfg(test)] +#[cfg(any(test, feature = "test-support"))] pub(crate) mod testkit; pub use crate::crypt::{ diff --git a/crates/pdf/src/cos/content.rs b/crates/pdf/src/cos/content.rs index a3087972d..f31c27359 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,13 +213,17 @@ 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)); 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. @@ -219,6 +236,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 +292,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..4076370cd 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,72 @@ 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 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/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..93898cc24 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::{ @@ -91,6 +91,12 @@ impl Document { &self.repair_log } + /// Whether the repair log records something read other than the file says: every line but + /// the note that `/Perms` disagrees with `/EncryptMetadata`, which changes nothing read. + pub fn structure_repaired(&self) -> bool { + self.repair_log.iter().any(|line| line != super::open::PERMS_MISMATCH) + } + /// Whether the file was rebuilt from its object headers because its last update has no `/Prev` /// and so cut its page tree off the cross-reference chain (ISO 32000-2 §7.5.6, §7.5.8.2). The /// renderer rebuilds such a file under the same conditions, so the two read the same objects. @@ -106,18 +112,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 +619,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 +804,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..1600256ab 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(), @@ -179,6 +179,12 @@ impl Document { { doc.authenticate(&enc, &credentials)?; } + // Algorithm 13 (ISO 32000-2 §7.6.4.4.12) says byte 8 of /Perms "should" match + // /EncryptMetadata: a should, so the file opens and the dictionary decides, as qpdf (which + // warns), MuPDF and PDFium read it. + if doc.security.as_deref().is_some_and(crate::crypt::SecurityHandler::perms_metadata_mismatch) { + Arc::make_mut(&mut doc.repair_log).push(PERMS_MISMATCH.into()); + } if Arc::make_mut(&mut doc.entries).remove_exhausted() { Arc::make_mut(&mut doc.repair_log).push("skipped exhausted xref object number 4294967295".into()); } @@ -256,7 +262,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(()) } @@ -507,6 +513,11 @@ impl Document { } } +/// The repair-log line for an R5/R6 `/Perms` whose byte 8 isn't the `T` or `F` `/EncryptMetadata` +/// gives (Algorithm 13, ISO 32000-2 §7.6.4.4.12). +pub(super) const PERMS_MISMATCH: &str = + "the encryption dictionary's /Perms disagrees with its /EncryptMetadata (Algorithm 13); metadata is read as /EncryptMetadata says"; + /// The repair-log line for a file rebuilt because its last update has no `/Prev`. const UNLINKED_UPDATE: &str = "the file's last update has no /Prev link to its earlier revisions, so their objects (the page tree among them) are unreachable through the cross-reference chain; rebuilding from object headers"; 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..dadb9fa82 100644 --- a/crates/pdf/src/cos/document/tests.rs +++ b/crates/pdf/src/cos/document/tests.rs @@ -172,13 +172,48 @@ fn an_object_stream_with_parameters_by_reference_is_read() { assert_eq!(hidden.as_dict().and_then(|d| d.get(b"Hidden")).and_then(Object::as_string).map(|s| s.bytes.clone()), Some(b"yes".to_vec())); } +/// The file key length an `/Encrypt` dictionary gives (ISO 32000-2 Table 20, Table 25). `/V 1` is +/// 40 bits whatever `/Length` says; `/V 2` takes `/Length`. At `/V 4` the crypt filter strings and +/// streams use decides: `AESV2` and `AESV3` take a 128-bit key (a stale `/Length 40` or a filter +/// `/Length 5` beside them was read as 40 bits, and the file didn't open as qpdf, MuPDF and +/// PDFium open it); an RC4 filter takes its own `/Length` (bytes, or bits), else the dictionary's +/// (as MuPDF and PDFium read a filter without one; it was read as 128), whatever the filter is +/// called (only `/StdCF` was looked at). +#[test] +fn the_key_length_comes_from_the_filter_in_use() { + let doc = Document::new_empty(); + let length = |dict: &str| { + let (_, o) = crate::cos::parse_indirect(format!("1 0 obj {dict} endobj").as_bytes(), 0, &|_| None).unwrap(); + crate::cos::security::encrypt_dict(&doc, o.as_dict().unwrap()).length_bits + }; + let v4 = |top: &str, filters: &str, stm: &str, str_: &str| { + length(&format!("<< /Filter /Standard /V 4 /R 4 {top} /CF << {filters} >> /StmF /{stm} /StrF /{str_} >>")) + }; + let std = |cfm: &str, len: &str| format!("/StdCF << /CFM /{cfm} {len} >>"); + assert_eq!(v4("/Length 128", &std("AESV2", "/Length 5"), "StdCF", "StdCF"), 128); + assert_eq!(v4("/Length 40", &std("AESV2", "/Length 16"), "StdCF", "StdCF"), 128, "a stale /Length 40"); + assert_eq!(v4("", &std("AESV3", "/Length 32"), "StdCF", "StdCF"), 128); + for (len, bits) in [("/Length 5", 40), ("/Length 6", 48), ("/Length 16", 128), ("/Length 40", 40), ("/Length 128", 128)] { + assert_eq!(v4("/Length 128", &std("V2", len), "StdCF", "StdCF"), bits, "{len}"); + } + assert_eq!(v4("/Length 40", &std("V2", ""), "StdCF", "StdCF"), 40, "RC4 without a length of its own"); + assert_eq!(v4("", &std("V2", ""), "StdCF", "StdCF"), 128); + assert_eq!(v4("/Length 40", "/MyCF << /CFM /V2 /Length 6 >>", "MyCF", "MyCF"), 48, "a filter not called StdCF"); + assert_eq!(v4("", "/MyCF << /CFM /V2 /Length 7 >>", "Identity", "MyCF"), 56, "strings only"); + // A filter that leaves streams as they are decides nothing: the strings' AES filter does. + assert_eq!(v4("", &format!("/Clear << /CFM /None /Length 5 >> {}", std("AESV2", "/Length 16")), "Clear", "StdCF"), 128, "a clear /StmF"); + assert_eq!(length("<< /Filter /Standard /V 1 /R 2 /Length 128 >>"), 40); + assert_eq!(length("<< /Filter /Standard /V 2 /R 3 /Length 56 >>"), 56); + assert_eq!(length("<< /Filter /Standard /V 2 /R 3 >>"), 40); +} + /// Each entry of an `/Encrypt` dictionary, and of a crypt filter in it, reads the same by reference. /// Read as absent, `/StmF` or `/CFM` was `/Identity`, so a whole file's streams stayed ciphertext. #[test] fn encrypt_dictionary_entries_read_the_same_by_reference() { let string = |s: &str| Object::String(crate::cos::PdfString::text(s)); let mut filter = Dict::new(); - filter.set(b"CFM".to_vec(), Object::name("AESV2")); + filter.set(b"CFM".to_vec(), Object::name("V2")); filter.set(b"Length".to_vec(), Object::Int(5)); let cf = |filter: Dict| { let mut cf = Dict::new(); @@ -209,7 +244,7 @@ fn encrypt_dictionary_entries_read_the_same_by_reference() { assert_eq!((direct.stm_f.as_slice(), direct.str_f.as_slice(), direct.ef_f.as_slice()), (&b"StdCF"[..], &b"Other"[..], &b"StdCF"[..])); assert_eq!(direct.length_bits, 40, "the filter's own length, in bytes"); assert!(!direct.encrypt_metadata); - assert_eq!(direct.crypt_filters.iter().filter(|(_, m)| *m == crate::crypt::Method::Aes128).count(), 1); + assert_eq!(direct.crypt_filters.iter().filter(|(_, m)| *m == crate::crypt::Method::Rc4).count(), 1); for (key, value) in &entries { let mut one = d.clone(); let r = doc.add(value.clone()); @@ -823,7 +858,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 +2746,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 763a5e514..5a0585ba3 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), @@ -283,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'>') { @@ -297,10 +309,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; } @@ -309,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()?; @@ -388,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. @@ -595,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). @@ -859,6 +954,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. diff --git a/crates/pdf/src/cos/security.rs b/crates/pdf/src/cos/security.rs index 69b59f39c..b8dafa330 100644 --- a/crates/pdf/src/cos/security.rs +++ b/crates/pdf/src/cos/security.rs @@ -82,31 +82,28 @@ pub(crate) fn encrypt_dict(doc: &Document, d: &Dict) -> EncryptDict { if let Some(cf) = d.get(b"CF").map(|c| doc.resolve(c)).and_then(|c| c.as_dict().cloned()) { for (k, v) in cf.iter() { let Some(f) = doc.resolve(v).as_dict().cloned() else { continue }; - let method = match name(&f, b"CFM").as_deref() { - Some(b"V2") => Method::Rc4, - Some(b"AESV2") => Method::Aes128, - Some(b"AESV3") => Method::Aes256, - _ => Method::Identity, + // ISO 32000-2 Table 25: `None` (the default) leaves data as it is to the standard + // handler; values other than these four are an algorithm the file can't be read with. + let cfm = f.get(b"CFM").map(|m| doc.resolve(m)); + let method = match cfm.as_deref() { + None | Some(Object::Null) => Method::Identity, + Some(m) => match m.as_name() { + Some(b"None") => Method::Identity, + Some(b"V2") => Method::Rc4, + Some(b"AESV2") => Method::Aes128, + Some(b"AESV3") => Method::Aes256, + _ => Method::Unsupported, + }, }; crypt_filters.push((k.clone(), method)); } } let v = int(b"V", 0); - // V4: the key length comes from the standard crypt filter's /Length (bytes, or bits in - // some files); /Length on the dictionary is often a stale 40. A length that isn't - // positive means nothing and reads as if absent. - let cf_len = d - .get(b"CF") - .map(|c| doc.resolve(c)) - .and_then(|c| c.as_dict().and_then(|c| c.get(b"StdCF").map(|f| doc.resolve(f)))) - .and_then(|f| f.as_dict().and_then(|f| f.get(b"Length").map(|n| doc.resolve(n)))) - .and_then(|n| n.as_int()) - .filter(|n| *n > 0); - let length_bits = match (v, cf_len) { - (5.., _) => 256, - (4, Some(n)) if n <= 32 => n * 8, - (4, Some(n)) => n, - (4, None) => 128, + let length_bits = match v { + 5.. => 256, + 4 => v4_length_bits(doc, d), + // Table 20: "1 ... with a file encryption key length of 40 bits". + 1 => 40, _ => int(b"Length", 40), }; EncryptDict { @@ -128,6 +125,34 @@ pub(crate) fn encrypt_dict(doc: &Document, d: &Dict) -> EncryptDict { } } +/// The file key length of a `/V 4` handler, in bits, from the crypt filter strings and streams +/// use (`/StmF`, else `/StrF`, whichever encrypts: `/CFM /None` leaves data as it is; else +/// `/StdCF`): 128 for `AESV2` and `AESV3`, which take a 128-bit key at `/V 4` (Table 25; +/// §7.6.4.1); for `V2` (RC4) the filter's `/Length` (in bytes, or bits in +/// some files), else the dictionary's `/Length`, else 128. The dictionary's `/Length` is often a +/// stale 40 next to an AES filter, so it counts only for RC4 without a length of its own, as MuPDF +/// and PDFium read it. A length that isn't positive reads as absent. +fn v4_length_bits(doc: &Document, d: &Dict) -> i64 { + let int = |o: &Object| doc.resolve(o).as_int().filter(|n| *n > 0); + let cf = d.get(b"CF").map(|c| doc.resolve(c)).and_then(|c| c.as_dict().cloned()); + let filter = |name: &[u8]| cf.as_ref().and_then(|cf| cf.get(name)).and_then(|f| doc.resolve(f).as_dict().cloned()); + let encrypts = |f: &Dict| matches!(f.get(b"CFM").map(|m| doc.resolve(m)).as_deref().and_then(Object::as_name), Some(b"V2" | b"AESV2" | b"AESV3")); + let named = |key: &[u8]| { + d.get(key).and_then(|n| doc.resolve(n).as_name().map(<[u8]>::to_vec)).filter(|n| n != b"Identity").and_then(|n| filter(&n)).filter(encrypts) + }; + let Some(f) = named(b"StmF").or_else(|| named(b"StrF")).or_else(|| filter(b"StdCF")) else { + return d.get(b"Length").and_then(int).unwrap_or(128); + }; + if matches!(f.get(b"CFM").map(|m| doc.resolve(m)).as_deref().and_then(Object::as_name), Some(b"AESV2" | b"AESV3")) { + return 128; + } + match f.get(b"Length").and_then(int) { + Some(n) if n <= 32 => n * 8, + Some(n) => n, + None => d.get(b"Length").and_then(int).unwrap_or(128), + } +} + /// Whether `d`, an `/Encrypt` dictionary, has crypt filters that encrypt (`/CFM` `V2`, `AESV2` or /// `AESV3`), each authorised only when an embedded file is opened (`/AuthEvent /EFOpen`, ISO /// 32000-2 §7.6.6, Table 25): what a document asks for its embedded files alone, which it opens @@ -151,10 +176,11 @@ pub(crate) fn efopen_only(doc: &Document, d: &Dict) -> bool { !encrypting.is_empty() } -/// Whether `s`, read from a document whose handler has no file key, holds data that handler would -/// decrypt, which therefore reads as stored: still encrypted. +/// Whether `s` holds encrypted data that reads as stored: still encrypted. Either the handler has +/// no file key and would decrypt it, or the stream names a crypt filter whose method the handler +/// can't decrypt (ISO 32000-2 Table 25). pub(crate) fn stream_reads_as_stored(doc: &Document, h: &SecurityHandler, s: &Stream) -> bool { - if h.has_key() { + if h.has_key() && !h.dict().crypt_filters.iter().any(|(_, m)| *m == Method::Unsupported) { return false; } let _scope = FollowScope::enter(); @@ -165,7 +191,7 @@ pub(crate) fn stream_reads_as_stored(doc: &Document, h: &SecurityHandler, s: &St (None, Some(b"EmbeddedFile")) => StreamKind::EmbeddedFile, _ => StreamKind::Normal, }; - h.decrypts(kind) + if h.has_key() { h.cannot_decrypt(kind) } else { h.decrypts(kind) } } /// Whether `f`, an entry of a `/Filter` chain or its only filter, is `/Crypt`. diff --git a/crates/pdf/src/cos/testkit.rs b/crates/pdf/src/cos/testkit.rs index 44e07b702..30b45bc1f 100644 --- a/crates/pdf/src/cos/testkit.rs +++ b/crates/pdf/src/cos/testkit.rs @@ -14,8 +14,9 @@ //! .build(); //! ``` //! -//! Test scaffolding: compiled into the unit tests (`cfg(test)`) and into the `cos` integration -//! test binary, never into the library. +//! Test scaffolding: compiled into the unit tests (`cfg(test)`), into the `cos` integration test +//! binary, and into the library only with the `test-support` feature, which exports [`Pdf`] as +//! `craft_pdf::testing::Pdf`. #![allow(dead_code)] /// A small PDF with a classic cross-reference table, built one object at a time. @@ -80,7 +81,7 @@ impl Pdf { /// The number the next object added will get, so a caller can refer forward to it. /// /// ``` - /// # use crate::cos::testkit::Pdf; + /// # use craft_pdf::testing::Pdf; /// let mut p = Pdf::new().obj("<< /Type /Catalog /Pages 2 0 R >>"); /// assert_eq!(p.next_obj(), 2); /// ``` diff --git a/crates/pdf/src/cos/writer.rs b/crates/pdf/src/cos/writer.rs index 4d8981dd5..8ebe8081d 100644 --- a/crates/pdf/src/cos/writer.rs +++ b/crates/pdf/src/cos/writer.rs @@ -169,21 +169,41 @@ fn write_stream(s: &Stream, out: &mut Vec) { /// A document opened without the password its embedded files need holds their data as stored and /// can't encrypt: a save keeps its `/Encrypt` as it is, and writes no edited or added stream that /// would have to be encrypted (an attached file put in, say), which would be written in the clear. +/// A stream naming a crypt filter whose method the handler can't decrypt is held as stored too, and +/// an edited one would be written as if encrypted with it. fn keyless_check(doc: &Document) -> Result<(), CosError> { - if !doc.embedded_files_locked() { + let locked = doc.embedded_files_locked(); + if !locked && !doc.security().is_some_and(defines_unsupported) { return Ok(()); } let refuse = |what: &str| Err(CosError::Security(format!("{what} without the password of the document's embedded files: open it with the password"))); - if doc.encryption_changed() || doc.trailer().get(b"Encrypt").is_none() { + if locked && (doc.encryption_changed() || doc.trailer().get(b"Encrypt").is_none()) { return refuse("the document's security can't change"); } if doc.overlay_entries().any(|(_, _, o)| matches!(o.as_deref(), Some(Object::Stream(s)) if doc.reads_as_stored(s))) { + if !locked { + return Err(unsupported_stream()); + } return refuse("an edited or added embedded file can't be encrypted"); } Ok(()) } +/// Whether `h` defines a crypt filter whose method it can't decrypt (ISO 32000-2 Table 25). +fn defines_unsupported(h: &crate::crypt::SecurityHandler) -> bool { + h.dict().crypt_filters.iter().any(|(_, m)| *m == crate::crypt::Method::Unsupported) +} + +/// A stream encrypted with a method the handler can't decrypt is held as stored: it can keep its +/// number and its document's security, nothing else, or it would be written as plaintext or under a +/// key it wasn't made with. +fn unsupported_stream() -> CosError { + CosError::Security( + "a stream is encrypted with an unsupported algorithm (its crypt filter's /CFM): it can be saved only incrementally, with the document's security unchanged".into(), + ) +} + /// The object as written: encrypted with its (output) number when the document is encrypted, /// except the `/Encrypt` dictionary itself (`source_num` is its number in the source document). /// `o` has the document's numbers in its references ([`crate::cos::security::transform`]). @@ -454,6 +474,13 @@ pub fn write_full(doc: &Document, opts: &SaveOptions) -> Result, CosErro packed.push((num, *r, kept[i].take())); } else { let o = written_object(&mut reader, *r, *is_stream, kept[i].take())?; + let document = &reader.document; + if let Object::Stream(s) = &*o + && document.security().is_some_and(|h| h.has_key() && defines_unsupported(h)) + && document.reads_as_stored(s) + { + return Err(unsupported_stream()); + } let o = renumber(&prepared(&reader.document, r.num, num, 0, &o), &map); rows.insert(num, Row::InFile(out.len() as u64, 0)); write_indirect(num, 0, &o, &mut out); diff --git a/crates/pdf/src/crypt.rs b/crates/pdf/src/crypt.rs index c516fa86e..3d0ea8d42 100644 --- a/crates/pdf/src/crypt.rs +++ b/crates/pdf/src/crypt.rs @@ -31,6 +31,11 @@ pub enum CryptError { Unsupported(String), #[error("malformed encryption dictionary: {0}")] Malformed(String), + /// A crypt filter the document's strings, streams or embedded files use has a `/CFM` other + /// than `None`, `V2`, `AESV2` or `AESV3` (ISO 32000-2 Table 25: "Applications that encounter + /// other values shall report that the file is encrypted with an unsupported algorithm"). + #[error("the file is encrypted with an unsupported algorithm: {0}")] + UnsupportedAlgorithm(String), } /// 32-byte padding string used by revisions 2–4 (§7.6.4.3.2, step a). @@ -50,6 +55,11 @@ pub enum Method { Aes128, /// `AESV3`: AES-256-CBC. Aes256, + /// Any other `/CFM` (or one that isn't a name): a method this handler can't decrypt (ISO + /// 32000-2 Table 25 lists the only values to support). Data it encrypts is left as stored, + /// read and written alike, and [`SecurityHandler::open`] refuses a document whose strings, + /// streams or embedded files use it. + Unsupported, } /// The values of an `/Encrypt` dictionary that the handler needs. @@ -59,7 +69,8 @@ pub struct EncryptDict { pub filter: Vec, pub v: i64, pub r: i64, - /// Key length in bits (`/Length`; 40 when absent). + /// File key length in bits: `/Length` (40 when absent, always 40 for `/V 1`), for `/V 4` the + /// crypt filter's (see `cos`). Revisions 2–4 clamp it to 40–128. pub length_bits: i64, pub o: Vec, pub u: Vec, @@ -208,29 +219,40 @@ impl SecurityHandler { if !dict.filter.is_empty() && dict.filter != b"Standard" { return Err(CryptError::Unsupported(format!("/Filter /{}", String::from_utf8_lossy(&dict.filter)))); } + // Table 20: 1, 2 and 4 are the RC4/crypt-filter algorithms and 5 is AES-256; 0 (or no /V) + // reads as RC4 with /Length, as MuPDF and PDFium read it. 3 is unpublished and others are + // unknown: their data can't be decrypted. + if !matches!(dict.v, 0 | 1 | 2 | 4 | 5) { + return Err(CryptError::Unsupported(format!("/V {}", dict.v))); + } + // Before the password: no password reads data encrypted with a method this handler lacks. + if let Some(name) = unsupported_in_use(&dict) { + return Err(CryptError::UnsupportedAlgorithm(format!( + "crypt filter /{} has a /CFM other than None, V2, AESV2 or AESV3", + String::from_utf8_lossy(name) + ))); + } let pw = password.unwrap_or(""); let mut recovered_user = None; + // Every spelling as the owner password first, then every spelling as the user password: + // one typed password can be the user password in one spelling and the owner password in + // another. let (key, auth) = match dict.r { 2..=4 => { - let mut found = None; - for legacy in legacy_candidates(pw) { - if let Some((k, user)) = owner_key_r4(&dict, id0, &legacy) { - recovered_user = Some(user); - found = Some((k, Auth::Owner)); - } else if let Some(k) = user_key_r4(&dict, id0, &legacy) { - found = Some((k, Auth::User)); - } - if found.is_some() { - break; - } + let candidates = legacy_candidates(pw); + if let Some((k, user)) = candidates.iter().find_map(|legacy| owner_key_r4(&dict, id0, legacy)) { + recovered_user = Some(user); + (k, Auth::Owner) + } else { + let user = candidates.iter().find_map(|legacy| user_key_r4(&dict, id0, legacy)); + (user.ok_or(CryptError::WrongPassword)?, Auth::User) } - found.ok_or(CryptError::WrongPassword)? } 5 | 6 => { - let pw = sasl_password(pw); - if let Some(k) = key_r6(&dict, &pw, true)? { + let candidates = aes256_candidates(pw); + if let Some(k) = first_key_r6(&dict, &candidates, true)? { (k, Auth::Owner) - } else if let Some(k) = key_r6(&dict, &pw, false)? { + } else if let Some(k) = first_key_r6(&dict, &candidates, false)? { (k, Auth::User) } else { return Err(CryptError::WrongPassword); @@ -268,13 +290,35 @@ impl SecurityHandler { self.method(Some(kind)) != Method::Identity } + /// Whether data of `kind` is encrypted with a method this handler can't decrypt + /// ([`Method::Unsupported`]): only a stream naming such a crypt filter for itself, as + /// [`SecurityHandler::open`] refuses one its strings, streams or embedded files use. That data + /// is left as stored, and isn't what it encrypts. + pub fn cannot_decrypt(&self, kind: StreamKind) -> bool { + self.method(Some(kind)) == Method::Unsupported + } + /// Whether data left as stored by a handler without the key still decrypts after its object - /// is renumbered: only AES-256 doesn't mix the object number into the key (Algorithm 1.A). + /// is renumbered: only AES-256 with a 256-bit file key doesn't mix the object number into the + /// key (Algorithm 1.A). pub fn survives_renumbering(&self) -> bool { + let direct = self.uses_file_key_directly(); [self.methods.string, self.methods.stream, self.methods.embedded_file] .into_iter() .chain(self.methods.named.values().copied()) - .all(|m| matches!(m, Method::Identity | Method::Aes256)) + .all(|m| m == Method::Identity || (m == Method::Aes256 && direct)) + } + + /// Whether `AESV3` data is encrypted with the file key itself (Algorithm 1.A, §7.6.3.3) rather + /// than a per-object key (Algorithm 1, §7.6.3.2): for `/V 5` (§7.6.3.1) and for a 256-bit file + /// key, the only kind Algorithm 1.A is for, which revisions 5 and 6 make (a handler without + /// the key goes by the revision). A `/V 4` handler of revision 4 or earlier that names + /// `/CFM /AESV3` (§7.6.4.1 allows only `V2` or `AESV2` at revision 4, and Table 25 asks for a + /// 256-bit key with `AESV3`) has a key of at most 128 bits. The files seen in practice derive + /// per-object keys from it as for `AESV2`, MD5 of the key, the object, the generation and + /// "sAlT", and qpdf and PDFium read them that way too. + fn uses_file_key_directly(&self) -> bool { + self.dict.v >= 5 || self.dict.r >= 5 || self.key.len() == 32 } /// Upgrade to owner access with the owner (permissions) password, as when a restricted @@ -310,12 +354,27 @@ impl SecurityHandler { /// `/P` as `/Perms` holds it: AES-256 ECB of one block (= CBC with a zero IV), marked `adb`. fn perms_p(&self) -> Option { + let plain = self.perms_block()?; + Some(i32::from_le_bytes(*plain.first_chunk::<4>()?)) + } + + /// `/Perms` decrypted (Algorithm 13 step a), when it is one block marked `adb` (bytes 9–11). + fn perms_block(&self) -> Option>> { if !matches!(self.dict.r, 5 | 6) || !self.has_key() { return None; } let plain = Zeroizing::new(aes_cbc_decrypt(&self.key, &[0; 16], self.dict.perms.first_chunk::<16>()?, false)); - let p = i32::from_le_bytes(*plain.first_chunk::<4>()?); - (plain.get(9..12) == Some(&b"adb"[..])).then_some(p) + (plain.get(9..12) == Some(&b"adb"[..])).then_some(plain) + } + + /// Whether byte 8 of a readable `/Perms` isn't the `T` or `F` that `/EncryptMetadata` gives + /// (Algorithm 13 step a, ISO 32000-2 §7.6.4.4.12: it "should match"). A "should", so the + /// document still opens, metadata read as `/EncryptMetadata` says: qpdf warns of it, and MuPDF + /// and PDFium open such files. False when `/Perms` can't be read, which [`Self::permissions`] + /// already reads past. + pub fn perms_metadata_mismatch(&self) -> bool { + let expected = if self.dict.encrypt_metadata { b'T' } else { b'F' }; + self.perms_block().is_some_and(|plain| plain.get(8) != Some(&expected)) } pub fn dict(&self) -> &EncryptDict { @@ -345,8 +404,9 @@ impl SecurityHandler { } } - /// Algorithm 1 (§7.6.3.2): the key for one object. AES-256 uses the file key directly - /// (Algorithm 1.A, §7.6.3.3). + /// Algorithm 1 (§7.6.3.2): the key for one object. AES-256 with a 256-bit file key uses the + /// file key directly (Algorithm 1.A, §7.6.3.3); with a shorter one it is derived as for + /// AES-128 (see [`Self::uses_file_key_directly`]). /// /// For an RC4 crypt filter under `/V 4`, a file key shorter than 16 bytes is first extended /// to 16 bytes with zeros. The standard doesn't say so (Algorithm 1 takes the n-byte key as @@ -356,7 +416,7 @@ impl SecurityHandler { /// left as they are: `AESV2` takes a 128-bit key (Table 25), and Acrobat's extension is only /// seen with RC4. Every key [`create`] makes under `/V 4` is 16 bytes already. fn object_key(&self, method: Method, num: u32, generation: u16) -> Zeroizing> { - if method == Method::Aes256 { + if method == Method::Aes256 && self.uses_file_key_directly() { return self.key.clone(); } let mut key = self.key.clone(); @@ -367,7 +427,7 @@ impl SecurityHandler { h.update(&key); h.update(&num.to_le_bytes()[..3]); h.update(generation.to_le_bytes()); - if method == Method::Aes128 { + if matches!(method, Method::Aes128 | Method::Aes256) { h.update(b"sAlT"); } let mut digest = Zeroizing::new(h.finalize().to_vec()); @@ -381,7 +441,8 @@ impl SecurityHandler { return data.to_vec(); } match method { - Method::Identity => data.to_vec(), + // Data whose method is unknown keeps the bytes it has, so a save writes it back as it was. + Method::Identity | Method::Unsupported => data.to_vec(), Method::Rc4 => rc4(&self.object_key(method, num, generation), data), Method::Aes128 | Method::Aes256 => { let key = self.object_key(method, num, generation); @@ -433,6 +494,20 @@ impl SecurityHandler { } } +/// The name of a crypt filter `d`'s strings, streams or embedded files use (`/StrF`, `/StmF`, +/// `/EFF`, which defaults to `/StmF`) whose method is [`Method::Unsupported`]. Handlers older than +/// crypt filters (`/V` below 4) encrypt everything with RC4 whatever `/CF` says. A filter `/CF` +/// defines and nothing uses doesn't count: qpdf, MuPDF and PDFium all open such a file. +fn unsupported_in_use(d: &EncryptDict) -> Option<&[u8]> { + if d.v < 4 { + return None; + } + let ef = if d.ef_f.is_empty() { &d.stm_f } else { &d.ef_f }; + [&d.str_f, &d.stm_f, ef].into_iter().map(Vec::as_slice).find(|name| { + *name != b"Identity" && d.crypt_filters.iter().find(|(n, _)| n.as_slice() == *name).is_some_and(|(_, m)| *m == Method::Unsupported) + }) +} + // ── Passwords ────────────────────────────────────────────────────────────────────────────────── /// PDFDocEncoding (ISO 32000-2 Annex D) where it differs from Latin-1: bytes 0x18–0x1F and @@ -463,22 +538,47 @@ pub fn pdfdoc_byte(c: char) -> Option { } /// Revisions 2–4: the password in PDFDocEncoding (§7.6.4.3.2, Algorithm 2), at most 32 bytes. -/// Characters PDFDocEncoding lacks are dropped. +/// Characters PDFDocEncoding lacks are dropped, as MuPDF drops them. U+FFFD stands for the byte +/// 0x9F, which PDFDocEncoding leaves undefined and [`pdfdoc_char`] reads as U+FFFD: a user +/// password with that byte, recovered with the owner password and handed on as text, reads back +/// to the same bytes. fn legacy_password(pw: &str) -> Zeroizing> { - Zeroizing::new(pw.chars().filter_map(pdfdoc_byte).take(32).collect()) + Zeroizing::new(pw.chars().filter_map(|c| if c == '\u{FFFD}' { Some(0x9F) } else { pdfdoc_byte(c) }).take(32).collect()) } /// The bytes an R2–R4 password may have been written as: PDFDocEncoding, as the specification -/// asks; and for a password with characters PDFDocEncoding lacks (ğ, ş, İ, …), which it gives -/// no bytes, also its UTF-8 bytes, which qpdf and other tools write for such passwords. +/// asks; and for a password with any non-ASCII character, also its UTF-8 bytes. Tools write +/// those for a password with characters PDFDocEncoding lacks (ğ, ş, İ, …), and some for every +/// non-ASCII password, even one PDFDocEncoding holds (qpdf's `--password-mode=bytes` writes +/// "pässwört" as its UTF-8 bytes). An ASCII password is the same in both. fn legacy_candidates(pw: &str) -> Vec>> { let mut out = vec![legacy_password(pw)]; - if pw.chars().any(|c| pdfdoc_byte(c).is_none()) { + if !pw.is_ascii() { out.push(Zeroizing::new(pw.bytes().take(32).collect())); } out } +/// The bytes an R5/R6 password may have been written as: its SASLprep form (Algorithm 2.A, step +/// a), and, where that differs, the password as typed, at most 127 bytes of UTF-8 each. qpdf, +/// MuPDF and PDFium key and read passwords without SASLprep, so a decomposed "café" or a no-break +/// space reaches the file as typed. +fn aes256_candidates(pw: &str) -> Vec>> { + let prepared = sasl_password(pw); + let typed = Zeroizing::new(pw.as_bytes().get(..127).unwrap_or(pw.as_bytes()).to_vec()); + if typed == prepared { vec![prepared] } else { vec![prepared, typed] } +} + +/// Algorithm 2.A for each of `candidates` in turn: the first file key one of them unlocks. +fn first_key_r6(d: &EncryptDict, candidates: &[Zeroizing>], owner: bool) -> Result>>, CryptError> { + for pw in candidates { + if let Some(k) = key_r6(d, pw, owner)? { + return Ok(Some(k)); + } + } + Ok(None) +} + /// Revisions 5–6: SASLprep (RFC 4013), UTF-8, at most 127 bytes. fn sasl_password(pw: &str) -> Zeroizing> { let prepped = Zeroizing::new(stringprep::saslprep(pw).map(|c| c.into_owned()).unwrap_or_else(|_| pw.to_string())); @@ -495,8 +595,13 @@ fn pad(pw: &[u8]) -> Zeroizing<[u8; 32]> { out } +/// The file key's length in bytes: `/Length` (in bits, 40 to 128). Algorithms 2 and 3 say 5 bytes +/// for revision 2 whatever `/Length` says, but qpdf, MuPDF and PDFium all take `/Length` at +/// revision 2 too (a `/V 2 /R 2 /Length 128` file opens in each of them only with a 16-byte key), +/// and so does this. `/V 1` is always 40 bits (Table 20), which the caller puts in `length_bits`. fn key_len(d: &EncryptDict) -> usize { - if d.r == 2 { 5 } else { (d.length_bits.clamp(40, 128) / 8) as usize } + // Provably in 5..=16 after the clamp, so the cast is lossless. + (d.length_bits.clamp(40, 128) / 8) as usize } // ── Revisions 2–4 ────────────────────────────────────────────────────────────────────────────── @@ -562,26 +667,51 @@ fn user_key_r4(d: &EncryptDict, id0: &[u8], pw: &[u8]) -> Option Zeroizing> { + owner_rc4_key_hashing(d, owner_pw, 16) +} + +/// Algorithm 3, steps a–d, with each of the 50 rehashes of step c taking the first `hashed` bytes +/// of the previous digest. The standard hashes the whole digest (16 bytes); some producers hash +/// only the first n bytes, as Algorithm 2 step h does (see [`owner_rc4_keys`]). +fn owner_rc4_key_hashing(d: &EncryptDict, owner_pw: &[u8], hashed: usize) -> Zeroizing> { let n = key_len(d); let mut digest = Zeroizing::new(Md5::digest(*pad(owner_pw)).to_vec()); if d.r >= 3 { for _ in 0..50 { - digest = Zeroizing::new(Md5::digest(&*digest).to_vec()); + let take = hashed.min(digest.len()); + digest = Zeroizing::new(Md5::digest(digest.get(..take).unwrap_or(&digest)).to_vec()); } } digest.truncate(n); digest } +/// The RC4 keys an owner password may have been turned into. The first is Algorithm 3 as the +/// standard has it. For an R3 or R4 key shorter than 16 bytes some producers rehash only the first +/// n bytes in step c (as Algorithm 2 step h does for the file key), and qpdf and MuPDF accept an +/// owner password written that way, so it is tried too. +fn owner_rc4_keys(d: &EncryptDict, owner_pw: &[u8]) -> Vec>> { + let n = key_len(d); + let mut keys = vec![owner_rc4_key(d, owner_pw)]; + if d.r >= 3 && n < 16 { + keys.push(owner_rc4_key_hashing(d, owner_pw, n)); + } + keys +} + type SecretBytes = Zeroizing>; /// Algorithm 7: authenticate an owner password (recover the user password from `/O`). /// Returns the file key and the recovered user password (padding removed). fn owner_key_r4(d: &EncryptDict, id0: &[u8], pw: &[u8]) -> Option<(SecretBytes, SecretBytes)> { - let rk = owner_rc4_key(d, pw); + owner_rc4_keys(d, pw).into_iter().find_map(|rk| owner_key_with(d, id0, &rk)) +} + +/// Algorithm 7 with one RC4 key from Algorithm 3, steps a–d. +fn owner_key_with(d: &EncryptDict, id0: &[u8], rk: &[u8]) -> Option<(SecretBytes, SecretBytes)> { let mut user = Zeroizing::new(d.o[..d.o.len().min(32)].to_vec()); if d.r == 2 { - user = Zeroizing::new(rc4(&rk, &user)); + user = Zeroizing::new(rc4(rk, &user)); } else { for i in (0..=19u8).rev() { let k = Zeroizing::new(rk.iter().map(|b| b ^ i).collect::>()); diff --git a/crates/pdf/src/crypt/tests.rs b/crates/pdf/src/crypt/tests.rs index 08878c8be..9fb685bea 100644 --- a/crates/pdf/src/crypt/tests.rs +++ b/crates/pdf/src/crypt/tests.rs @@ -325,8 +325,8 @@ proptest::proptest! { #[test] fn malformed_dictionaries_never_panic(o in proptest::collection::vec(proptest::num::u8::ANY, 0..60), u in proptest::collection::vec(proptest::num::u8::ANY, 0..60), - r in 0i64..9, len in -10i64..300) { - let d = EncryptDict { filter: b"Standard".to_vec(), v: 4, r, length_bits: len, o, u, p: -1, encrypt_metadata: true, ..Default::default() }; + r in 0i64..9, v in -2i64..8, len in -10i64..300) { + let d = EncryptDict { filter: b"Standard".to_vec(), v, r, length_bits: len, o, u, p: -1, encrypt_metadata: true, ..Default::default() }; let _ = SecurityHandler::open(d, ID, Some("x")); } } @@ -476,10 +476,289 @@ fn pdfdoc_encoding_round_trips() { for c in ['ğ', 'ş', 'İ', '\u{A0}', '\u{85}', 'Ж', '日'] { assert_eq!(pdfdoc_byte(c), None, "{c}"); } - assert_eq!(legacy_candidates("Çok"), [Zeroizing::new(vec![0xC7, b'o', b'k'])]); + assert_eq!(legacy_candidates("Çok"), [Zeroizing::new(vec![0xC7, b'o', b'k']), Zeroizing::new("Çok".as_bytes().to_vec())]); assert_eq!(legacy_candidates("şifre"), [Zeroizing::new(b"ifre".to_vec()), Zeroizing::new("şifre".as_bytes().to_vec())]); } +/// An R2–R4 dictionary whose `/O` and `/U` were made from raw password bytes, with Algorithm 3 +/// step c rehashing the first `owner_hashed` bytes of each digest (16 as the standard has it). +fn legacy_dict(v: i64, r: i64, bits: i64, user: &[u8], owner: &[u8], owner_hashed: usize) -> EncryptDict { + let mut d = EncryptDict { filter: b"Standard".to_vec(), v, r, length_bits: bits, p: -4, encrypt_metadata: true, ..Default::default() }; + let rk = owner_rc4_key_hashing(&d, owner, owner_hashed); + let mut o = rc4(&rk, &*pad(user)); + if r >= 3 { + for i in 1..=19u8 { + let k: Vec = rk.iter().map(|b| b ^ i).collect(); + o = rc4(&k, &o); + } + } + d.o = o; + let key = file_key_r4(&d, ID, user); + d.u = u_value_r4(&d, ID, &key); + d +} + +/// A password PDFDocEncoding holds ("pässwört": ä and ö are 0xE4 and 0xF6) written as its UTF-8 +/// bytes, as `qpdf --password-mode=bytes` writes it, opens with that password, user and owner +/// alike; the PDFDocEncoding-written one keeps opening too. +#[test] +fn a_pdfdoc_password_written_as_utf8_bytes_opens() { + for r in [2, 3, 4] { + let (v, bits) = if r == 2 { (1, 40) } else { (2, 128) }; + let d = legacy_dict(v, r, bits, "pässwört".as_bytes(), "Öwnér".as_bytes(), 16); + let user = SecurityHandler::open(d.clone(), ID, Some("pässwört")).unwrap(); + assert_eq!(user.auth(), Auth::User, "R{r}"); + assert_eq!(user.file_key(), &*file_key_r4(&d, ID, "pässwört".as_bytes()), "R{r}"); + let owner = SecurityHandler::open(d.clone(), ID, Some("Öwnér")).unwrap(); + assert_eq!(owner.auth(), Auth::Owner, "R{r}"); + assert_eq!(owner.recovered_user_password().as_deref().map(Vec::as_slice), Some("pässwört".as_bytes()), "R{r}"); + for wrong in ["passwort", "pässwort", "Ownér"] { + assert_eq!(SecurityHandler::open(d.clone(), ID, Some(wrong)).unwrap_err(), CryptError::WrongPassword, "R{r} {wrong}"); + } + let pdfdoc = legacy_dict(v, r, bits, b"p\xE4ssw\xF6rt", b"owner", 16); + assert_eq!(SecurityHandler::open(pdfdoc, ID, Some("pässwört")).unwrap().auth(), Auth::User, "R{r}"); + // One typed password, the user password in PDFDocEncoding and the owner password in + // UTF-8: it opens as the owner, and it unlocks a session opened without a password. + let both = legacy_dict(v, r, bits, b"p\xE4ssw\xF6rt", "pässwört".as_bytes(), 16); + let owner = SecurityHandler::open(both.clone(), ID, Some("pässwört")).unwrap(); + assert_eq!(owner.auth(), Auth::Owner, "R{r}"); + assert_eq!(owner.recovered_user_password().as_deref().map(Vec::as_slice), Some(&b"p\xE4ssw\xF6rt"[..]), "R{r}"); + let empty_user = legacy_dict(v, r, bits, b"", "pässwört".as_bytes(), 16); + let user = SecurityHandler::open(empty_user, ID, None).unwrap(); + assert_eq!(user.authenticate_owner(ID, "pässwört").unwrap().auth(), Auth::Owner, "R{r}"); + } + assert_eq!(legacy_candidates("pässwört"), [Zeroizing::new(b"p\xE4ssw\xF6rt".to_vec()), Zeroizing::new("pässwört".as_bytes().to_vec())]); + assert_eq!(legacy_candidates("plain"), [Zeroizing::new(b"plain".to_vec())]); +} + +/// R3 with a key shorter than 16 bytes: `/O` made by rehashing only the first n bytes in +/// Algorithm 3 step c (as a 40-bit V1 R3 file in PDFBOX-3276 was written) authenticates the owner +/// password, as qpdf and MuPDF accept it, and so does `/O` made as the standard has it. With the +/// empty owner password (Algorithm 3 step a then uses the user password) the empty password is +/// the owner password too. +#[test] +fn a_short_key_owner_password_opens_under_either_rehash() { + for bits in [40, 56, 88, 120] { + let n = (bits / 8) as usize; + for hashed in [n, 16] { + let case = format!("{bits}-bit key, step c over {hashed} bytes"); + let d = legacy_dict(1, 3, bits, b"", b"", hashed); + let h = SecurityHandler::open(d.clone(), ID, None).unwrap(); + assert_eq!(h.auth(), Auth::Owner, "{case}"); + assert!(h.permissions().owner, "{case}"); + let d = legacy_dict(2, 3, bits, b"usr", b"own", hashed); + let owner = SecurityHandler::open(d.clone(), ID, Some("own")).unwrap(); + assert_eq!(owner.auth(), Auth::Owner, "{case}"); + assert_eq!(owner.recovered_user_password().as_deref().map(Vec::as_slice), Some(&b"usr"[..]), "{case}"); + let user = SecurityHandler::open(d.clone(), ID, Some("usr")).unwrap(); + assert_eq!((user.auth(), user.file_key()), (Auth::User, owner.file_key()), "{case}"); + assert_eq!(user.authenticate_owner(ID, "own").unwrap().auth(), Auth::Owner, "{case}"); + assert_eq!(SecurityHandler::open(d, ID, Some("ow")).unwrap_err(), CryptError::WrongPassword, "{case}"); + } + } + // A 128-bit key has one reading, and new encryption keeps writing the standard's. + assert_eq!(owner_rc4_keys(&legacy_dict(2, 3, 128, b"", b"", 16), b"").len(), 1); + let made = new(Algorithm::Rc4_128, "u", "o", -1); + assert_eq!(made.dict().o, legacy_dict(2, 3, 128, b"u", b"o", 16).o); +} + +/// `/V 4` with `/CFM /AESV3` and a 128-bit key (§7.6.4.1 and Table 25 don't allow it; PDFBOX-5345): +/// each object's key is MD5(key, object, generation, "sAlT"), as for AESV2, and AES-128 with it +/// decrypts the data. Only a 256-bit key from R5/R6 is used directly (Algorithm 1.A), and only +/// then does data left as stored survive renumbering. +#[test] +fn aesv3_with_a_128_bit_key_derives_object_keys_as_aesv2() { + let text = b"Crypto sample".to_vec(); + let mut d = legacy_dict(4, 4, 128, b"", b"owner", 16); + d.crypt_filters = vec![(b"StdCF".to_vec(), Method::Aes256)]; + d.stm_f = b"StdCF".to_vec(); + d.str_f = b"StdCF".to_vec(); + let h = SecurityHandler::open(d.clone(), ID, None).unwrap(); + assert_eq!(h.file_key().len(), 16); + let (num, generation) = (7u32, 0u16); + let mut md5 = Md5::new(); + md5.update(h.file_key()); + md5.update(&num.to_le_bytes()[..3]); + md5.update(generation.to_le_bytes()); + md5.update(b"sAlT"); + let object_key = md5.finalize().to_vec(); + let iv = [5u8; 16]; + let written = [iv.to_vec(), aes_cbc_encrypt(&object_key, &iv, &text, true)].concat(); + assert_eq!(h.decrypt_string(num, generation, &written), text); + assert_eq!(h.decrypt_stream(num, generation, &written, StreamKind::Normal), text); + let saved = h.encrypt_stream(num, generation, &text, StreamKind::Normal); + assert_eq!(aes_cbc_decrypt(&object_key, saved.first_chunk::<16>().unwrap(), &saved[16..], true), text); + // Data a keyless handler leaves as stored: AESV3 at R4 mixes in the object number, R6 doesn't. + let keyless = |mut d: EncryptDict| { + d.crypt_filters = vec![(b"EFF".to_vec(), Method::Aes256)]; + (d.stm_f, d.str_f, d.ef_f) = (b"Identity".to_vec(), b"Identity".to_vec(), b"EFF".to_vec()); + SecurityHandler::without_key(d).unwrap().survives_renumbering() + }; + assert!(!keyless(d)); + assert!(keyless(new(Algorithm::Aes256, "u", "o", -1).dict().clone())); + // R6 still uses its 256-bit key directly. + let r6 = new(Algorithm::Aes256, "u", "o", -1); + let written = [iv.to_vec(), aes_cbc_encrypt(r6.file_key(), &iv, &text, true)].concat(); + assert_eq!(r6.decrypt_string(num, generation, &written), text); +} + +/// An R5 or R6 dictionary keyed on raw password bytes (Algorithms 8–10 without SASLprep), as qpdf +/// writes one from a password SASLprep would change. +fn aes256_dict(r: i64, user: &[u8], owner: &[u8]) -> EncryptDict { + let key = [3u8; 32]; + let (uv, uk, ov, ok) = ([1u8; 8], [2u8; 8], [4u8; 8], [5u8; 8]); + let u = [&hash_r6(r, user, &uv, &[])[..], &uv, &uk].concat(); + let ue = aes_cbc_encrypt(&hash_r6(r, user, &uk, &[]), &[0; 16], &key, false); + let o = [&hash_r6(r, owner, &ov, &u)[..], &ov, &ok].concat(); + let oe = aes_cbc_encrypt(&hash_r6(r, owner, &ok, &u), &[0; 16], &key, false); + EncryptDict { filter: b"Standard".to_vec(), v: 5, r, length_bits: 256, o, u, oe, ue, p: -4, encrypt_metadata: true, ..Default::default() } +} + +/// ISO 32000-2 Algorithm 2.A keys R5/R6 files on the SASLprep form of a password, but qpdf (in +/// every `--password-mode`), MuPDF and PDFium write and read it as typed: a decomposed "café" or a +/// no-break space reaches the file unchanged. Such a file opens with the password as typed, user +/// and owner alike, as it does in those readers. Every spelling is tried as the owner password before any as the user password. +#[test] +fn an_aes256_password_written_without_saslprep_opens_as_typed() { + for r in [5, 6] { + let d = aes256_dict(r, "cafe\u{301}".as_bytes(), "a\u{A0}b".as_bytes()); + let user = SecurityHandler::open(d.clone(), ID, Some("cafe\u{301}")).unwrap(); + assert_eq!((user.auth(), user.file_key()), (Auth::User, &[3u8; 32][..]), "R{r}"); + assert_eq!(SecurityHandler::open(d.clone(), ID, Some("a\u{A0}b")).unwrap().auth(), Auth::Owner, "R{r}"); + assert_eq!(user.authenticate_owner(ID, "a\u{A0}b").unwrap().auth(), Auth::Owner, "R{r}"); + // The SASLprep forms are other passwords to this file, as to qpdf and MuPDF. + for wrong in ["caf\u{E9}", "a b", "cafe"] { + assert_eq!(SecurityHandler::open(d.clone(), ID, Some(wrong)).unwrap_err(), CryptError::WrongPassword, "R{r} {wrong:?}"); + } + // One typed password, the user password in its SASLprep form and the owner password as + // typed: it opens as the owner. + let both = aes256_dict(r, "caf\u{E9}".as_bytes(), "cafe\u{301}".as_bytes()); + assert_eq!(SecurityHandler::open(both, ID, Some("cafe\u{301}")).unwrap().auth(), Auth::Owner, "R{r}"); + } + assert_eq!( + aes256_candidates("cafe\u{301}"), + [Zeroizing::new("caf\u{E9}".as_bytes().to_vec()), Zeroizing::new("cafe\u{301}".as_bytes().to_vec())] + ); + assert_eq!(aes256_candidates("plain"), [Zeroizing::new(b"plain".to_vec())]); + // At most 127 bytes each: 64 decomposed é (192 bytes) and their 128-byte SASLprep form. + let long = "e\u{301}".repeat(64); + assert!(aes256_candidates(&long).iter().all(|c| c.len() == 127)); +} + +/// Algorithm 2 says a revision 2 key is always 5 bytes, but qpdf, MuPDF and PDFium all take +/// `/Length` at revision 2 too: a `/V 2 /R 2 /Length 128` file keyed with 16 bytes opens in each, +/// one keyed with 5 bytes in none. `/V 1` stays 40 bits (`cos` reads it so). +#[test] +fn a_revision_2_key_has_the_length_length_gives() { + let o = vec![9u8; 32]; + let mut d = EncryptDict { filter: b"Standard".to_vec(), v: 2, r: 2, length_bits: 128, o, p: -4, encrypt_metadata: true, ..Default::default() }; + // Algorithm 2 by hand, without step h (revision 2): MD5 of the padded empty password, /O, /P + // and the ID, the first 16 bytes; /U is the padding encrypted with it (Algorithm 4). + let mut md5 = Md5::new(); + md5.update(PADDING); + md5.update(&d.o); + md5.update((-4i32).to_le_bytes()); + md5.update(ID); + let key = md5.finalize().to_vec(); + d.u = rc4(&key, &PADDING); + let h = SecurityHandler::open(d.clone(), ID, None).unwrap(); + assert_eq!(h.file_key(), &key[..]); + // The same file read as 40 bits has another /U. + d.u = rc4(&key[..5], &PADDING); + assert_eq!(SecurityHandler::open(d, ID, None).unwrap_err(), CryptError::WrongPassword); +} + +/// Table 20 defines `/V` 1, 2, 4 and 5 (3 is unpublished); `/V 0` or no `/V` reads as RC4 with +/// `/Length`, as MuPDF and PDFium read it. Other values are unsupported. +#[test] +fn only_known_algorithms_open() { + let made = legacy_dict(2, 3, 128, b"", b"owner", 16); + for v in [0, 2] { + assert!(SecurityHandler::open(EncryptDict { v, ..made.clone() }, ID, None).is_ok(), "/V {v}"); + } + for v in [3, 6, -1, 4_294_967_298] { + assert!(matches!(SecurityHandler::open(EncryptDict { v, ..made.clone() }, ID, None), Err(CryptError::Unsupported(_))), "/V {v}"); + } +} + +/// A user password with the byte 0x9F, which PDFDocEncoding leaves undefined and `pdfdoc_char` +/// reads as U+FFFD: recovered with the owner password and handed on as text, as an app hands it +/// to another reader, it reads back to the same bytes. +#[test] +fn an_undefined_pdfdoc_byte_in_a_password_reads_back() { + let user = b"\x9Fuser\xFF"; + let d = legacy_dict(2, 3, 128, user, b"owner", 16); + let recovered = SecurityHandler::open(d.clone(), ID, Some("owner")).unwrap().recovered_user_password().unwrap(); + assert_eq!(&recovered[..], user); + let text: String = recovered.iter().map(|b| pdfdoc_char(*b)).collect(); + assert_eq!(text, "\u{FFFD}user\u{FF}"); + assert_eq!(SecurityHandler::open(d, ID, Some(&text)).unwrap().auth(), Auth::User); +} + +/// ISO 32000-2 Table 25: a `/CFM` other than `None`, `V2`, `AESV2` or `AESV3` is an algorithm the +/// file can't be read with, to be reported as such. A filter the strings, streams or embedded +/// files use with such a method refuses the file before any password (none would read it); one +/// `/CF` only defines, or a stream names for itself, doesn't, and that stream's data stays as +/// stored, both ways. +#[test] +fn a_crypt_filter_method_in_use_that_cant_be_decrypted_is_reported() { + let made = new(Algorithm::Aes256, "user", "owner", -4).dict().clone(); + let with = |filters: &[(&[u8], Method)], stm_f: &[u8], str_f: &[u8], ef_f: &[u8]| EncryptDict { + crypt_filters: filters.iter().map(|(n, m)| (n.to_vec(), *m)).collect(), + stm_f: stm_f.to_vec(), + str_f: str_f.to_vec(), + ef_f: ef_f.to_vec(), + ..made.clone() + }; + let unknown: &[(&[u8], Method)] = &[(b"StdCF", Method::Aes256), (b"X", Method::Unsupported)]; + for (case, d) in [ + ("both", with(&[(b"StdCF", Method::Unsupported)], b"StdCF", b"StdCF", b"")), + ("streams", with(unknown, b"X", b"StdCF", b"")), + ("strings", with(unknown, b"StdCF", b"X", b"")), + ("embedded files", with(unknown, b"StdCF", b"StdCF", b"X")), + ] { + for pw in [Some("user"), Some("owner"), Some("wrong"), None] { + assert!(matches!(SecurityHandler::open(d.clone(), ID, pw), Err(CryptError::UnsupportedAlgorithm(_))), "{case} with {pw:?}"); + } + } + // Defined and unused, or named by a stream: the file opens, and that stream reads as stored. + let h = SecurityHandler::open(with(unknown, b"StdCF", b"StdCF", b""), ID, Some("user")).unwrap(); + let named = StreamKind::Named(b"X"); + assert!(h.cannot_decrypt(named) && h.decrypts(named)); + assert!(!h.cannot_decrypt(StreamKind::Normal) && !h.cannot_decrypt(StreamKind::EmbeddedFile)); + assert_eq!(h.decrypt_stream(4, 0, b"stored", named), b"stored"); + assert_eq!(h.encrypt_stream(4, 0, b"stored", named), b"stored"); + assert!(!h.survives_renumbering()); + // `/Identity` names no filter of `/CF`, whatever a file puts there; handlers before crypt + // filters encrypt everything with RC4. + assert!(SecurityHandler::open(with(&[(b"Identity", Method::Unsupported)], b"Identity", b"Identity", b""), ID, Some("user")).is_ok()); + let rc4 = new(Algorithm::Rc4_128, "user", "owner", -4).dict().clone(); + let old = EncryptDict { crypt_filters: vec![(b"StdCF".to_vec(), Method::Unsupported)], stm_f: b"StdCF".to_vec(), ..rc4 }; + assert!(SecurityHandler::open(old, ID, Some("user")).is_ok()); +} + +/// Algorithm 13 (ISO 32000-2 §7.6.4.4.12): byte 8 of the decrypted `/Perms` "should match" `T` or +/// `F` as `/EncryptMetadata` is true or false. Reported, not refused. +#[test] +fn perms_byte_8_is_checked_against_encrypt_metadata() { + let h = new(Algorithm::Aes256, "user", "owner", -4); + let open = |d: &EncryptDict| SecurityHandler::open(d.clone(), ID, Some("user")).unwrap(); + let made = h.dict().clone(); + assert!(!open(&made).perms_metadata_mismatch(), "T and true"); + assert!(open(&EncryptDict { encrypt_metadata: false, ..made.clone() }).perms_metadata_mismatch(), "T and false"); + let block = |flag: u8| { + let mut plain = aes_cbc_decrypt(h.file_key(), &[0; 16], made.perms.first_chunk::<16>().unwrap(), false); + plain[8] = flag; + aes_cbc_encrypt(h.file_key(), &[0; 16], &plain, false) + }; + assert!(open(&EncryptDict { perms: block(b'F'), ..made.clone() }).perms_metadata_mismatch(), "F and true"); + assert!(!open(&EncryptDict { perms: block(b'F'), encrypt_metadata: false, ..made.clone() }).perms_metadata_mismatch(), "F and false"); + assert!(open(&EncryptDict { perms: block(b'X'), ..made.clone() }).perms_metadata_mismatch(), "neither"); + // A /Perms that doesn't read as an `adb` block says nothing; R4 has none. + assert!(!open(&EncryptDict { perms: vec![0; 16], encrypt_metadata: false, ..made }).perms_metadata_mismatch()); + assert!(!new(Algorithm::Aes128, "user", "owner", -4).perms_metadata_mismatch()); +} + #[test] fn r2_create_sets_every_bit_revision_2_reserves() { // ISO 32000-1 section 7.6.3.2: -44 permits printing and copying only. diff --git a/crates/pdf/src/lib.rs b/crates/pdf/src/lib.rs index 7356ab743..8893a84b0 100644 --- a/crates/pdf/src/lib.rs +++ b/crates/pdf/src/lib.rs @@ -25,6 +25,8 @@ pub use read::*; pub mod paths; #[cfg(feature = "raster")] pub mod raster; +#[cfg(all(feature = "cos", any(test, feature = "test-support")))] +pub mod testing; #[cfg(feature = "write")] pub mod write; #[cfg(feature = "write-raster")] diff --git a/crates/pdf/src/testing.rs b/crates/pdf/src/testing.rs new file mode 100644 index 000000000..c829f5458 --- /dev/null +++ b/crates/pdf/src/testing.rs @@ -0,0 +1,16 @@ +//! Test support (feature `test-support`): builds small synthetic PDF files in code, so that crates +//! which read PDF files can test with a real file instead of a binary fixture. +//! +//! ``` +//! use craft_pdf::testing::Pdf; +//! +//! let bytes = Pdf::new() +//! .obj("<< /Type /Catalog /Pages 2 0 R >>") +//! .obj("<< /Type /Pages /Kids [3 0 R] /Count 1 >>") +//! .obj("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 300] /Contents 4 0 R >>") +//! .stream("", b"0 0 50 50 re f") +//! .build(); +//! assert!(bytes.starts_with(b"%PDF-1.7\n")); +//! ``` + +pub use crate::cos::testkit::Pdf; diff --git a/crates/pdf/tests/cos/encryption.rs b/crates/pdf/tests/cos/encryption.rs index 2ac53cb69..407de7826 100644 --- a/crates/pdf/tests/cos/encryption.rs +++ b/crates/pdf/tests/cos/encryption.rs @@ -1319,3 +1319,181 @@ fn selectors_that_lead_to_selectors_load_at_once() { // margin this wide can't fail on a busy machine. assert_eq!(finished.recv_timeout(std::time::Duration::from_secs(120)), Ok(true), "loading must not fan out"); } + +/// An R6 file of the fixture's page, its `/Encrypt` given `cf` as `/CF` and `selectors` (`/StmF`, +/// `/StrF`, `/EFF`), its content stream `extra` in its dictionary and `data` as stored (the page +/// encrypted with the file key when `None`), and its `/Info /Title` encrypted with the file key. +fn r6_file(cf: &str, selectors: &str, extra: &str, data: Option<&[u8]>) -> Vec { + const ID0: &[u8] = b"0123456789abcdef"; + let params = NewEncryption { + algorithm: Algorithm::Aes256, + user_password: "user", + owner_password: "owner", + permissions: -4, + encrypt_metadata: true, + seed: [3; 32], + }; + let h = craft_pdf::crypt::create(¶ms, ID0).unwrap(); + let d = h.dict(); + let hex = |b: &[u8]| b.iter().map(|x| format!("{x:02X}")).collect::(); + let encrypt = format!( + "<< /Filter /Standard /V 5 /R 6 /Length 256 /P -4 /O <{}> /U <{}> /OE <{}> /UE <{}> /Perms <{}> /CF << {cf} >> {selectors} >>", + hex(&d.o), + hex(&d.u), + hex(&d.oe), + hex(&d.ue), + hex(&d.perms) + ); + let data = data.map_or_else(|| h.encrypt_stream(4, 0, SECRET.as_bytes(), craft_pdf::crypt::StreamKind::Normal), <[u8]>::to_vec); + let title = h.encrypt_string(6, 0, b"Quarterly numbers"); + let mut stream = format!("<< /Length {}{extra} >>\nstream\n", data.len()).into_bytes(); + stream.extend_from_slice(&data); + stream.extend_from_slice(b"\nendstream"); + let objs: Vec> = vec![ + b"<< /Type /Catalog /Pages 2 0 R >>".to_vec(), + b"<< /Type /Pages /Kids [3 0 R] /Count 1 /MediaBox [0 0 300 200] >>".to_vec(), + b"<< /Type /Page /Parent 2 0 R /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>".to_vec(), + stream, + b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>".to_vec(), + format!("<< /Title <{}> >>", hex(&title)).into_bytes(), + encrypt.into_bytes(), + ]; + let mut out = b"%PDF-2.0\n".to_vec(); + let mut offsets = Vec::new(); + for (i, o) in objs.iter().enumerate() { + offsets.push(out.len()); + out.extend_from_slice(format!("{} 0 obj\n", i + 1).as_bytes()); + out.extend_from_slice(o); + out.extend_from_slice(b"\nendobj\n"); + } + let xref = out.len(); + out.extend_from_slice(format!("xref\n0 {}\n0000000000 65535 f \n", objs.len() + 1).as_bytes()); + for o in offsets { + out.extend_from_slice(format!("{o:010} 00000 n \n").as_bytes()); + } + let id = hex(ID0); + let trailer = + format!("trailer\n<< /Size {} /Root 1 0 R /Info 6 0 R /Encrypt 7 0 R /ID [<{id}> <{id}>] >>\nstartxref\n{xref}\n%%EOF\n", objs.len() + 1); + out.extend_from_slice(trailer.as_bytes()); + out +} + +const STD_CF: &str = "/StdCF << /Type /CryptFilter /CFM /AESV3 /Length 32 /AuthEvent /DocOpen >>"; + +/// ISO 32000-2 Table 25: a `/CFM` other than `None`, `V2`, `AESV2` or `AESV3` is to be reported +/// as an algorithm the file is encrypted with and can't be read with. When strings, streams or +/// embedded files use it, the file doesn't open, with any password (it opened, its page and title read as ciphertext). `/CFM /None`, or none, leaves data +/// as it is. +#[test] +fn a_crypt_filter_method_that_cant_be_decrypted_is_reported() { + let unknown = |cfm: &str| format!("{STD_CF} /X << /CFM {cfm} /Length 32 >>"); + for cfm in ["/AESV9", "/Identity", "3", "(AESV3)"] { + for selectors in ["/StmF /X /StrF /X", "/StmF /X /StrF /StdCF", "/StmF /StdCF /StrF /X", "/StmF /StdCF /StrF /StdCF /EFF /X"] { + let bytes = Arc::new(r6_file(&unknown(cfm), selectors, "", None)); + for pw in [Some("user"), Some("owner"), Some("wrong"), None] { + match Document::open_with_password(bytes.clone(), pw) { + Err(CosError::Security(why)) => assert!(why.contains("unsupported algorithm"), "{cfm} {selectors}: {why}"), + other => panic!("{cfm} {selectors} with {pw:?}: {:?}", other.map(|_| ())), + } + } + } + } + // Defined and used by nothing: the file opens (as in qpdf, MuPDF and PDFium). + let unused = Arc::new(r6_file(&unknown("/AESV9"), "/StmF /StdCF /StrF /StdCF", "", None)); + let doc = Document::open_with_password(unused, Some("user")).unwrap(); + assert_eq!((content(&doc).as_str(), title(&doc).as_deref()), (SECRET, Some("Quarterly numbers"))); + // `/CFM /None`, a null one, or none: the data is as stored. + for cfm in ["/CFM /None", "/CFM null", ""] { + let clear = Arc::new(r6_file(&format!("{STD_CF} /Clear << {cfm} >>"), "/StmF /Clear /StrF /StdCF", "", Some(SECRET.as_bytes()))); + let doc = Document::open_with_password(clear, Some("user")).unwrap(); + assert_eq!((content(&doc).as_str(), title(&doc).as_deref()), (SECRET, Some("Quarterly numbers")), "{cfm}"); + } +} + +/// A stream naming, for itself, a crypt filter whose method can't be decrypted holds data as +/// stored, which isn't the stream it encrypts: the document opens, the stream reads as stored, and +/// a save never writes it as anything else. An incremental save keeps it as it is; a full save, +/// which renumbers it, and a save that removes or changes the security are refused (they wrote its +/// ciphertext as plaintext, or under a key it wasn't made with). +#[test] +fn a_stream_encrypted_with_a_method_that_cant_be_decrypted_stays_as_stored() { + let stored = "ciphertext of an unknown method"; + let bytes = Arc::new(r6_file( + &format!("{STD_CF} /X << /CFM /AESV9 /Length 32 >>"), + "/StmF /StdCF /StrF /StdCF", + " /Filter /Crypt /DecodeParms << /Name /X >>", + Some(stored.as_bytes()), + )); + let doc = Document::open_with_password(bytes.clone(), Some("owner")).unwrap(); + assert_eq!(raw_content(&doc), stored); + let contents = contents_of(&doc); + let Object::Stream(s) = doc.get(contents).as_ref().clone() else { panic!("no content stream") }; + assert!(doc.reads_as_stored(&s)); + assert_eq!(title(&doc).as_deref(), Some("Quarterly numbers"), "the rest decrypts"); + // An edit elsewhere: incremental, the stream untouched and still as stored. + let mut edited_info = doc.clone(); + let info = edited_info.trailer().reference(b"Info").unwrap(); + let mut d = craft_pdf::cos::Dict::new(); + d.set(b"Title".to_vec(), Object::String(PdfString::text("Edited"))); + edited_info.set(info, Object::Dict(d)); + let saved = write_incremental(&edited_info, &SaveOptions::default()).unwrap(); + assert!(holds(&saved, stored)); + let reread = Document::open_with_password(Arc::new(saved), Some("owner")).unwrap(); + assert_eq!((raw_content(&reread).as_str(), title(&reread).as_deref()), (stored, Some("Edited"))); + let refused = |doc: &Document, case: &str| match write_full(doc, &SaveOptions::default()) { + Err(CosError::Security(why)) => assert!(why.contains("unsupported algorithm"), "{case}: {why}"), + other => panic!("{case}: {:?}", other.map(|b| b.len())), + }; + refused(&doc, "a full save"); + // A catalog naming the stream first has a full save number it 4 again (after the catalog, + // /Info and /Encrypt). Refused all the same: written as `4 0 obj` whatever its generation was, + // and through a full save, which the security of such a stream doesn't survive. + let mut same_number = doc.clone(); + let root = same_number.trailer().reference(b"Root").unwrap(); + let mut catalog = craft_pdf::cos::Dict::new(); + catalog.set(b"A".to_vec(), Object::Ref(contents)); + catalog.set(b"Type".to_vec(), Object::name("Catalog")); + catalog.set(b"Pages".to_vec(), Object::Ref(ObjRef::new(2, 0))); + same_number.set(root, Object::Dict(catalog)); + let no_mod_date = SaveOptions { mod_date: None, ..SaveOptions::default() }; + match write_full(&same_number, &no_mod_date) { + Err(CosError::Security(why)) => assert!(why.contains("unsupported algorithm"), "{why}"), + other => panic!("a full save that keeps the stream's number: {:?}", other.map(|b| b.len())), + } + let mut unprotected = doc.clone(); + unprotected.remove_encryption(); + refused(&unprotected, "removing the security"); + assert!(matches!(write_incremental(&unprotected, &SaveOptions::default()), Err(CosError::Security(_))), "incremental removal"); + let mut changed = doc.clone(); + changed + .set_encryption(&NewEncryption { + algorithm: Algorithm::Aes128, + user_password: "", + owner_password: "o", + permissions: -1, + encrypt_metadata: true, + seed: [1; 32], + }) + .unwrap(); + refused(&changed, "changing the security"); + // The stream edited: it would be written as if encrypted with the method. + let mut edited = doc.clone(); + edited.set(contents, Object::Stream(s)); + assert!(matches!(write_incremental(&edited, &SaveOptions::default()), Err(CosError::Security(_))), "an edited stream"); +} + +/// Algorithm 13 (ISO 32000-2 §7.6.4.4.12): byte 8 of `/Perms` "should match" `/EncryptMetadata`. +/// A file where it doesn't opens as before, with a repair-log line (qpdf warns of it; MuPDF and +/// PDFium open such files). +#[test] +fn a_perms_entry_that_disagrees_with_encrypt_metadata_is_recorded() { + let lines = |selectors: &str| { + let doc = Document::open_with_password(Arc::new(r6_file(STD_CF, selectors, "", None)), Some("user")).unwrap(); + assert_eq!(content(&doc), SECRET, "{selectors}"); + doc.repair_log().iter().filter(|l| l.contains("/Perms")).count() + }; + // The file's /Perms says T (metadata encrypted). + assert_eq!(lines("/StmF /StdCF /StrF /StdCF"), 0); + assert_eq!(lines("/StmF /StdCF /StrF /StdCF /EncryptMetadata true"), 0); + assert_eq!(lines("/StmF /StdCF /StrF /StdCF /EncryptMetadata false"), 1); +} 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/crates/pdf/tests/knockout_backdrop.rs b/crates/pdf/tests/knockout_backdrop.rs new file mode 100644 index 000000000..f56fa12a6 --- /dev/null +++ b/crates/pdf/tests/knockout_backdrop.rs @@ -0,0 +1,206 @@ +//! #870: a non-isolated knockout group (`/I false /K true`) starts from the backdrop under it +//! (ISO 32000-2 §11.4.7, §11.4.8), so each element blends with the page there, in its own blend +//! mode, and replaces the elements before it under its shape. White with `/BM /Difference` over +//! magenta is green; drawn into a layer of its own starting transparent, it stayed white. +//! Adapted from PdfCraft #4898 (`it::knockout_backdrop` in pdfcraft-render at +//! 6a76d280168ebad42198de184d03ac11bf31f647, MIT OR Apache-2.0). +#![cfg(feature = "raster")] + +use craft_pdf::interpret::InterpreterSettings; +use craft_pdf::{ + open_slice, + raster::{self, Options, RenderCache}, +}; + +const MAGENTA: [u8; 3] = [255, 0, 255]; +const GREEN: [u8; 3] = [0, 255, 0]; +const WHITE: [u8; 3] = [255, 255, 255]; + +fn pdf(objects: &[String]) -> Vec { + let mut out = b"%PDF-1.7\n".to_vec(); + let mut offsets = Vec::new(); + for (i, body) in objects.iter().enumerate() { + offsets.push(out.len()); + out.extend_from_slice(format!("{} 0 obj\n{body}\nendobj\n", i + 1).as_bytes()); + } + let xref = out.len(); + out.extend_from_slice(format!("xref\n0 {}\n0000000000 65535 f \n", objects.len() + 1).as_bytes()); + for offset in offsets { + out.extend_from_slice(format!("{offset:010} 00000 n \n").as_bytes()); + } + out.extend_from_slice(format!("trailer\n<< /Size {} /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n", objects.len() + 1).as_bytes()); + out +} + +fn stream(dict: &str, content: &str) -> String { + format!("<< {dict} /Length {} >>\nstream\n{content}\nendstream", content.len()) +} + +/// Renders a 200 x 200 page: magenta, then the group `/Fk` with group attributes `group` and +/// content `content`. Its resources have `/D` (`/BM /Difference`), `/N` (`/BM /Normal`), `/H` +/// (`/ca 0.5`), `/W`, a white square from 40 to 160 in a group of its own, `/Nest`, a group +/// holding a non-isolated knockout group with a white Difference square from 80 to 120, and +/// `/Img`, a white 1 x 1 image, `/Img2`, a blue 2 x 1 image whose soft mask is opaque on the +/// left and transparent on the right, `/St`, a 2 x 1 stencil mask painting its left pixel, and +/// the shading `/Sh0`, a mesh whose one triangle lies off the page, and `/Sh1`, a red mesh +/// triangle from (90, 90) to (110, 90) and (100, 110). +/// Returns a lookup of the colour at PDF point (x, y). +fn render(group: &str, content: &str) -> impl Fn(u32, u32) -> [u8; 3] { + let gs = "/ExtGState << /D << /BM /Difference >> /H << /ca 0.5 >> /N << /BM /Normal >> >>"; + let objects = [ + "<< /Type /Catalog /Pages 2 0 R >>".to_string(), + "<< /Type /Pages /Kids [3 0 R] /Count 1 >>".to_string(), + "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] /Contents 4 0 R /Group << /S /Transparency /CS /DeviceRGB >> /Resources << /XObject << /Fk 5 0 R >> >> >>" + .to_string(), + stream("", "1 0 1 rg 0 0 200 200 re f /Fk Do"), + stream( + &format!("/Type /XObject /Subtype /Form /BBox [0 0 200 200] /Group << /S /Transparency /CS /DeviceRGB {group} >> /Resources << {gs} /XObject << /W 6 0 R /Nest 7 0 R /Img 9 0 R /Img2 10 0 R /St 12 0 R >> /Shading << /Sh0 13 0 R /Sh1 14 0 R >> >>"), + content, + ), + stream("/Type /XObject /Subtype /Form /BBox [0 0 200 200] /Group << /S /Transparency >>", "1 1 1 rg 40 40 120 120 re f"), + stream("/Type /XObject /Subtype /Form /BBox [0 0 200 200] /Group << /S /Transparency >> /Resources << /XObject << /K2 8 0 R >> >>", "/K2 Do"), + stream( + &format!("/Type /XObject /Subtype /Form /BBox [0 0 200 200] /Group << /S /Transparency /I false /K true >> /Resources << {gs} >>"), + "/D gs 1 1 1 rg 80 80 40 40 re f", + ), + stream("/Type /XObject /Subtype /Image /Width 1 /Height 1 /ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /ASCIIHexDecode", "FFFFFF>"), + stream( + "/Type /XObject /Subtype /Image /Width 2 /Height 1 /ColorSpace /DeviceRGB /BitsPerComponent 8 /SMask 11 0 R /Filter /ASCIIHexDecode", + "0000FF0000FF>", + ), + stream("/Type /XObject /Subtype /Image /Width 2 /Height 1 /ColorSpace /DeviceGray /BitsPerComponent 8 /Filter /ASCIIHexDecode", "FF00>"), + stream("/Type /XObject /Subtype /Image /Width 2 /Height 1 /ImageMask true /BitsPerComponent 1 /Filter /ASCIIHexDecode", "40>"), + stream( + "/ShadingType 4 /ColorSpace /DeviceRGB /BitsPerCoordinate 8 /BitsPerComponent 8 /BitsPerFlag 8 /Decode [300 310 300 310 0 1 0 1 0 1] /Filter /ASCIIHexDecode", + "000000FF0000 00FF00FF0000 0000FFFF0000>", + ), + stream( + "/ShadingType 4 /ColorSpace /DeviceRGB /BitsPerCoordinate 8 /BitsPerComponent 8 /BitsPerFlag 8 /Decode [0 255 0 255 0 1 0 1 0 1] /Filter /ASCIIHexDecode", + "005A5AFF0000 006E5AFF0000 00646EFF0000>", + ), + ]; + let pdf = pdf(&objects); + let doc = open_slice(&pdf, None).unwrap(); + let options = Options { background: [255; 4], ..Default::default() }; + let raster = raster::render(&doc.pages()[0], &RenderCache::new(), &InterpreterSettings::default(), &options).unwrap(); + let (rgba, width) = (raster.bytes().to_vec(), raster.width); + move |x, y| { + // Pixel rows run top down. + let offset = usize::try_from(((200 - y) * width + x) * 4).unwrap(); + [rgba[offset], rgba[offset + 1], rgba[offset + 2]] + } +} + +fn check(at: &impl Fn(u32, u32) -> [u8; 3], x: u32, y: u32, want: [u8; 3], what: &str) { + let got = at(x, y); + assert!(got.iter().zip(want).all(|(a, b)| a.abs_diff(b) <= 2), "{what} at ({x}, {y}): {got:?}, expected {want:?}"); +} + +const NON_ISOLATED: &str = "/I false /K true"; +const SQUARES: &str = "/D gs 1 1 1 rg 20 20 110 110 re f 70 70 110 110 re f"; + +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn a_non_isolated_knockout_group_blends_each_element_with_the_page() { + let squares = render(NON_ISOLATED, SQUARES); + check(&squares, 40, 40, GREEN, "first square"); + check(&squares, 160, 160, GREEN, "second square"); + // The second square blends with the page, not with the first: green, not magenta again. + check(&squares, 100, 100, GREEN, "overlap"); + check(&squares, 190, 10, MAGENTA, "page outside the group's elements"); +} + +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn the_last_element_over_a_point_decides_its_blend_mode() { + // Normal blue at 50 % after a Difference square: blue over the page where they overlap. + let blue_last = render(NON_ISOLATED, "/D gs 1 1 1 rg 20 20 110 110 re f /N gs 0 0 1 rg q /H gs 70 70 110 110 re f Q"); + check(&blue_last, 40, 40, GREEN, "Difference alone"); + check(&blue_last, 100, 100, [128, 0, 255], "Normal blue last"); + check(&blue_last, 160, 160, [128, 0, 255], "Normal blue alone"); + // The other way round: the Difference square replaces the blue and blends with the page. + let white_last = render(NON_ISOLATED, "q /H gs 0 0 1 rg 20 20 110 110 re f Q /D gs 1 1 1 rg 70 70 110 110 re f"); + check(&white_last, 40, 40, [128, 0, 255], "Normal blue alone"); + check(&white_last, 100, 100, GREEN, "Difference last"); +} + +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn a_nested_group_in_a_non_isolated_knockout_group_blends_with_the_page() { + let nested = render(NON_ISOLATED, "0 0 1 rg 20 20 160 160 re f /D gs /W Do"); + check(&nested, 100, 100, GREEN, "nested group drawn with Difference over the knocked-out blue"); + check(&nested, 30, 30, [0, 0, 255], "blue beside the nested group"); +} + +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn an_isolated_knockout_group_still_starts_transparent() { + let isolated = render("/I true /K true", SQUARES); + check(&isolated, 40, 40, WHITE, "isolated: nothing to blend with"); + check(&isolated, 100, 100, WHITE, "isolated overlap"); +} + +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn an_image_and_a_partly_transparent_element_blend_with_the_page() { + let image = render(NON_ISOLATED, "/D gs q 120 0 0 120 40 40 cm /Img Do Q"); + check(&image, 100, 100, GREEN, "white image drawn with Difference"); + check(&image, 20, 20, MAGENTA, "page beside the image"); + // Difference at 50 %: half the page, half the blend result (green). + let half = render(NON_ISOLATED, "/D gs /H gs 1 1 1 rg 40 40 120 120 re f"); + check(&half, 100, 100, [128, 128, 128], "Difference at 50 %"); +} + +/// A knockout group nested in another one's element is drawn first in that element's erase +/// pass, which must leave the outer group's passes alone. +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn a_knockout_group_inside_an_element_keeps_the_outer_groups_passes() { + let nested = render(NON_ISOLATED, "/D gs 1 1 1 rg 10 10 50 50 re f /N gs /Nest Do /D gs 1 1 1 rg 140 140 50 50 re f"); + check(&nested, 30, 30, GREEN, "Difference square before the nested groups"); + check(&nested, 165, 165, GREEN, "Difference square after the nested groups"); +} + +/// A masked image (or, below, a stencil) in another pass than its own replaces what is under +/// its mask there too: a blue image over a white Difference square stays blue where its mask is +/// opaque, and leaves the square to blend with the page where it is transparent. +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn a_masked_image_replaces_what_is_under_its_mask_in_every_pass() { + let masked = render(NON_ISOLATED, "/D gs 1 1 1 rg 40 40 120 120 re f /N gs q 120 0 0 120 40 40 cm /Img2 Do Q"); + check(&masked, 60, 100, [0, 0, 255], "image over the square, mask opaque"); + check(&masked, 140, 100, GREEN, "square under the transparent half of the mask"); +} + +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn a_stencil_replaces_what_is_under_it_in_every_pass() { + let stencil = render(NON_ISOLATED, "/D gs 1 1 1 rg 40 40 120 120 re f /N gs 0 0 1 rg q 120 0 0 120 40 40 cm /St Do Q"); + check(&stencil, 60, 100, [0, 0, 255], "stencil over the square"); + check(&stencil, 140, 100, GREEN, "square beside the stencil"); +} + +/// A shading that paints nothing (a mesh off the page) replaces nothing in another pass either. +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn a_shading_that_paints_nothing_clears_nothing_in_another_pass() { + let mesh = render(NON_ISOLATED, "0 0 1 rg 20 20 160 160 re f /D gs /Sh0 sh"); + check(&mesh, 100, 100, [0, 0, 255], "blue under an off-page Difference mesh"); +} + +/// A shading replaces only what is under the part it paints: a small mesh triangle over a +/// square leaves the rest of the square, in its own pass, in another pass and in an isolated +/// knockout group. +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn a_small_mesh_replaces_only_what_is_under_its_triangle() { + let square = "0 0 1 rg 20 20 160 160 re f"; + for (group, mode) in [(NON_ISOLATED, ""), (NON_ISOLATED, "/D gs"), ("/K true", "")] { + let content = format!("{square} {mode} /Sh1 sh"); + let mesh = render(group, &content); + check(&mesh, 40, 40, [0, 0, 255], &format!("{group} {mode}: square beside the triangle")); + if mode.is_empty() { + check(&mesh, 100, 97, [255, 0, 0], &format!("{group}: triangle")); + } + } +} diff --git a/crates/pdf/tests/plates.rs b/crates/pdf/tests/plates.rs index 41e6d653e..e466778d0 100644 --- a/crates/pdf/tests/plates.rs +++ b/crates/pdf/tests/plates.rs @@ -516,6 +516,31 @@ fn a_knockout_group_separates_with_only_the_top_object_in_the_overlap() { assert_eq!(blended.at(20, 20), [25, 50, 0, 0], "both squares without /K"); } +/// #870: in a non-isolated knockout group each element composites with the group's backdrop in +/// its own blend mode (ISO 32000-2 §11.4.6, §11.4.8). Magenta, then cyan over it, both Multiply, +/// over a yellow page keep the yellow under them, and the cyan replaces the magenta where they +/// overlap. Drawn into a layer starting transparent, the yellow was knocked out. +#[cfg_attr(not(target_arch = "wasm32"), test)] +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +fn a_non_isolated_knockout_group_multiplies_each_element_with_its_backdrop() { + let form = "/M gs 0 1 0 0 k 5 5 20 20 re f 1 0 0 0 k 15 15 20 20 re f"; + let pdf = page_pdf( + "0 0 1 0 k 0 0 40 40 re f /Fm Do", + "/XObject << /Fm 5 0 R >>", + &[stream( + "/Type /XObject /Subtype /Form /BBox [0 0 40 40] /Group << /S /Transparency /CS /DeviceCMYK /K true >> /Resources << /ExtGState << /M << /BM /Multiply >> >> >>", + form.as_bytes(), + )], + ); + // Device rows run top down: magenta alone at (8, 32), the overlap at (20, 20), cyan alone at + // (32, 8), the page alone at (37, 37). + let s = plates(&pdf, &inks(&[]), true, None); + assert_eq!(s.at(8, 32), [0, 100, 100, 0], "magenta multiplied with the yellow"); + assert_eq!(s.at(20, 20), [100, 0, 100, 0], "cyan replaces the magenta, multiplied with the yellow"); + assert_eq!(s.at(32, 8), [100, 0, 100, 0], "cyan multiplied with the yellow"); + assert_eq!(s.at(37, 37), [0, 0, 100, 0], "the page"); +} + /// PdfCraft #3018: `/DefaultCMYK` and `/DefaultGray` change how device color looks, not the /// inks it prints with. Under them DeviceCMYK still separates as its components (and keeps the /// nonzero overprint mode), a DeviceCMYK image sample by sample, and DeviceGray on black alone, diff --git a/crates/pdf/tests/testing_pdf.rs b/crates/pdf/tests/testing_pdf.rs new file mode 100644 index 000000000..81fa98189 --- /dev/null +++ b/crates/pdf/tests/testing_pdf.rs @@ -0,0 +1,52 @@ +//! `craft_pdf::testing::Pdf`, the builder other crates' tests reach through `test-support`: a file +//! it builds opens in the object layer with every object where the cross-reference table says. +#![cfg(feature = "test-support")] +#![allow(clippy::unwrap_used, clippy::panic)] + +use std::sync::Arc; + +use craft_pdf::cos::{Document, ObjRef, Object, XrefEntry}; +use craft_pdf::testing::Pdf; + +fn one_page() -> Pdf { + Pdf::new() + .version("1.4") + .obj("<< /Type /Catalog /Pages 2 0 R >>") + .obj("<< /Type /Pages /Kids [3 0 R] /Count 1 >>") + .obj("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 300] /Contents 4 0 R >>") + .stream("", b"0 0 50 50 re f") + .trailer_entry("/Info 5 0 R") + .obj("<< /Title (Fixture) >>") +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[cfg_attr(not(target_arch = "wasm32"), test)] +fn a_built_file_opens_without_repair() { + let bytes = one_page().build(); + assert!(bytes.starts_with(b"%PDF-1.4\n")); + assert!(bytes.ends_with(b"%%EOF\n")); + + let doc = Document::open(Arc::new(bytes)).unwrap(); + assert!(!doc.reconstructed(), "the cross-reference table is exact: {:?}", doc.repair_log()); + assert_eq!(doc.version(), "1.4"); + assert_eq!(doc.root(), Some(ObjRef::new(1, 0))); + for num in 1..=5 { + assert!(matches!(doc.xref_entry(num), Some(XrefEntry::InFile { generation: 0, .. })), "object {num} is in the table"); + assert!(doc.xref_entry_is_exact(num), "object {num} is at its table offset"); + } + assert_eq!(doc.xref_entry(6), None); + let Object::Stream(contents) = &*doc.get(ObjRef::new(4, 0)) else { panic!("object 4 is the content stream") }; + assert_eq!(contents.decoded().unwrap(), b"0 0 50 50 re f"); + assert_eq!(doc.trailer().get(b"Info"), Some(&Object::Ref(ObjRef::new(5, 0)))); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[cfg_attr(not(target_arch = "wasm32"), test)] +fn next_obj_names_the_object_added_next() { + let pdf = one_page(); + assert_eq!(pdf.next_obj(), 6); + let doc = Document::open(Arc::new(pdf.obj("<< /Marker true >>").build())).unwrap(); + assert!(matches!(doc.xref_entry(6), Some(XrefEntry::InFile { .. }))); + assert!(doc.xref_entry_is_exact(6)); + assert_eq!(doc.dict(&doc.get(ObjRef::new(6, 0))).and_then(|d| d.get(b"Marker").cloned()), Some(Object::Bool(true))); +} 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..ef35e062b 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`). @@ -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 @@ -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..584331fb2 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,11 +30,16 @@ 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}; 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, + write_prc, +}; 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]]]); +} 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])); + } +} diff --git a/crates/prepress/README.md b/crates/prepress/README.md index fe559e8d4..6da17e334 100644 --- a/crates/prepress/README.md +++ b/crates/prepress/README.md @@ -163,7 +163,9 @@ let worst = over.regions().first().copied(); `Plates::composite_to(enabled, &output)` returns the enabled inks in an output profile, for a print or a proof. `Output::new(press, output, intent, bpc)` takes the press's CMYK profile -(`CmsConversion::profile`) and a gray, RGB or CMYK output profile: +(`CmsConversion::profile`) and a gray, RGB or CMYK output profile. `press_profile(pdf, page, +&opts)` returns the press a page's plates separate through (its output intent's profile, else +the fallback's; `None` for the device formulas), so the composite converts from the same one: - the process plates convert from the press straight to the output (CMYK to PCS to output), not through sRGB, at `intent`, with black point compensation when `bpc`. Relative diff --git a/crates/prepress/src/flatten/compose.rs b/crates/prepress/src/flatten/compose.rs index fc5f2ef4b..433f11f58 100644 --- a/crates/prepress/src/flatten/compose.rs +++ b/crates/prepress/src/flatten/compose.rs @@ -303,6 +303,7 @@ fn flatten_group( isolated: false, knockout: false, clip: None, + clip_rule: FillRule::NonZero, mask: None, actual_text: Some(text), children, @@ -614,7 +615,7 @@ impl<'a> Builder<'a> { let outer = self.push_tag(g.actual_text.as_deref()); if let Some(clip) = &g.clip { self.clip_stack.push(self.clips.len()); - self.clips.push(ClipPath { path: clip.clone(), rule: FillRule::NonZero }); + self.clips.push(ClipPath { path: clip.clone(), rule: g.clip_rule }); } let masked = masked || g.mask.is_some(); let (plain_path, knockout_path) = (self.plain_path, self.knockout_path); @@ -900,7 +901,17 @@ mod tests { } fn group(opacity: f32, blend: BlendMode, children: Vec) -> GroupItem { - GroupItem { opacity, blend, isolated: false, knockout: false, clip: None, mask: None, actual_text: None, children } + GroupItem { + opacity, + blend, + isolated: false, + knockout: false, + clip: None, + clip_rule: FillRule::NonZero, + mask: None, + actual_text: None, + children, + } } fn list(inks: InkSet, items: Vec) -> DisplayList { @@ -1017,6 +1028,18 @@ mod tests { assert_eq!(at(&flat(&list(InkSet::new(), vec![Item::Group(g)])), 75.0, 50.0, &[C, M]).1, [0.0, 0.5]); } + #[test] + fn even_odd_clip_leaves_its_hole_unpainted() { + // Two nested squares drawn in the same direction: filled even-odd, the inner one is a hole. + let mut ring = Rect::new(0.0, 0.0, 100.0, 100.0).to_path(0.1); + ring.extend(Rect::new(25.0, 25.0, 75.0, 75.0).to_path(0.1)); + let half_black = Item::Group(group(0.5, BlendMode::Normal, vec![solid(Rect::new(0.0, 0.0, 100.0, 100.0), &[(K, 1.0)])])); + let clip = GroupItem { clip: Some(ring), clip_rule: FillRule::EvenOdd, ..group(1.0, BlendMode::Normal, vec![half_black]) }; + let f = flat(&list(InkSet::new(), vec![solid(Rect::new(0.0, 0.0, 100.0, 100.0), &[(C, 1.0)]), Item::Group(clip)])); + assert_eq!(at(&f, 10.0, 50.0, &[C, K]).1, [0.5, 0.5]); + assert_eq!(at(&f, 50.0, 50.0, &[C, K]).1, [1.0, 0.0], "the hole shows the cyan under it"); + } + #[test] fn isolated_group_blends_without_the_backdrop() { let scene = |isolated| { diff --git a/crates/prepress/src/flatten/mod.rs b/crates/prepress/src/flatten/mod.rs index 860d9ed7b..1aa5c4392 100644 --- a/crates/prepress/src/flatten/mod.rs +++ b/crates/prepress/src/flatten/mod.rs @@ -156,8 +156,11 @@ pub struct GroupItem { pub blend: BlendMode, pub isolated: bool, pub knockout: bool, - /// Nonzero clip in page space. + /// Clip in page space, filled by `clip_rule`. pub clip: Option, + /// The fill rule of `clip`. The PDF reader rebuilds an even-odd clip as a nonzero path, + /// and keeps the path even-odd when the rebuild fails. + pub clip_rule: FillRule, pub mask: Option>, /// The Unicode text the children show, for content drawn as items that is text in the /// source, such as a colored Type 3 glyph. diff --git a/crates/prepress/src/flatten/pdf.rs b/crates/prepress/src/flatten/pdf.rs index 2a472f460..0e7108fc0 100644 --- a/crates/prepress/src/flatten/pdf.rs +++ b/crates/prepress/src/flatten/pdf.rs @@ -320,7 +320,22 @@ struct Reader<'s, 'a> { } fn plain_group(clip: Option) -> GroupItem { - GroupItem { opacity: 1.0, blend: BlendMode::Normal, isolated: false, knockout: false, clip, mask: None, actual_text: None, children: Vec::new() } + GroupItem { + opacity: 1.0, + blend: BlendMode::Normal, + isolated: false, + knockout: false, + clip, + clip_rule: FillRule::NonZero, + mask: None, + actual_text: None, + children: Vec::new(), + } +} + +/// A plain group clipping to `clip` filled by `rule`. +fn clip_group((clip, rule): (BezPath, FillRule)) -> GroupItem { + GroupItem { clip_rule: rule, ..plain_group(Some(clip)) } } impl<'s, 'a> Reader<'s, 'a> { @@ -601,16 +616,16 @@ impl<'s, 'a> Reader<'s, 'a> { fn area_fill(&mut self, path: BezPath, rule: FillRule, paint: &PdfPaint<'a>, stroke: bool) { let PdfPaint::Pattern(pattern) = paint else { return }; self.flush(); - let clip = nonzero(&path, rule); + let (clip, rule) = nonzero(&path, rule); let (op, big_op, _) = self.overprint; let flag = if stroke { big_op } else { op }; match pattern.as_ref() { - Pattern::Shading(sp) => self.shading_area(clip, sp, flag), - Pattern::Tiling(t) => self.tiling_area(clip, t, flag, stroke), + Pattern::Shading(sp) => self.shading_area(clip, rule, sp, flag), + Pattern::Tiling(t) => self.tiling_area(clip, rule, t, flag, stroke), } } - fn shading_area(&mut self, clip: BezPath, sp: &ShadingPattern, flag: bool) { + fn shading_area(&mut self, clip: BezPath, rule: FillRule, sp: &ShadingPattern, flag: bool) { let look = self.look(sp.opacity); let cs = &sp.shading.color_space; // Nonzero overprint mode is for colors set in DeviceCMYK, not shadings or images @@ -625,12 +640,12 @@ impl<'s, 'a> Reader<'s, 'a> { if let Some((inks, channels)) = self.space_inks(&space, cs) { let kind = inks.stop_inks(); let paint = Paint::Solid(shade::stop_color(&kind, &channels.apply_f32(&values))); - children.push(Item::Fill(FillItem { path: clip.clone(), rule: FillRule::NonZero, paint, overprint })); + children.push(Item::Fill(FillItem { path: clip.clone(), rule, paint, overprint })); } } let shaded = if matches!(sp.shading.shading_type.as_ref(), ShadingType::RadialAxial { .. }) { self.gradient(sp).map(|(paint, extent)| { - let fill = Item::Fill(FillItem { path: clip.clone(), rule: FillRule::NonZero, paint, overprint }); + let fill = Item::Fill(FillItem { path: clip.clone(), rule, paint, overprint }); match extent { Some(extent) => Item::Group(GroupItem { children: vec![fill], ..plain_group(Some(extent)) }), None => fill, @@ -646,7 +661,7 @@ impl<'s, 'a> Reader<'s, 'a> { } } if !children.is_empty() { - self.push(Item::Group(GroupItem { children, ..plain_group(Some(clip)) }), &look); + self.push(Item::Group(GroupItem { children, ..clip_group((clip, rule)) }), &look); } } @@ -684,7 +699,7 @@ impl<'s, 'a> Reader<'s, 'a> { /// A tiling pattern over `clip`: its cells, each read like page content, or an image past /// [`MAX_TILING_CELLS`] or [`MAX_TILING_ITEMS`]. - fn tiling_area(&mut self, clip: BezPath, t: &TilingPattern<'a>, flag: bool, stroke: bool) { + fn tiling_area(&mut self, clip: BezPath, rule: FillRule, t: &TilingPattern<'a>, flag: bool, stroke: bool) { let area = clip.bounding_box().intersect(self.clip_bounds()); if !(area.width() > 0.0 && area.height() > 0.0) { return; @@ -757,7 +772,7 @@ impl<'s, 'a> Reader<'s, 'a> { self.shared.report.rasterized_tilings += 1; vec![Item::Image(image)] }; - self.push(Item::Group(GroupItem { children: child, ..plain_group(Some(clip)) }), &look); + self.push(Item::Group(GroupItem { children: child, ..clip_group((clip, rule)) }), &look); } fn raster_image(&mut self, image: &RasterImage<'_>, transform: Affine) { @@ -948,14 +963,23 @@ impl<'s, 'a> Reader<'s, 'a> { let unicode = glyph.as_unicode().map(unicode); // A glyph that only fills in the text's paint (`d1`, or `d0` painting that color) is a // shape: it joins the run. + // Its outline is filled nonzero, so an even-odd fill that can't be rebuilt as nonzero + // keeps the glyph a group. let shape = items.iter().all(|item| matches!(item, Item::Fill(f) if Some(&f.paint) == run_paint.as_ref())); - if let (true, Some(run_paint)) = (shape, run_paint) { + let outline = shape.then(|| { let mut outline = BezPath::new(); for item in &items { if let Item::Fill(f) = item { - outline.extend(nonzero(&f.path, f.rule).iter()); + let (path, rule) = nonzero(&f.path, f.rule); + if rule != FillRule::NonZero { + return None; + } + outline.extend(path.iter()); } } + Some(outline) + }); + if let (Some(outline), Some(run_paint)) = (outline.flatten(), run_paint) { self.add_glyph(None, 0, transform * glyph_transform, outline, unicode, run_paint, look, overprint); } else if !items.is_empty() { self.flush(); @@ -988,7 +1012,7 @@ impl<'a> Device<'a> for Reader<'_, 'a> { fn push_clip_path(&mut self, clip_path: &ClipPath) { self.flush(); let clip = nonzero(&clip_path.path, fill_rule(clip_path.fill)); - self.frames.push(Frame { kind: FrameKind::Clip, group: plain_group(Some(clip)) }); + self.frames.push(Frame { kind: FrameKind::Clip, group: clip_group(clip) }); } fn push_transparency_group(&mut self, opacity: f32, mask: Option>, blend_mode: PdfBlend) { @@ -1287,11 +1311,12 @@ fn dash_pattern(path: &BezPath, dashes: &[f32]) -> Option> { (pieces.is_finite() && pieces <= MAX_DASHES_PER_STROKE).then(|| dashes.iter().map(|d| f64::from(*d)).collect()) } -/// `path` filled by `rule`, as a path filled nonzero. An even-odd path is rebuilt from its -/// boundary; if that fails it is kept as it is. -fn nonzero(path: &BezPath, rule: FillRule) -> BezPath { +/// `path` filled by `rule`, as a path and the rule it is filled by. An even-odd path is +/// rebuilt from its boundary as a path filled nonzero; if that fails it is kept closed and +/// filled even-odd. +fn nonzero(path: &BezPath, rule: FillRule) -> (BezPath, FillRule) { if rule == FillRule::NonZero { - return path.clone(); + return (path.clone(), FillRule::NonZero); } let closed = closed(path); match linesweeper::binary_op(&closed, &BezPath::new(), linesweeper::FillRule::EvenOdd, linesweeper::BinaryOp::Union) { @@ -1300,9 +1325,9 @@ fn nonzero(path: &BezPath, rule: FillRule) -> BezPath { for contour in contours.contours() { out.extend(contour.path.iter()); } - out + (out, FillRule::NonZero) } - Err(_) => closed, + Err(_) => (closed, FillRule::EvenOdd), } } @@ -1369,4 +1394,24 @@ mod tests { }); assert_eq!(item_count(&[fill]), 1 + path.elements().len()); } + + #[test] + fn even_odd_paths_keep_their_rule_when_the_rebuild_fails() { + // Two nested squares drawn in the same direction: even-odd leaves a hole, nonzero fills it. + let mut nested = Rect::new(0.0, 0.0, 100.0, 100.0).to_path(0.1); + nested.extend(Rect::new(25.0, 25.0, 75.0, 75.0).to_path(0.1)); + let (rebuilt, rule) = nonzero(&nested, FillRule::EvenOdd); + assert_eq!(rule, FillRule::NonZero); + assert_eq!(rebuilt.winding(Point::new(50.0, 50.0)), 0, "the hole"); + assert_ne!(rebuilt.winding(Point::new(10.0, 50.0)), 0); + + // An infinite coordinate makes the rebuild fail. + let mut broken = nested.clone(); + broken.move_to((f64::INFINITY, 0.0)); + broken.line_to((f64::INFINITY, 10.0)); + let (kept, rule) = nonzero(&broken, FillRule::EvenOdd); + assert_eq!(rule, FillRule::EvenOdd, "the path is still filled even-odd"); + assert_eq!(kept, closed(&broken)); + assert_eq!(nonzero(&broken, FillRule::NonZero), (broken.clone(), FillRule::NonZero)); + } } diff --git a/crates/prepress/src/flatten/raster.rs b/crates/prepress/src/flatten/raster.rs index 9b2516b39..5c7ddd81a 100644 --- a/crates/prepress/src/flatten/raster.rs +++ b/crates/prepress/src/flatten/raster.rs @@ -163,6 +163,7 @@ impl<'a> Rasterizer<'a> { isolated: g.isolated, knockout: g.knockout, clip: g.clip.clone(), + clip_rule: g.clip_rule, mask, actual_text: g.actual_text.clone(), children, @@ -231,6 +232,7 @@ impl<'a> Rasterizer<'a> { isolated: false, knockout: false, clip: None, + clip_rule: FillRule::NonZero, mask: None, actual_text: None, children: vec![Item::Image(image)], diff --git a/crates/prepress/src/flatten/shade.rs b/crates/prepress/src/flatten/shade.rs index a67d4f340..df2cfba81 100644 --- a/crates/prepress/src/flatten/shade.rs +++ b/crates/prepress/src/flatten/shade.rs @@ -373,7 +373,7 @@ impl<'a> Canvas<'a> { Item::Image(im) => self.image(im, clip, opacity), Item::Group(g) => { let own = g.clip.as_ref().map(|c| { - let mut cov = self.coverage(c, FillRule::NonZero); + let mut cov = self.coverage(c, g.clip_rule); if let Some(outer) = clip { cov.iter_mut().zip(outer).for_each(|(a, b)| *a *= b); } @@ -832,3 +832,45 @@ pub(super) fn rect_path(r: Rect, t: Affine) -> BezPath { path.close_path(); path } + +#[cfg(test)] +mod tests { + use kurbo::Shape; + + use super::*; + use crate::flatten::{BlendMode, FillItem, GroupItem}; + + #[test] + fn canvas_clips_by_the_clip_rule() { + // Two nested squares drawn in the same direction: even-odd leaves a hole, nonzero fills it. + let mut ring = Rect::new(0.0, 0.0, 100.0, 100.0).to_path(0.1); + ring.extend(Rect::new(25.0, 25.0, 75.0, 75.0).to_path(0.1)); + let black = InkColor::Tints(vec![(InkId::process(Process::Black), 1.0)]); + let fill = Item::Fill(FillItem { + path: Rect::new(0.0, 0.0, 100.0, 100.0).to_path(0.1), + rule: FillRule::NonZero, + paint: Paint::Solid(black), + overprint: Overprint::default(), + }); + let inks = InkSet::new(); + let alpha = |clip_rule| { + let group = GroupItem { + opacity: 1.0, + blend: BlendMode::Normal, + isolated: false, + knockout: false, + clip: Some(ring.clone()), + clip_rule, + mask: None, + actual_text: None, + children: vec![fill.clone()], + }; + let Some(mut canvas) = Canvas::new(Rect::new(0.0, 0.0, 100.0, 100.0), 1.0, &inks) else { panic!("no canvas") }; + canvas.draw(&[Item::Group(group)]); + let at = |x, y| canvas.sample(Point::new(x, y)).map(|(_, a)| a); + (at(10.5, 50.5), at(50.5, 50.5)) + }; + assert_eq!(alpha(FillRule::NonZero), (Some(1.0), Some(1.0))); + assert_eq!(alpha(FillRule::EvenOdd), (Some(1.0), Some(0.0)), "the hole"); + } +} diff --git a/crates/prepress/src/flatten/write.rs b/crates/prepress/src/flatten/write.rs index 06fcc4850..3167ff9f6 100644 --- a/crates/prepress/src/flatten/write.rs +++ b/crates/prepress/src/flatten/write.rs @@ -255,10 +255,7 @@ impl<'a> Painter<'a, '_> { fn fill(&mut self, s: &mut Surface<'_>, f: &FillItem, opacity: f32) -> Result<(), WriteError> { let Some(path) = to_path(&f.path) else { return Ok(()) }; - let rule = match f.rule { - FillRule::NonZero => KFillRule::NonZero, - FillRule::EvenOdd => KFillRule::EvenOdd, - }; + let rule = k_fill_rule(f.rule); let (paint, overprint) = self.paint(&f.paint, f.overprint, Affine::IDENTITY)?; with_overprint(s, overprint, |s| { s.set_fill(Some(Fill { paint, opacity: normalized(opacity), rule })); @@ -424,7 +421,7 @@ impl<'a> Painter<'a, '_> { None => None, }; if let Some(clip) = clip { - s.push_clip_path(&clip, &KFillRule::NonZero); + s.push_clip_path(&clip, &k_fill_rule(g.clip_rule)); pushed += 1; } let tag = match &g.actual_text { @@ -694,6 +691,13 @@ fn to_transform(a: Affine) -> Transform { Transform::from_row(a, b, c, d, e, f) } +fn k_fill_rule(rule: FillRule) -> KFillRule { + match rule { + FillRule::NonZero => KFillRule::NonZero, + FillRule::EvenOdd => KFillRule::EvenOdd, + } +} + /// `None` for an empty path, which paints nothing. fn to_path(path: &BezPath) -> Option { let mut b = PathBuilder::new(); diff --git a/crates/prepress/src/lib.rs b/crates/prepress/src/lib.rs index 1afc7cf6f..7f8a5518f 100644 --- a/crates/prepress/src/lib.rs +++ b/crates/prepress/src/lib.rs @@ -21,4 +21,6 @@ pub use coverage::{Above, Coverage, InkStats, MAX_REGIONS, Region, Stats}; pub use ink::{Alternate, Ink, InkColor, InkId, InkSet, Overprint, Process, Spot, normalize_name, to_pdf_color}; pub use marks::{MarkOptions, Marks, MarksError}; pub use output::{Output, OutputError}; -pub use plates::{Band, Conversion, Error, Fallback, MAX_BANDED_PIXELS, MAX_PLATE_PIXELS, MAX_SPOT_INKS, Options, Plates, plates, plates_in_bands}; +pub use plates::{ + Band, Conversion, Error, Fallback, MAX_BANDED_PIXELS, MAX_PLATE_PIXELS, MAX_SPOT_INKS, Options, Plates, plates, plates_in_bands, press_profile, +}; diff --git a/crates/prepress/src/plates.rs b/crates/prepress/src/plates.rs index b2e818efa..6c7752d97 100644 --- a/crates/prepress/src/plates.rs +++ b/crates/prepress/src/plates.rs @@ -16,6 +16,7 @@ use std::ops::ControlFlow; use std::panic::{AssertUnwindSafe, catch_unwind}; use std::sync::{Arc, Mutex}; +use craft_cms::Profile; use craft_pdf::interpret::InterpreterSettings; use craft_pdf::interpret::color::{CmykSimulation, Ink as PdfInk, InkSinkFn, Plate}; use craft_pdf::raster::{self, MAX_SIDE, RenderCache}; @@ -189,6 +190,26 @@ pub fn plates_in_bands(pdf: &[u8], page: usize, dpi: f32, opts: &Options, mut ea separate(pdf, page, dpi, opts, banded_scale, None, &mut each) } +/// The printing condition page `page` (from 0) of `pdf` separates through with `opts`: the CMYK +/// profile of its output intent, else of [`Options::fallback`]. Build an +/// [`Output`](crate::Output) from it, so a composite converts the plates from the profile they +/// were made for. `None` for [`Fallback::DeviceFormulas`] when the page has no usable output +/// intent: those plates are device values of no profile. Never panics. +pub fn press_profile(pdf: &[u8], page: usize, opts: &Options) -> Result, Error> { + let doc = open_slice(pdf, None)?; + if doc.pages().get(page).is_none() { + return Err(Error::NoPage(page)); + } + if let Ok(Some((_, conversion, _))) = catch_unwind(AssertUnwindSafe(|| intent_condition(&doc, page))) { + return Ok(Some(conversion.profile().clone())); + } + Ok(match &opts.fallback { + Fallback::DeviceFormulas => None, + Fallback::Fogra39 => Some(CmsConversion::fogra39().profile().clone()), + Fallback::Profile(icc) => Some(CmsConversion::new(icc)?.profile().clone()), + }) +} + /// Separates in bands of `rows` rows, else as many as fit [`MAX_PLATE_PIXELS`], at `scale_of`'s /// scale. fn separate( @@ -369,17 +390,24 @@ pub(crate) fn pdf_text(bytes: &[u8]) -> String { /// `/OutputIntents` (PDF 2.0), else the catalog's, the first whose `/DestOutputProfile` is a /// CMYK profile craft-cms converts into, a `GTS_PDFX` intent before the others. pub(crate) fn output_intent(pdf: &Pdf, page: usize) -> Option<(CmykSimulation, Conversion)> { - output_intents(pdf, page).iter().find_map(|intent| { + let (intent, conversion, icc) = intent_condition(pdf, page)?; + let simulation = conversion.simulation(&icc); + let condition = text_entry(&intent, OUTPUT_CONDITION_IDENTIFIER); + let profile = simulation + .description() + .map(str::to_string) + .or_else(|| text_entry(&intent, OUTPUT_CONDITION)) + .or_else(|| condition.clone()) + .unwrap_or_else(|| "unnamed CMYK profile".to_string()); + Some((simulation, Conversion::OutputIntent { profile, condition })) +} + +/// The output intent [`output_intent`] picks, its printing condition and its profile's bytes. +fn intent_condition<'a>(pdf: &'a Pdf, page: usize) -> Option<(Dict<'a>, CmsConversion, Vec)> { + output_intents(pdf, page).into_iter().find_map(|intent| { let icc = intent.get::>(DEST_OUTPUT_PROFILE)?.decoded_within(MAX_PROFILE_BYTES).ok()?; - let simulation = CmsConversion::new(&icc).ok()?.simulation(&icc); - let condition = text_entry(intent, OUTPUT_CONDITION_IDENTIFIER); - let profile = simulation - .description() - .map(str::to_string) - .or_else(|| text_entry(intent, OUTPUT_CONDITION)) - .or_else(|| condition.clone()) - .unwrap_or_else(|| "unnamed CMYK profile".to_string()); - Some((simulation, Conversion::OutputIntent { profile, condition })) + let conversion = CmsConversion::new(&icc).ok()?; + Some((intent, conversion, icc.into_owned())) }) } diff --git a/crates/prepress/tests/flatten_raster.rs b/crates/prepress/tests/flatten_raster.rs index 7f9af1c25..6d088c451 100644 --- a/crates/prepress/tests/flatten_raster.rs +++ b/crates/prepress/tests/flatten_raster.rs @@ -204,7 +204,17 @@ fn solid(r: Rect, tints: &[(InkId, f32)]) -> Item { } fn group(opacity: f32, blend: BlendMode, children: Vec) -> Item { - Item::Group(GroupItem { opacity, blend, isolated: false, knockout: false, clip: None, mask: None, actual_text: None, children }) + Item::Group(GroupItem { + opacity, + blend, + isolated: false, + knockout: false, + clip: None, + clip_rule: FillRule::NonZero, + mask: None, + actual_text: None, + children, + }) } fn ramp(r: Rect, from: InkColor, to: InkColor) -> Item { diff --git a/crates/prepress/tests/flatten_timings.rs b/crates/prepress/tests/flatten_timings.rs index 842c9c50c..37e8ca30e 100644 --- a/crates/prepress/tests/flatten_timings.rs +++ b/crates/prepress/tests/flatten_timings.rs @@ -158,6 +158,7 @@ fn heavy(size: f64, gradients: usize) -> DisplayList { isolated: false, knockout: false, clip: None, + clip_rule: FillRule::NonZero, mask: None, actual_text: None, children: vec![fill], diff --git a/crates/prepress/tests/flatten_write.rs b/crates/prepress/tests/flatten_write.rs index 8e0c98750..6836e9637 100644 --- a/crates/prepress/tests/flatten_write.rs +++ b/crates/prepress/tests/flatten_write.rs @@ -50,6 +50,7 @@ fn group(opacity: f32, children: Vec) -> Item { isolated: false, knockout: false, clip: None, + clip_rule: FillRule::NonZero, mask: None, actual_text: None, children, @@ -119,6 +120,21 @@ fn group_opacity_applies_to_the_group_not_to_each_child() { } } +#[test] +fn an_even_odd_clip_keeps_its_hole_written_or_flattened() { + // Two nested squares drawn in the same direction: filled even-odd, the inner one is a hole. + let mut ring = Rect::new(0.0, 0.0, 100.0, 100.0).to_path(0.1); + ring.extend(Rect::new(25.0, 25.0, 75.0, 75.0).to_path(0.1)); + let Item::Group(half_black) = group(0.5, vec![solid(Rect::new(0.0, 0.0, 100.0, 100.0), &[(K, 1.0)])]) else { unreachable!() }; + let clipped = Item::Group(GroupItem { clip: Some(ring), clip_rule: FillRule::EvenOdd, ..half_black }); + let list = page(InkSet::new(), vec![solid(Rect::new(0.0, 0.0, 100.0, 100.0), &[(C, 1.0)]), clipped]); + for written in [pdf(&list), flat_pdf(&list)] { + let p = separate(&written); + assert_inks(&p, 10, 50, &[("Cyan", 128), ("Black", 128)]); + assert_inks(&p, 50, 50, &[("Cyan", 255), ("Black", 0)]); + } +} + #[test] fn black_overprint_keeps_the_cyan_under_it() { let list = page( diff --git a/crates/prepress/tests/plates.rs b/crates/prepress/tests/plates.rs index 791d4a44b..f49190a81 100644 --- a/crates/prepress/tests/plates.rs +++ b/crates/prepress/tests/plates.rs @@ -1,7 +1,7 @@ use std::sync::Arc; use craft_cms::{Intent, Profile, Transform, builtin}; -use craft_prepress::{Alternate, CmsConversion, Conversion, Error, Fallback, Ink, InkId, MAX_SPOT_INKS, Options, Process, plates}; +use craft_prepress::{Alternate, CmsConversion, Conversion, Error, Fallback, Ink, InkId, MAX_SPOT_INKS, Options, Process, plates, press_profile}; /// A 40 × 40 pt page with `content` and `resources`, `catalog` entries, and `objects` /// numbered from 5 (each a whole object body). @@ -128,6 +128,26 @@ fn process_color_converts_through_the_output_intent_else_the_fallback() { assert!(matches!(plates(&red(""), 0, 72.0, &broken), Err(Error::Profile(_)))); } +#[test] +fn the_press_profile_is_the_one_the_plates_separate_through() { + let synthetic = builtin::COATED_CMYK_ICC; + let intent = "/OutputIntents [<< /Type /OutputIntent /S /GTS_PDFX /DestOutputProfile 5 0 R >>]"; + let red = |catalog: &str| page_pdf("1 0 0 rg 0 0 40 40 re f", "", catalog, &[stream("/N 4", synthetic)]); + let parsed = |icc: &[u8]| Some(Profile::parse(icc).unwrap()); + let defaults = Options::default(); + + assert_eq!(press_profile(&red(intent), 0, &defaults).unwrap(), parsed(synthetic), "the output intent's"); + assert_eq!(press_profile(&red(""), 0, &defaults).unwrap(), parsed(builtin::COATED_FOGRA39_ICC), "FOGRA39"); + let callers = Options { fallback: Fallback::Profile(Arc::from(synthetic)), ..Options::default() }; + assert_eq!(press_profile(&red(""), 0, &callers).unwrap(), parsed(synthetic), "the caller's"); + let formulas = Options { fallback: Fallback::DeviceFormulas, ..Options::default() }; + assert_eq!(press_profile(&red(""), 0, &formulas).unwrap(), None, "device formulas have no profile"); + assert_eq!(press_profile(&red(intent), 0, &formulas).unwrap(), parsed(synthetic), "an output intent still wins"); + assert!(matches!(press_profile(&red(""), 1, &defaults), Err(Error::NoPage(1)))); + let broken = Options { fallback: Fallback::Profile(Arc::from(&b"not a profile"[..])), ..Options::default() }; + assert!(matches!(press_profile(&red(""), 0, &broken), Err(Error::Profile(_)))); +} + #[test] fn spot_inks_past_the_cap_are_listed_not_separated_and_bad_input_is_refused() { let n = MAX_SPOT_INKS + 2; diff --git a/crates/press-print/Cargo.toml b/crates/press-print/Cargo.toml new file mode 100644 index 000000000..92ca65455 --- /dev/null +++ b/crates/press-print/Cargo.toml @@ -0,0 +1,17 @@ +[package] +name = "craft-press-print" +description = "Press-accurate printing for the Craft apps: a PDF page separated into plates, composited into the printer's RGB profile and printed application-managed" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true + +[lints] +workspace = true + +[dependencies] +craft-cms = { workspace = true } +craft-prepress = { workspace = true } +craft-print = { workspace = true } +thiserror = { workspace = true } diff --git a/crates/press-print/README.md b/crates/press-print/README.md new file mode 100644 index 000000000..acb4f5d7f --- /dev/null +++ b/crates/press-print/README.md @@ -0,0 +1,57 @@ +# craft-press-print + +Press-accurate printing for the Craft apps. A page prints as the press would print it: overprint +decided per plate, spot inks as inks rather than their alternates, knockout and isolated groups, +and the press's colors, converted once into the printer's RGB profile. + +It is an opt-in alternative to craft-print's PDF path, which draws a job with the system's PDF +renderer. That renderer does not simulate overprint and draws spot and DeviceN colors through their +alternates. + +## How a page prints + +1. craft-prepress separates the page in bands (`plates_in_bands`), one 8-bit plate per ink. +2. Each band composites into the printer's profile (`Plates::composite_to`). The process plates + convert from the printing condition they were separated through (`press_profile`: the page's + output intent, else `Options::fallback`), straight from CMYK to the printer. Spot plates + combine over them. +3. The bands join into one RGB image of the page. +4. `craft_print::rgb::print` sends it with `ColorPolicy::ApplicationManaged`, so the driver + applies no second conversion. + +```rust +use craft_cms::Profile; +use craft_press_print::{Settings, print, render}; +use craft_print::rgb; + +let settings = Settings::new(Profile::parse(&printer_icc)?); +// The page as it prints, to preview or to keep. +let page = render(&pdf, 0, 600.0, &settings)?; +// Or straight to a printer, at its resolution. +let job = rgb::Job { + printer: "Office printer", + settings: None, + title: "proof.pdf", + output_file: None, + copies: 1, + color_policy: rgb::ColorPolicy::ApplicationManaged, + primitives: &[], +}; +print(&job, &pdf, 0, &settings, (0.0, 0.0, 612.0, 792.0))?; +``` + +`Settings` holds the separation options, the printer's RGB profile (sRGB when the printer's own +profile is not known), the rendering intent and black point compensation. A gray or CMYK printer +profile is refused: `rgb::print` takes RGB. + +## Limits + +- `rgb::print` takes one image per job, so `print` sends one page per job. +- `print` separates at the printer's resolution, whatever the size of `rect`, within + craft-prepress's limits: the renderer's 8192-pixel side limit across the page (about 960 dpi on + Letter or A4) and `MAX_BANDED_PIXELS` in all. The page image is 3 bytes per pixel and is held + whole. `rgb::print` takes at most 512 MiB, so a page past that separates again at the + resolution that fits. +- Each band renders the page once per ink, so time grows with resolution and ink count. +- Printing needs Windows. Elsewhere `print` returns `rgb::PrintError::Unsupported`, and `render` + still works. diff --git a/crates/press-print/src/lib.rs b/crates/press-print/src/lib.rs new file mode 100644 index 000000000..74c55fb02 --- /dev/null +++ b/crates/press-print/src/lib.rs @@ -0,0 +1,222 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +//! Press-accurate printing for the Craft apps: a PDF page separated into plates by +//! craft-prepress, composited into the printer's RGB profile and printed through +//! `craft_print::rgb` with its color already managed, so overprint, spot inks and the press's +//! colors reach the driver as the plates have them. See the README. + +use std::ops::ControlFlow; + +use craft_cms::{Builtin, ColorSpace, Intent, Profile}; +use craft_prepress::{Band, Conversion, Options, Output, OutputError, plates_in_bands, press_profile}; +use craft_print::rgb; + +/// How a page becomes the printer's pixels. +#[derive(Clone, Debug)] +pub struct Settings { + /// How the page separates: overprint, and the printing condition when the page has no + /// output intent. + pub separation: Options, + /// The printer's RGB profile: the pixels go to the driver in this space. sRGB when the + /// printer's own is not known. + pub printer: Profile, + /// The rendering intent from the press to the printer. + pub intent: Intent, + /// Black point compensation from the press to the printer. + pub bpc: bool, +} + +impl Settings { + /// Default separation, relative colorimetric with black point compensation, into `printer`. + pub fn new(printer: Profile) -> Self { + Self { separation: Options::default(), printer, intent: Intent::RelativeColorimetric, bpc: true } + } +} + +/// A page as the press prints it, in the printer's RGB. +#[derive(Clone, Debug)] +pub struct PressPage { + pub width: u32, + pub height: u32, + /// The resolution separated at, after craft-prepress's limits. + pub dpi: f32, + /// How process color that wasn't CMYK became CMYK. + pub conversion: Conversion, + /// Rows top to bottom, `width * 3` bytes each. + pub rgb: Vec, +} + +impl PressPage { + /// The page as `craft_print::rgb` takes it. + pub fn image(&self) -> rgb::RgbImage<'_> { + rgb::RgbImage { width: self.width, height: self.height, data: &self.rgb } + } +} + +/// Why a page couldn't be rendered or printed. +#[derive(Debug, thiserror::Error)] +#[non_exhaustive] +pub enum Error { + #[error(transparent)] + Separate(#[from] craft_prepress::Error), + #[error(transparent)] + Output(#[from] OutputError), + #[error("the printer profile is not RGB")] + PrinterNotRgb, + #[error("the page image is too large to hold")] + TooLarge, + #[error("the plates could not be converted into the printer profile")] + Composite, + #[error(transparent)] + Print(#[from] rgb::PrintError), +} + +/// Page `page` (from 0) of `pdf` at `dpi` as the press prints it, in `settings.printer`. +/// +/// The page separates in bands (`plates_in_bands`), each band composites into the printer's +/// profile from the printing condition its plates were made for (`press_profile`), and the +/// bands join into one image. Plates made by the device formulas have no profile; they convert +/// from craft-cms's Coated FOGRA39, as craft-prepress's preview does by default. The image is +/// at most `MAX_BANDED_PIXELS` pixels, 3 bytes each. Never panics. +pub fn render(pdf: &[u8], page: usize, dpi: f32, settings: &Settings) -> Result { + match render_within(pdf, page, dpi, settings, usize::MAX)? { + Within::Page(page) => Ok(page), + Within::Over(_) => Err(Error::TooLarge), + } +} + +/// Bytes of the largest image `rgb::print` takes. +const PRINT_BYTES: usize = 512 * 1024 * 1024; + +/// A render that fits in a byte limit, or the bytes the page would take at that resolution. +enum Within { + Page(PressPage), + Over(usize), +} + +/// [`render`], stopping at the first band when the page image would take more than `max` bytes. +fn render_within(pdf: &[u8], page: usize, dpi: f32, settings: &Settings, max: usize) -> Result { + if settings.printer.color_space != ColorSpace::Rgb { + return Err(Error::PrinterNotRgb); + } + let press = press_profile(pdf, page, &settings.separation)?.unwrap_or_else(|| Builtin::CoatedFogra39.profile().clone()); + let output = Output::new(&press, &settings.printer, settings.intent, settings.bpc)?; + let mut joined: Option = None; + let mut over = None; + let mut failed = None; + plates_in_bands(pdf, page, dpi, &settings.separation, |band| { + let len = image_len(band.plates.width, band.page_height); + if joined.is_none() && len.is_some_and(|len| len > max) { + over = len; + return ControlFlow::Break(()); + } + match add_band(&mut joined, band, &output) { + Ok(()) => ControlFlow::Continue(()), + Err(e) => { + failed = Some(e); + ControlFlow::Break(()) + } + } + })?; + if let Some(e) = failed { + return Err(e); + } + if let Some(bytes) = over { + return Ok(Within::Over(bytes)); + } + let page = joined.ok_or(Error::Composite)?; + if Some(page.rgb.len()) != image_len(page.width, page.height) { + return Err(Error::Composite); + } + Ok(Within::Page(page)) +} + +/// [`render`] at `dpi`, or at the resolution that keeps the page image within `max` bytes when +/// `dpi` would exceed it. The page then separates twice: the first time stops at its first band. +fn fitted(pdf: &[u8], page: usize, dpi: f32, settings: &Settings, max: usize) -> Result { + let bytes = match render_within(pdf, page, dpi, settings, max)? { + Within::Page(page) => return Ok(page), + Within::Over(bytes) => bytes, + }; + // Pixels scale with the square of the resolution; the margin covers the floored sides. + let dpi = dpi * ((max as f64 / bytes as f64).sqrt() * 0.99) as f32; + match render_within(pdf, page, dpi, settings, max)? { + Within::Page(page) => Ok(page), + Within::Over(_) => Err(Error::TooLarge), + } +} + +/// Prints page `page` of `pdf` as the press prints it, on `job.printer` with `job.settings`, +/// into `rect` (points from the sheet's top-left, as `rgb::print` takes it), `job.copies` +/// times. +/// +/// The page separates at the printer's resolution, the larger of its two, whatever the size of +/// `rect`, within craft-prepress's limits and the 512 MiB image `rgb::print` takes: past that, +/// at the resolution that fits. The job is application-managed whatever `job.color_policy` says: +/// the pixels are in the printer's profile already, and a second conversion by the driver +/// would undo the press colors. One call is one job; `rgb::print` takes one image per job. +pub fn print(job: &rgb::Job<'_>, pdf: &[u8], page: usize, settings: &Settings, rect: (f64, f64, f64, f64)) -> Result { + let device = rgb::page(job.printer, job.settings)?; + let dpi = device.dpi.0.max(device.dpi.1) as f32; + let press = fitted(pdf, page, dpi, settings, PRINT_BYTES)?; + let job = rgb::Job { color_policy: rgb::ColorPolicy::ApplicationManaged, ..*job }; + Ok(rgb::print(&job, &press.image(), rect)?) +} + +/// Bytes of a `width` × `height` RGB image, `None` on overflow. +fn image_len(width: u32, height: u32) -> Option { + usize::try_from(width).ok()?.checked_mul(usize::try_from(height).ok()?)?.checked_mul(3) +} + +/// Composites `band` into `output` and appends it to the page, allocated on the first band. +fn add_band(joined: &mut Option, band: Band, output: &Output) -> Result<(), Error> { + let plates = band.plates; + if joined.is_none() { + let len = image_len(plates.width, band.page_height).ok_or(Error::TooLarge)?; + let mut rgb = Vec::new(); + rgb.try_reserve_exact(len).map_err(|_| Error::TooLarge)?; + *joined = Some(PressPage { width: plates.width, height: band.page_height, dpi: plates.dpi, conversion: plates.conversion.clone(), rgb }); + } + let page = joined.as_mut().ok_or(Error::Composite)?; + let start = image_len(plates.width, band.top).ok_or(Error::TooLarge)?; + let pixels = plates.composite_to(&[], output); + let fits = plates.width == page.width + && page.rgb.len() == start + && image_len(plates.width, plates.height) == Some(pixels.len()) + && start.checked_add(pixels.len()).is_some_and(|end| Some(end) <= image_len(page.width, page.height)); + if !fits { + return Err(Error::Composite); + } + page.rgb.extend_from_slice(&pixels); + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_page_too_large_to_print_separates_at_a_resolution_that_fits() { + let content = "0 0 1 0 k 0 0 40 40 re f"; + let pdf = format!( + "%PDF-1.7 +1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj +2 0 obj << /Type /Pages /Kids [3 0 R] /Count 1 >> endobj +3 0 obj << /Type /Page /Parent 2 0 R /MediaBox [0 0 40 40] /Contents 4 0 R >> endobj +4 0 obj << /Length {} >> stream +{content} +endstream endobj +trailer << /Root 1 0 R >> +%%EOF", + content.len() + ); + let settings = Settings::new(craft_cms::builtin::srgb().clone()); + // 40 pt at 1800 dpi is 1000 × 1000 pixels, 3 MB. + let max = 1_000_000; + assert!(matches!(render_within(pdf.as_bytes(), 0, 1800.0, &settings, max).unwrap(), Within::Over(3_000_000))); + let page = fitted(pdf.as_bytes(), 0, 1800.0, &settings, max).unwrap(); + assert!(page.rgb.len() <= max && page.rgb.len() > max * 9 / 10, "{} bytes", page.rgb.len()); + assert!(page.dpi < 1800.0 * 0.6, "at {} dpi", page.dpi); + assert_eq!(fitted(pdf.as_bytes(), 0, 72.0, &settings, max).unwrap().dpi, 72.0, "a page that fits keeps its resolution"); + } +} diff --git a/crates/press-print/tests/press_print.rs b/crates/press-print/tests/press_print.rs new file mode 100644 index 000000000..d4e1e1046 --- /dev/null +++ b/crates/press-print/tests/press_print.rs @@ -0,0 +1,113 @@ +use craft_cms::{Builtin, Intent, Profile, builtin}; +use craft_prepress::{MAX_PLATE_PIXELS, Options, Output, plates}; +use craft_press_print::{Error, PressPage, Settings, print, render}; +use craft_print::rgb; + +/// A one-page PDF of `w` × `h` pt with `content`, `resources` and `catalog` entries, and +/// `objects` numbered from 5 (each a whole object body). +fn page_pdf(w: u32, h: u32, content: &str, resources: &str, catalog: &str, objects: &[Vec]) -> Vec { + let mut out = b"%PDF-1.7\n".to_vec(); + out.extend_from_slice(format!("1 0 obj << /Type /Catalog /Pages 2 0 R {catalog} >> endobj\n").as_bytes()); + out.extend_from_slice(b"2 0 obj << /Type /Pages /Kids [3 0 R] /Count 1 >> endobj\n"); + out.extend_from_slice( + format!("3 0 obj << /Type /Page /Parent 2 0 R /MediaBox [0 0 {w} {h}] /Contents 4 0 R /Resources << {resources} >> >> endobj\n").as_bytes(), + ); + out.extend_from_slice(format!("4 0 obj << /Length {} >> stream\n{content}\nendstream endobj\n", content.len()).as_bytes()); + for (i, body) in objects.iter().enumerate() { + out.extend_from_slice(format!("{} 0 obj ", i + 5).as_bytes()); + out.extend_from_slice(body); + out.extend_from_slice(b" endobj\n"); + } + out.extend_from_slice(b"trailer << /Root 1 0 R >>\n%%EOF"); + out +} + +fn srgb() -> Settings { + Settings::new(builtin::srgb().clone()) +} + +fn px(page: &PressPage, x: u32, y: u32) -> [u8; 3] { + let at = ((y * page.width + x) * 3) as usize; + page.rgb[at..at + 3].try_into().unwrap() +} + +/// Yellow paper, a 50% cyan bar that overprints it (x 10..20) and one that knocks it out +/// (x 25..35), both the full height of the page, so every row is the same. Overprint mode 1 +/// leaves the yellow under the zero components of the overprinting cyan. +const BARS: &str = "0 0 1 0 k 0 0 40 40 re f /OP gs 0.5 0 0 0 k 10 0 10 40 re f /KO gs 25 0 10 40 re f"; +const BARS_RESOURCES: &str = "/ExtGState << /OP << /op true /OP true /OPM 1 >> /KO << /op false /OP false >> >>"; + +/// Yellow paper with cyan over its top half: in device rows, cyan down to the middle, then +/// yellow. +const HALVES: &str = "0 0 1 0 k 0 0 40 40 re f 1 0 0 0 k 0 20 40 20 re f"; + +#[test] +fn bands_join_without_a_seam_into_one_page_image() { + let pdf = page_pdf(40, 40, HALVES, "", "", &[]); + let page = render(&pdf, 0, 3700.0, &srgb()).unwrap(); + assert_eq!(page.rgb.len(), (page.width * page.height * 3) as usize); + assert!((page.width * page.height) as f32 > MAX_PLATE_PIXELS, "more than one band: {} × {}", page.width, page.height); + let rows: Vec<&[u8]> = page.rgb.chunks_exact((page.width * 3) as usize).collect(); + let (top, bottom) = (rows[0], rows[rows.len() - 1]); + assert_ne!(top, bottom); + // Every row is the top's or the bottom's, except at most one at the edge, which is in the + // middle of the page. + let cyan = rows.iter().take_while(|r| **r == top).count(); + let yellow = rows.iter().rev().take_while(|r| **r == bottom).count(); + assert!(cyan + yellow + 1 >= rows.len(), "{cyan} cyan and {yellow} yellow rows of {}", rows.len()); + assert!(cyan.abs_diff(rows.len() / 2) <= 1, "the edge at row {cyan} of {}", rows.len()); +} + +#[test] +fn overprint_reaches_the_printer_pixels() { + let pdf = page_pdf(40, 40, BARS, BARS_RESOURCES, "", &[]); + let page = render(&pdf, 0, 72.0, &srgb()).unwrap(); + let wide = |p: [u8; 3]| p.map(i32::from); + let [r, g, b] = wide(px(&page, 15, 20)); + assert!(g > r && g > b + 60, "cyan over yellow prints green: {:?}", [r, g, b]); + let [r, g, b] = wide(px(&page, 30, 20)); + assert!(b > g - 40 && b > r + 60, "knocked-out cyan prints cyan: {:?}", [r, g, b]); + + let off = Settings { separation: Options { overprint: false, ..Options::default() }, ..srgb() }; + let knocked = render(&pdf, 0, 72.0, &off).unwrap(); + assert_eq!(px(&knocked, 15, 20), px(&knocked, 30, 20), "with overprint off both bars knock out"); +} + +#[test] +fn the_plates_convert_from_the_output_intents_profile() { + let intent = "/OutputIntents [<< /Type /OutputIntent /S /GTS_PDFX /DestOutputProfile 5 0 R >>]"; + let icc = builtin::COATED_CMYK_ICC; + let mut profile = format!("<< /N 4 /Length {} >> stream\n", icc.len()).into_bytes(); + profile.extend_from_slice(icc); + profile.extend_from_slice(b"\nendstream"); + let pdf = page_pdf(40, 40, "1 0 0 rg 0 0 20 40 re f 0.2 0.6 0.9 0.1 k 20 0 20 40 re f", "", intent, &[profile]); + + let page = render(&pdf, 0, 72.0, &srgb()).unwrap(); + let plates = plates(&pdf, 0, 72.0, &Options::default()).unwrap(); + let synthetic = Profile::parse(icc).unwrap(); + let through = |press: &Profile| plates.composite_to(&[], &Output::new(press, builtin::srgb(), Intent::RelativeColorimetric, true).unwrap()); + assert_ne!(through(&synthetic), through(Builtin::CoatedFogra39.profile()), "the two presses differ here"); + assert_eq!(page.rgb, through(&synthetic), "the press is the output intent's"); +} + +#[test] +fn bad_input_is_refused_before_anything_prints() { + let pdf = page_pdf(40, 40, BARS, BARS_RESOURCES, "", &[]); + let cmyk = Settings::new(Builtin::CoatedFogra39.profile().clone()); + assert!(matches!(render(&pdf, 0, 72.0, &cmyk), Err(Error::PrinterNotRgb))); + assert!(matches!(render(&pdf, 0, f32::NAN, &srgb()), Err(Error::Separate(_)))); + assert!(matches!(render(&pdf, 3, 72.0, &srgb()), Err(Error::Separate(_)))); + assert!(matches!(render(b"not a pdf", 0, 72.0, &srgb()), Err(Error::Separate(_)))); + + // No such printer: refused while asking for its page, before a job starts. + let job = rgb::Job { + printer: "Craft press print: no such printer", + settings: None, + title: "press", + output_file: None, + copies: 1, + color_policy: rgb::ColorPolicy::DriverManaged, + primitives: &[], + }; + assert!(matches!(print(&job, &pdf, 0, &srgb(), (0.0, 0.0, 40.0, 40.0)), Err(Error::Print(_)))); +} diff --git a/crates/psd/Cargo.toml b/crates/psd/Cargo.toml index c9aa6dbe0..30bf3a471 100644 --- a/crates/psd/Cargo.toml +++ b/crates/psd/Cargo.toml @@ -12,7 +12,10 @@ repository.workspace = true corpus = [] default = [] serde = ["dep:serde"] -testgen = [] +# `fixtures` and `testgen`: test-data generators for the tests of crates that read PSD files. +test-support = [] +# The former name of `test-support`. +testgen = ["test-support"] [dependencies] thiserror = { workspace = true } @@ -26,7 +29,7 @@ rayon = { workspace = true } [dev-dependencies] proptest = { workspace = true } -craft-psd = { path = ".", features = ["testgen"] } +craft-psd = { path = ".", features = ["test-support"] } [lints] workspace = true diff --git a/crates/psd/README.md b/crates/psd/README.md index 5bac98732..7a7bfa2d7 100644 --- a/crates/psd/README.md +++ b/crates/psd/README.md @@ -127,7 +127,7 @@ builder.push_layer(LayerSpec) / begin_group(GroupSpec) / end_group()? / composit builder.build() -> Result; builder.to_bytes() PixelData::{Rgba8, Rgba16, GrayA8, GrayA16, Cmyka8, Cmyka16} // CMYK given as ink, stored inverted -// Test generator (feature `testgen`) +// Test generator (feature `test-support`; `testgen` is an alias) testgen::{all_cases, merged_only, layered, small, sample_descriptor, pattern_plane} ``` diff --git a/crates/psd/examples/big_psb.rs b/crates/psd/examples/big_psb.rs index 18ce78ccf..3ed6c8175 100644 --- a/crates/psd/examples/big_psb.rs +++ b/crates/psd/examples/big_psb.rs @@ -1,6 +1,6 @@ //! Writes multi-gigabyte PSB files (and the 2 GB PSD) for large-file tests (photocraft#375, photocraft#216), straight //! from the Adobe PSD spec and independent of this crate's writer, so the fixtures don't inherit -//! its limits. The generator is `craft_psd::fixtures` (feature `testgen`). +//! its limits. The generator is `craft_psd::fixtures` (feature `test-support`). //! //! `cargo run --release -p craft-psd --example big_psb -- [case...]` //! diff --git a/crates/psd/src/lib.rs b/crates/psd/src/lib.rs index efcc474b2..5b84fcb91 100644 --- a/crates/psd/src/lib.rs +++ b/crates/psd/src/lib.rs @@ -71,7 +71,7 @@ pub mod engine_data; pub mod error; pub mod file; pub mod filter_effects; -#[cfg(any(test, feature = "testgen"))] +#[cfg(any(test, feature = "test-support"))] pub mod fixtures; pub mod flat; pub mod float; @@ -97,7 +97,7 @@ pub mod slices; pub mod smart; pub mod source; pub mod tagged; -#[cfg(any(test, feature = "testgen"))] +#[cfg(any(test, feature = "test-support"))] // Test-data generator (tests and fuzz seeds only): failing loudly is the point. #[allow(clippy::expect_used)] pub mod testgen; diff --git a/crates/psd/tests/it/main.rs b/crates/psd/tests/it/main.rs index 08825ddf9..3bb60a8d9 100644 --- a/crates/psd/tests/it/main.rs +++ b/crates/psd/tests/it/main.rs @@ -22,3 +22,13 @@ fn corpus_dir(sub: &str) -> std::path::PathBuf { .map_or_else(|| std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../corpus"), std::path::PathBuf::from); root.join(sub) } + +/// The self dev-dependency builds these tests with `test-support`, the feature that gates +/// `craft_psd::fixtures` and `craft_psd::testgen`. +#[test] +fn tests_build_with_the_test_support_feature() { + const { assert!(cfg!(feature = "test-support")) }; + let file = craft_psd::testgen::small(craft_psd::Version::Psd, craft_psd::Compression::Raw); + assert_eq!(file.header.version, craft_psd::Version::Psd); + let _sample: fn(u32, u32, u32, bool) -> u8 = craft_psd::fixtures::sample; +} diff --git a/crates/pst/Cargo.toml b/crates/pst/Cargo.toml index 25a1a08bd..60ead7d8f 100644 --- a/crates/pst/Cargo.toml +++ b/crates/pst/Cargo.toml @@ -10,7 +10,9 @@ repository.workspace = true [features] # The test writer (`test_writer`): synthetic .pst files for the tests of code that reads them. # A dev-dependency feature only. -test-writer = [] +test-support = [] +# The earlier name of `test-support`, kept as an alias that turns it on. +test-writer = ["test-support"] [lints] workspace = true @@ -18,4 +20,5 @@ workspace = true [dependencies] [dev-dependencies] +craft-pst = { path = ".", features = ["test-support"] } proptest = { workspace = true } diff --git a/crates/pst/README.md b/crates/pst/README.md index 68b57c7a4..d6c8583d8 100644 --- a/crates/pst/README.md +++ b/crates/pst/README.md @@ -53,7 +53,8 @@ is left out and named (`Error::Cap`). ## What is not here -- Writing. The `test-writer` feature has a writer of small synthetic files, for tests only. +- Writing. The `test-support` feature has a writer of small synthetic files, for tests only. + `test-writer` is an alias of `test-support`. - Offline folders files with 4 KB pages (version 36) and files protected by Windows Information Protection (version 37): `Error::UnsupportedVersion`. - Text in a code page: `PropValue::String8` carries the bytes, and the caller decodes them in diff --git a/crates/pst/src/crypt.rs b/crates/pst/src/crypt.rs index 984bacc34..e5a9f94ab 100644 --- a/crates/pst/src/crypt.rs +++ b/crates/pst/src/crypt.rs @@ -24,7 +24,7 @@ pub(crate) fn decode(method: Encryption, data: &mut [u8], bid: u64) { } /// Encodes `data` in place (the test writer's side). -#[cfg(any(test, feature = "test-writer"))] +#[cfg(any(test, feature = "test-support"))] pub(crate) fn encode(method: Encryption, data: &mut [u8], bid: u64) { match method { Encryption::None => {} diff --git a/crates/pst/src/lib.rs b/crates/pst/src/lib.rs index b532fbeaa..c1f86236e 100644 --- a/crates/pst/src/lib.rs +++ b/crates/pst/src/lib.rs @@ -36,9 +36,9 @@ mod pst; pub mod recur; mod source; /// The test writer: synthetic .pst files from invented folders and messages, for this crate's -/// tests and, through the `test-writer` feature (a dev-dependency only, never in a build that -/// ships), for the tests of the import that reads them. -#[cfg(any(test, feature = "test-writer"))] +/// tests and, through the `test-support` feature (a dev-dependency only, never in a build that +/// ships; `test-writer` is an alias of it), for the tests of the import that reads them. +#[cfg(any(test, feature = "test-support"))] #[doc(hidden)] #[path = "tests/writer.rs"] #[allow( diff --git a/crates/pst/tests/test_support.rs b/crates/pst/tests/test_support.rs new file mode 100644 index 000000000..e5b5a6e02 --- /dev/null +++ b/crates/pst/tests/test_support.rs @@ -0,0 +1,36 @@ +//! The test writer used the way a dependent crate's tests use it: through the `test-support` +//! feature (or `test-writer`, its alias), from outside the crate. + +use std::io::Cursor; + +use craft_pst::test_writer::{FileSpec, FolderSpec, Layout, MessageSpec, build}; +use craft_pst::{Encryption, Format, Pst}; + +#[test] +fn a_file_from_the_test_writer_opens() { + let spec = FileSpec { + layout: Layout::new(Format::Unicode, Encryption::Permute), + password: None, + password_ansi: false, + name: "Personal Folders".into(), + folders: vec![FolderSpec { + name: "Inbox".into(), + class: Some("IPF.Note".into()), + messages: vec![MessageSpec { class: "IPM.Note".into(), subject: "Lunch on Friday?".into(), ..Default::default() }], + children: Vec::new(), + }], + named: Vec::new(), + named_strings: Vec::new(), + }; + let bytes = build(&spec); + let mut pst = Pst::open(Cursor::new(bytes.as_slice())).unwrap(); + assert_eq!(pst.format(), Format::Unicode); + assert_eq!(pst.encryption(), Encryption::Permute); + assert_eq!(pst.store().unwrap().display_name.as_deref(), Some("Personal Folders")); + + let tree = pst.walk_folders().unwrap(); + let inbox = tree.folders.iter().find(|f| f.folder.name == "Inbox").unwrap(); + let items = pst.items(inbox.folder.id).unwrap(); + let subjects: Vec> = items.items.iter().map(|i| i.properties.text(0x0037)).collect(); + assert_eq!(subjects, vec![Some("Lunch on Friday?".to_string())]); +} diff --git a/crates/raw/docs/raf-compression.md b/crates/raw/docs/raf-compression.md index 5dfad256d..e19a8ba6a 100644 --- a/crates/raw/docs/raf-compression.md +++ b/crates/raw/docs/raf-compression.md @@ -30,7 +30,7 @@ Complete sensor arrays were compared sample by sample with an external decoder u All 24 files matched the reference sensor arrays exactly. This covers 13 camera bodies and both older and current compression variants. Synthetic tests also cover 12-bit streams; a real compressed 12-bit camera file has not been verified. Support is selected from the file's layout, without a camera-name allowlist. Other bodies using this layout should decode, but this is not a claim that every Fujifilm model has been tested. Older FinePix layouts without the supported raw TIFF IFD remain unsupported. -The 17 CC0 files live in the gitignored corpus. Their published SHA-256 identities are pinned in [raf-corpus.sha256](raf-corpus.sha256); their source licence records were checked as CC0 1.0. `cargo xtask corpus --download` fetches them. `cargo test -p lightcraft-raw corpus_fujifilm_compressed_samples -- --nocapture` verifies each available file's checksum before checking its reference sensor sum and position-weighted sum. The test skips absent corpus files; the full-array comparisons were performed locally. No supplied media or large binary fixtures are committed. +The 17 CC0 files live in a gitignored corpus and are not bundled. [raf-corpus.sha256](raf-corpus.sha256) pins their published SHA-256 identities: `#` comment lines, then one tab-separated row per file with the digest and the path relative to the corpus folder. Their source license records were checked as CC0 1.0. `tests/it/raf_corpus_manifest.rs` checks the list's format without the files. In LightCraft, `cargo xtask corpus --download` fetches them, and `cargo test -p lightcraft-raw corpus_fujifilm_compressed_samples -- --nocapture` verifies each available file's checksum before checking its reference sensor sum and position-weighted sum. That test skips absent corpus files; the full-array comparisons were performed locally. No supplied media or large binary fixtures are committed. Unconditional procedural tests cover Bayer/X-Trans, 12/14/16 bits, partial final stripes, quantizer changes, residual signs and escapes, malformed headers and truncated/random entropy streams. Regressions also check overflowing uncompressed row strides, unsupported modes and CFA layouts, and container/stream mode mismatches. diff --git a/crates/raw/docs/raf-corpus.sha256 b/crates/raw/docs/raf-corpus.sha256 index 0fd957283..8af0396a9 100644 --- a/crates/raw/docs/raf-corpus.sha256 +++ b/crates/raw/docs/raf-corpus.sha256 @@ -1,19 +1,19 @@ # Fujifilm RAF regression files; CC0 1.0, raw.pixls.us. # Published SHA-256 values retrieved 2026-10-07; see docs/raf-compression.md. -018781e126842596fcf3876b3fb6cd8973dc3936ccc753ee8648618be8889287 corpus/raw/raf-fuji-gfx100-3773.raf -0e7dad9819a748bb3d3be26bbf5770d4968e2d80b9cb41d97036bf7c27f7bfe7 corpus/raw/raf-fuji-gfx100-3775.raf -14bed5ac8191d6f2a7c82984e3bf6470ad4740df329293eac42b8018cc6a668a corpus/raw/raf-fuji-gfx100rf-8091.raf -a7bf8f061b603f7ef5fd29276eb6b2ac57355ca2f589a340117bfff0d03c065c corpus/raw/raf-fuji-gfx100s-4495.raf -1bb4608b61861a3d9e85b0ca6c00689b8ba4620cbe8579374d958c21ed08edf0 corpus/raw/raf-fuji-gfx100s-4503.raf -a7124d13910e0241a6b035154bc1fcdb7be4439371d043b1e1950a0251feb51e corpus/raw/raf-fuji-gfx50s-1435.raf -28f56cc9784164209e92fae209bdcc78267bd692aa2fb964595485f7e93692ab corpus/raw/raf-fuji-xe5-8509.raf -caeadb2666f6c5d9bbe32fbe692c2079b6a7e028f8514a13173f360656d08507 corpus/raw/raf-fuji-xh2-6001.raf -109be38f59963c9b8ff289ebe1f5ec9168c52f609e5b601432bd194520b4605b corpus/raw/raf-fuji-xh2-6002.raf -c76ce546e15727abb4ba201471010c554403176963a1a6b8cc017462606429e5 corpus/raw/raf-fuji-xm5-7748.raf -f756ad5be551a8b3e1b503a8a6f7e8e637fba519c0b0f8c79dd58e94b0287602 corpus/raw/raf-fuji-xt2-865.raf -a23045101b2912e64f154100d646c228c0d16585d21e95e0d1a006e537f7784c corpus/raw/raf-fuji-xt20-compressed.raf -07ea642656074834ffe5c661870a612ffa2e80fc1218a05166ee966bbe5f6fae corpus/raw/raf-fuji-xt4-3914.raf -871836938ffa695f4c41765ddb107c2703ce755f7f3ced7e10f9e04746f1734e corpus/raw/raf-fuji-xt4-3918.raf -b2a067e7fda16338f15c2532caa12b238b2415dc1c75a96a6d24d3445cfd0ae3 corpus/raw/raf-fuji-xt5-6122.raf -cddd7ae0c43f9280876e5fdcbdf8878718972ebd3d034d8affc8cfc6752d33dc corpus/raw/raf-fuji-xt5-6123.raf -3a8a9ac6d92274969aaa1f55ea669191b98bb8f588d00ec8ec17afd8b3963dea corpus/raw/raf-fuji-xt50-7807.raf +018781e126842596fcf3876b3fb6cd8973dc3936ccc753ee8648618be8889287 corpus/raw/raf-fuji-gfx100-3773.raf +0e7dad9819a748bb3d3be26bbf5770d4968e2d80b9cb41d97036bf7c27f7bfe7 corpus/raw/raf-fuji-gfx100-3775.raf +14bed5ac8191d6f2a7c82984e3bf6470ad4740df329293eac42b8018cc6a668a corpus/raw/raf-fuji-gfx100rf-8091.raf +a7bf8f061b603f7ef5fd29276eb6b2ac57355ca2f589a340117bfff0d03c065c corpus/raw/raf-fuji-gfx100s-4495.raf +1bb4608b61861a3d9e85b0ca6c00689b8ba4620cbe8579374d958c21ed08edf0 corpus/raw/raf-fuji-gfx100s-4503.raf +a7124d13910e0241a6b035154bc1fcdb7be4439371d043b1e1950a0251feb51e corpus/raw/raf-fuji-gfx50s-1435.raf +28f56cc9784164209e92fae209bdcc78267bd692aa2fb964595485f7e93692ab corpus/raw/raf-fuji-xe5-8509.raf +caeadb2666f6c5d9bbe32fbe692c2079b6a7e028f8514a13173f360656d08507 corpus/raw/raf-fuji-xh2-6001.raf +109be38f59963c9b8ff289ebe1f5ec9168c52f609e5b601432bd194520b4605b corpus/raw/raf-fuji-xh2-6002.raf +c76ce546e15727abb4ba201471010c554403176963a1a6b8cc017462606429e5 corpus/raw/raf-fuji-xm5-7748.raf +f756ad5be551a8b3e1b503a8a6f7e8e637fba519c0b0f8c79dd58e94b0287602 corpus/raw/raf-fuji-xt2-865.raf +a23045101b2912e64f154100d646c228c0d16585d21e95e0d1a006e537f7784c corpus/raw/raf-fuji-xt20-compressed.raf +07ea642656074834ffe5c661870a612ffa2e80fc1218a05166ee966bbe5f6fae corpus/raw/raf-fuji-xt4-3914.raf +871836938ffa695f4c41765ddb107c2703ce755f7f3ced7e10f9e04746f1734e corpus/raw/raf-fuji-xt4-3918.raf +b2a067e7fda16338f15c2532caa12b238b2415dc1c75a96a6d24d3445cfd0ae3 corpus/raw/raf-fuji-xt5-6122.raf +cddd7ae0c43f9280876e5fdcbdf8878718972ebd3d034d8affc8cfc6752d33dc corpus/raw/raf-fuji-xt5-6123.raf +3a8a9ac6d92274969aaa1f55ea669191b98bb8f588d00ec8ec17afd8b3963dea corpus/raw/raf-fuji-xt50-7807.raf diff --git a/crates/raw/src/cr2.rs b/crates/raw/src/cr2.rs index 314489e92..03ab9c376 100644 --- a/crates/raw/src/cr2.rs +++ b/crates/raw/src/cr2.rs @@ -24,6 +24,12 @@ //! bytes (ColorData versions -3 and -4), which are paired up in the maker note's byte order first. //! - The same array lists the levels of the camera's white-balance presets, each with the colour temperature Canon //! gives it ([`kelvin_presets_from_color_data`]): a Kelvin scale for a body without colour matrices. +//! - `AspectInfo` (maker note `0x009a`, as in CR3: aspect code, width, height, left, top): the in-camera aspect +//! ratio (3:2, 4:3, 16:9, 1:1) is not applied to the sensor data, and the rectangle is measured from the top-left +//! of the `SensorInfo` image area. It becomes the default crop (storytold/lightcraft#3313). Checked on the CC0 +//! PowerShot G12 and S120 files shot at 3:2 (3648 x 2432 at top 152 of a 3648 x 2736 area, 4000 x 2664 at top 168 +//! of 4000 x 3000: centred) and a G16 shot at 4:3 (the whole area); files shot at the sensor's own aspect store +//! the whole area or no tag. //! - sRAW / mRAW (raw IFD tag `0xc6c5` = 4) hold subsampled YCbCr instead of a mosaic: see [`sraw`]. mod sraw; @@ -273,10 +279,14 @@ pub(crate) fn decode(bytes: &[u8], mode: Mode, limits: &Limits) -> Result= 9) { let (l, tp, r, b) = (si[5] as usize, si[6] as usize, si[7] as usize, si[8] as usize); if r > l && b > tp && r < width && b < height { active = Rect::new(l, tp, r - l + 1, b - tp + 1); + // `AspectInfo` is measured from the image area's origin, so it only applies when that area is known. + let image = Rect::new(0, 0, active.width, active.height); + crop = crate::shared::aspect_crop(mn.as_ref().map(|m| &m.ifd), image).unwrap_or(image); } } let color_data = mn.as_ref().and_then(|m| m.ifd.value(COLOR_BALANCE).map(|v| words(v, m.order))); @@ -306,7 +316,7 @@ pub(crate) fn decode(bytes: &[u8], mode: Mode, limits: &Limits) -> Result)]) -> RawImage { + decode_sized_with_note(64, 10, entries) + } + + /// [`decode_with_note`] with a `w` x `h` sensor. + fn decode_sized_with_note(w: usize, h: usize, entries: &[(u16, u16, Vec)]) -> RawImage { let ifd_len = 2 + 12 * entries.len() + 4; let (mut note, mut data, mut at) = (Vec::new(), Vec::new(), Vec::new()); note.extend_from_slice(&(entries.len() as u16).to_le_bytes()); for (tag, ty, value) in entries { - let count = if *ty == 3 { value.len() / 2 } else { value.len() } as u32; + let count = match ty { + 3 => value.len() / 2, + 4 => value.len() / 4, + _ => value.len(), + } as u32; note.extend_from_slice(&tag.to_le_bytes()); note.extend_from_slice(&ty.to_le_bytes()); note.extend_from_slice(&count.to_le_bytes()); @@ -618,7 +637,7 @@ pub(crate) mod tests { } note.extend_from_slice(&0u32.to_le_bytes()); note.extend_from_slice(&data); - let (mut bytes, _) = synthetic_cr2_note(64, 10, None, Some(note)); + let (mut bytes, _) = synthetic_cr2_note(w, h, None, Some(note)); let tiff = Tiff::parse(&bytes).unwrap(); let off = tiff.exif().unwrap().get(t::MAKER_NOTE).unwrap().offset as usize; for (field, value) in at { @@ -766,4 +785,44 @@ pub(crate) mod tests { assert_eq!(r.active_area, Rect::new(left, top, w - left, h - top)); assert!((13300.0..=13433.0).contains(&r.white[0]), "{:?}", r.white); } + + /// A 68 x 50 sensor whose `SensorInfo` image area is the 64 x 48 (4:3) at (4, 2), with `aspect` as its + /// `AspectInfo` (LONG x 5), decoded. + fn decode_with_aspect(aspect: Option<[u32; 5]>) -> RawImage { + let si: Vec = [68u16, 50, 0, 0, 0, 4, 2, 67, 49].iter().flat_map(|v| v.to_le_bytes()).collect(); + let mut entries = vec![(SENSOR_INFO, 3, si)]; + if let Some(a) = aspect { + entries.push((crate::shared::ASPECT_INFO, 4, a.iter().flat_map(|v| v.to_le_bytes()).collect())); + } + decode_sized_with_note(68, 50, &entries) + } + + /// storytold/lightcraft#3313: a CR2 shot at 3:2 on a 4:3 sensor (PowerShot G12: `AspectInfo` 3648 x 2432 at + /// top 152 of the 3648 x 2736 image area) opens with that rectangle as its crop, as a CR3 does; the active + /// area is unchanged. + #[test] + fn aspect_info_replaces_the_crop() { + let image = decode_with_aspect(Some([0, 64, 42, 0, 3])); + assert_eq!(image.active_area, Rect::new(4, 2, 64, 48)); + assert_eq!(image.crop, Rect::new(0, 3, 64, 42)); + assert_eq!(image.info().developed_size(), (64, 42)); + // 1:1 with a left offset + assert_eq!(decode_with_aspect(Some([1, 48, 48, 8, 0])).crop, Rect::new(8, 0, 48, 48)); + // the whole image area, as stored for a shot at the sensor's own aspect (G16 at 4:3), or no tag: unchanged + for aspect in [Some([2, 64, 48, 0, 0]), None] { + assert_eq!(decode_with_aspect(aspect).crop, Rect::new(0, 0, 64, 48), "{aspect:?}"); + } + } + + /// Rectangles that don't fit the image area leave the crop alone and cannot overflow; without a usable + /// `SensorInfo` the origin `AspectInfo` is measured from is unknown, so it isn't applied either. + #[test] + fn aspect_info_that_does_not_fit_is_ignored() { + for bad in [[0, 65, 42, 0, 3], [0, 64, 42, 0, 7], [0, 64, 42, 1, 3], [0, 1, 42, 0, 0], [0, 64, 0, 0, 0], [0, u32::MAX, 42, 0, 0]] { + assert_eq!(decode_with_aspect(Some(bad)).crop, Rect::new(0, 0, 64, 48), "{bad:?}"); + } + let aspect = [0u32, 32, 8, 0, 1].iter().flat_map(|v| v.to_le_bytes()).collect(); + let image = decode_with_note(&[(crate::shared::ASPECT_INFO, 4, aspect)]); + assert_eq!((image.active_area, image.crop), (Rect::new(0, 0, 64, 10), Rect::new(0, 0, 64, 10))); + } } diff --git a/crates/raw/src/cr3.rs b/crates/raw/src/cr3.rs index bea3766fa..d8f23f339 100644 --- a/crates/raw/src/cr3.rs +++ b/crates/raw/src/cr3.rs @@ -19,14 +19,13 @@ //! Unknown camera metadata versions are ignored rather than assigned a guessed white balance. use crate::crx; -use crate::shared::{black_from_columns, white_from_data}; +use crate::shared::{aspect_crop, black_from_columns, white_from_data}; use crate::{BlackLevel, Camera, Cfa, ColorData, Limits, Mode, OpcodeLists, Orientation, RawData, RawError, RawFormat, RawImage, Rect, Result}; use craft_metadata::cr3::{Cr3ImageArea, Cr3Track, Cr3TrackKind, parse_cr3}; use craft_tiff::{Ifd, Tiff}; const SENSOR_INFO: u16 = 0x00e0; const COLOR_DATA: u16 = 0x4001; -const ASPECT_INFO: u16 = 0x009a; /// Pick the first largest raw track. Equal-sized later tracks can be the Dual Pixel delta, which /// must never replace the main sensor image. An invalid full-size descriptor is reported, not @@ -93,18 +92,6 @@ fn sensor_crop(maker: Option<&Ifd>, width: usize, height: usize) -> Option ) } -/// The shot's aspect-ratio rectangle from `AspectInfo`, placed inside `image` (the recommended crop). `None` -/// when the tag is absent or malformed, or its rectangle doesn't fit inside `image`. -fn aspect_crop(maker: Option<&Ifd>, image: Rect) -> Option { - let data = maker?.u64s(ASPECT_INFO)?; - let [width, height, left, top] = [1usize, 2, 3, 4].map(|i| data.get(i).and_then(|&v| usize::try_from(v).ok())); - let (width, height, left, top) = (width?, height?, left?, top?); - if width < 2 || height < 2 || left.checked_add(width)? > image.width || top.checked_add(height)? > image.height { - return None; - } - Some(Rect::new(image.x.checked_add(left)?, image.y.checked_add(top)?, width, height)) -} - fn geometry(area: Option<&Cr3ImageArea>, maker: Option<&Ifd>, width: usize, height: usize) -> (Rect, Rect) { let area = area.filter(|a| usize::from(a.width) == width && usize::from(a.height) == height); let sensor = sensor_crop(maker, width, height); @@ -385,6 +372,7 @@ fn extend_white(image: &mut RawImage) -> bool { #[cfg(test)] mod tests { use super::*; + use crate::shared::ASPECT_INFO; use craft_tiff::{IfdBuilder, Value}; fn maker(version: u16, wb_at: usize, black_at: usize, white_at: usize) -> Ifd { diff --git a/crates/raw/src/shared.rs b/crates/raw/src/shared.rs index 407f8427a..c2da593cb 100644 --- a/crates/raw/src/shared.rs +++ b/crates/raw/src/shared.rs @@ -223,6 +223,22 @@ fn solve4(mut a: [[f64; 4]; 4], mut b: [f64; 4]) -> Option<[f64; 4]> { x.iter().all(|v| v.is_finite()).then_some(x) } +/// Canon maker-note `AspectInfo` (`0x009a`): aspect code, width, height, left, top, as 32-bit values. +pub(crate) const ASPECT_INFO: u16 = 0x009a; + +/// The shot's aspect-ratio rectangle from a Canon maker note's `AspectInfo`, placed inside `image` (the image area +/// it is measured from). `None` when the tag is absent or malformed, or its rectangle doesn't fit inside `image`. +/// Used by CR2 and CR3, so it lives here rather than behind either decoder's feature. +pub(crate) fn aspect_crop(maker: Option<&craft_tiff::Ifd>, image: Rect) -> Option { + let data = maker?.u64s(ASPECT_INFO)?; + let [width, height, left, top] = [1usize, 2, 3, 4].map(|i| data.get(i).and_then(|&v| usize::try_from(v).ok())); + let (width, height, left, top) = (width?, height?, left?, top?); + if width < 2 || height < 2 || left.checked_add(width)? > image.width || top.checked_add(height)? > image.height { + return None; + } + Some(Rect::new(image.x.checked_add(left)?, image.y.checked_add(top)?, width, height)) +} + #[cfg(test)] pub(crate) fn declare_strip_len(file: &mut [u8], len: u32, declared: u32) { let big = file.starts_with(b"MM"); diff --git a/crates/raw/tests/it/main.rs b/crates/raw/tests/it/main.rs index 5a9386eb0..30f331263 100644 --- a/crates/raw/tests/it/main.rs +++ b/crates/raw/tests/it/main.rs @@ -6,6 +6,7 @@ mod dng; mod dng_lines; #[cfg(feature = "line-dng")] mod dng_metadata; +mod raf_corpus_manifest; #[cfg(feature = "dng")] mod robust; mod vendor_robust; diff --git a/crates/raw/tests/it/raf_corpus_manifest.rs b/crates/raw/tests/it/raf_corpus_manifest.rs new file mode 100644 index 000000000..4cd1cfde6 --- /dev/null +++ b/crates/raw/tests/it/raf_corpus_manifest.rs @@ -0,0 +1,24 @@ +//! The pinned RAF corpus list `docs/raf-corpus.sha256` holds `#` comment lines, then one +//! `sha256path[license[url]]` row per file. The test reads the list only, not the corpus files. + +use std::collections::HashSet; + +const MANIFEST: &str = include_str!("../../docs/raf-corpus.sha256"); + +#[test] +fn raf_corpus_list_is_a_tab_separated_manifest() { + let mut paths = HashSet::new(); + let mut digests = HashSet::new(); + for line in MANIFEST.lines().filter(|l| !l.trim().is_empty() && !l.starts_with('#')) { + let cols: Vec<&str> = line.split('\t').collect(); + assert!((2..=4).contains(&cols.len()), "not a tab-separated manifest row: {line:?}"); + let (digest, path) = (cols[0], cols[1]); + assert!(digest.len() == 64 && digest.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')), "not a lowercase SHA-256 digest: {line:?}"); + assert!(path.starts_with("corpus/raw/") && path.len() > "corpus/raw/.raf".len() && path.ends_with(".raf"), "not a corpus RAF path: {line:?}"); + assert!(!path.contains(char::is_whitespace), "whitespace in the path: {line:?}"); + assert!(cols[2..].iter().all(|c| !c.is_empty()), "empty optional column: {line:?}"); + assert!(paths.insert(path), "path listed twice: {path}"); + assert!(digests.insert(digest), "digest listed twice: {digest}"); + } + assert_eq!(paths.len(), 17, "the pinned list holds the 17 CC0 RAF files"); +} 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"]); +} 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. 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); + } +} diff --git a/crates/testkit/Cargo.toml b/crates/testkit/Cargo.toml new file mode 100644 index 000000000..d32ed735f --- /dev/null +++ b/crates/testkit/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "craft-testkit" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +description = "Source-level platform regression guards and verification utilities for the Craft application suite" +publish = false + +[dependencies] + +[lints] +workspace = true diff --git a/crates/testkit/README.md b/crates/testkit/README.md new file mode 100644 index 000000000..8b8e9b208 --- /dev/null +++ b/crates/testkit/README.md @@ -0,0 +1,268 @@ +# craft-testkit + +Source-level platform regression guards and verification utilities for the Craft application suite. + +## Overview + +`craft-testkit` provides lightweight, non-panicking source guards that prevent applications in the Craft ecosystem from repeating platform defects that were previously diagnosed and resolved in peer applications: + +1. **`predefined_quit`**: Flags direct calls to `muda`'s `PredefinedMenuItem::quit` outside comments, strings and character literals, also with whitespace or a line break around `::`, in the qualified form `::quit`, and through a `use muda::PredefinedMenuItem as ...` rename. A type of the same name reached through another crate or module, such as `other::PredefinedMenuItem::quit`, is not flagged. On macOS, this predefined menu item routes directly to `NSApplication terminate:`, completely bypassing application dirty document checks and unsaved changes save prompts. Applications should instead wire Quit through `craft-quit` lifecycle interceptors. +2. **`wgsl_float_literals` / `wgsl_float_literals_in`**: Scans WGSL shader sources and flags decimal and hexadecimal float literals whose value, rounded to `f64`, exceeds `f32::MAX` (such as `3.40282347e38` or `0x1p+500f`), or 65504, the largest finite `f16`, for a literal with an `h` suffix. A literal that exceeds the maximum by less than `f64` precision rounds to the maximum and is not reported. Integer literals are not checked. Some native compilers round such literals down, but browser WebGPU compilers reject them with pipeline compilation errors, forcing applications into CPU fallback rendering. `f32::MAX` can be written as the hex float `0x1.fffffep+127f`, which equals it, or as the decimal `3.4028234663852886e38`, which rounds to it. +3. **`std_instant`**: Flags `std::time::Instant` outside comments and strings: the full path, `::Instant` where a `use` binds `m` to `std::time`, and each `use` that imports `std::time::Instant` or `std::time::*`, under any name. The parts of a path may be split by whitespace, comments or line breaks. Other crates' `Instant` (such as `web_time::Instant` or `tokio::time::Instant`) is not flagged, and neither is an item whose `cfg` attribute is false on `wasm32-unknown-unknown`; code before that attribute or after its item on the same line is still checked. A `mod name;` inside such an item also skips the module's file (`name.rs` or `name/mod.rs`, or the file a `#[path]` attribute names) and the files of the modules declared in it, when they are among the files passed in and no declaration outside such items also reaches them. On that target, `std::time::Instant::now()` panics at runtime with `"time not implemented on this platform"`. Code targeting the web must use `web_time::Instant`. +4. **`rust_sources`**: Recursively discovers a crate's `.rs` source files while excluding integration tests (`tests/`), test modules (`tests.rs`, `tests_*.rs`, `*_tests.rs`, `*_test.rs`), build artifacts (`target/`, any folder holding a `CACHEDIR.TAG` file that starts with the line `Signature: 8a477f597d28d172789f06886806bc55`, `.git/` and other folders whose name starts with `.`) and symbolic links, which it does not follow. A file over 8 MiB, more than 256 MiB in all or more than 50,000 files returns an error; `rust_sources_with_limits` takes other limits. It is not built for `wasm32`. + +## Epistemic Scope: Syntactic Guards vs Runtime Validation + +Source-level guards provide deterministic syntactic evidence about codebase structure: + +### What They Establish +- Checked source files do not contain forbidden symbol invocations, known out-of-range literal representations, or platform-hazardous imports. +- Reusable, deterministic checks that run in milliseconds as regular Cargo tests without external runners. + +### What They Cannot Establish +- **Runtime execution safety**: Syntactic checks do not verify whether code branches actually execute at runtime. +- **Semantic type resolution**: The scanners follow `use` renames within one file only. They do not resolve paths through other modules or re-exports, a rename of `std` itself, or expand macros. +- **Complex target predicates**: `std_instant` evaluates `cfg` predicates (`all`, `any`, `not`, `unix`, `windows` and the `target_*` keys) for `wasm32-unknown-unknown`, on outer attributes for the item that follows and on inner attributes (`#![cfg(...)]`) for the rest of the module, and on `mod name;` declarations for the module's file and its descendants. It compares file paths as text, so the files must come from one `rust_sources` call or be named the same way. A predicate that depends on a feature or on `test` is not known from the source, so its item is checked. Applications should scope `std_instant` tests to the specific crates that compile into their web distribution. +- **Driver and host OS behavior**: Syntactic checks do not verify WebGPU driver compatibility or host window manager event dispatch. + +Source guards serve as fast, zero-dependency regression gates in application test suites, complementing platform integration tests and CI workflows. + +## Consumer Adoption Examples + +### 1. PhotoCraft: Adopt `wgsl_float_literals` and `predefined_quit` + +In `photocraft/crates/gpu/src/lib.rs`, replace the in-tree `decimal_float_literals` helper with `craft_testkit::wgsl_float_literals`: + +```rust +#[test] +fn shader_float_literals_fit_f32() { + let bad = craft_testkit::wgsl_float_literals(SHADER); + assert!( + bad.is_empty(), + "float literals outside f32 finite range reject on WebGPU (Tint):\n{}", + bad.iter().map(|f| f.to_string()).collect::>().join("\n") + ); +} +``` + +In `photocraft/apps/photocraft/tests/native_menu_tests.rs`: + +```rust +#[test] +fn no_unintercepted_predefined_quit_in_menu() { + let sources = craft_testkit::rust_sources("src").expect("scan sources"); + let findings = craft_testkit::predefined_quit(&sources); + assert!( + findings.is_empty(), + "predefined muda Quit bypasses dirty document save prompts:\n{}", + findings.iter().map(|f| f.to_string()).collect::>().join("\n") + ); +} +``` + +### 2. FilmCraft: Adopt `std_instant` and `wgsl_float_literals` + +In `filmcraft/crates/engine/src/wasm_clock_tests.rs`, replace in-tree textual search with `craft_testkit::std_instant`: + +```rust +#[test] +fn no_std_instant_in_code_the_web_build_runs() { + let sources = craft_testkit::rust_sources(Path::new(env!("CARGO_MANIFEST_DIR")).join("src")) + .expect("scan engine sources"); + let findings = craft_testkit::std_instant(&sources); + assert!( + findings.is_empty(), + "std::time::Instant panics on wasm32; use web_time::Instant:\n{}", + findings.iter().map(|f| f.to_string()).collect::>().join("\n") + ); +} +``` + +## deadline + +The `deadline` module is not built for `wasm32`. + +`with_deadline(limit, label, f)` runs `f` on its own thread and returns its value. When `f` does not +finish within the limit, the test fails with a message that names `label`, the limit and the variable +that sets it. A panic in `f` is raised again in the test with its original payload. The limit counts +from the call, including the time spent starting the thread. When `f` returns or panics after the +limit has passed, the test fails with the label and the limit, and with the panic's message if it has +one. + +`wait_until(limit, what, cond)` calls `cond` on the test's thread until it returns `true`. It calls +`cond` at once, then after pauses that start at 1 ms and double up to 50 ms, and does not call it +again once the limit has passed. When the limit passes first, or `cond` returns `true` only after the +limit has passed, the test fails with a message that names `what`. + +```rust +use std::time::Duration; +use craft_testkit::deadline::{DeadlineLimit, wait_until, with_deadline}; + +// The default of 30 s; CRAFT_TEST_TIMEOUT_SECS replaces it. +let pixels = with_deadline(Duration::from_secs(30), "decode seed 7", move || decode(&bytes)); + +// The app's own variable replaces the default instead. +let limit = DeadlineLimit::new(Duration::from_secs(30)).with_variable("FILMCRAFT_HOSTILE_TIMEOUT_SECS"); +with_deadline(limit, "hostile input 12", move || parse(&input)); + +wait_until(Duration::from_secs(10), "the export to finish", || job.is_done()); +``` + +### The limit variable + +A `Duration` reads `CRAFT_TEST_TIMEOUT_SECS`. `DeadlineLimit::with_variable` names another variable. +The variable is read on every call; neither function sets or caches it. + +| Value | Result | +|---|---| +| Not set | The default limit applies. | +| Decimal digits above zero, such as `30` or `007` | That many seconds replace the default. | +| Empty, signed (`+5`, `-5`), fractional (`1.5`), with spaces or units (`5s`), zero, or larger than a `u64` | The test fails with the variable's name and value, before `f` runs or `cond` is called. | +| Not Unicode | The test fails with the variable's name, before `f` runs or `cond` is called. | + +A zero default, a variable name that is empty or holds `=` or a NUL character, and a limit that ends past +the latest time the platform's clock can represent also fail the test before any work starts. + +FilmCraft's `filmcraft-testkit` uses the default when the variable holds something other than a +number or holds zero. This module fails the test instead. `craft-media-testkit`'s `with_deadline` +calls this module's. + +### Limits + +- A body that runs past its limit fails the test, but its thread is left running until the test + process exits. A body that never returns can keep the test binary alive after its tests finish. +- `wait_until` checks its limit only between calls of `cond`. A `cond` that blocks is not interrupted, + so it must return promptly. +- Neither function returns elapsed time. Tests of this crate use channel handshakes, and the only time + bounds in them are the limits under test. + +## hostile + +`mutations(seed, rounds)` yields `rounds` damaged copies of a valid seed. Each round makes one to four +edits: a bit flip, a random byte, a 1, 2, 4 or 8-byte overwrite with an extreme value +(0, 1, 0x7F, 0x80, 0xFF, 0xFFFF, 0x8000_0000 or `u64::MAX`) in either byte order, a deletion of up to +16 bytes, or a truncation. Each copy carries a label that lists its edits, such as +`flip[3].5 del[7..9]`. The xorshift64* generator behind it is seeded from the seed's length, so the +same seed length and round count give the same edits on every run and every platform. An empty seed +yields no copies. `mutations` and `Rng` build for `wasm32`. + +`hammer(&config, seed, parse)` runs `parse` on the unmodified seed, on every truncation of it +(lengths 0 to one less than its length), and on `mutations(seed, rounds)`. The cases run one after +another on one worker thread, and the test's thread fails the test when a case runs past its limit. +A case that finishes after its limit also fails the test. The test fails on the first case that +panics or does not finish, with a message that names the config's label, the case +(`the unmodified seed`, `truncation to N` or the edits), the input's length and the panic's message. +`parse` must be `Fn(&[u8]) + Send + Sync + 'static`, since a case that does not finish keeps running +on the worker thread after the test fails. `hammer` is not built for `wasm32`. + +```rust +use std::time::Duration; +use craft_testkit::DeadlineLimit; +use craft_testkit::hostile::{HammerConfig, hammer}; + +// 2,000 rounds times CRAFT_HOSTILE_MULT; 5 s per case, or CRAFT_TEST_TIMEOUT_SECS. +hammer(&HammerConfig::new("png seed 3", 2_000), &seed, |data| { + let _ = decode(data); +}); + +// The app's own variables instead. +let config = HammerConfig::new("mxf primer", 5_000) + .with_multiplier_variable("CRAFT_MEDIA_HOSTILE_MULT") + .with_timeout(DeadlineLimit::new(Duration::from_secs(5)).with_variable("FILMCRAFT_HOSTILE_TIMEOUT_SECS")); +hammer(&config, &primer, |data| { + let _ = parse_primer(data); +}); +``` + +### The rounds + +The rounds are the config's iterations times the multiplier variable, `CRAFT_HOSTILE_MULT` unless +`with_multiplier_variable` names another. The limit for each case is 5 s, replaced by +`CRAFT_TEST_TIMEOUT_SECS` or the variable that `with_timeout` names, as in `deadline`. Both variables +are read once, before any case runs. `HammerConfig::rounds` returns the rounds or the error that `hammer` would fail with. + +| Multiplier value | Result | +|---|---| +| Not set | The multiplier is 1. | +| Decimal digits above zero, such as `10` | The rounds are multiplied by that number. | +| Empty, signed, fractional, with spaces, zero, or larger than a `usize` | The test fails with the variable's name and value before `parse` is called. | +| Not Unicode | The test fails with the variable's name before `parse` is called. | + +A product of the iterations and the multiplier that does not fit in a `usize`, a call that would run +more than `MAX_CASES` (10,000,000) cases in all, and a limit variable that `deadline` would reject +also fail the test before `parse` is called. + +Changes from `craft-media-testkit`'s `hammer`: + +- A case that does not finish fails the test after its limit with the case's label. Before, a case + was timed after it returned and failed only when it took longer than 5 s. +- A panic's message is part of the failure. +- Every truncation runs. Before, a seed of 8,192 bytes or more ran every `len / 4096`th truncation. +- The caller names the multiplier variable. Before, it was always `CRAFT_MEDIA_HOSTILE_MULT`, and a + value that was not a number counted as 1. +- An empty seed runs once. Before, it ran once more for each round. +- A mutation's label joins its edits with single spaces. Before, every edit ended with a space, so + each label ended with one. +- `parse` is owned and runs on a worker thread. A closure that borrows from the test needs its data + moved or shared with an `Arc`. + +## Origin + +### guards + +| Module | Source | Path | Commit | +|---|---|---|---| +| `guards` | storytold/craft-libs#163 (zachshallbetter), with the rules of PhotoCraft's shader float test and FilmCraft's web clock test | `crates/testkit/src/guards.rs` | `e92825e427` | + +### deadline + +| Code | Repository | Path | SHA | +|---|---|---|---| +| `with_deadline`, its panic and timeout tests (`a_slow_body_passes`, `a_panic_in_the_body_is_re_raised`, `a_hang_fails_and_names_the_input`) | storytold/filmcraft | `crates/testkit/src/deadline.rs` | `cff7e144` | +| `with_deadline` under `CRAFT_TEST_TIMEOUT_SECS`, tests `with_deadline_completes` and `with_deadline_times_out` | storytold/craft-libs | `crates/media-testkit/src/lib.rs` | `75a654f4` | +| `within`, a deadline that returns the body's value | storytold/lightcraft | `crates/engine/src/demo/tests.rs` | `487833ad` | +| `within`, a deadline that returns the body's value | storytold/gridcraft | `crates/math/src/lib.rs` | `c2aba7a3` | +| `wait_until` | storytold/photocraft | `crates/ui-egui/src/canvas/paint_thread_tests.rs` | `0d3b1e85` | +| `wait_until` | storytold/lightcraft | `crates/engine/src/availability.rs` | `7ebbb17a` | +| `wait_until` | storytold/effectcraft | `crates/engine/src/footage/footage_reload.rs` | `53576d22` | +| `wait_until` | storytold/filmcraft | `crates/ui-egui/tests/it/export_ui.rs` | `cff7e144` | + +### hostile + +| Code | Repository | Path | SHA | +|---|---|---|---| +| `Rng`, the edits of `mutations` and `hammer` | storytold/craft-libs | `crates/media-testkit/src/hostile.rs` | `75a654f4` | + +## Migration + +### guards + +| Consumer | Guard | Replaces | State | +|---|---|---|---| +| PhotoCraft | `wgsl_float_literals` | `crates/gpu/src/tests.rs` scanner | Not started | +| FilmCraft | `std_instant` | `crates/engine/src/wasm_clock_tests.rs` search | Not started | + +### deadline + +| Consumer | Code it replaces | State | +|---|---|---| +| FilmCraft | `filmcraft-testkit`'s `with_deadline` (`FILMCRAFT_HOSTILE_TIMEOUT_SECS`) and the export UI tests' `wait_until` | Pending | +| LightCraft | `within` in the demo tests and `wait_until` in the availability tests | Pending | +| GridCraft | `within` in the tests of its `crates/math` | Pending | +| PhotoCraft | `wait_until` in the paint thread tests | Pending | +| EffectCraft | `wait_until` in the footage reload tests | Pending | +| `craft-media-testkit` | `with_deadline` (`CRAFT_TEST_TIMEOUT_SECS`) | Done | + +An adoption keeps the variable name the app uses today. + +### hostile + +| Consumer | Code it replaces | State | +|---|---|---| +| `craft-media-testkit` | `hostile::hammer` (`CRAFT_MEDIA_HOSTILE_MULT`), called by the ISO BMFF, AVI, Matroska, MXF and MPEG TS hostile tests | Done | +| `craft-cfb` | its `hostile_input_never_panics` test, through `craft-media-testkit` | Done | +| CADCraft | the mutation loop of `hostile_files_never_panic` in `crates/fonts/src/shx/tests.rs` | Pending | +| TextureCraft | the `hammer` of `malformed_meshes_are_errors` in `crates/formats/src/mesh_import/tests.rs` | Pending | + +CADCraft's and TextureCraft's loops make other edits than `mutations`. Their adoptions say which +cases change, and keep the test names. diff --git a/crates/testkit/src/deadline.rs b/crates/testkit/src/deadline.rs new file mode 100644 index 000000000..918719e6b --- /dev/null +++ b/crates/testkit/src/deadline.rs @@ -0,0 +1,788 @@ +//! Limits on how long a test waits. +//! +//! [`with_deadline`] runs a test body on its own thread and returns its value. When the body does not +//! finish within the limit, the test fails with the call's label, the limit and the variable that sets +//! it. A panic in the body is raised again in the test with its original payload. +//! +//! [`wait_until`] calls a condition on the test's thread until it returns `true`, pausing between +//! calls, and fails the test with its description when the limit passes first. +//! +//! A limit is a default [`Duration`] and the name of a variable that replaces it. A plain `Duration` +//! reads [`DEFAULT_VARIABLE`]; [`DeadlineLimit::with_variable`] names another one. The variable holds +//! whole seconds as decimal digits and is read on every call. A value that is empty, signed, +//! fractional, not Unicode, zero, or larger than a `u64` fails the test that reads it, as does a zero +//! default and a limit past the latest time the platform's clock can represent. +//! +//! Neither function can stop code that does not return. A body that runs past its limit fails the +//! test, and its thread is left running until the test process exits. A condition that blocks is +//! not interrupted: [`wait_until`] checks its limit only between calls, so a condition must return +//! promptly. + +use std::any::Any; +use std::ffi::OsString; +use std::fmt; +use std::io; +use std::panic::{AssertUnwindSafe, catch_unwind, resume_unwind}; +use std::sync::mpsc::{self, RecvTimeoutError, Sender}; +use std::sync::{Arc, Mutex, PoisonError}; +use std::thread; +use std::time::{Duration, Instant}; + +/// The variable a limit reads unless [`DeadlineLimit::with_variable`] names another. +pub const DEFAULT_VARIABLE: &str = "CRAFT_TEST_TIMEOUT_SECS"; + +/// The first pause of [`wait_until`] between two calls of its condition. +const FIRST_PAUSE: Duration = Duration::from_millis(1); + +/// The longest pause of [`wait_until`]: each pause doubles up to this. +const MAX_PAUSE: Duration = Duration::from_millis(50); + +/// The name of the thread [`with_deadline`] runs a body on. +const WORKER_NAME: &str = "craft-testkit deadline"; + +/// A limit for [`with_deadline`] and [`wait_until`]: a default duration and the name of the +/// variable that replaces it. +/// +/// ``` +/// use std::time::Duration; +/// use craft_testkit::deadline::DeadlineLimit; +/// +/// // Reads CRAFT_TEST_TIMEOUT_SECS. +/// let limit: DeadlineLimit = Duration::from_secs(30).into(); +/// assert_eq!(limit.variable(), "CRAFT_TEST_TIMEOUT_SECS"); +/// +/// // Reads the app's own variable instead. +/// let limit = DeadlineLimit::new(Duration::from_secs(30)).with_variable("FILMCRAFT_HOSTILE_TIMEOUT_SECS"); +/// assert_eq!(limit.default_limit(), Duration::from_secs(30)); +/// ``` +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct DeadlineLimit<'a> { + default: Duration, + variable: &'a str, +} + +impl DeadlineLimit<'static> { + /// A limit of `default` that [`DEFAULT_VARIABLE`] replaces. + pub fn new(default: Duration) -> Self { + Self { default, variable: DEFAULT_VARIABLE } + } +} + +impl<'a> DeadlineLimit<'a> { + /// The same default, replaced by the variable `name` instead. + pub fn with_variable<'b>(self, name: &'b str) -> DeadlineLimit<'b> { + DeadlineLimit { default: self.default, variable: name } + } + + /// The limit that applies when the variable is not set. + pub fn default_limit(&self) -> Duration { + self.default + } + + /// The name of the variable that replaces the default. + pub fn variable(&self) -> &'a str { + self.variable + } +} + +impl From for DeadlineLimit<'static> { + fn from(default: Duration) -> Self { + Self::new(default) + } +} + +/// Runs `f` on its own thread and returns its value, failing the calling test when `f` does not +/// finish within `limit`. +/// +/// The failure names `label`, the limit and the variable that sets it. A panic in `f` is raised +/// again here with its original payload. The limit is read and checked before `f` starts, and a +/// limit that is not valid fails the test without running `f`. The limit counts from the call, so +/// the time spent starting the thread counts against it. When `f` returns or panics after the limit +/// has passed, the test fails with the label and the limit, and with the panic's message if it has +/// one. When the limit passes, the thread running `f` is left running. +/// +/// ``` +/// use std::time::Duration; +/// use craft_testkit::deadline::with_deadline; +/// +/// let sum = with_deadline(Duration::from_secs(30), "sum of 1 to 10", || (1..=10).sum::()); +/// assert_eq!(sum, 55); +/// ``` +// Failing the calling test is what this function is for. +#[allow(clippy::panic)] +#[track_caller] +pub fn with_deadline<'a, T: Send + 'static>(limit: impl Into>, label: &str, f: impl FnOnce() -> T + Send + 'static) -> T { + let start = Instant::now(); + match run_with_deadline(limit.into(), label, f, read_variable, spawn_worker, Arc::new(move || start.elapsed())) { + Ok(value) => value, + Err(Failure::Panic(payload)) => resume_unwind(payload), + Err(Failure::Message(message)) => panic!("{message}"), + } +} + +/// Calls `cond` on the calling thread until it returns `true`, failing the calling test when the +/// limit passes first. +/// +/// `cond` is called at once, and then after pauses that grow from 1 ms to 50 ms, but not again once +/// the limit has passed. The failure names `what`, the limit and the variable that sets it. A `true` +/// that `cond` returns after the limit has passed also fails the test. A panic in `cond` reaches the +/// caller unchanged. `cond` runs on the calling thread and is not interrupted, so it must return +/// promptly. +/// +/// ``` +/// use std::sync::atomic::{AtomicBool, Ordering}; +/// use std::time::Duration; +/// use craft_testkit::deadline::wait_until; +/// +/// let ready = AtomicBool::new(false); +/// std::thread::scope(|s| { +/// s.spawn(|| ready.store(true, Ordering::SeqCst)); +/// wait_until(Duration::from_secs(30), "the worker to start", || ready.load(Ordering::SeqCst)); +/// }); +/// ``` +// Failing the calling test is what this function is for. +#[allow(clippy::panic)] +#[track_caller] +pub fn wait_until<'a>(limit: impl Into>, what: &str, mut cond: impl FnMut() -> bool) { + let limit = limit.into(); + let start = Instant::now(); + let resolved = match resolve(&limit, read_variable, start) { + Ok(resolved) => resolved, + Err(error) => panic!("waiting for {what}: {error}"), + }; + let mut elapsed = || start.elapsed(); + if let Err(message) = poll_until(&resolved, what, &mut cond, &mut elapsed, &mut thread::sleep) { + panic!("{message}"); + } +} + +/// A limit after reading its variable. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) struct Resolved<'a> { + pub(crate) limit: Duration, + variable: &'a str, + from_variable: bool, +} + +impl fmt::Display for Resolved<'_> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + if self.from_variable { + write!(f, "{:?}, set by {}", self.limit, self.variable) + } else { + write!(f, "{:?}, the default; {} replaces it in whole seconds", self.limit, self.variable) + } + } +} + +/// Why a limit cannot be used. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) enum LimitError<'a> { + /// The variable name is empty or holds `=` or a NUL character. + BadName { variable: &'a str }, + /// The variable's value is not Unicode. + NotUnicode { variable: &'a str }, + /// The variable's value is not a whole number of seconds above zero. + BadValue { variable: &'a str, value: String, reason: &'static str }, + /// The default limit is zero. + ZeroDefault { variable: &'a str }, + /// The limit ends past the latest time the clock can represent. + TooLarge { resolved: Resolved<'a> }, +} + +impl fmt::Display for LimitError<'_> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::BadName { variable } => write!(f, "{variable:?} cannot name a variable: it is empty or holds `=` or a NUL character"), + Self::NotUnicode { variable } => write!(f, "{variable} is not valid Unicode; set it to a whole number of seconds above zero"), + Self::BadValue { variable, value, reason } => { + write!(f, "{variable}={value:?} {reason}; set it to a whole number of seconds above zero") + } + Self::ZeroDefault { variable } => write!(f, "the default limit is zero; pass a default above zero ({variable} replaces it)"), + Self::TooLarge { resolved } => write!(f, "the limit of {resolved} ends past the latest time this platform's clock can represent"), + } + } +} + +/// Reads and checks `limit`: the variable's value when `lookup` finds one, otherwise the default. +/// `now` is the time the limit starts from. +pub(crate) fn resolve<'a>( + limit: &DeadlineLimit<'a>, + lookup: impl FnOnce(&str) -> Option, + now: Instant, +) -> Result, LimitError<'a>> { + let variable = limit.variable; + if variable.is_empty() || variable.contains(['=', '\0']) { + return Err(LimitError::BadName { variable }); + } + if limit.default.is_zero() { + return Err(LimitError::ZeroDefault { variable }); + } + let resolved = match lookup(variable) { + None => Resolved { limit: limit.default, variable, from_variable: false }, + Some(raw) => { + let value = raw.into_string().map_err(|_| LimitError::NotUnicode { variable })?; + let secs = parse_secs(&value).map_err(|reason| LimitError::BadValue { variable, value: value.clone(), reason })?; + Resolved { limit: Duration::from_secs(secs), variable, from_variable: true } + } + }; + if now.checked_add(resolved.limit).is_none() { + return Err(LimitError::TooLarge { resolved }); + } + Ok(resolved) +} + +/// Parses a whole number of seconds above zero, written as decimal digits only. +fn parse_secs(value: &str) -> Result { + if value.is_empty() { + return Err("is empty"); + } + if !value.bytes().all(|b| b.is_ascii_digit()) { + return Err("is not a whole number of seconds written in digits"); + } + match value.parse::() { + Ok(0) => Err("is zero"), + Ok(secs) => Ok(secs), + Err(_) => Err("is more seconds than a u64 holds"), + } +} + +/// Reads the variable `name` from the process environment. +fn read_variable(name: &str) -> Option { + std::env::var_os(name) +} + +/// A body boxed for the worker thread. +type Job = Box; + +/// Starts `job` on a named thread and detaches it. The thread sends on `done` after `job` returns. +fn spawn_worker(job: Job, done: Sender<()>) -> io::Result<()> { + thread::Builder::new() + .name(WORKER_NAME.to_owned()) + .spawn(move || { + job(); + let _ = done.send(()); + }) + .map(drop) +} + +/// The body's result and the clock reading when it finished, filled in by the worker. +type Slot = Arc, Duration)>>>; + +/// How a [`with_deadline`] call failed. +enum Failure { + /// The body panicked with this payload. + Panic(Box), + /// The call failed for this reason. + Message(String), +} + +/// A clock that returns the time since a [`with_deadline`] call started. +type Clock = Arc Duration + Send + Sync>; + +/// The text of a panic payload that holds a message. +fn panic_text(payload: &(dyn Any + Send)) -> Option<&str> { + payload.downcast_ref::().map(String::as_str).or_else(|| payload.downcast_ref::<&str>().copied()) +} + +/// [`with_deadline`] with the variable lookup, the thread start and the clock passed in. Starting +/// the worker counts against the limit. The worker stores the body's result with the clock reading +/// when it finished, under a lock, and then sends on the channel `spawn` receives. When the wait +/// times out, the stored result is still used if it is there, so a body that finished in time passes +/// even when its thread sends late. +fn run_with_deadline( + limit: DeadlineLimit<'_>, + label: &str, + f: impl FnOnce() -> T + Send + 'static, + lookup: impl FnOnce(&str) -> Option, + spawn: impl FnOnce(Job, Sender<()>) -> io::Result<()>, + clock: Clock, +) -> Result { + let resolved = resolve(&limit, lookup, Instant::now()).map_err(|error| Failure::Message(format!("{label}: {error}")))?; + let (tx, rx) = mpsc::channel(); + let slot: Slot = Arc::new(Mutex::new(None)); + let worker_slot = Arc::clone(&slot); + let worker_clock = Arc::clone(&clock); + let job: Job = Box::new(move || { + let result = catch_unwind(AssertUnwindSafe(f)); + // The clock is read under the lock: once the caller finds the slot empty after its limit, + // any later reading is past the limit too. + let mut stored = worker_slot.lock().unwrap_or_else(PoisonError::into_inner); + *stored = Some((result, worker_clock())); + }); + spawn(job, tx).map_err(|error| Failure::Message(format!("{label}: could not start the worker thread: {error}")))?; + let waited = rx.recv_timeout(resolved.limit.saturating_sub(clock())); + let stored = slot.lock().unwrap_or_else(PoisonError::into_inner).take(); + match (stored, waited) { + (Some((result, finished)), _) if finished > resolved.limit => { + let panicked = match &result { + Ok(_) => String::new(), + Err(payload) => format!(" (it panicked: {})", panic_text(payload.as_ref()).unwrap_or("a payload that is not a message")), + }; + Err(Failure::Message(format!("{label} finished only after its limit of {resolved}{panicked}"))) + } + (Some((Ok(value), _)), _) => Ok(value), + (Some((Err(payload), _)), _) => Err(Failure::Panic(payload)), + (None, Err(RecvTimeoutError::Timeout)) => { + Err(Failure::Message(format!("{label} did not finish within {resolved}; its thread is left running"))) + } + (None, _) => Err(Failure::Message(format!("{label}: the worker thread stopped without a result"))), + } +} + +/// The loop of [`wait_until`], with the clock and the pause passed in. `elapsed` returns the time +/// since the wait started. +fn poll_until( + resolved: &Resolved<'_>, + what: &str, + cond: &mut dyn FnMut() -> bool, + elapsed: &mut dyn FnMut() -> Duration, + pause: &mut dyn FnMut(Duration), +) -> Result<(), String> { + let mut next_pause = FIRST_PAUSE; + let mut first = true; + loop { + // After the first call, the condition is called only while the limit has not passed. + if !first && elapsed() >= resolved.limit { + return Err(format!("timed out waiting for {what} within {resolved}")); + } + first = false; + let held = cond(); + let spent = elapsed(); + if held && spent <= resolved.limit { + return Ok(()); + } + if held { + return Err(format!("timed out waiting for {what} within {resolved} (it held only after the limit had passed)")); + } + if spent < resolved.limit { + pause(next_pause.min(resolved.limit - spent)); + } + next_pause = next_pause.saturating_mul(2).min(MAX_PAUSE); + } +} + +#[cfg(test)] +mod tests { + use super::*; + use std::ffi::OsStr; + use std::process::Command; + use std::sync::atomic::{AtomicBool, AtomicU64, Ordering}; + + /// A variable no test sets, so the environment cannot lengthen a test's short limit. + const UNSET: &str = "CRAFT_TESTKIT_DEADLINE_UNSET_IN_TESTS"; + + /// The variable `run_child` sets for the child process. + const CHILD_VARIABLE: &str = "CRAFT_TESTKIT_DEADLINE_CHILD_SECS"; + + fn short() -> DeadlineLimit<'static> { + DeadlineLimit::new(Duration::from_millis(50)).with_variable(UNSET) + } + + fn long() -> DeadlineLimit<'static> { + DeadlineLimit::new(Duration::from_secs(600)).with_variable(UNSET) + } + + fn message(payload: Box) -> String { + match payload.downcast::() { + Ok(text) => *text, + Err(payload) => match payload.downcast::<&str>() { + Ok(text) => (*text).to_owned(), + Err(_) => panic!("the panic payload is not a message"), + }, + } + } + + fn failure_message(result: Result) -> String { + match result { + Ok(_) => panic!("the call did not fail"), + Err(Failure::Panic(payload)) => message(payload), + Err(Failure::Message(text)) => text, + } + } + + /// Runs `child_reads_its_variable` in a child process with `CHILD_VARIABLE` set to `value`, and + /// returns what the child printed. The child must fail. + fn run_child(value: &OsStr) -> String { + let out = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "deadline::tests::child_reads_its_variable", "--nocapture", "--test-threads=1"]) + .env(CHILD_VARIABLE, value) + .output() + .unwrap(); + let printed = format!("{}{}", String::from_utf8_lossy(&out.stdout), String::from_utf8_lossy(&out.stderr)); + assert!(!out.status.success(), "the child passed:\n{printed}"); + assert!(printed.contains("running 1 test"), "the child did not run the test:\n{printed}"); + printed + } + + /// Runs in the child processes of `run_child`. Without the variable it takes its default and + /// passes; with it, the body blocks until the limit passes. + #[test] + fn child_reads_its_variable() { + let blocks = std::env::var_os(CHILD_VARIABLE).is_some(); + let (_keep, rx) = mpsc::channel::<()>(); + with_deadline(DeadlineLimit::new(Duration::from_secs(2)).with_variable(CHILD_VARIABLE), "child body", move || { + if blocks { + let _ = rx.recv(); + } + }); + } + + #[test] + fn a_slow_body_passes() { + let (tx, rx) = mpsc::channel(); + let sender = thread::spawn(move || tx.send(()).unwrap()); + with_deadline(long(), "slow body", move || rx.recv().unwrap()); + sender.join().unwrap(); + } + + #[test] + #[should_panic(expected = "boom")] + fn a_panic_in_the_body_is_re_raised() { + with_deadline(long(), "panicking body", || panic!("boom")); + } + + #[test] + #[should_panic(expected = "seed 7 byte 3 did not finish within 50ms")] + fn a_hang_fails_and_names_the_input() { + let (gate, gate_rx) = mpsc::channel::<()>(); + let (done_tx, done) = mpsc::channel(); + let result = catch_unwind(AssertUnwindSafe(|| { + with_deadline(short(), "seed 7 byte 3", move || { + let _ = gate_rx.recv(); + done_tx.send(()).unwrap(); + }) + })); + drop(gate); + done.recv().unwrap(); + if let Err(payload) = result { + resume_unwind(payload); + } + } + + #[test] + fn with_deadline_completes() { + with_deadline(Duration::from_secs(5), "fast body", || { + // fast operation + }); + } + + #[test] + #[should_panic(expected = "did not finish within")] + fn with_deadline_times_out() { + let (gate, gate_rx) = mpsc::channel::<()>(); + let result = catch_unwind(AssertUnwindSafe(|| with_deadline(short(), "blocked body", move || gate_rx.recv().unwrap_or_default()))); + drop(gate); + if let Err(payload) = result { + resume_unwind(payload); + } + } + + #[test] + fn returns_worker_value() { + assert_eq!(with_deadline(long(), "value", || vec![1u8, 2, 3]), vec![1, 2, 3]); + } + + #[test] + fn worker_panic_keeps_original_payload() { + #[derive(Debug, PartialEq)] + struct Marker(u32); + let payload = catch_unwind(|| with_deadline(long(), "typed panic", || std::panic::panic_any(Marker(7)))).unwrap_err(); + assert_eq!(payload.downcast_ref::(), Some(&Marker(7))); + } + + #[test] + fn timeout_names_this_call_only() { + let call = |label: &'static str| { + thread::spawn(move || { + let (gate, gate_rx) = mpsc::channel::<()>(); + let result = catch_unwind(AssertUnwindSafe(|| with_deadline(short(), label, move || gate_rx.recv().unwrap_or_default()))); + drop(gate); + message(result.unwrap_err()) + }) + }; + let first = call("first call"); + let second = call("second call"); + let first = first.join().unwrap(); + let second = second.join().unwrap(); + assert!(first.contains("first call") && !first.contains("second call"), "{first}"); + assert!(second.contains("second call") && !second.contains("first call"), "{second}"); + } + + #[test] + fn concurrent_calls_keep_limits_and_labels_separate() { + let (release, release_rx) = mpsc::channel(); + let long_call = thread::spawn(move || { + with_deadline(long(), "long call", move || { + release_rx.recv().unwrap(); + 7 + }) + }); + let (gate, gate_rx) = mpsc::channel::<()>(); + let short_call = catch_unwind(AssertUnwindSafe(|| with_deadline(short(), "short call", move || gate_rx.recv().unwrap_or_default()))); + let text = message(short_call.unwrap_err()); + assert!(text.contains("short call") && text.contains("50ms") && !text.contains("long call"), "{text}"); + release.send(()).unwrap(); + assert_eq!(long_call.join().unwrap(), 7); + drop(gate); + } + + #[test] + fn spawn_failure_reports_cause() { + let ran = AtomicBool::new(false); + let spawn = |_job: Job, _done: Sender<()>| { + ran.store(true, Ordering::SeqCst); + Err(io::Error::other("no threads left")) + }; + let result = run_with_deadline(long(), "no thread", || (), |_| None, spawn, Arc::new(|| Duration::ZERO)); + let text = failure_message(result); + assert!(ran.load(Ordering::SeqCst)); + assert!(text.contains("no thread: could not start the worker thread: no threads left"), "{text}"); + } + + #[test] + fn invalid_override_fails() { + let printed = run_child(OsStr::new("5s")); + assert!(printed.contains("CRAFT_TESTKIT_DEADLINE_CHILD_SECS=\"5s\" is not a whole number of seconds"), "{printed}"); + } + + #[test] + fn zero_override_fails() { + let printed = run_child(OsStr::new("0")); + assert!(printed.contains("CRAFT_TESTKIT_DEADLINE_CHILD_SECS=\"0\" is zero"), "{printed}"); + } + + #[cfg(unix)] + #[test] + fn non_unicode_override_fails() { + use std::os::unix::ffi::OsStrExt; + let printed = run_child(OsStr::from_bytes(b"3\xff")); + assert!(printed.contains("CRAFT_TESTKIT_DEADLINE_CHILD_SECS is not valid Unicode"), "{printed}"); + } + + #[test] + fn valid_override_replaces_the_default() { + let printed = run_child(OsStr::new("1")); + assert!(printed.contains("child body did not finish within 1s, set by CRAFT_TESTKIT_DEADLINE_CHILD_SECS"), "{printed}"); + } + + #[test] + #[should_panic(expected = "the default limit is zero")] + fn zero_default_fails() { + with_deadline(DeadlineLimit::new(Duration::ZERO).with_variable(UNSET), "zero", || ()); + } + + #[test] + fn huge_limit_fails_cleanly() { + let huge = DeadlineLimit::new(Duration::MAX).with_variable(UNSET); + let ran = AtomicBool::new(false); + let spawn = |_job: Job, _done: Sender<()>| { + ran.store(true, Ordering::SeqCst); + Ok(()) + }; + let text = failure_message(run_with_deadline(huge, "huge", || (), |_| None, spawn, Arc::new(|| Duration::ZERO))); + assert!(text.contains("ends past the latest time"), "{text}"); + assert!(!ran.load(Ordering::SeqCst), "the body started"); + let text = message(catch_unwind(|| wait_until(huge, "a huge limit", || true)).unwrap_err()); + assert!(text.contains("waiting for a huge limit: the limit of") && text.contains("ends past the latest time"), "{text}"); + } + + #[test] + fn malformed_values_are_rejected() { + let limit = DeadlineLimit::new(Duration::from_secs(5)).with_variable("X"); + let now = Instant::now(); + for value in ["", "+5", "-5", "1.5", " 5", "5 ", "abc", "5s", "0", "000", "18446744073709551616"] { + let result = resolve(&limit, |_| Some(OsString::from(value)), now); + assert!(matches!(result, Err(LimitError::BadValue { .. })), "{value:?} gave {result:?}"); + } + let resolved = resolve(&limit, |_| Some(OsString::from("007")), now).unwrap(); + assert_eq!(resolved, Resolved { limit: Duration::from_secs(7), variable: "X", from_variable: true }); + let resolved = resolve(&limit, |_| None, now).unwrap(); + assert_eq!(resolved, Resolved { limit: Duration::from_secs(5), variable: "X", from_variable: false }); + } + + #[test] + fn bad_variable_names_are_rejected_before_reading() { + for name in ["", "A=B", "A\0B"] { + let limit = DeadlineLimit::new(Duration::from_secs(5)).with_variable(name); + let result = resolve(&limit, |_| panic!("the variable was read"), Instant::now()); + assert_eq!(result, Err(LimitError::BadName { variable: name })); + } + } + + #[test] + fn a_duration_reads_the_default_variable() { + let limit: DeadlineLimit = Duration::from_secs(3).into(); + assert_eq!(limit.variable(), DEFAULT_VARIABLE); + assert_eq!(limit.default_limit(), Duration::from_secs(3)); + } + + #[test] + fn wait_until_returns_on_condition() { + let ready = &AtomicBool::new(false); + let (asked, asked_rx) = mpsc::channel(); + let (stored, stored_rx) = mpsc::channel(); + thread::scope(|s| { + s.spawn(move || { + asked_rx.recv().unwrap(); + ready.store(true, Ordering::SeqCst); + stored.send(()).unwrap(); + }); + let mut calls = 0; + wait_until(long(), "the flag", || { + calls += 1; + if calls == 1 { + // The flag is set before this call returns, and it still answers false, so the + // condition is called a second time whatever order the threads run in. + asked.send(()).unwrap(); + stored_rx.recv().unwrap(); + return false; + } + ready.load(Ordering::SeqCst) + }); + assert_eq!(calls, 2); + }); + } + + #[test] + #[should_panic(expected = "timed out waiting for the export to finish within 50ms")] + fn wait_until_times_out_with_label() { + wait_until(short(), "the export to finish", || false); + } + + #[test] + #[should_panic(expected = "condition boom")] + fn wait_until_propagates_condition_panic() { + wait_until(long(), "a panicking condition", || panic!("condition boom")); + } + + #[test] + fn wait_until_keeps_a_typed_condition_payload() { + #[derive(Debug, PartialEq)] + struct Marker(u32); + let payload = catch_unwind(|| wait_until(long(), "a typed panic", || std::panic::panic_any(Marker(9)))).unwrap_err(); + assert_eq!(payload.downcast_ref::(), Some(&Marker(9))); + } + + /// A default limit for the loop tests, which pass their own clock. + fn fake_resolved(limit: Duration) -> Resolved<'static> { + Resolved { limit, variable: UNSET, from_variable: false } + } + + #[test] + fn wait_until_rejects_a_true_after_the_limit() { + let resolved = fake_resolved(Duration::from_millis(10)); + let mut now = Duration::ZERO; + let mut cond = || true; + // The condition took 11 ms to return. + let mut elapsed = || { + now += Duration::from_millis(11); + now + }; + let result = poll_until(&resolved, "a late flag", &mut cond, &mut elapsed, &mut |_| panic!("paused")); + let text = result.unwrap_err(); + assert!(text.contains("timed out waiting for a late flag") && text.contains("held only after the limit"), "{text}"); + } + + #[test] + fn wait_until_pauses_grow_and_stop_at_the_limit() { + let resolved = fake_resolved(Duration::from_millis(100)); + let now = std::cell::Cell::new(Duration::ZERO); + let mut pauses = Vec::new(); + let mut calls = 0; + let mut cond = || { + calls += 1; + false + }; + let mut elapsed = || now.get(); + let mut pause = |d: Duration| { + pauses.push(d); + now.set(now.get() + d); + }; + let result = poll_until(&resolved, "never", &mut cond, &mut elapsed, &mut pause); + assert!(result.is_err()); + let ms: Vec = pauses.iter().map(Duration::as_millis).collect(); + // 1 + 2 + 4 + 8 + 16 + 32 = 63, then the 37 ms left, after which the limit is reached. + assert_eq!(ms, [1, 2, 4, 8, 16, 32, 37]); + // One call before each pause, and none after the last one. + assert_eq!(calls, 7); + } + + #[test] + fn wait_until_stops_calling_after_an_overshooting_pause() { + let resolved = fake_resolved(Duration::from_millis(100)); + let now = std::cell::Cell::new(Duration::from_millis(99)); + let mut calls = 0; + let mut cond = || { + calls += 1; + false + }; + let mut elapsed = || now.get(); + // The thread wakes 50 ms late from the 1 ms pause. + let mut pause = |d: Duration| now.set(now.get() + d + Duration::from_millis(50)); + let result = poll_until(&resolved, "late wake", &mut cond, &mut elapsed, &mut pause); + assert!(result.unwrap_err().contains("timed out waiting for late wake")); + assert_eq!(calls, 1); + } + + /// Runs `run_with_deadline` with a 5 s limit on a fake clock. The worker runs on the calling + /// thread: the clock reads `start_secs` while the body runs and `received_secs` when the result + /// is received. When `sends` is false, the worker stores its result but does not send, as if its + /// thread stopped running between the two. + fn on_fake_clock( + f: impl FnOnce() -> T + Send + 'static, + start_secs: u64, + received_secs: u64, + sends: bool, + ) -> Result { + let now = Arc::new(AtomicU64::new(0)); + let clock_now = Arc::clone(&now); + let clock: Clock = Arc::new(move || Duration::from_secs(clock_now.load(Ordering::SeqCst))); + let unsent = std::cell::RefCell::new(None); + let spawn = |job: Job, done: Sender<()>| { + now.store(start_secs, Ordering::SeqCst); + job(); + now.store(received_secs, Ordering::SeqCst); + if sends { + let _ = done.send(()); + } else { + // Kept alive so that the wait times out instead of seeing a closed channel. + *unsent.borrow_mut() = Some(done); + } + Ok(()) + }; + let limit = DeadlineLimit::new(Duration::from_secs(5)).with_variable(UNSET); + run_with_deadline(limit, "fake clock", f, |_| None, spawn, clock) + } + + #[test] + fn a_value_returned_after_the_limit_fails() { + let text = failure_message(on_fake_clock(|| 1, 6, 6, true)); + assert!(text.contains("fake clock finished only after its limit of 5s"), "{text}"); + } + + #[test] + fn a_value_finished_in_time_but_received_late_passes() { + assert!(matches!(on_fake_clock(|| 1, 1, 6, true), Ok(1))); + } + + #[test] + fn a_value_finished_in_time_but_sent_late_passes() { + assert!(matches!(on_fake_clock(|| 1, 1, 6, false), Ok(1))); + } + + #[test] + fn a_panic_finished_in_time_but_sent_late_keeps_its_payload() { + let payload = match on_fake_clock(|| -> u8 { panic!("early boom") }, 1, 6, false) { + Err(Failure::Panic(payload)) => payload, + Ok(_) => panic!("the call did not fail"), + Err(Failure::Message(text)) => panic!("the payload was replaced: {text}"), + }; + assert_eq!(message(payload), "early boom"); + } + + #[test] + fn a_panic_after_the_limit_names_the_limit_and_the_panic() { + let text = failure_message(on_fake_clock(|| -> u8 { panic!("late boom") }, 6, 6, true)); + assert!(text.contains("fake clock finished only after its limit of 5s") && text.ends_with("(it panicked: late boom)"), "{text}"); + } +} diff --git a/crates/testkit/src/guards.rs b/crates/testkit/src/guards.rs new file mode 100644 index 000000000..3541ea21b --- /dev/null +++ b/crates/testkit/src/guards.rs @@ -0,0 +1,2280 @@ +//! Platform regression guards checking source code for known defects and lifecycle hazards. + +use std::collections::{BTreeMap, BTreeSet}; +use std::fmt; +#[cfg(not(target_arch = "wasm32"))] +use std::path::Path; +use std::rc::Rc; + +/// A diagnostic finding reported by a source guard. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Finding { + /// File path where the violation was detected. + pub path: String, + /// 1-based line number of the violation. + pub line: usize, + /// Diagnostic context (the offending code snippet or float literal). + pub text: String, +} + +impl Finding { + /// Create a new diagnostic finding. + pub fn new(path: impl Into, line: usize, text: impl Into) -> Self { + Self { path: path.into(), line, text: text.into() } + } +} + +impl fmt::Display for Finding { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + if self.path.is_empty() { write!(f, "{}: {}", self.line, self.text) } else { write!(f, "{}:{}: {}", self.path, self.line, self.text) } + } +} + +/// Abstraction over a source file path and its text content. +pub trait AsFileSource { + /// Path of the source file. + fn path(&self) -> &str; + /// Text content of the source file. + fn content(&self) -> &str; +} + +impl AsFileSource for (String, String) { + fn path(&self) -> &str { + &self.0 + } + fn content(&self) -> &str { + &self.1 + } +} + +impl AsFileSource for &(String, String) { + fn path(&self) -> &str { + &self.0 + } + fn content(&self) -> &str { + &self.1 + } +} + +impl AsFileSource for (&str, &str) { + fn path(&self) -> &str { + self.0 + } + fn content(&self) -> &str { + self.1 + } +} + +impl AsFileSource for &(&str, &str) { + fn path(&self) -> &str { + self.0 + } + fn content(&self) -> &str { + self.1 + } +} + +impl AsFileSource for (String, &str) { + fn path(&self) -> &str { + &self.0 + } + fn content(&self) -> &str { + self.1 + } +} + +impl AsFileSource for &(String, &str) { + fn path(&self) -> &str { + &self.0 + } + fn content(&self) -> &str { + self.1 + } +} + +impl AsFileSource for (&str, String) { + fn path(&self) -> &str { + self.0 + } + fn content(&self) -> &str { + &self.1 + } +} + +impl AsFileSource for &(&str, String) { + fn path(&self) -> &str { + self.0 + } + fn content(&self) -> &str { + &self.1 + } +} + +/// The deepest `use` group nesting and `cfg` predicate nesting the guards follow. Deeper input is +/// read as far as this depth, so hostile nesting cannot exhaust the stack. +const MAX_NESTING: usize = 64; + +/// The most segments of a `use` path that [`use_leaves`] keeps. The guards compare paths of at most +/// three segments, so a leaf with a longer path keeps only the name it binds, and a long prefix shared +/// by many leaves is not copied into each of them. +const MAX_USE_PATH: usize = 8; + +/// The longest segment, in bytes, of a `use` path that [`use_leaves`] keeps. The longest segment the +/// guards compare is `PredefinedMenuItem`, so a leaf with a longer segment keeps only the name it binds, +/// and a long name shared by many leaves is not copied into each of them. +const MAX_USE_SEGMENT: usize = 32; + +/// The kind of a Rust token. Comments are dropped; string, character and number literals keep no text +/// except the decoded contents of strings, which `cfg` predicates compare. A string with an escape +/// that is not valid is `Other`. +#[derive(Debug, Clone, PartialEq, Eq)] +enum Kind { + Ident(String), + Punct(char), + Str(String), + Other, +} + +#[derive(Debug, Clone)] +struct Token { + kind: Kind, + line: usize, +} + +impl Token { + fn is_ident(&self, name: &str) -> bool { + matches!(&self.kind, Kind::Ident(s) if s == name) + } + + fn is_punct(&self, c: char) -> bool { + self.kind == Kind::Punct(c) + } +} + +fn is_ident_start(c: char) -> bool { + c == '_' || c.is_alphabetic() +} + +fn is_ident_continue(c: char) -> bool { + c == '_' || c.is_alphanumeric() +} + +/// Split Rust source into tokens with 1-based line numbers. +/// +/// Line comments, nested block comments, string literals (normal, byte, C and raw strings with any +/// number of `#`), character and byte literals, lifetimes and raw identifiers are recognized, so a quote +/// or comment marker inside one of them does not hide the code after it. Unterminated literals and +/// comments run to the end of the input. +fn lex_rust(code: &str) -> Vec { + let chars: Vec = code.chars().collect(); + let len = chars.len(); + let at = |i: usize| chars.get(i).copied(); + let mut tokens = Vec::new(); + let mut i = 0; + let mut line = 1usize; + + while i < len { + let c = chars[i]; + if c == '\n' { + line += 1; + i += 1; + } else if c.is_whitespace() { + i += 1; + } else if c == '/' && at(i + 1) == Some('/') { + while i < len && chars[i] != '\n' { + i += 1; + } + } else if c == '/' && at(i + 1) == Some('*') { + let mut depth = 1usize; + i += 2; + while i < len && depth > 0 { + if chars[i] == '/' && at(i + 1) == Some('*') { + depth += 1; + i += 2; + } else if chars[i] == '*' && at(i + 1) == Some('/') { + depth -= 1; + i += 2; + } else { + if chars[i] == '\n' { + line += 1; + } + i += 1; + } + } + } else if is_ident_start(c) { + let start = i; + while i < len && is_ident_continue(chars[i]) { + i += 1; + } + let word: String = chars[start..i].iter().collect(); + let token_line = line; + if matches!(word.as_str(), "r" | "br" | "cr") && matches!(at(i), Some('"' | '#')) { + let mut j = i; + while j < len && chars[j] == '#' { + j += 1; + } + let hashes = j - i; + if at(j) == Some('"') { + let (end, text) = scan_raw_string(&chars, j + 1, hashes, &mut line); + tokens.push(Token { kind: Kind::Str(text), line: token_line }); + i = end; + continue; + } + if word == "r" && hashes == 1 && at(j).is_some_and(is_ident_start) { + let name_start = j; + while j < len && is_ident_continue(chars[j]) { + j += 1; + } + tokens.push(Token { kind: Kind::Ident(raw_identifier(&chars[name_start..j])), line: token_line }); + i = j; + continue; + } + } + if matches!(word.as_str(), "b" | "c") && at(i) == Some('"') { + let (end, kind) = scan_string(&chars, i + 1, &mut line); + tokens.push(Token { kind, line: token_line }); + i = end; + continue; + } + if word == "b" + && at(i) == Some('\'') + && let Some(end) = char_literal_end(&chars, i) + { + tokens.push(Token { kind: Kind::Other, line: token_line }); + i = end; + continue; + } + tokens.push(Token { kind: Kind::Ident(word), line: token_line }); + } else if c.is_ascii_digit() { + while i < len && (is_ident_continue(chars[i]) || (chars[i] == '.' && at(i + 1).is_some_and(|d| d.is_ascii_digit()))) { + i += 1; + } + tokens.push(Token { kind: Kind::Other, line }); + } else if c == '"' { + let token_line = line; + let (end, kind) = scan_string(&chars, i + 1, &mut line); + tokens.push(Token { kind, line: token_line }); + i = end; + } else if c == '\'' { + if let Some(end) = char_literal_end(&chars, i) { + i = end; + } else { + // A lifetime or a loop label. + i += 1; + while i < len && is_ident_continue(chars[i]) { + i += 1; + } + } + tokens.push(Token { kind: Kind::Other, line }); + } else { + tokens.push(Token { kind: Kind::Punct(c), line }); + i += 1; + } + } + tokens +} + +/// The name of a raw identifier written after `r#`. A raw identifier spelled like a keyword the guards +/// read (`r#let`, `r#in`, `r#match`, `r#true`) keeps its prefix, so it is read as a name rather than as +/// that keyword or as a `cfg` literal. +fn raw_identifier(name: &[char]) -> String { + let name: String = name.iter().collect(); + let keyword = |list: &[&str]| list.contains(&name.as_str()); + if keyword(&["true", "false"]) || keyword(KEYWORDS) || keyword(BLOCK_KEYWORDS) || keyword(VALUE_KEYWORDS) { format!("r#{name}") } else { name } +} + +/// Read a normal string body starting after its opening quote. Returns the index after the closing +/// quote and the token for the body: `Str` with its escapes decoded, or `Other` when an escape is not +/// valid in a string. +fn scan_string(chars: &[char], mut i: usize, line: &mut usize) -> (usize, Kind) { + let mut text = Some(String::new()); + while i < chars.len() { + match chars[i] { + '\\' => { + let (next, decoded) = string_escape(chars, i + 1, line); + match decoded { + Ok(Some(c)) => text.iter_mut().for_each(|t| t.push(c)), + Ok(None) => {} + Err(()) => text = None, + } + i = next; + } + '"' => return (i + 1, text.map_or(Kind::Other, Kind::Str)), + c => { + if c == '\n' { + *line += 1; + } + text.iter_mut().for_each(|t| t.push(c)); + i += 1; + } + } + } + (chars.len(), text.map_or(Kind::Other, Kind::Str)) +} + +/// Decode the string escape whose `\` is right before `chars[i]` +/// (). Returns the index after the +/// escape and the character it stands for, `None` for a line continuation, or an error when it is not +/// a valid escape. +fn string_escape(chars: &[char], i: usize, line: &mut usize) -> (usize, Result, ()>) { + let hex = |k: usize| chars.get(k).and_then(|c| c.to_digit(16)); + match chars.get(i) { + Some('n') => (i + 1, Ok(Some('\n'))), + Some('r') => (i + 1, Ok(Some('\r'))), + Some('t') => (i + 1, Ok(Some('\t'))), + Some('0') => (i + 1, Ok(Some('\0'))), + Some(&c @ ('\\' | '\'' | '"')) => (i + 1, Ok(Some(c))), + Some('x') => match (hex(i + 1), hex(i + 2)) { + (Some(high), Some(low)) if high < 8 => (i + 3, Ok(char::from_u32(high * 16 + low))), + _ => (i + 1, Err(())), + }, + Some('u') if chars.get(i + 1) == Some(&'{') => { + // At most six hex digits, with underscores, before the closing brace. + let mut value = 0u32; + let mut digits = 0; + let mut j = i + 2; + while let Some(&c) = chars.get(j) { + if c == '}' { + break; + } + if c != '_' { + match c.to_digit(16) { + Some(d) if digits < 6 => { + value = value * 16 + d; + digits += 1; + } + _ => return (j, Err(())), + } + } + j += 1; + } + match (chars.get(j), char::from_u32(value)) { + (Some('}'), Some(c)) if digits > 0 && chars.get(i + 2) != Some(&'_') => (j + 1, Ok(Some(c))), + _ => (j.min(chars.len()), Err(())), + } + } + Some('\n') => { + // A line continuation skips the line break and the whitespace after it. + let mut j = i; + while let Some(&c) = chars.get(j).filter(|c| matches!(c, ' ' | '\t' | '\n' | '\r')) { + if c == '\n' { + *line += 1; + } + j += 1; + } + (j, Ok(None)) + } + Some('\r') if chars.get(i + 1) == Some(&'\n') => { + let (j, _) = string_escape(chars, i + 1, line); + (j, Ok(None)) + } + Some(_) => (i + 1, Err(())), + None => (i, Err(())), + } +} + +/// Read a raw string body starting after its opening quote; it ends at a quote followed by `hashes` `#`. +fn scan_raw_string(chars: &[char], mut i: usize, hashes: usize, line: &mut usize) -> (usize, String) { + let start = i; + while i < chars.len() { + if chars[i] == '"' && (1..=hashes).all(|h| chars.get(i + h) == Some(&'#')) { + return (i + 1 + hashes, chars[start..i].iter().collect()); + } + if chars[i] == '\n' { + *line += 1; + } + i += 1; + } + (chars.len(), chars[start.min(chars.len())..].iter().collect()) +} + +/// The index after a character or byte literal whose opening quote is at `quote`, or `None` when the +/// quote starts a lifetime or a label. +fn char_literal_end(chars: &[char], quote: usize) -> Option { + match chars.get(quote + 1) { + Some('\\') => { + // An escape: `\n`, `\'`, `\x7f`, `\u{10FFFF}`. The longest is twelve characters. + let mut j = quote + 3; + while j < chars.len() && j <= quote + 12 && chars[j] != '\'' && chars[j] != '\n' { + j += 1; + } + (chars.get(j) == Some(&'\'')).then_some(j + 1) + } + Some('\n') | None => None, + Some(_) => (chars.get(quote + 2) == Some(&'\'')).then_some(quote + 3), + } +} + +/// Rust keywords that can come right before a path that starts with `::`, as in `return ::std::time`. +/// `crate`, `self`, `super` and `Self` are path segments and are not listed. +const KEYWORDS: &[&str] = &[ + "as", "async", "await", "box", "break", "const", "continue", "dyn", "else", "enum", "extern", "fn", "for", "if", "impl", "in", "let", "loop", + "match", "mod", "move", "mut", "pub", "ref", "return", "static", "struct", "trait", "type", "unsafe", "use", "where", "while", "yield", +]; + +/// Whether `toks[i]` follows `::` that itself follows a path segment, as `time` does in `a::time`. +/// The `>` of `->` and `=>` ends no path, so `-> ::std::time` starts one. +fn continues_a_path(toks: &[Token], i: usize) -> bool { + i >= 3 + && toks[i - 1].is_punct(':') + && toks[i - 2].is_punct(':') + && match &toks[i - 3].kind { + Kind::Ident(s) => !KEYWORDS.contains(&s.as_str()), + Kind::Punct('>') => !(i >= 4 && (toks[i - 4].is_punct('-') || toks[i - 4].is_punct('='))), + _ => false, + } +} + +/// Whether `toks[i..]` starts with `::` followed by the identifier `name`. +fn then_path(toks: &[Token], i: usize, name: impl Fn(&str) -> bool) -> bool { + toks.get(i).is_some_and(|t| t.is_punct(':')) + && toks.get(i + 1).is_some_and(|t| t.is_punct(':')) + && toks.get(i + 2).is_some_and(|t| matches!(&t.kind, Kind::Ident(s) if name(s))) +} + +/// Whether the path that ends at `toks[i]` starts right after the `<` of a qualified path, as in +/// `::quit`, rather than after the `<` of generic arguments (`Vec::new`, +/// `f::`). +fn opens_qualified_path(toks: &[Token], i: usize) -> bool { + let mut start = i; + while start >= 2 && toks[start - 1].is_punct(':') && toks[start - 2].is_punct(':') { + if start >= 3 && matches!(toks[start - 3].kind, Kind::Ident(_)) { + start -= 3; + } else { + start -= 2; + break; + } + } + start >= 1 + && toks[start - 1].is_punct('<') + && match start.checked_sub(2).map(|j| &toks[j].kind) { + None => true, + Some(Kind::Ident(s)) => KEYWORDS.contains(&s.as_str()), + Some(Kind::Punct(c)) => !matches!(*c, ':' | '>'), + Some(_) => false, + } +} + +/// One name a `use` declaration brings into scope. +#[derive(Debug)] +struct UseLeaf { + /// The full path, `self` removed and without a leading `::`. It is empty for a path longer than + /// [`MAX_USE_PATH`] segments or with a segment longer than [`MAX_USE_SEGMENT`] bytes, whose leaf then + /// records only the name it binds. + path: Vec, + /// The name it is bound to, `_` for an underscore import; `None` for a glob import. The name is + /// shared with the other leaves that bind the same segment of one path. + name: Option>, + /// The first segment of the path, kept when the path is not. + root: Option>, + line: usize, + /// Index of the `use` keyword. + start: usize, + /// Index of the alias of `std::time` that the path was read through, when [`use_leaves`] was given one. + alias: Option, + /// Whether the path starts with `::`, so that its first segment names an external crate. + absolute: bool, +} + +impl UseLeaf { + /// The name the leaf binds in scope: `None` for a glob import and for an underscore import, which + /// imports an item without binding a name. + fn binding(&self) -> Option<&str> { + self.name.as_deref().filter(|name| *name != "_") + } +} + +/// Every name the `use` declarations of a file bring into scope. A path that starts with a name in +/// `time_aliases` is read as a path that starts with `std::time`, so the alias, at any length, is not +/// copied into the leaves and the limits do not drop them. +fn use_leaves(toks: &[Token], time_aliases: &BTreeSet) -> Vec { + let mut leaves = Vec::new(); + let mut i = 0; + while i < toks.len() { + // `use<...>` is a precise capturing bound on `impl Trait`, not a `use` declaration. + if toks[i].is_ident("use") && !continues_a_path(toks, i) && !toks.get(i + 1).is_some_and(|t| t.is_punct('<')) { + let start = i; + let end = (i + 1..toks.len()).find(|&j| toks[j].is_punct(';')).unwrap_or(toks.len()); + let mut pos = i + 1; + let mut prefix = Vec::new(); + parse_use_tree(&toks[..end], &mut pos, &mut prefix, (start, None, false), &mut leaves, time_aliases, 0); + i = end; + } else { + i += 1; + } + } + leaves +} + +fn parse_use_tree( + toks: &[Token], + pos: &mut usize, + prefix: &mut Vec>, + // The index of the `use` keyword, the alias of `std::time` that `prefix` was read through, and whether + // the path starts with `::`. + (start, mut via, mut absolute): (usize, Option, bool), + out: &mut Vec, + time_aliases: &BTreeSet, + depth: usize, +) { + let base = prefix.len(); + if toks.get(*pos).is_some_and(|t| t.is_punct(':')) && toks.get(*pos + 1).is_some_and(|t| t.is_punct(':')) { + absolute |= prefix.is_empty(); + *pos += 2; + } + // A leaf is reported on the line where its path starts in this tree, not where its last name is. + let line = toks.get(*pos).map_or(0, |t| t.line); + while let Some(tok) = toks.get(*pos) { + match &tok.kind { + Kind::Ident(name) => { + *pos += 1; + if toks.get(*pos).is_some_and(|t| t.is_punct(':')) && toks.get(*pos + 1).is_some_and(|t| t.is_punct(':')) { + if prefix.is_empty() && time_aliases.contains(name) { + prefix.extend([Rc::from("std"), Rc::from("time")]); + via = Some(*pos - 1); + } else { + prefix.push(Rc::from(name.as_str())); + } + *pos += 2; + continue; + } + let length = prefix.len() + usize::from(name != "self"); + let alias = match (toks.get(*pos), toks.get(*pos + 1).map(|t| &t.kind)) { + (Some(t), Some(Kind::Ident(alias))) if t.is_ident("as") => { + *pos += 2; + Some(alias) + } + _ => None, + }; + // The name the leaf binds: its alias, its last name, or for `self` the last segment of + // the prefix, shared rather than copied. + let bound = match alias { + Some(alias) => Some(Rc::from(alias.as_str())), + None if name != "self" => Some(Rc::from(name.as_str())), + None => prefix.last().cloned(), + }; + // A path past the limits is not copied, but the leaf still binds its name, so that the name + // does not read as unbound. + let path = if length <= MAX_USE_PATH && short_segments(prefix) && name.len() <= MAX_USE_SEGMENT { + let mut path: Vec = prefix.iter().map(|segment| segment.to_string()).collect(); + if name != "self" { + path.push(name.clone()); + } + path + } else { + Vec::new() + }; + if bound.is_some() { + let root = prefix.first().cloned().or_else(|| Some(Rc::from(name.as_str()))); + out.push(UseLeaf { path, name: bound, root, line, start, alias: via, absolute }); + } + break; + } + Kind::Punct('*') => { + if prefix.len() <= MAX_USE_PATH && short_segments(prefix) { + let path = prefix.iter().map(|segment| segment.to_string()).collect(); + out.push(UseLeaf { path, name: None, root: prefix.first().cloned(), line, start, alias: via, absolute }); + } + *pos += 1; + break; + } + Kind::Punct('{') => { + *pos += 1; + while let Some(t) = toks.get(*pos) { + if t.is_punct('}') { + *pos += 1; + break; + } + let before = *pos; + if !t.is_punct(',') && depth < MAX_NESTING { + parse_use_tree(toks, pos, prefix, (start, via, absolute), out, time_aliases, depth + 1); + } + if *pos == before { + *pos += 1; + } + } + break; + } + _ => break, + } + } + prefix.truncate(base); +} + +/// Whether every segment of `path` is at most [`MAX_USE_SEGMENT`] bytes long. +fn short_segments(path: &[Rc]) -> bool { + path.iter().all(|segment| segment.len() <= MAX_USE_SEGMENT) +} + +/// A value of a `cfg` predicate on `wasm32-unknown-unknown`, where the value of a feature or of +/// `test` is not known from the source. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Tri { + True, + False, + Unknown, +} + +impl Tri { + fn from_bool(b: bool) -> Self { + if b { Self::True } else { Self::False } + } + + fn not(self) -> Self { + match self { + Self::True => Self::False, + Self::False => Self::True, + Self::Unknown => Self::Unknown, + } + } +} + +/// Evaluate the `cfg` predicate at `toks[*pos]` for `wasm32-unknown-unknown`. +fn eval_cfg(toks: &[Token], pos: &mut usize, depth: usize) -> Tri { + let Some(Kind::Ident(name)) = toks.get(*pos).map(|t| &t.kind) else { + return Tri::Unknown; + }; + *pos += 1; + if toks.get(*pos).is_some_and(|t| t.is_punct('=')) { + let value = match toks.get(*pos + 1).map(|t| &t.kind) { + Some(Kind::Str(v)) => v.clone(), + _ => return Tri::Unknown, + }; + *pos += 2; + let expected = match name.as_str() { + "target_arch" => "wasm32", + "target_os" | "target_vendor" => "unknown", + "target_family" => "wasm", + "target_env" => "", + "target_pointer_width" => "32", + "target_endian" => "little", + _ => return Tri::Unknown, + }; + return Tri::from_bool(value == expected); + } + if toks.get(*pos).is_some_and(|t| t.is_punct('(')) { + if depth >= MAX_NESTING { + // Too deep to read: the predicate is skipped as a whole, and its value is not known. + *pos = matching_close(toks, *pos).saturating_add(1); + return Tri::Unknown; + } + *pos += 1; + let mut values = Vec::new(); + while let Some(t) = toks.get(*pos) { + if t.is_punct(')') { + *pos += 1; + break; + } + if t.is_punct(',') { + *pos += 1; + continue; + } + let before = *pos; + values.push(eval_cfg(toks, pos, depth + 1)); + if *pos == before { + *pos += 1; + } + } + return match name.as_str() { + "not" => values.first().map_or(Tri::Unknown, |v| v.not()), + "all" if values.contains(&Tri::False) => Tri::False, + "all" if values.contains(&Tri::Unknown) => Tri::Unknown, + "all" => Tri::True, + "any" if values.contains(&Tri::True) => Tri::True, + "any" if values.contains(&Tri::Unknown) => Tri::Unknown, + "any" => Tri::False, + _ => Tri::Unknown, + }; + } + match name.as_str() { + "unix" | "windows" | "false" => Tri::False, + "true" => Tri::True, + _ => Tri::Unknown, + } +} + +/// The index of the token that closes the bracket opened at `open`, or `toks.len()`. +fn matching_close(toks: &[Token], open: usize) -> usize { + let mut depth = 0usize; + for (j, t) in toks.iter().enumerate().skip(open) { + match t.kind { + Kind::Punct('(' | '[' | '{') => depth += 1, + Kind::Punct(')' | ']' | '}') => { + depth = depth.saturating_sub(1); + if depth == 0 { + return j; + } + } + _ => {} + } + } + toks.len() +} + +/// Keywords whose item or expression ends with its closing brace rather than with `;`. +const BLOCK_KEYWORDS: &[&str] = + &["fn", "mod", "impl", "trait", "struct", "enum", "union", "extern", "macro_rules", "if", "match", "loop", "while", "for", "unsafe"]; + +/// Keywords that start a statement whose value follows them, so a block keyword after them is part of +/// that value. +const VALUE_KEYWORDS: &[&str] = &["let", "return", "break", "yield", "become"]; + +/// Where [`item_end`] is in the head of an `if`, `while`, `match` or `for` before its body's `{`. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Condition { + /// Not in such a head: the next `{` outside brackets opens the body. + Done, + /// In the pattern of a `let` or a `for`, where a `{` opens a struct pattern. + Pattern, + /// In a condition, a scrutinee or an iterator, where the next `{` outside brackets opens the body. + Expression, +} + +/// Whether the `=` at `toks[j]` stands alone, as the `=` between a `let` pattern and its value, rather +/// than as part of `==`, `!=`, `<=`, `>=`, `=>` or the range pattern `..=`. +fn lone_equals(toks: &[Token], j: usize) -> bool { + let punct = |k: usize, cs: &[char]| toks.get(k).is_some_and(|t| cs.iter().any(|&c| t.is_punct(c))); + !punct(j + 1, &['=', '>']) && j.checked_sub(1).is_none_or(|k| !punct(k, &['=', '!', '<', '>', '.'])) +} + +/// Whether a block expression starts at `j`: `{`, a labeled block (`'label: {`) or a `const` block. +fn starts_block(toks: &[Token], j: usize) -> bool { + let punct = |k: usize, c: char| toks.get(k).is_some_and(|t| t.is_punct(c)); + match toks.get(j).map(|t| &t.kind) { + Some(Kind::Punct('{')) => true, + Some(Kind::Other) => punct(j + 1, ':') && punct(j + 2, '{'), + Some(Kind::Ident(k)) => k == "const" && punct(j + 1, '{'), + _ => false, + } +} + +/// Whether the `{` at `toks[j]`, in the condition, scrutinee or iterator of an `if`, `while`, `match` or +/// `for`, stands where an operand is still needed, so it opens a block expression rather than the body: +/// right after the keyword, after `in`, after the `=` of a `let`, after an operator or `!`, after +/// `unsafe`, `const`, `loop`, `async` or `async move`, or after a loop label's `:`. +fn operand_expected(toks: &[Token], j: usize) -> bool { + let Some(k) = j.checked_sub(1) else { return false }; + match &toks[k].kind { + Kind::Ident(prev) => matches!(prev.as_str(), "if" | "while" | "match" | "in" | "unsafe" | "const" | "loop" | "async" | "move"), + Kind::Punct('=' | '+' | '-' | '*' | '/' | '%' | '^' | '|' | '&' | '<' | '>' | '!') => true, + Kind::Punct(':') => k.checked_sub(1).is_some_and(|l| toks[l].kind == Kind::Other), + _ => false, + } +} + +/// The index after the item, statement, field or match arm that starts at `start`, or with `inner`, the +/// index of the bracket that closes the enclosing scope. +/// +/// It ends after a `;` or a `,` outside brackets, after the closing brace of a block item, or before a +/// closing bracket of the enclosing scope. A block item starts with `{`, a labeled block, a `const` +/// block, a keyword in [`BLOCK_KEYWORDS`] or a macro call with braces, at the head of the item or of a +/// match arm's body (after its `=>`). An `async` block is not a block item: it runs on to its `;`. A +/// block keyword or macro brace after a `=`, a binary operator or a keyword in [`VALUE_KEYWORDS`] +/// outside brackets is part of an expression, which runs on to its `;` or `,`. When a `.` or `?` +/// follows the closing brace of a block item, the item runs on to its `;` or `,`. A `,` inside the angle +/// brackets of a field's or a `let`'s type ends the item early, which leaves the rest of it checked. +/// +/// The body of an `if`, `while`, `match` or `for` at the head is the first `{` outside brackets after its +/// condition, scrutinee or iterator. A `{` where the condition still needs an operand (see +/// [`operand_expected`]) opens a block expression in it, as in `if { ready() } { ... }`, and the body is +/// the next `{` after that block. A `{` in the pattern of a `let` (`if let S { .. } = s`, also after +/// `&&` in a chain) or of a `for` opens a struct pattern and does not end the item. An `else` chain ends +/// at its last block. +/// +/// In the head of an `fn`, `impl`, `trait`, `struct`, `enum` or `union` item, a block inside angle +/// brackets (a const generic default or argument such as ``, also in a +/// return type or a `where` clause) does not end the item. The `>` of `->` does not close an angle +/// bracket. +fn item_end(toks: &[Token], start: usize, inner: bool) -> usize { + let mut depth = 0usize; + let mut block_item = false; + let mut arm = false; + let mut head = true; + let mut condition = Condition::Done; + let mut generics = false; + let mut angle = 0usize; + let mut j = start; + while j < toks.len() { + let at_top = depth == 0 && !inner; + if j == start && at_top && starts_block(toks, j) { + block_item = true; + } + match &toks[j].kind { + Kind::Ident(k) if at_top && head && (BLOCK_KEYWORDS.contains(&k.as_str()) || starts_block(toks, j)) => { + if !block_item { + condition = match k.as_str() { + "if" | "while" | "match" => Condition::Expression, + "for" => Condition::Pattern, + _ => Condition::Done, + }; + } + if matches!(k.as_str(), "fn" | "impl" | "trait" | "struct" | "enum" | "union") { + generics = true; + } + block_item = true; + } + Kind::Punct('<') if at_top && generics => angle += 1, + Kind::Punct('>') if at_top && generics && !j.checked_sub(1).is_some_and(|k| toks[k].is_punct('-')) => { + angle = angle.saturating_sub(1); + } + Kind::Ident(k) if at_top && condition == Condition::Expression && k == "let" => condition = Condition::Pattern, + Kind::Ident(k) if at_top && condition == Condition::Pattern && k == "in" => condition = Condition::Expression, + Kind::Punct('=') if at_top && condition == Condition::Pattern && lone_equals(toks, j) => condition = Condition::Expression, + Kind::Punct('{') if at_top && condition == Condition::Expression => { + // A `{` where the condition still needs an operand opens a block expression inside it + // (`if { ready() } { ... }`); the body's `{` comes after the condition's last operand. + if !operand_expected(toks, j) { + condition = Condition::Done; + } + depth += 1; + } + Kind::Ident(k) if at_top && VALUE_KEYWORDS.contains(&k.as_str()) => head = false, + Kind::Punct('!') if at_top && head && toks.get(j + 1).is_some_and(|t| t.is_punct('{')) => block_item = true, + Kind::Punct('=') if at_top && toks.get(j + 1).is_some_and(|t| t.is_punct('>')) => { + // A match arm's body has a head of its own: a block or block keyword there ends the arm. + arm = true; + head = true; + block_item = starts_block(toks, j + 2); + condition = Condition::Done; + j += 2; + continue; + } + // The `:` after a field's or a static's name starts its type, where `fn` is a function pointer + // type rather than an item. The `:` of a path (`::`) and the one after a loop label are not. + Kind::Punct(':') + if at_top + && !block_item + && !toks.get(j + 1).is_some_and(|t| t.is_punct(':')) + && j.checked_sub(1).is_none_or(|k| !toks[k].is_punct(':') && toks[k].kind != Kind::Other) => + { + head = false; + } + Kind::Punct('=' | '+' | '-' | '*' | '/' | '%' | '^' | '|' | '&' | '<' | '>' | '!') if at_top && !block_item => head = false, + Kind::Punct('(' | '[' | '{') => depth += 1, + Kind::Punct(c @ (')' | ']' | '}')) => { + if depth == 0 { + return j; + } + depth -= 1; + if depth == 0 && *c == '}' && block_item && !inner && condition == Condition::Done && angle == 0 { + if toks.get(j + 1).is_some_and(|t| t.is_ident("else")) { + // `else if` has a condition of its own before its body; `else {` opens the body. + if toks.get(j + 2).is_some_and(|t| t.is_ident("if")) { + condition = Condition::Expression; + } + j += 1; + continue; + } + if toks.get(j + 1).is_some_and(|t| t.is_punct('.') || t.is_punct('?')) { + // A method call, field or `?` after the block continues the expression to its `;` or `,`. + block_item = false; + head = false; + j += 1; + continue; + } + let comma = toks.get(j + 1).is_some_and(|t| t.is_punct(',')); + return if arm && comma { j + 2 } else { j + 1 }; + } + } + Kind::Punct(';') if at_top => return j + 1, + Kind::Punct(',') if at_top && (arm || !block_item) => return j + 1, + _ => {} + } + j += 1; + } + toks.len() +} + +/// Mark the tokens of every item whose `cfg` attribute is false on `wasm32-unknown-unknown`. +/// +/// An outer attribute (`#[cfg(...)]`) covers the item after it; an inner attribute (`#![cfg(...)]`) +/// covers the rest of the module or block it is in. +fn native_only(toks: &[Token]) -> Vec { + cfg_covered(toks, false) +} + +/// Mark the tokens of every item that a `cfg` attribute covers: with `any`, whatever its predicate, +/// otherwise only when the predicate is false on `wasm32-unknown-unknown`, as [`native_only`] does. +fn cfg_covered(toks: &[Token], any: bool) -> Vec { + let mut skip = vec![false; toks.len()]; + let mut i = 0; + while i < toks.len() { + if !toks[i].is_punct('#') { + i += 1; + continue; + } + let inner = toks.get(i + 1).is_some_and(|t| t.is_punct('!')); + let open = if inner { i + 2 } else { i + 1 }; + if !toks.get(open).is_some_and(|t| t.is_punct('[')) { + i += 1; + continue; + } + let close = matching_close(toks, open); + if close >= toks.len() { + // An unclosed attribute: no later bracket closes it, so nothing after it is an item. + break; + } + let excluded = toks.get(open + 1).is_some_and(|t| t.is_ident("cfg")) && toks.get(open + 2).is_some_and(|t| t.is_punct('(')) && { + let mut pos = open + 3; + any || eval_cfg(&toks[..close], &mut pos, 0) == Tri::False + }; + if !excluded { + i = close + 1; + continue; + } + // Further outer attributes on the same item. + let mut item = close + 1; + while !inner && item < toks.len() && toks[item].is_punct('#') && toks.get(item + 1).is_some_and(|t| t.is_punct('[')) { + item = matching_close(toks, item + 1).saturating_add(1); + } + let end = item_end(toks, item.min(toks.len()), inner); + for s in skip.iter_mut().take(end).skip(i) { + *s = true; + } + i = end.max(i + 1); + } + skip +} + +/// The index of the keyword of every item that carries an outer `cfg` attribute of its own whose predicate +/// is not known to be true on `wasm32-unknown-unknown`, so the item may be absent from the web build: the +/// token after the item's outer attributes and its visibility (`pub`, `pub(...)`). +fn cfg_items(toks: &[Token]) -> BTreeSet { + let mut items = BTreeSet::new(); + let mut i = 0; + while i < toks.len() { + let cfg = toks[i].is_punct('#') + && toks.get(i + 1).is_some_and(|t| t.is_punct('[')) + && toks.get(i + 2).is_some_and(|t| t.is_ident("cfg")) + && toks.get(i + 3).is_some_and(|t| t.is_punct('(')); + if !cfg { + i += 1; + continue; + } + let close = matching_close(toks, i + 1); + if close >= toks.len() { + break; + } + let mut pos = i + 4; + if eval_cfg(&toks[..close], &mut pos, 0) == Tri::True { + i = close + 1; + continue; + } + let mut item = close + 1; + while item < toks.len() && toks[item].is_punct('#') && toks.get(item + 1).is_some_and(|t| t.is_punct('[')) { + item = matching_close(toks, item + 1).saturating_add(1); + } + if toks.get(item).is_some_and(|t| t.is_ident("pub")) { + item += 1; + if toks.get(item).is_some_and(|t| t.is_punct('(')) { + item = matching_close(toks, item).saturating_add(1); + } + } + if item < toks.len() { + items.insert(item); + } + i = item.max(i + 1); + } + items +} + +/// A module declaration, `mod name;` or the head of `mod name { ... }`. +#[derive(Debug, Clone)] +struct ModName { + name: String, + /// The string of a `#[path = "..."]` attribute on the declaration. + path_attribute: Option, +} + +/// An out-of-line module declaration, `mod name;`. +#[derive(Debug)] +struct ModDecl { + module: ModName, + /// The inline modules (`mod a { ... }`) the declaration is inside, outermost first, shared between the + /// declarations inside them. + inline: Vec>, + /// Whether the declaration is inside an item whose `cfg` is false on `wasm32-unknown-unknown`. + native: bool, +} + +/// The most tokens [`path_attribute`] reads back from one `mod` keyword, so that hostile nesting cannot +/// make the scan quadratic. +const ATTRIBUTE_SCAN_LIMIT: usize = 4096; + +/// The index of the bracket `open` that matches the bracket `close` at `toks[end - 1]`, reading back +/// from `end`, or `None` when it is not found within `budget` tokens. +fn matching_open_back(toks: &[Token], end: usize, open: char, close: char, budget: &mut usize) -> Option { + let mut depth = 0usize; + let mut j = end; + while j > 0 && *budget > 0 { + j -= 1; + *budget -= 1; + if toks[j].is_punct(close) { + depth += 1; + } else if toks[j].is_punct(open) { + depth = depth.saturating_sub(1); + if depth == 0 { + return Some(j); + } + } + } + None +} + +/// The string of a `#[path = "..."]` outer attribute on the item whose `mod` keyword is at `toks[m]`. +fn path_attribute(toks: &[Token], m: usize) -> Option { + let mut budget = ATTRIBUTE_SCAN_LIMIT; + let mut k = m; + if k > 0 && toks[k - 1].is_punct(')') { + // A visibility such as `pub(crate)`. + let j = matching_open_back(toks, k, '(', ')', &mut budget)?; + if j > 0 && toks[j - 1].is_ident("pub") { + k = j - 1; + } + } else if k > 0 && toks[k - 1].is_ident("pub") { + k -= 1; + } + let mut found = None; + while k > 0 && toks[k - 1].is_punct(']') { + let Some(j) = matching_open_back(toks, k, '[', ']', &mut budget) else { break }; + if j == 0 || !toks[j - 1].is_punct('#') { + break; + } + if toks.get(j + 1).is_some_and(|t| t.is_ident("path")) + && toks.get(j + 2).is_some_and(|t| t.is_punct('=')) + && let Some(Kind::Str(s)) = toks.get(j + 3).map(|t| &t.kind) + { + found = Some(s.clone()); + } + k = j - 1; + } + found +} + +/// What an open brace in [`module_decls`] opened. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Brace { + /// A block that is not an inline module. + Block, + /// An inline module, pushed on the inline stack. + Module, + /// An inline module deeper than [`MAX_NESTING`], not tracked. + TooDeep, +} + +/// The name of a module's file or folder: a raw identifier such as `r#match` names `match`. +fn module_name(name: &str) -> String { + name.strip_prefix("r#").unwrap_or(name).to_owned() +} + +/// Every out-of-line module declaration in a file, in one pass that tracks the inline modules around it. +/// +/// Declarations inside more than [`MAX_NESTING`] inline modules are left out, so their files are checked. +fn module_decls(toks: &[Token], skip: &[bool]) -> Vec { + let mut decls = Vec::new(); + let mut braces: Vec = Vec::new(); + let mut inline: Vec> = Vec::new(); + let mut too_deep = 0usize; + for (i, tok) in toks.iter().enumerate() { + match &tok.kind { + Kind::Punct('{') => { + let brace = match i.checked_sub(2).map(|j| (&toks[j], &toks[j + 1].kind)) { + Some((m, Kind::Ident(name))) if m.is_ident("mod") => { + if too_deep == 0 && inline.len() < MAX_NESTING { + inline.push(Rc::new(ModName { name: module_name(name), path_attribute: path_attribute(toks, i - 2) })); + Brace::Module + } else { + too_deep += 1; + Brace::TooDeep + } + } + _ => Brace::Block, + }; + braces.push(brace); + } + Kind::Punct('}') => match braces.pop() { + Some(Brace::Module) => { + inline.pop(); + } + Some(Brace::TooDeep) => too_deep -= 1, + _ => {} + }, + Kind::Ident(k) if k == "mod" && too_deep == 0 => { + if let Some(Kind::Ident(name)) = toks.get(i + 1).map(|t| &t.kind) + && toks.get(i + 2).is_some_and(|t| t.is_punct(';')) + { + decls.push(ModDecl { + module: ModName { name: module_name(name), path_attribute: path_attribute(toks, i) }, + inline: inline.clone(), + native: skip.get(i).copied().unwrap_or(false), + }); + } + } + _ => {} + } + } + decls +} + +/// A path with `\` read as `/`, empty and `.` components removed and `..` applied to the component before it. +fn normalize_path(path: &str) -> String { + let path = path.replace('\\', "/"); + let absolute = path.starts_with('/'); + let mut parts: Vec<&str> = Vec::new(); + for part in path.split('/') { + match part { + "" | "." => {} + ".." if parts.last().is_some_and(|p| *p != "..") => { + parts.pop(); + } + p => parts.push(p), + } + } + let joined = parts.join("/"); + if absolute { format!("/{joined}") } else { joined } +} + +/// `child` below the folder `parent`, normalized. A `child` that is an absolute path (`/x`, `\x` or `C:...`) +/// stands alone. `\\` is read as one separator, since a string literal keeps its escapes. +fn join_path(parent: &str, child: &str) -> String { + let child = child.replace("\\\\", "/"); + if parent.is_empty() || child.starts_with('/') || child.starts_with('\\') || child.as_bytes().get(1) == Some(&b':') { + normalize_path(&child) + } else { + normalize_path(&format!("{parent}/{child}")) + } +} + +/// The paths, normalized, where the module `decl` declared in the file at `parent` (normalized) can be. +/// +/// The modules of `lib.rs`, `main.rs` and `mod.rs`, and with `path_loaded`, of a file that a `#[path]` +/// attribute names, are in the file's folder, and those of any other file are in the folder named after +/// its stem. Each inline module around the declaration adds a folder named +/// after it, or with a `path` attribute, moves to that path relative to the current folder (without the +/// stem folder). The module is then `.rs` or `/mod.rs` there, or with a `path` attribute, that +/// path relative to the current folder, again without the stem folder. +fn module_files(parent: &str, decl: &ModDecl, path_loaded: bool) -> Vec { + let (dir, file) = match parent.rsplit_once('/') { + Some(("", file)) => ("/", file), + Some(split) => split, + None => ("", parent), + }; + let mut folder = dir.to_string(); + let mut stem = (!path_loaded && !matches!(file, "lib.rs" | "main.rs" | "mod.rs")).then(|| file.strip_suffix(".rs").unwrap_or(file)); + for inline in &decl.inline { + if let Some(attr) = &inline.path_attribute { + folder = join_path(&folder, attr); + stem = None; + } else { + if let Some(stem) = stem.take() { + folder = join_path(&folder, stem); + } + folder = join_path(&folder, &inline.name); + } + } + if let Some(attr) = &decl.module.path_attribute { + return vec![join_path(&folder, attr)]; + } + if let Some(stem) = stem { + folder = join_path(&folder, stem); + } + let name = &decl.module.name; + vec![join_path(&folder, &format!("{name}.rs")), join_path(&folder, &format!("{name}/mod.rs"))] +} + +/// For each file, whether it is native-only: a `mod` declaration in a native-only item, or any declaration +/// in a native-only file, names it, and no chain of declarations outside native-only items reaches it from +/// a crate root (a file that no declaration names, or in a cycle of declarations that no file outside the +/// cycle names, its `lib.rs` or `main.rs`, or every member when it has neither). +fn native_only_files(paths: &[String], decls: &[Vec]) -> Vec { + let mut index: BTreeMap<&str, Vec> = BTreeMap::new(); + for (i, path) in paths.iter().enumerate() { + index.entry(path.as_str()).or_default().push(i); + } + // rustc reads a file that a `#[path]` attribute names as if it were a `mod.rs`, so the modules it + // declares are in its own folder rather than its stem folder. Each file is therefore two nodes: node + // `2 * file` for the file loaded by a plain `mod name;` (or as a crate root), and node `2 * file + 1` + // for the file loaded through a `#[path]` attribute. Each node lists the nodes its declarations name, + // with whether the declaration is in a native-only item. + let edges: Vec> = (0..paths.len() * 2) + .map(|node| { + let (parent, path_loaded) = (node / 2, node % 2 == 1); + let mut targets = Vec::new(); + for decl in &decls[parent] { + let by_path = usize::from(decl.module.path_attribute.is_some()); + for candidate in module_files(&paths[parent], decl, path_loaded) { + for &j in index.get(candidate.as_str()).into_iter().flatten() { + targets.push((decl.native, 2 * j + by_path)); + } + } + } + targets + }) + .collect(); + + // A group of files that name each other in a cycle, and that no file outside the group names, has no + // member that a crate root can reach. rustc does not load a cycle of enabled declarations, so such a + // cycle runs through a declaration the build leaves out. When the group holds a `lib.rs` or `main.rs`, + // those files are its crate roots and the declarations that name them are read as left out; otherwise + // no declaration of the group names its own members, and each of them can be a crate root. + let file_edges: Vec> = + (0..paths.len()).map(|file| edges[2 * file].iter().chain(&edges[2 * file + 1]).map(|&(_, target)| target / 2).collect()).collect(); + let component = components(&file_edges); + let root_file = |file: usize| matches!(paths[file].rsplit('/').next(), Some("lib.rs" | "main.rs")); + let mut entered = vec![false; paths.len()]; + let mut has_root = vec![false; paths.len()]; + for (file, targets) in file_edges.iter().enumerate() { + has_root[component[file]] |= root_file(file); + for &target in targets { + if component[target] != component[file] { + entered[component[target]] = true; + } + } + } + let names = |node: usize, target: usize| { + let group = component[target / 2]; + component[node / 2] != group || entered[group] || (has_root[group] && !root_file(target / 2)) + }; + + // The nodes that are loaded: a file that no loaded node names is a crate root, loaded plainly, and a + // node is loaded when a loaded node names it. Every file starts out loaded plainly, and the set is + // narrowed until it stops changing, or after `MAX_MODULE_ROUNDS` rounds. + let mut loaded: Vec = (0..paths.len() * 2).map(|node| node % 2 == 0).collect(); + let mut named = vec![false; paths.len()]; + for _ in 0..MAX_MODULE_ROUNDS { + let mut reached = vec![false; paths.len() * 2]; + for (node, targets) in edges.iter().enumerate() { + if loaded[node] { + for &(_, target) in targets { + if names(node, target) { + reached[target] = true; + } + } + } + } + named = (0..paths.len()).map(|j| reached[2 * j] || reached[2 * j + 1]).collect(); + let next: Vec = (0..paths.len() * 2).map(|node| reached[node] || (node % 2 == 0 && !named[node / 2])).collect(); + if next == loaded { + break; + } + loaded = next; + } + + // Files the web build compiles: crate roots, and every file a declaration outside a native-only item + // of such a file names. + let mut web = vec![false; paths.len() * 2]; + let mut queue: Vec = (0..paths.len()).filter(|&j| !named[j]).map(|j| 2 * j).collect(); + for &node in &queue { + web[node] = true; + } + while let Some(parent) = queue.pop() { + for &(_, target) in edges[parent].iter().filter(|(is_native, _)| !is_native) { + if !web[target] { + web[target] = true; + queue.push(target); + } + } + } + + // Files a native-only declaration of a loaded node names, and their descendants. + let mut native = vec![false; paths.len() * 2]; + let starts = edges.iter().enumerate().filter(|&(node, _)| loaded[node]).flat_map(|(_, targets)| targets.iter()); + for &(_, target) in starts.filter(|(is_native, _)| *is_native) { + if !native[target] { + native[target] = true; + queue.push(target); + } + } + while let Some(parent) = queue.pop() { + for &(_, target) in &edges[parent] { + if !native[target] { + native[target] = true; + queue.push(target); + } + } + } + (0..paths.len()).map(|j| (native[2 * j] || native[2 * j + 1]) && !web[2 * j] && !web[2 * j + 1]).collect() +} + +/// The most rounds [`native_only_files`] spends narrowing the set of loaded files. +const MAX_MODULE_ROUNDS: usize = 16; + +/// For each node of the graph `edges`, the number of its strongly connected component (Tarjan's +/// algorithm, with an explicit stack in place of recursion). +fn components(edges: &[Vec]) -> Vec { + const UNSEEN: usize = usize::MAX; + let mut index = vec![UNSEEN; edges.len()]; + let mut low = vec![0; edges.len()]; + let mut on_stack = vec![false; edges.len()]; + let mut component = vec![UNSEEN; edges.len()]; + let mut stack = Vec::new(); + let mut next = 0; + let mut count = 0; + for root in 0..edges.len() { + if index[root] != UNSEEN { + continue; + } + index[root] = next; + low[root] = next; + next += 1; + stack.push(root); + on_stack[root] = true; + // Each frame is a node and the position of the next edge of it to follow. + let mut work = vec![(root, 0usize)]; + while let Some(frame) = work.last_mut() { + let node = frame.0; + if let Some(&target) = edges[node].get(frame.1) { + frame.1 += 1; + if index[target] == UNSEEN { + index[target] = next; + low[target] = next; + next += 1; + stack.push(target); + on_stack[target] = true; + work.push((target, 0)); + } else if on_stack[target] { + low[node] = low[node].min(index[target]); + } + continue; + } + work.pop(); + if let Some(&(parent, _)) = work.last() { + low[parent] = low[parent].min(low[node]); + } + if low[node] == index[node] { + while let Some(member) = stack.pop() { + on_stack[member] = false; + component[member] = count; + if member == node { + break; + } + } + count += 1; + } + } + } + component +} + +/// The innermost `{` around each token, and for each `}` the `{` it closes. +fn brace_scopes(toks: &[Token]) -> (Vec>, Vec>) { + let mut around = vec![None; toks.len()]; + let mut opener = vec![None; toks.len()]; + let mut open = Vec::new(); + for (j, t) in toks.iter().enumerate() { + around[j] = open.last().copied(); + if t.is_punct('{') { + open.push(j); + } else if t.is_punct('}') { + opener[j] = open.pop(); + } + } + (around, opener) +} + +/// Look a name up from `toks[at]` outward through the braces around it (`around`, from +/// [`brace_scopes`]): the first value that `get` returns for a pair of braces, given the index of its +/// `{`, or for the file, given `None`. The search ends with the body of the `mod` it starts in, since a +/// module does not see the names its parent binds. `Some(None)` means no braces bind the name; `None` +/// means the search passed [`MAX_NESTING`] levels. +fn lookup(toks: &[Token], around: &[Option], at: usize, get: impl Fn(Option) -> Option) -> Option> { + let mut scope = around.get(at).copied().flatten(); + for _ in 0..=MAX_NESTING { + if let Some(value) = get(scope) { + return Some(Some(value)); + } + match scope { + Some(o) if o >= 2 && toks[o - 2].is_ident("mod") && matches!(toks[o - 1].kind, Kind::Ident(_)) => return Some(None), + Some(o) => scope = around[o], + None => return Some(None), + } + } + None +} + +/// Add one finding for each line in `lines`, in line order, with the trimmed text of that line. +fn report(findings: &mut Vec, path: &str, content: &str, lines: &BTreeSet) { + if lines.is_empty() { + return; + } + let text: Vec<&str> = content.lines().collect(); + for &line in lines { + let line_text = text.get(line.saturating_sub(1)).map_or("", |s| s.trim()); + findings.push(Finding::new(path, line, line_text)); + } +} + +/// For each pair of braces (`None` for the file) and a name: whether a binding in those braces binds the +/// name to the muda crate, and whether one binds it to something else. +type CrateBindings<'a> = BTreeMap<(&'a str, Option), (bool, bool)>; + +/// The names of the muda crate in a file, and where each is bound. The names are `muda` itself and each +/// name that `use muda as m;`, `use muda::{self as m};` or `extern crate muda as m;` gives it. For each +/// name and each pair of braces, the bindings record whether a `use` or an `extern crate` in them binds +/// the name to the crate, and whether a `use`, an `extern crate` or a `mod` in them binds it to something +/// else. A binding to something else inside an item with a `cfg` attribute, or through `crate::`, `self::` +/// or `super::` (which may be a re-export of the crate), is left out. +fn muda_crate_bindings<'a>( + toks: &'a [Token], + leaves: &'a [UseLeaf], + around: &[Option], + gated: &[bool], +) -> (BTreeSet<&'a str>, CrateBindings<'a>) { + // Each `extern crate c;` or `extern crate c as n;`: whether `c` is muda, and the index of the name it + // binds. + let mut externs: Vec<(bool, &'a str, usize)> = Vec::new(); + for i in 0..toks.len() { + if toks[i].is_ident("extern") + && toks.get(i + 1).is_some_and(|t| t.is_ident("crate")) + && let Some(Kind::Ident(krate)) = toks.get(i + 2).map(|t| &t.kind) + { + let at = if toks.get(i + 3).is_some_and(|t| t.is_ident("as")) { i + 4 } else { i + 2 }; + if let Some(Kind::Ident(name)) = toks.get(at).map(|t| &t.kind) + && name != "_" + { + externs.push((krate == "muda", name.as_str(), at)); + } + } + } + let mut names: BTreeSet<&'a str> = BTreeSet::from(["muda"]); + names.extend(leaves.iter().filter(|leaf| leaf.path == ["muda"]).filter_map(UseLeaf::binding)); + names.extend(externs.iter().filter(|&&(muda, _, _)| muda).map(|&(_, name, _)| name)); + let mut bound: CrateBindings<'a> = BTreeMap::new(); + // `use muda as m;` binds `m` to the crate only where `muda` itself names the crate, so it is read + // after every other binding. + let renames = |leaf: &UseLeaf| leaf.path == ["muda"] && leaf.binding() != Some("muda"); + for leaf in leaves.iter().filter(|leaf| !renames(leaf)) { + let Some(name) = leaf.binding().filter(|name| names.contains(name)) else { continue }; + let local = leaf.root.as_deref().is_some_and(|s| matches!(s, "crate" | "self" | "super")); + let entry = bound.entry((name, around.get(leaf.start).copied().flatten())); + if leaf.path == ["muda"] { + entry.or_default().0 = true; + } else if !local && !gated.get(leaf.start).copied().unwrap_or(false) { + entry.or_default().1 = true; + } + } + for &(muda, name, at) in &externs { + if !names.contains(name) { + continue; + } + if muda { + bound.entry((name, around[at])).or_default().0 = true; + } else if !gated[at] { + bound.entry((name, around[at])).or_default().1 = true; + } + } + for (i, t) in toks.iter().enumerate() { + if let Kind::Ident(name) = &t.kind + && names.contains(name.as_str()) + && i.checked_sub(1).is_some_and(|k| toks[k].is_ident("mod")) + && !gated[i] + { + bound.entry((name, around[i])).or_default().1 = true; + } + } + let mut renamed = Vec::new(); + for leaf in leaves.iter().filter(|leaf| renames(leaf)) { + let Some(name) = leaf.binding() else { continue }; + let crate_here = + leaf.absolute || !matches!(lookup(toks, around, leaf.start, |scope| bound.get(&("muda", scope)).copied()), Some(Some((false, true)))); + let local = leaf.root.as_deref().is_some_and(|s| matches!(s, "crate" | "self" | "super")); + let scope = around.get(leaf.start).copied().flatten(); + if crate_here { + renamed.push((name, scope, true)); + } else if !local && !gated.get(leaf.start).copied().unwrap_or(false) { + renamed.push((name, scope, false)); + } + } + for (name, scope, muda) in renamed { + let entry = bound.entry((name, scope)).or_default(); + if muda { + entry.0 = true; + } else { + entry.1 = true; + } + } + (names, bound) +} + +/// Guard: detects direct calls to `muda`'s predefined Quit menu item. +/// +/// Using `PredefinedMenuItem::quit` connects the macOS menu directly to `NSApplication terminate:`, +/// which bypasses dirty document checks, unsaved changes save prompts, and lifecycle cleanup. +/// Applications should route Quit through custom menu items or interceptors connected to `craft-quit`. +/// +/// The guard reads Rust tokens, so comments, strings and character literals are ignored, and whitespace +/// or line breaks around `::` do not hide a call. A qualified path such as `::quit` +/// is reported too. A path that names the type through another crate or module, such as +/// `other::PredefinedMenuItem::quit`, is not, and neither is a path through a name `muda` that the innermost +/// braces binding it bind only to something else (`use other_menu as muda;`, `mod muda`), read like a name +/// used on its own below; `::muda::PredefinedMenuItem` always names the crate. A name that the crate is +/// imported under (`use muda as menu;`, `use muda::{self as menu};`, `extern crate muda as menu;`) is read +/// like `muda` in the braces that bind it, so `menu::PredefinedMenuItem::quit` is reported there. It also +/// follows a `use` or a `type` alias that renames muda's type (`use muda::PredefinedMenuItem as Item;` then +/// `Item::quit`); a rename of another crate's `PredefinedMenuItem` is not followed, including one through a +/// name `muda` that the braces around the `use` or `type` bind to something else, read as for a qualified +/// path. +/// +/// A name used on its own (`PredefinedMenuItem::quit`, `Item::quit`) is read in the innermost braces +/// around it, within its module, or the file, that bind the name. It is reported when those braces +/// import or alias muda's type under it, and not when they only import another type under it +/// (`use other::PredefinedMenuItem;`) or define one (`struct PredefinedMenuItem`). Where no braces bind +/// it, `PredefinedMenuItem` is reported and a renamed name is not. An import or definition inside an +/// item with a `cfg` attribute, an import or a type alias through `crate::`, `self::` or `super::` +/// (which may be a re-export of muda's type), and an associated `type` in an `impl` or `trait` do not +/// bind the name. Each finding names the line where the type's name starts, once per line, in line order. +pub fn predefined_quit(files: I) -> Vec +where + I: IntoIterator, + I::Item: AsFileSource, +{ + let mut findings = Vec::new(); + for file in files { + let path = file.path(); + let content = file.content(); + let toks = lex_rust(content); + let leaves = use_leaves(&toks, &BTreeSet::new()); + let (around, opener) = brace_scopes(&toks); + let gated = cfg_covered(&toks, true); + let (crate_names, crate_bound) = muda_crate_bindings(&toks, &leaves, &around, &gated); + let names_crate = |s: &str| crate_names.contains(s); + // Whether `name`, read at token `i`, names the crate. After a leading `::` only `muda` does. + // Otherwise `muda` does unless the innermost braces around `i` that bind `muda` bind it only to + // something else, and another name of the crate does when those braces bind it to the crate, or + // only to nothing else. + let crate_name_at = |name: &str, i: usize, absolute: bool| { + if absolute || !names_crate(name) { + return name == "muda"; + } + match lookup(&toks, &around, i, |scope| crate_bound.get(&(name, scope)).copied()) { + None => true, + Some(Some((muda, other))) => muda || !other, + Some(None) => name == "muda", + } + }; + // Whether the identifier at `i` names the crate. + let crate_is_muda = |i: usize| { + let Kind::Ident(name) = &toks[i].kind else { return false }; + let absolute = i >= 2 && toks[i - 1].is_punct(':') && toks[i - 2].is_punct(':'); + crate_name_at(name, i, absolute) + }; + // A `use` path to muda's type, read through a name of the crate bound where the `use` is. After + // a leading `::` the first segment is an external crate, so only `muda` names it. + let is_muda = + |leaf: &UseLeaf| leaf.path.len() == 2 && leaf.path[1] == "PredefinedMenuItem" && crate_name_at(&leaf.path[0], leaf.start, leaf.absolute); + // Whether the braces opened at `o` are the body of an `impl` or a `trait`, whose `type` items are + // associated types rather than names in scope. The head is read back from `o` to the `;`, `{` or + // `}` before it, stepping over a block in angle brackets (`impl Foo<{ N }>`), for at most + // `ATTRIBUTE_SCAN_LIMIT` tokens. + let assoc_body = |o: usize| { + let mut j = o; + let mut depth = 0usize; + let mut start = None; + for _ in 0..ATTRIBUTE_SCAN_LIMIT { + let Some(k) = j.checked_sub(1) else { + start = Some(0); + break; + }; + let t = &toks[k]; + if depth == 0 && (t.is_punct(';') || t.is_punct('{')) { + start = Some(k + 1); + break; + } + if depth == 0 && t.is_punct('}') { + let generic = opener[k].filter(|&b| b.checked_sub(1).is_some_and(|p| ['<', ',', '='].iter().any(|&c| toks[p].is_punct(c)))); + if let Some(b) = generic { + j = b; + continue; + } + start = Some(k + 1); + break; + } + match t.kind { + Kind::Punct(')' | ']') => depth += 1, + Kind::Punct('(' | '[') => depth = depth.saturating_sub(1), + _ => {} + } + j = k; + } + let Some(mut s) = start else { return false }; + // Attributes and modifiers before the keyword. + while s < o { + let next = |c: char| toks.get(s + 1).is_some_and(|t| t.is_punct(c)); + if (toks[s].is_punct('#') && next('[')) || (toks[s].is_ident("pub") && next('(')) { + // `#[...]` or `pub(...)`. + s = matching_close(&toks, s + 1).saturating_add(1); + } else if ["pub", "unsafe", "auto", "default"].iter().any(|m| toks[s].is_ident(m)) { + s += 1; + } else { + break; + } + } + s < o && (toks[s].is_ident("impl") || toks[s].is_ident("trait")) + }; + // Whether the `type` name at `i` is followed by `= muda::PredefinedMenuItem;` (or `::muda::...`, or + // a name of the crate in place of `muda`). + let aliases_muda = |i: usize| { + let mut j = i + 1; + if !toks.get(j).is_some_and(|t| t.is_punct('=')) { + return false; + } + j += 1; + if toks.get(j).is_some_and(|t| t.is_punct(':')) && toks.get(j + 1).is_some_and(|t| t.is_punct(':')) { + j += 2; + } + j < toks.len() + && crate_is_muda(j) + && then_path(&toks, j + 1, |s| s == "PredefinedMenuItem") + && toks.get(j + 4).is_some_and(|t| t.is_punct(';')) + }; + let definition = + |i: usize| i.checked_sub(1).is_some_and(|k| ["struct", "enum", "union", "type", "trait"].iter().any(|kw| toks[k].is_ident(kw))); + // The names of muda's type: its own, and each name a `use` or a `type` alias gives it. + let mut names: BTreeSet<&str> = BTreeSet::from(["PredefinedMenuItem"]); + names.extend(leaves.iter().filter(|leaf| is_muda(leaf)).filter_map(UseLeaf::binding)); + for (i, t) in toks.iter().enumerate() { + if let Kind::Ident(name) = &t.kind + && i.checked_sub(1).is_some_and(|k| toks[k].is_ident("type")) + && aliases_muda(i) + { + names.insert(name); + } + } + // For each of those names and each pair of braces (`None` for the file), whether a `use` or a + // type alias in it binds the name to muda's type, and whether a `use` or an item definition in it + // binds the name to another type. A binding to another type inside an item with a `cfg` + // attribute may not apply on the platform the guard protects, so it is left out. + let mut bound: BTreeMap<(&str, Option), (bool, bool)> = BTreeMap::new(); + for leaf in &leaves { + let Some(name) = leaf.binding().filter(|name| names.contains(name)) else { continue }; + let muda = is_muda(leaf); + // A path into this crate (`crate::`, `self::`, `super::`) may lead to a re-export of muda's + // type, so it is not counted as another type. + let local = leaf.root.as_deref().is_some_and(|s| matches!(s, "crate" | "self" | "super")); + if muda || (!local && !gated.get(leaf.start).copied().unwrap_or(false)) { + let entry = bound.entry((name, around.get(leaf.start).copied().flatten())).or_default(); + if muda { + entry.0 = true; + } else { + entry.1 = true; + } + } + } + for (i, t) in toks.iter().enumerate() { + let Kind::Ident(name) = &t.kind else { continue }; + let Some(k) = i.checked_sub(1) else { continue }; + if !names.contains(name.as_str()) || !definition(i) { + continue; + } + if toks[k].is_ident("type") && around[i].is_some_and(assoc_body) { + continue; + } + // An alias of a path into this crate may name a re-export of muda's type, as an import does. + let local_alias = toks.get(i + 1).is_some_and(|t| t.is_punct('=')) + && toks.get(i + 2).is_some_and(|t| t.is_ident("crate") || t.is_ident("self") || t.is_ident("super")); + if toks[k].is_ident("type") && local_alias { + continue; + } + let key = (name.as_str(), around[i]); + if toks[k].is_ident("type") && aliases_muda(i) { + bound.entry(key).or_default().0 = true; + } else if !gated[i] { + bound.entry(key).or_default().1 = true; + } + } + // A name used on its own is muda's type when the innermost braces around it that bind it (within + // its module) bind it to muda's type, or only to nothing else. Where no braces bind it, only + // `PredefinedMenuItem` itself is muda's type. Past `MAX_NESTING` levels it is read as muda's type. + let bare_is_muda = |name: &str, i: usize| match lookup(&toks, &around, i, |scope| bound.get(&(name, scope)).copied()) { + None => true, + Some(Some((muda, other))) => muda || !other, + Some(None) => name == "PredefinedMenuItem", + }; + let mut lines = BTreeSet::new(); + for (i, tok) in toks.iter().enumerate() { + let Kind::Ident(name) = &tok.kind else { continue }; + if !names.contains(name.as_str()) { + continue; + } + // A qualified name counts only as `muda::PredefinedMenuItem` (or `::muda::...`, or a name of the + // crate in place of `muda`), not as another crate's or module's type of the same name. + let named = if continues_a_path(&toks, i) { + name == "PredefinedMenuItem" && !continues_a_path(&toks, i - 3) && crate_is_muda(i - 3) + } else { + bare_is_muda(name, i) + }; + let quit = |at: usize| then_path(&toks, at, |s| s == "quit" || s == "Quit"); + // `::quit`, a qualified path to the same function. + let qualified = || toks.get(i + 1).is_some_and(|t| t.is_punct('>')) && quit(i + 2) && opens_qualified_path(&toks, i); + if named && (quit(i + 1) || qualified()) { + lines.insert(tok.line); + } + } + report(&mut findings, path, content, &lines); + } + findings +} + +/// Guard: detects uses of `std::time::Instant` in code paths running on the web. +/// +/// On `wasm32-unknown-unknown`, `std::time::Instant::now()` panics with "time not implemented +/// on this platform". Crates running in the browser should use `web_time::Instant`, which maps to +/// `std::time::Instant` on native platforms and `performance.now()` on the web. +/// +/// ### Syntactic Scope and Limitations +/// +/// * **Targeted files**: Callers should pass files from crates that compile into the application's web build. +/// * **What is reported**: the paths `std::time::Instant` and `::std::time::Instant`; `::Instant` where a +/// `use` outside a native-only item binds `m` to `std::time` (`use std::time;`, `use std::time as t;`, +/// `use std::time::{self as t}`); +/// and every `use` that imports `std::time::Instant` or `std::time::*`, under any name, directly or through +/// such an `m` of any length (`use m::{Instant as Clock};`, `use m::*;`). Whitespace, comments +/// and line breaks may separate the parts of a path. Each finding names the line where the path starts (in a +/// `use` group, the line where the name's part of the group starts), once per line, in line order. +/// * **What is skipped**: comments, string and character literals, other crates' `Instant` (`web_time::Instant`, +/// a `time` module that is not `std::time`), and items whose `cfg` attribute is false on `wasm32-unknown-unknown` +/// (for example `#[cfg(not(target_arch = "wasm32"))]`, `#[cfg(all(unix, ...))]`, `#[cfg(target_os = "macos")]`, +/// or `#![cfg(...)]` for the rest of a module). Such an attribute covers only its item: code before the +/// attribute or after the item on the same line is checked. A statement whose value holds a block, such as +/// `let n = match x { ... } as u64 + ...;`, is covered up to its `;`. `cfg(false)` is false and `cfg(true)` +/// is true. A predicate that depends on a feature or on `test`, or that is nested more than 64 levels deep, +/// is not known from the source, so the item is checked. Escapes in a predicate's string values are decoded. +/// * **Module files**: a `mod name;` inside such an item makes the module's file native-only, and so are the +/// files of the modules declared in it, when they are among `files`, unless a chain of declarations outside +/// such items also reaches the file from a crate root (a file that no declaration names, or in a cycle of +/// declarations that no file outside the cycle names, such as `lib.rs` naming itself through `#[path]`, the +/// cycle's `lib.rs` or `main.rs`, or every file of the cycle when it has neither). The module's file is `name.rs` or +/// `name/mod.rs` next to `lib.rs`, `main.rs`, `mod.rs` or a file that a `#[path]` attribute names, and in +/// the folder named after any other file's stem, below the folders of enclosing inline modules; a `#[path = "..."]` attribute on the declaration +/// or on an enclosing inline module is followed. Paths are compared as text with `\` read as `/`, so the files must be named the same way +/// (for example all from one `rust_sources` call), and a crate root other than `lib.rs` or `main.rs` +/// (such as `src/bin/tool.rs`) is read as an ordinary module file. A declaration inside more than 64 inline +/// modules is not followed, so its file is checked. +/// * **Limitations**: This is a lexical source guard. It does not expand macros, resolve paths through other +/// modules or re-exports, or rename `std` itself (`use std as s;`). An alias of `std::time` counts inside the +/// braces of its `use` (or the file), down to but not into the body of a nested `mod`; nearer braces whose +/// `use` or `mod` binds the same name to something else hide it, unless that `use` or `mod` carries a `cfg` +/// attribute of its own that is not known to be true on `wasm32-unknown-unknown`, which may leave it out of +/// the web build. +pub fn std_instant(files: I) -> Vec +where + I: IntoIterator, + I::Item: AsFileSource, +{ + let files: Vec = files.into_iter().collect(); + let paths: Vec = files.iter().map(|file| normalize_path(file.path())).collect(); + // Only the declarations are kept from this pass, so the tokens of every file are never held at once. + let decls: Vec> = files + .iter() + .map(|file| { + let toks = lex_rust(file.content()); + module_decls(&toks, &native_only(&toks)) + }) + .collect(); + let excluded = native_only_files(&paths, &decls); + + let mut findings = Vec::new(); + for (file, excluded) in files.iter().zip(excluded) { + if excluded { + continue; + } + let path = file.path(); + let content = file.content(); + let toks = lex_rust(content); + let skip = native_only(&toks); + let leaves = use_leaves(&toks, &BTreeSet::new()); + let modules: BTreeSet = leaves + .iter() + .filter(|leaf| leaf.path == ["std", "time"] && !skip.get(leaf.start).copied().unwrap_or(false)) + .filter_map(|leaf| leaf.binding().map(str::to_owned)) + .collect(); + // For each alias name and each pair of braces (`None` for the file), whether a `use` in it binds + // the name to `std::time`, and whether a `use` or a `mod` binds the name to something else, unless + // its own `cfg` attribute may be false on the web. + let (around, _) = brace_scopes(&toks); + let gated = cfg_items(&toks); + let mut bound: BTreeMap<(&str, Option), (bool, bool)> = BTreeMap::new(); + for leaf in &leaves { + let Some(name) = leaf.binding().filter(|name| modules.contains(*name)) else { continue }; + let time = leaf.path == ["std", "time"]; + // A `use` of something else that carries a `cfg` attribute of its own that may be false on the + // web may be absent from the web build, so it does not hide an outer alias. + if !skip.get(leaf.start).copied().unwrap_or(false) && (time || !gated.contains(&leaf.start)) { + let entry = bound.entry((name, around.get(leaf.start).copied().flatten())).or_default(); + if time { + entry.0 = true; + } else { + entry.1 = true; + } + } + } + for (i, t) in toks.iter().enumerate() { + if let Kind::Ident(name) = &t.kind + && modules.contains(name) + && !skip[i] + && i.checked_sub(1).is_some_and(|k| toks[k].is_ident("mod") && !gated.contains(&k)) + { + bound.entry((name.as_str(), around[i])).or_default().1 = true; + } + } + // Whether `name` at `toks[at]` is an alias of `std::time`: the innermost braces around it that + // bind the name (within its module) bind it to `std::time`. Past `MAX_NESTING` levels it is. + let time_alias = |name: &str, at: usize| match lookup(&toks, &around, at, |scope| bound.get(&(name, scope)).copied()) { + None => true, + Some(Some((time, _))) => time, + Some(None) => false, + }; + // Read again with the aliases of `std::time`, so a path through an alias starts with `std::time`. + // The leaves read without aliases are checked as well, since an alias does not reach every `use` + // whose path starts with its name (an alias in a nested module named `std`). + let aliased = if modules.is_empty() { Vec::new() } else { use_leaves(&toks, &modules) }; + let is_std_time = |path: &[String]| path == ["std", "time"]; + + let mut lines = BTreeSet::new(); + for leaf in leaves.iter().chain(&aliased) { + if skip.get(leaf.start).copied().unwrap_or(false) { + continue; + } + let imports_instant = if leaf.name.is_none() { + is_std_time(&leaf.path) + } else { + leaf.path.split_last().is_some_and(|(last, parent)| last == "Instant" && is_std_time(parent)) + }; + // A path read through an alias counts only where the alias names `std::time`. + let through_other = leaf.alias.is_some_and(|a| matches!(&toks[a].kind, Kind::Ident(root) if !time_alias(root, leaf.start))); + if imports_instant && !through_other { + lines.insert(leaf.line); + } + } + for (i, tok) in toks.iter().enumerate() { + if skip[i] || continues_a_path(&toks, i) { + continue; + } + let Kind::Ident(name) = &tok.kind else { continue }; + let hit = if name == "std" { + then_path(&toks, i + 1, |s| s == "time") && then_path(&toks, i + 4, |s| s == "Instant") + } else { + modules.contains(name) && then_path(&toks, i + 1, |s| s == "Instant") && time_alias(name, i) + }; + if hit { + lines.insert(tok.line); + } + } + report(&mut findings, path, content, &lines); + } + findings +} + +/// Replace WGSL comments (`//` and nested `/* ... */`) with spaces, and write each WGSL line break as +/// `\n`: line feed, vertical tab, form feed, carriage return, carriage return and line feed as one +/// break, next line (U+0085), line separator (U+2028) and paragraph separator (U+2029) +/// (). A line comment ends at any of them, and `str::lines` +/// then counts lines the way WGSL does. +fn mask_wgsl_comments(code: &str) -> String { + let chars: Vec = code.chars().collect(); + let len = chars.len(); + let mut out = String::with_capacity(code.len()); + let mut i = 0; + let mut depth = 0usize; + let mut in_line = false; + while i < len { + let c = chars[i]; + let next = chars.get(i + 1).copied(); + let line_break = match c { + '\r' if next == Some('\n') => 2, + '\n' | '\u{000B}' | '\u{000C}' | '\r' | '\u{0085}' | '\u{2028}' | '\u{2029}' => 1, + _ => 0, + }; + if line_break > 0 { + in_line = false; + out.push('\n'); + i += line_break; + } else if in_line { + out.push(' '); + i += 1; + } else if c == '/' && next == Some('*') { + depth += 1; + out.push_str(" "); + i += 2; + } else if depth > 0 && c == '*' && next == Some('/') { + depth -= 1; + out.push_str(" "); + i += 2; + } else if depth > 0 { + out.push(' '); + i += 1; + } else if c == '/' && next == Some('/') { + in_line = true; + out.push_str(" "); + i += 2; + } else { + out.push(c); + i += 1; + } + } + out +} + +/// The largest finite value of the type a WGSL float literal with this suffix has. +fn float_limit(suffix: Option) -> f64 { + if suffix == Some(b'h') { 65504.0 } else { f64::from(f32::MAX) } +} + +/// Read a WGSL hexadecimal literal starting at the `0` of `0x`. Returns the index after it, the length of +/// its text without a suffix, and whether it is a float above the range of its type. +fn scan_wgsl_hex(code: &[u8], start: usize) -> (usize, usize, bool) { + // Significant hex digits kept; 15 hold 60 bits, more than an f64 mantissa. + const KEPT: usize = 15; + let mut i = start + 2; + let mut mantissa = 0f64; + let mut kept = 0usize; + let mut exponent: i64 = 0; + let mut digits = 0usize; + let mut digit = |d: u8, fraction: bool, exponent: &mut i64| { + let value = (d as char).to_digit(16).unwrap_or(0); + if mantissa == 0.0 && value == 0 { + if fraction { + *exponent -= 4; + } + } else if kept < KEPT { + mantissa = mantissa * 16.0 + f64::from(value); + kept += 1; + if fraction { + *exponent -= 4; + } + } else if !fraction { + *exponent += 4; + } + }; + while i < code.len() && code[i].is_ascii_hexdigit() { + digit(code[i], false, &mut exponent); + digits += 1; + i += 1; + } + let mut is_float = false; + if code.get(i) == Some(&b'.') { + is_float = true; + i += 1; + while i < code.len() && code[i].is_ascii_hexdigit() { + digit(code[i], true, &mut exponent); + digits += 1; + i += 1; + } + } + let mut has_exponent = false; + if matches!(code.get(i), Some(b'p' | b'P')) { + let mut j = i + 1; + let negative = code.get(j) == Some(&b'-'); + if matches!(code.get(j), Some(b'+' | b'-')) { + j += 1; + } + if code.get(j).is_some_and(u8::is_ascii_digit) { + let mut e: i64 = 0; + while j < code.len() && code[j].is_ascii_digit() { + e = (e * 10 + i64::from(code[j] - b'0')).min(1_000_000); + j += 1; + } + exponent += if negative { -e } else { e }; + has_exponent = true; + is_float = true; + i = j; + } + } + let text_len = i - start; + let suffix = if has_exponent && matches!(code.get(i), Some(b'f' | b'h')) { code.get(i).copied() } else { None }; + let end = if suffix.is_some() || (!is_float && matches!(code.get(i), Some(b'i' | b'u'))) { i + 1 } else { i }; + if !is_float || digits == 0 || mantissa == 0.0 { + return (end, text_len, false); + } + let scale = i32::try_from(exponent.clamp(-4000, 4000)).unwrap_or(0); + let value = mantissa * 2f64.powi(scale); + (end, text_len, !value.is_finite() || value > float_limit(suffix)) +} + +/// Guard: scans a single WGSL shader string and detects float literals outside their type's finite range. +/// +/// WebGPU compilers in browsers reject a float literal above `f32::MAX` (e.g. `3.40282347e38`) with a +/// pipeline build error, which turns off GPU rendering. `f32::MAX` can be written as the hex float +/// `0x1.fffffep+127f`, which equals it, or as the decimal `3.4028234663852886e38`, which rounds to it. +/// +/// ### Policy and Limitations +/// +/// * **Conservative mathematical bound**: The guard compares the literal's value, rounded to `f64`, +/// with `f64::from(f32::MAX)`, or with 65504 (the largest finite `f16`) for an `h` suffix. Any literal +/// above it is reported, even one that a compiler would round down to the maximum. A literal that exceeds +/// the maximum by less than `f64` precision (such as `0x1.fffffe000000001p+127f`) rounds to the maximum and +/// is not reported. +/// * **Which literals**: decimal floats (with a `.`, an exponent or an `f`/`h` suffix) and hexadecimal floats +/// (`0x` with a `.` or a `p` exponent). Integer literals (`123`, `123u`, `0xFFi`, `0x1f`) are not floats and +/// are not reported. A `-` in front is not part of the literal, so `-1e39` is reported as `1e39`. +/// * **Comments**: Comments (`//` and nested `/* ... */`) are masked out prior to scanning. A `//` comment +/// ends at any WGSL line break, a lone carriage return included, and finding lines count every one of them. +/// * **Identifiers**: digits inside an identifier, `π1e39` included, are not a literal. +pub fn wgsl_float_literals(wgsl: &str) -> Vec { + wgsl_float_literals_in([("", wgsl)]) +} + +/// Guard: scans multiple WGSL shader files and detects float literals outside their type's finite range, +/// with the rules of [`wgsl_float_literals`]. +pub fn wgsl_float_literals_in(files: I) -> Vec +where + I: IntoIterator, + I::Item: AsFileSource, +{ + let mut findings = Vec::new(); + for file in files { + let path = file.path(); + let masked = mask_wgsl_comments(file.content()); + + for (n, line) in masked.lines().enumerate() { + let code = line.as_bytes(); + let mut i = 0; + while i < code.len() { + let digit_or_dot = code[i].is_ascii_digit() || (code[i] == b'.' && code.get(i + 1).is_some_and(u8::is_ascii_digit)); + // Outside comments, a character that is not ASCII and not blankspace (U+200E, U+200F) is part of an + // identifier, as in `π1e39`. + let word_before = digit_or_dot + && i > 0 + && (code[i - 1].is_ascii_alphanumeric() + || code[i - 1] == b'_' + || code[i - 1] == b'.' + || (!code[i - 1].is_ascii() && !line[..i].ends_with(['\u{200E}', '\u{200F}']))); + if !digit_or_dot || word_before { + i += 1; + continue; + } + let start = i; + if code[i] == b'0' && matches!(code.get(i + 1), Some(b'x' | b'X')) { + let (end, text_len, over) = scan_wgsl_hex(code, i); + if over { + findings.push(Finding::new(path, n + 1, String::from_utf8_lossy(&code[start..start + text_len]).into_owned())); + } + i = end.max(i + 1); + continue; + } + let mut is_float = false; + while i < code.len() && code[i].is_ascii_digit() { + i += 1; + } + if code.get(i) == Some(&b'.') { + is_float = true; + i += 1; + while i < code.len() && code[i].is_ascii_digit() { + i += 1; + } + } + if matches!(code.get(i), Some(b'e' | b'E')) { + let mut j = i + 1; + if matches!(code.get(j), Some(b'+' | b'-')) { + j += 1; + } + if code.get(j).is_some_and(u8::is_ascii_digit) { + is_float = true; + i = j; + while i < code.len() && code[i].is_ascii_digit() { + i += 1; + } + } + } + let literal = String::from_utf8_lossy(&code[start..i]).into_owned(); + let suffix = match code.get(i) { + Some(&s @ (b'f' | b'h')) => { + is_float = true; + i += 1; + Some(s) + } + Some(b'i' | b'u') if !is_float => { + i += 1; + None + } + _ => None, + }; + if !is_float { + continue; + } + let is_overflow = match literal.parse::() { + Ok(v) => !v.is_finite() || v.abs() > float_limit(suffix), + Err(_) => true, + }; + if is_overflow { + findings.push(Finding::new(path, n + 1, literal)); + } + } + } + } + findings +} + +/// Size limits for [`rust_sources_with_limits`]. An input over a limit is an error. +#[cfg(not(target_arch = "wasm32"))] +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct SourceLimits { + /// The largest single file read, in bytes. Default 8 MiB. + pub max_file_bytes: u64, + /// The largest total of all files read, in bytes. Default 256 MiB. + pub max_total_bytes: u64, + /// The most files read. Default 50,000. + pub max_files: usize, +} + +#[cfg(not(target_arch = "wasm32"))] +impl Default for SourceLimits { + fn default() -> Self { + Self { max_file_bytes: 8 << 20, max_total_bytes: 256 << 20, max_files: 50_000 } + } +} + +/// The first line of a `CACHEDIR.TAG` file, which marks a folder of generated files +/// (). Cargo writes one in each target folder. +#[cfg(not(target_arch = "wasm32"))] +const CACHEDIR_SIGNATURE: &[u8] = b"Signature: 8a477f597d28d172789f06886806bc55"; + +/// Whether `dir` holds a `CACHEDIR.TAG` regular file that starts with [`CACHEDIR_SIGNATURE`]. A marker +/// that is a symbolic link, a folder, a FIFO or another special file is not opened and does not count. +#[cfg(not(target_arch = "wasm32"))] +fn is_cache_dir(dir: &Path) -> bool { + use std::io::Read; + let marker = dir.join("CACHEDIR.TAG"); + if !std::fs::symlink_metadata(&marker).is_ok_and(|m| m.file_type().is_file()) { + return false; + } + let Ok(file) = std::fs::File::open(&marker) else { + return false; + }; + let mut head = Vec::with_capacity(CACHEDIR_SIGNATURE.len()); + file.take(CACHEDIR_SIGNATURE.len() as u64).read_to_end(&mut head).is_ok() && head == CACHEDIR_SIGNATURE +} + +/// Recursively collect all Rust source files under `dir`, excluding test files and test directories, +/// with the default [`SourceLimits`]. +/// +/// Excluded files: +/// * `tests.rs` +/// * `tests_*.rs` +/// * `*_tests.rs` +/// * `*_test.rs` +/// * `test.rs` +/// * Any file below `dir` within a directory named `tests`, `benches`, `examples` or `target`, or whose +/// name starts with `.`, or that holds a `CACHEDIR.TAG` regular file starting with the signature line +/// `Signature: 8a477f597d28d172789f06886806bc55` (a build output folder with another name). A +/// `CACHEDIR.TAG` that is a symbolic link or a special file such as a FIFO is not read, and its folder +/// is listed. +/// * Symbolic links (and, on Windows, junctions) to files or folders, which are not followed. +/// +/// Results are sorted lexicographically by file path for deterministic behavior across platforms. +#[cfg(not(target_arch = "wasm32"))] +pub fn rust_sources(dir: impl AsRef) -> std::io::Result> { + rust_sources_with_limits(dir, SourceLimits::default()) +} + +/// [`rust_sources`] with explicit size limits. A file over `max_file_bytes` returns an error of kind +/// [`std::io::ErrorKind::FileTooLarge`]; more than `max_files` files or `max_total_bytes` bytes in all +/// returns an error of kind [`std::io::ErrorKind::QuotaExceeded`]. +#[cfg(not(target_arch = "wasm32"))] +pub fn rust_sources_with_limits(dir: impl AsRef, limits: SourceLimits) -> std::io::Result> { + use std::io::{Error, ErrorKind, Read}; + + let root = dir.as_ref(); + let mut files = Vec::new(); + let mut total: u64 = 0; + let mut dirs = vec![root.to_path_buf()]; + + while let Some(d) = dirs.pop() { + for entry in std::fs::read_dir(&d)? { + let entry = entry?; + let p = entry.path(); + let kind = entry.file_type()?; + if kind.is_symlink() { + continue; + } + let name = entry.file_name(); + let name = name.to_string_lossy(); + if kind.is_dir() { + if name.starts_with('.') || name == "target" || name == "tests" || name == "benches" || name == "examples" || is_cache_dir(&p) { + continue; + } + dirs.push(p); + } else if kind.is_file() { + if !name.ends_with(".rs") { + continue; + } + if name == "tests.rs" || name.starts_with("tests_") || name.ends_with("_tests.rs") || name.ends_with("_test.rs") || name == "test.rs" + { + continue; + } + if files.len() >= limits.max_files { + return Err(Error::new( + ErrorKind::QuotaExceeded, + format!("more than {} Rust source files under {}", limits.max_files, root.display()), + )); + } + let over_file = || Error::new(ErrorKind::FileTooLarge, format!("{} is larger than {} bytes", p.display(), limits.max_file_bytes)); + if entry.metadata()?.len() > limits.max_file_bytes { + return Err(over_file()); + } + let mut content = String::new(); + std::fs::File::open(&p)?.take(limits.max_file_bytes.saturating_add(1)).read_to_string(&mut content)?; + let size = content.len() as u64; + if size > limits.max_file_bytes { + return Err(over_file()); + } + total = total.saturating_add(size); + if total > limits.max_total_bytes { + return Err(Error::new( + ErrorKind::QuotaExceeded, + format!("Rust sources under {} are larger than {} bytes in all", root.display(), limits.max_total_bytes), + )); + } + files.push((p.display().to_string(), content)); + } + } + } + + files.sort_by(|a, b| a.0.cmp(&b.0)); + Ok(files) +} + +#[cfg(test)] +mod tests { + use std::collections::BTreeSet; + + use super::{MAX_USE_PATH, MAX_USE_SEGMENT, lex_rust, use_leaves}; + + fn paths_and_names(source: &str) -> Vec<(Vec, Option)> { + use_leaves(&lex_rust(source), &BTreeSet::new()).into_iter().map(|leaf| (leaf.path, leaf.name.map(|name| name.to_string()))).collect() + } + + #[test] + fn use_leaves_keep_no_path_longer_than_the_limit() { + let source = format!("use {}{{x, y::z, *}};\nuse std::time::{{Instant, self as t}};\n", "a::".repeat(MAX_USE_PATH)); + let some = |name: &str| Some(name.to_string()); + let path = |segments: &[&str]| segments.iter().map(|s| s.to_string()).collect::>(); + assert_eq!( + paths_and_names(&source), + vec![ + (Vec::new(), some("x")), + (Vec::new(), some("z")), + (vec!["a".to_string(); MAX_USE_PATH], None), + (path(&["std", "time", "Instant"]), some("Instant")), + (path(&["std", "time"]), some("t")), + ] + ); + } + + #[test] + fn use_leaves_keep_no_segment_longer_than_the_limit() { + let long = "n".repeat(MAX_USE_SEGMENT + 1); + let fits = "n".repeat(MAX_USE_SEGMENT); + let source = format!("use {long}::{{self, x, *}};\nuse a::{long};\nuse {fits}::{{self as b, *}};\n"); + assert_eq!( + paths_and_names(&source), + vec![ + (Vec::new(), Some(long.clone())), + (Vec::new(), Some("x".to_string())), + (Vec::new(), Some(long)), + (vec![fits.clone()], Some("b".to_string())), + (vec![fits], None), + ] + ); + } +} diff --git a/crates/testkit/src/hostile.rs b/crates/testkit/src/hostile.rs new file mode 100644 index 000000000..4480d6aaf --- /dev/null +++ b/crates/testkit/src/hostile.rs @@ -0,0 +1,817 @@ +//! Hostile inputs made from a valid seed, for tests that a parser fails cleanly on damaged data. +//! +//! [`mutations`] yields a fixed sequence of damaged copies of a seed: each round applies one to +//! four edits (a bit flip, a random byte, a 1, 2, 4 or 8-byte overwrite with an extreme value in +//! either byte order, a deletion of up to 16 bytes, or a truncation) and labels the result with +//! the edits it made. The sequence depends only on the seed's length and the number of rounds, so +//! a failing case can be found again from its label. It builds for every target, `wasm32` +//! included. +//! +//! [`hammer`] runs a parser on the unmodified seed, on every truncation of it and on the +//! mutations, one case after another on a worker thread, with a time limit for each case. It fails +//! the test, naming the case and the input length, when the parser panics or does not finish in +//! time. The number of rounds is a count the caller gives, multiplied by a variable the caller +//! names. [`hammer`] and [`HammerConfig`] are not built for `wasm32`. + +use std::fmt::Write as _; + +#[cfg(not(target_arch = "wasm32"))] +use crate::deadline::{DeadlineLimit, Resolved, resolve}; +#[cfg(not(target_arch = "wasm32"))] +use std::any::Any; +#[cfg(not(target_arch = "wasm32"))] +use std::ffi::OsString; +#[cfg(not(target_arch = "wasm32"))] +use std::fmt; +#[cfg(not(target_arch = "wasm32"))] +use std::panic::{AssertUnwindSafe, catch_unwind}; +#[cfg(not(target_arch = "wasm32"))] +use std::sync::{Arc, Condvar, Mutex, MutexGuard, PoisonError}; +#[cfg(not(target_arch = "wasm32"))] +use std::thread; +#[cfg(not(target_arch = "wasm32"))] +use std::time::{Duration, Instant}; + +/// The name of the thread [`hammer`] runs its cases on. +#[cfg(not(target_arch = "wasm32"))] +const WORKER_NAME: &str = "craft-testkit hostile"; + +/// The variable that multiplies a [`HammerConfig`]'s rounds unless +/// [`HammerConfig::with_multiplier_variable`] names another. +pub const DEFAULT_MULTIPLIER_VARIABLE: &str = "CRAFT_HOSTILE_MULT"; + +/// The default limit for one case of [`hammer`]. The limit's variable, `CRAFT_TEST_TIMEOUT_SECS` +/// unless [`HammerConfig::with_timeout`] names another, replaces it. +#[cfg(not(target_arch = "wasm32"))] +pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(5); + +/// The most cases one [`hammer`] call runs: the unmodified seed, its truncations and the rounds +/// together. A call that would run more fails before it runs any. +pub const MAX_CASES: usize = 10_000_000; + +/// The values the overwrite edits write, in 1, 2, 4 or 8 bytes. +const EXTREMES: [u64; 8] = [0, 1, 0x7F, 0x80, 0xFF, 0xFFFF, 0x8000_0000, u64::MAX]; + +/// The xorshift64* generator behind [`mutations`]. +/// +/// ``` +/// use craft_testkit::hostile::Rng; +/// +/// let mut rng = Rng(1); +/// assert_eq!(rng.next_u64(), 0x47E4_CE4B_896C_DD1D); +/// ``` +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Rng(pub u64); + +impl Rng { + /// The next value. + pub fn next_u64(&mut self) -> u64 { + self.0 ^= self.0 >> 12; + self.0 ^= self.0 << 25; + self.0 ^= self.0 >> 27; + self.0.wrapping_mul(0x2545_F491_4F6C_DD1D) + } + + /// A value below `n`, or 0 when `n` is 0. + pub fn below(&mut self, n: usize) -> usize { + (self.next_u64() % n.max(1) as u64) as usize + } +} + +/// One damaged copy of a seed, from [`mutations`]. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Mutation { + /// The damaged bytes. + pub bytes: Vec, + /// The edits made, in order, separated by spaces, such as `flip[3].5 del[7..9]`. + pub label: String, +} + +/// `rounds` damaged copies of `seed`, in a sequence fixed by the seed's length and `rounds`. +/// +/// An empty seed yields no copies, since there is no byte to edit. +/// +/// ``` +/// use craft_testkit::hostile::mutations; +/// +/// let all: Vec<_> = mutations(&[0, 1, 2, 3], 2).collect(); +/// assert_eq!(all[1].label, "trunc2"); +/// assert_eq!(all[1].bytes, [0, 1]); +/// ``` +pub fn mutations(seed: &[u8], rounds: usize) -> Mutations<'_> { + Mutations { seed, rng: Rng((0x5EED_F00D ^ seed.len() as u64) | 1), remaining: if seed.is_empty() { 0 } else { rounds } } +} + +/// The iterator [`mutations`] returns. +#[derive(Clone, Debug)] +pub struct Mutations<'a> { + seed: &'a [u8], + rng: Rng, + remaining: usize, +} + +impl Iterator for Mutations<'_> { + type Item = Mutation; + + fn next(&mut self) -> Option { + if self.remaining == 0 { + return None; + } + self.remaining -= 1; + let rng = &mut self.rng; + let mut d = self.seed.to_vec(); + let mut label = String::new(); + for _ in 0..1 + rng.below(4) { + if d.is_empty() { + break; + } + if !label.is_empty() { + label.push(' '); + } + let pos = rng.below(d.len()); + match rng.below(7) { + 0 => { + let b = rng.below(8); + if let Some(byte) = d.get_mut(pos) { + *byte ^= 1 << b; + } + let _ = write!(label, "flip[{pos}].{b}"); + } + 1 => { + let value = rng.next_u64() as u8; + if let Some(byte) = d.get_mut(pos) { + *byte = value; + } + let _ = write!(label, "set[{pos}]={value:#x}"); + } + 2..=4 => { + let w = [1usize, 2, 4, 8][rng.below(4)]; + let v = EXTREMES[rng.below(EXTREMES.len())]; + let be = rng.below(2) == 0; + let all = if be { v.to_be_bytes() } else { v.to_le_bytes() }; + let bytes = if be { &all[8 - w..] } else { &all[..w] }; + let end = (pos + w).min(d.len()); + if let (Some(target), Some(source)) = (d.get_mut(pos..end), bytes.get(..end - pos)) { + target.copy_from_slice(source); + } + let _ = write!(label, "put{w}{}[{pos}]={v:#x}", if be { "be" } else { "le" }); + } + 5 => { + let n = 1 + rng.below(16); + let end = (pos + n).min(d.len()); + d.drain(pos..end); + let _ = write!(label, "del[{pos}..{end}]"); + } + _ => { + d.truncate(pos); + let _ = write!(label, "trunc{pos}"); + } + } + } + Some(Mutation { bytes: d, label }) + } + + fn size_hint(&self) -> (usize, Option) { + (self.remaining, Some(self.remaining)) + } +} + +impl ExactSizeIterator for Mutations<'_> {} + +/// The settings of one [`hammer`] call: a label for its failures, the number of rounds, the +/// variable that multiplies them, and the limit for each case. +/// +/// ``` +/// use std::time::Duration; +/// use craft_testkit::hostile::HammerConfig; +/// +/// // 2,000 rounds, times CRAFT_HOSTILE_MULT when it is set; 5 s per case, or CRAFT_TEST_TIMEOUT_SECS. +/// let config = HammerConfig::new("png seed 3", 2_000); +/// +/// // The app's own variables instead. +/// let config = HammerConfig::new("mxf primer", 5_000) +/// .with_multiplier_variable("CRAFT_MEDIA_HOSTILE_MULT") +/// .with_timeout(craft_testkit::DeadlineLimit::new(Duration::from_secs(5)).with_variable("FILMCRAFT_HOSTILE_TIMEOUT_SECS")); +/// assert_eq!(config.multiplier_variable(), "CRAFT_MEDIA_HOSTILE_MULT"); +/// ``` +#[cfg(not(target_arch = "wasm32"))] +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct HammerConfig<'a> { + label: &'a str, + iterations: usize, + multiplier_variable: &'a str, + timeout: DeadlineLimit<'a>, +} + +#[cfg(not(target_arch = "wasm32"))] +impl<'a> HammerConfig<'a> { + /// `iterations` rounds of mutations under `label`, multiplied by [`DEFAULT_MULTIPLIER_VARIABLE`], + /// with a limit of [`DEFAULT_TIMEOUT`] for each case. + pub fn new(label: &'a str, iterations: usize) -> Self { + Self { label, iterations, multiplier_variable: DEFAULT_MULTIPLIER_VARIABLE, timeout: DeadlineLimit::new(DEFAULT_TIMEOUT) } + } + + /// The same settings, with the rounds multiplied by the variable `name` instead. + pub fn with_multiplier_variable(self, name: &'a str) -> Self { + Self { multiplier_variable: name, ..self } + } + + /// The same settings, with `limit` for each case. + pub fn with_timeout(self, limit: impl Into>) -> Self { + Self { timeout: limit.into(), ..self } + } + + /// The label that failures start with. + pub fn label(&self) -> &'a str { + self.label + } + + /// The rounds before the multiplier. + pub fn iterations(&self) -> usize { + self.iterations + } + + /// The name of the variable that multiplies the rounds. + pub fn multiplier_variable(&self) -> &'a str { + self.multiplier_variable + } + + /// The limit for each case. + pub fn timeout(&self) -> DeadlineLimit<'a> { + self.timeout + } + + /// The rounds after reading the multiplier variable, or why they cannot be used. + /// + /// When the variable is not set, the multiplier is 1. A value must be a whole number above + /// zero written in decimal digits. + pub fn rounds(&self) -> Result { + self.rounds_with(read_variable) + } + + /// [`Self::rounds`] with the variable lookup passed in. + fn rounds_with(&self, lookup: impl FnOnce(&str) -> Option) -> Result { + let variable = self.multiplier_variable.to_owned(); + if variable.is_empty() || variable.contains(['=', '\0']) { + return Err(HammerError::BadName { variable }); + } + let multiplier = match lookup(&variable) { + None => 1, + Some(raw) => { + let value = raw.into_string().map_err(|_| HammerError::NotUnicode { variable: variable.clone() })?; + parse_multiplier(&value).map_err(|reason| HammerError::BadValue { variable: variable.clone(), value, reason })? + } + }; + self.iterations.checked_mul(multiplier).ok_or(HammerError::Overflow { iterations: self.iterations, variable, multiplier }) + } +} + +/// Why a [`hammer`] call cannot run. +#[cfg(not(target_arch = "wasm32"))] +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum HammerError { + /// The multiplier variable's name is empty or holds `=` or a NUL character. + BadName { + /// The name. + variable: String, + }, + /// The multiplier variable's value is not Unicode. + NotUnicode { + /// The variable's name. + variable: String, + }, + /// The multiplier variable's value is not a whole number above zero. + BadValue { + /// The variable's name. + variable: String, + /// The value. + value: String, + /// What is wrong with the value. + reason: &'static str, + }, + /// The rounds times the multiplier is more than a `usize` holds. + Overflow { + /// The rounds before the multiplier. + iterations: usize, + /// The variable's name. + variable: String, + /// The multiplier. + multiplier: usize, + }, + /// The call would run more than [`MAX_CASES`] cases. + TooManyCases { + /// The cases the call would run. + cases: u128, + }, +} + +#[cfg(not(target_arch = "wasm32"))] +impl fmt::Display for HammerError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::BadName { variable } => write!(f, "{variable:?} cannot name a variable: it is empty or holds `=` or a NUL character"), + Self::NotUnicode { variable } => write!(f, "{variable} is not valid Unicode; set it to a whole number above zero"), + Self::BadValue { variable, value, reason } => write!(f, "{variable}={value:?} {reason}; set it to a whole number above zero"), + Self::Overflow { iterations, variable, multiplier } => { + write!(f, "{iterations} rounds times {variable}={multiplier} is more than a usize holds") + } + Self::TooManyCases { cases } => write!(f, "{cases} cases is more than the limit of {MAX_CASES}"), + } + } +} + +#[cfg(not(target_arch = "wasm32"))] +impl std::error::Error for HammerError {} + +/// Parses a whole number above zero, written as decimal digits only. +#[cfg(not(target_arch = "wasm32"))] +fn parse_multiplier(value: &str) -> Result { + if value.is_empty() { + return Err("is empty"); + } + if !value.bytes().all(|b| b.is_ascii_digit()) { + return Err("is not a whole number written in digits"); + } + match value.parse::() { + Ok(0) => Err("is zero"), + Ok(n) => Ok(n), + Err(_) => Err("is more than a usize holds"), + } +} + +/// Reads the variable `name` from the process environment. +#[cfg(not(target_arch = "wasm32"))] +fn read_variable(name: &str) -> Option { + std::env::var_os(name) +} + +/// Runs `parse` on `seed`, on every truncation of it (lengths 0 to one less than its length), and +/// on [`mutations`] of it for the config's rounds, failing the calling test on the first case +/// that panics or does not finish within the config's limit. +/// +/// The cases run one after another on one worker thread, while the calling thread fails the test +/// when a case runs past the config's limit. A case that finishes after the limit also fails it. A +/// failure starts with the config's label and names the case (`the unmodified seed`, +/// `truncation to N` or the mutation's edits), the input's length and the panic's message. A case +/// that does not finish fails the test while the worker thread is left running, so `parse` must be +/// owned and able to move to another thread. The multiplier and limit variables are read before +/// any case runs; a value that cannot be used, or a call that would run more than [`MAX_CASES`] +/// cases, fails the test before `parse` is called. +/// +/// ``` +/// use craft_testkit::hostile::{HammerConfig, hammer}; +/// +/// hammer(&HammerConfig::new("length prefix", 200), &[3, b'a', b'b', b'c'], |data| { +/// if let Some((&n, rest)) = data.split_first() { +/// let _ = rest.get(..usize::from(n)); +/// } +/// }); +/// ``` +// Failing the calling test is what this function is for. +#[cfg(not(target_arch = "wasm32"))] +#[allow(clippy::panic)] +#[track_caller] +pub fn hammer(config: &HammerConfig<'_>, seed: &[u8], parse: F) +where + F: Fn(&[u8]) + Send + Sync + 'static, +{ + if let Err(message) = hammer_with(config, seed, parse, read_variable) { + panic!("{message}"); + } +} + +/// [`hammer`] with the variable lookup passed in, returning the failure's message. +#[cfg(not(target_arch = "wasm32"))] +fn hammer_with(config: &HammerConfig<'_>, seed: &[u8], parse: F, lookup: impl Fn(&str) -> Option) -> Result<(), String> +where + F: Fn(&[u8]) + Send + Sync + 'static, +{ + let label = config.label; + let rounds = config.rounds_with(&lookup).map_err(|error| format!("{label}: {error}"))?; + let rounds = if seed.is_empty() { 0 } else { rounds }; + let cases = 1 + seed.len() as u128 + rounds as u128; + if cases > MAX_CASES as u128 { + return Err(format!("{label}: {}", HammerError::TooManyCases { cases })); + } + let start = Instant::now(); + let limit = resolve(&config.timeout, &lookup, start).map(Limit::from).map_err(|error| format!("{label}: {error}"))?; + let clock: Clock = Arc::new(move || start.elapsed()); + run_cases(label.to_owned(), limit, Arc::from(seed), rounds, parse, clock) +} + +/// A clock that returns the time since a [`hammer`] call started. +#[cfg(not(target_arch = "wasm32"))] +type Clock = Arc Duration + Send + Sync>; + +/// The limit for each case, and how failures describe it. +#[cfg(not(target_arch = "wasm32"))] +#[derive(Clone, Debug)] +struct Limit { + limit: Duration, + text: String, +} + +#[cfg(not(target_arch = "wasm32"))] +impl From> for Limit { + fn from(resolved: Resolved<'_>) -> Self { + Self { limit: resolved.limit, text: resolved.to_string() } + } +} + +/// The case the worker is running, shared with the calling thread that watches it. +#[cfg(not(target_arch = "wasm32"))] +struct Progress { + /// The case's description: `the unmodified seed`, `truncation to N` or the mutation's edits. + case: String, + /// The length of the case's input. + len: usize, + /// The clock reading when the case started. + started: Duration, + /// Whether the case is still running. + running: bool, + /// Set when the worker stops: `Ok` after the last case, or the failure's message. + outcome: Option>, +} + +/// [`Progress`] under a lock, with a signal for when the worker stops. +#[cfg(not(target_arch = "wasm32"))] +struct Watch { + state: Mutex, + stopped: Condvar, +} + +#[cfg(not(target_arch = "wasm32"))] +impl Watch { + fn lock(&self) -> MutexGuard<'_, Progress> { + self.state.lock().unwrap_or_else(PoisonError::into_inner) + } +} + +/// Hands the worker's outcome to the calling thread when the worker stops, including when it +/// unwinds outside a case. +#[cfg(not(target_arch = "wasm32"))] +struct Report { + watch: Arc, + outcome: Result<(), String>, +} + +#[cfg(not(target_arch = "wasm32"))] +impl Drop for Report { + fn drop(&mut self) { + let mut state = self.watch.lock(); + state.outcome = Some(std::mem::replace(&mut self.outcome, Ok(()))); + self.watch.stopped.notify_all(); + } +} + +/// Starts the worker that runs every case, then waits for it, failing when a case runs past the +/// limit. +#[cfg(not(target_arch = "wasm32"))] +fn run_cases(label: String, limit: Limit, seed: Arc<[u8]>, rounds: usize, parse: F, clock: Clock) -> Result<(), String> +where + F: Fn(&[u8]) + Send + Sync + 'static, +{ + // No case counts as running until the worker starts it, so a worker that starts late is not + // reported as a case past its limit. + let first = Progress { case: "the unmodified seed".to_owned(), len: seed.len(), started: clock(), running: false, outcome: None }; + let watch = Arc::new(Watch { state: Mutex::new(first), stopped: Condvar::new() }); + let (worker_watch, worker_clock, worker_label, worker_limit) = (Arc::clone(&watch), Arc::clone(&clock), label.clone(), limit.clone()); + thread::Builder::new() + .name(WORKER_NAME.to_owned()) + .spawn(move || { + let mut report = Report { watch: worker_watch, outcome: Err(format!("{worker_label}: the worker thread stopped without a result")) }; + report.outcome = run_all(&report.watch, &worker_clock, &worker_label, &worker_limit, &seed, rounds, &parse); + }) + .map_err(|error| format!("{label}: could not start the worker thread: {error}"))?; + let mut state = watch.lock(); + loop { + if let Some(outcome) = state.outcome.take() { + return outcome; + } + let deadline = state.started.saturating_add(limit.limit); + let now = clock(); + if state.running && now >= deadline { + return Err(format!("{label}: {} (len {}) did not finish within {}; its thread is left running", state.case, state.len, limit.text)); + } + let wait = if state.running { deadline.saturating_sub(now) } else { limit.limit }; + state = watch.stopped.wait_timeout(state, wait).unwrap_or_else(PoisonError::into_inner).0; + } +} + +/// Runs the unmodified seed, its truncations and its mutations in order, stopping at the first +/// failure. +#[cfg(not(target_arch = "wasm32"))] +fn run_all(watch: &Watch, clock: &Clock, label: &str, limit: &Limit, seed: &[u8], rounds: usize, parse: &F) -> Result<(), String> { + for n in std::iter::once(seed.len()).chain(0..seed.len()) { + let case = if n == seed.len() { "the unmodified seed".to_owned() } else { format!("truncation to {n}") }; + run_one(watch, clock, label, limit, case, seed.get(..n).unwrap_or_default(), parse)?; + } + for mutation in mutations(seed, rounds) { + run_one(watch, clock, label, limit, mutation.label, &mutation.bytes, parse)?; + } + Ok(()) +} + +/// Runs one case, recording it in `watch` while it runs, and returns the failure's message when it +/// panics or finishes after the limit. +#[cfg(not(target_arch = "wasm32"))] +fn run_one(watch: &Watch, clock: &Clock, label: &str, limit: &Limit, case: String, data: &[u8], parse: &F) -> Result<(), String> { + let started = clock(); + { + let mut state = watch.lock(); + (state.case, state.len, state.started, state.running) = (case, data.len(), started, true); + } + let outcome = catch_unwind(AssertUnwindSafe(|| parse(data))); + let spent = clock().saturating_sub(started); + // The payload is dropped before the lock is taken and while the case still counts as running, so + // the watchdog still reports a payload whose drop does not return. + let panicked = outcome.err().map(|payload| panic_text(payload.as_ref())); + let mut state = watch.lock(); + state.running = false; + let name = || format!("{label}: {} (len {})", state.case, state.len); + if spent > limit.limit { + let panicked = panicked.map_or_else(String::new, |text| format!(" (it panicked: {text})")); + return Err(format!("{} finished only after its limit of {}{panicked}", name(), limit.text)); + } + panicked.map_or(Ok(()), |text| Err(format!("{}: the parser panicked: {text}", name()))) +} + +/// The text of a panic payload. +#[cfg(not(target_arch = "wasm32"))] +fn panic_text(payload: &(dyn Any + Send)) -> String { + payload + .downcast_ref::() + .cloned() + .or_else(|| payload.downcast_ref::<&str>().map(|text| (*text).to_owned())) + .unwrap_or_else(|| "a payload that is not a message".to_owned()) +} + +#[cfg(test)] +#[cfg(not(target_arch = "wasm32"))] +mod tests { + use super::*; + use std::collections::BTreeMap; + use std::sync::Mutex; + use std::sync::mpsc; + + /// A variable no test sets, so the environment cannot change a test's rounds or limits. + const UNSET: &str = "CRAFT_TESTKIT_HOSTILE_UNSET_IN_TESTS"; + + fn config(label: &'static str, iterations: usize) -> HammerConfig<'static> { + HammerConfig::new(label, iterations) + .with_multiplier_variable(UNSET) + .with_timeout(DeadlineLimit::new(Duration::from_secs(600)).with_variable(UNSET)) + } + + fn unset(_: &str) -> Option { + None + } + + /// Runs `hammer_with` with no variables set and returns the inputs `parse` saw, in order. + fn inputs(config: &HammerConfig<'_>, seed: &[u8]) -> Vec> { + let seen = Arc::new(Mutex::new(Vec::new())); + let record = Arc::clone(&seen); + hammer_with(config, seed, move |d| record.lock().unwrap().push(d.to_vec()), unset).unwrap(); + seen.lock().unwrap().clone() + } + + #[test] + fn reports_truncation_panic_with_case_and_payload() { + let result = hammer_with(&config("demo seed 2", 0), &[9, 8, 7, 6], |d| assert!(d.len() != 2, "boom at {}", d.len()), unset); + let message = result.unwrap_err(); + assert!(message.starts_with("demo seed 2: truncation to 2 (len 2): the parser panicked: "), "{message}"); + assert!(message.contains("boom at 2"), "{message}"); + } + + #[test] + fn a_panic_without_a_message_is_reported() { + let message = hammer_with(&config("demo", 0), &[1], |_| std::panic::panic_any(7u8), unset).unwrap_err(); + assert_eq!(message, "demo: the unmodified seed (len 1): the parser panicked: a payload that is not a message"); + } + + #[test] + fn deadline_names_stuck_case() { + let (release, wait) = mpsc::channel::<()>(); + let wait = Mutex::new(wait); + let short = config("stuck demo", 0).with_timeout(DeadlineLimit::new(Duration::from_millis(50)).with_variable(UNSET)); + let result = hammer_with( + &short, + &[1, 2, 3], + move |d| { + if d.len() == 3 { + let _ = wait.lock().unwrap().recv(); + } + }, + unset, + ); + release.send(()).unwrap(); + let message = result.unwrap_err(); + assert!(message.contains("stuck demo: the unmodified seed (len 3) did not finish within 50ms"), "{message}"); + } + + #[test] + fn a_case_that_finishes_after_the_limit_fails() { + let readings = Arc::new(Mutex::new(vec![Duration::from_secs(6), Duration::ZERO])); + let clock: Clock = Arc::new(move || readings.lock().unwrap().pop().unwrap_or(Duration::MAX)); + let watch = Watch { + state: Mutex::new(Progress { case: String::new(), len: 0, started: Duration::ZERO, running: true, outcome: None }), + stopped: Condvar::new(), + }; + let limit = Limit { limit: Duration::from_secs(5), text: "5s".to_owned() }; + let message = run_one(&watch, &clock, "late", &limit, "the unmodified seed".to_owned(), &[1], &|_: &[u8]| {}).unwrap_err(); + assert_eq!(message, "late: the unmodified seed (len 1) finished only after its limit of 5s"); + assert!(!watch.lock().running); + } + + /// A panic payload that records, when it is dropped, whether the progress lock was free and + /// whether the case still counted as running. + struct DropProbe { + watch: Arc, + seen: Arc>>>, + } + + impl Drop for DropProbe { + fn drop(&mut self) { + let running = self.watch.state.try_lock().ok().map(|state| state.running); + *self.seen.lock().unwrap() = Some(running); + } + } + + #[test] + fn a_panic_payload_is_dropped_outside_the_lock_while_the_case_runs() { + let watch = Arc::new(Watch { + state: Mutex::new(Progress { case: String::new(), len: 0, started: Duration::ZERO, running: false, outcome: None }), + stopped: Condvar::new(), + }); + let seen = Arc::new(Mutex::new(None)); + let clock: Clock = Arc::new(|| Duration::ZERO); + let limit = Limit { limit: Duration::from_secs(5), text: "5s".to_owned() }; + let probe = (Arc::clone(&watch), Arc::clone(&seen)); + let parse = move |_: &[u8]| std::panic::panic_any(DropProbe { watch: Arc::clone(&probe.0), seen: Arc::clone(&probe.1) }); + let message = run_one(&watch, &clock, "probe", &limit, "the unmodified seed".to_owned(), &[1], &parse).unwrap_err(); + assert_eq!(message, "probe: the unmodified seed (len 1): the parser panicked: a payload that is not a message"); + assert_eq!(*seen.lock().unwrap(), Some(Some(true)), "the payload was dropped with the lock held or the case stopped"); + assert!(!watch.lock().running); + } + + #[test] + fn a_worker_that_starts_late_is_not_a_case_past_its_limit() { + // The worker's first clock reading waits until the calling thread has checked the limit once, + // and that check reads an hour after the start; every other reading is zero. + let (checked, worker_waits) = mpsc::channel::<()>(); + let (checked, worker_waits) = (Mutex::new(Some(checked)), Mutex::new(worker_waits)); + let caller_reads = Mutex::new(0usize); + let clock: Clock = Arc::new(move || { + if thread::current().name() == Some(WORKER_NAME) { + let _ = worker_waits.lock().unwrap().recv(); + return Duration::ZERO; + } + let mut reads = caller_reads.lock().unwrap(); + *reads += 1; + if *reads == 2 { + drop(checked.lock().unwrap().take()); + return Duration::from_secs(3600); + } + Duration::ZERO + }); + let limit = Limit { limit: Duration::from_secs(5), text: "5s".to_owned() }; + assert_eq!(run_cases("late start".to_owned(), limit, Arc::from(&[1u8][..]), 0, |_: &[u8]| {}, clock), Ok(())); + } + + #[test] + fn every_case_runs_on_one_worker_thread() { + let threads = Arc::new(Mutex::new(std::collections::BTreeSet::new())); + let record = Arc::clone(&threads); + let parse = move |_: &[u8]| { + record.lock().unwrap().insert(format!("{:?}", thread::current().id())); + }; + hammer_with(&config("one thread", 50), &[1, 2, 3, 4], parse, unset).unwrap(); + let threads = threads.lock().unwrap(); + assert_eq!(threads.len(), 1, "{threads:?}"); + assert!(!threads.contains(&format!("{:?}", thread::current().id()))); + } + + #[test] + fn invalid_limit_variable_fails_before_any_parse() { + let called = Arc::new(Mutex::new(false)); + let flag = Arc::clone(&called); + let config = config("bad limit", 3).with_timeout(DeadlineLimit::new(Duration::from_secs(5)).with_variable("MY_LIMIT")); + let lookup = |name: &str| (name == "MY_LIMIT").then(|| OsString::from("soon")); + let message = hammer_with(&config, &[1, 2], move |_| *flag.lock().unwrap() = true, lookup).unwrap_err(); + assert_eq!( + message, + r#"bad limit: MY_LIMIT="soon" is not a whole number of seconds written in digits; set it to a whole number of seconds above zero"# + ); + assert!(!*called.lock().unwrap()); + } + + #[test] + fn mutation_sequence_matches_source() { + let all: Vec<_> = mutations(&[0, 1, 2, 3], 4).collect(); + let bytes: Vec<&[u8]> = all.iter().map(|m| m.bytes.as_slice()).collect(); + let labels: Vec<&str> = all.iter().map(|m| m.label.as_str()).collect(); + assert_eq!(bytes, [&[0u8, 1, 2, 0][..], &[0, 1][..], &[0, 1, 0, 0][..], &[0, 0, 0, 1][..]]); + assert_eq!(labels, ["put1be[3]=0x0", "trunc2", "put4le[1]=0x1", "put4be[0]=0x1"]); + let mut expected: Vec> = vec![vec![0, 1, 2, 3], vec![], vec![0], vec![0, 1], vec![0, 1, 2]]; + expected.extend(all.into_iter().map(|m| m.bytes)); + assert_eq!(inputs(&config("sequence", 4), &[0, 1, 2, 3]), expected); + } + + #[test] + fn mutation_labels_join_edits_with_spaces() { + let seed: Vec = (0..64).collect(); + let joined = mutations(&seed, 200).find(|m| m.label.contains(' ')).unwrap(); + assert!(!joined.label.starts_with(' ') && !joined.label.ends_with(' ') && !joined.label.contains(" "), "{:?}", joined.label); + } + + #[test] + fn uses_caller_multiplier_variable() { + let config = config("mult", 7).with_multiplier_variable("CRAFT_MEDIA_HOSTILE_MULT"); + let lookup = |name: &str| match name { + "CRAFT_MEDIA_HOSTILE_MULT" => Some(OsString::from("3")), + DEFAULT_MULTIPLIER_VARIABLE => Some(OsString::from("100")), + _ => None, + }; + assert_eq!(config.rounds_with(lookup), Ok(21)); + let calls = Arc::new(Mutex::new(0usize)); + let count = Arc::clone(&calls); + hammer_with(&config, &[5, 6], move |_| *count.lock().unwrap() += 1, lookup).unwrap(); + // The seed, two truncations and 21 rounds. + assert_eq!(*calls.lock().unwrap(), 24); + assert_eq!(HammerConfig::new("default", 7).multiplier_variable(), "CRAFT_HOSTILE_MULT"); + assert_eq!(config.rounds_with(unset), Ok(7)); + } + + #[test] + fn invalid_multiplier_names_variable() { + for (value, reason) in [ + ("0", "is zero"), + ("", "is empty"), + ("ten", "is not a whole number written in digits"), + ("-2", "is not a whole number written in digits"), + ("1.5", "is not a whole number written in digits"), + ("99999999999999999999999999", "is more than a usize holds"), + ] { + let called = Arc::new(Mutex::new(false)); + let flag = Arc::clone(&called); + let message = hammer_with( + &config("bad mult", 3).with_multiplier_variable("MY_MULT"), + &[1, 2], + move |_| *flag.lock().unwrap() = true, + |_| Some(OsString::from(value)), + ) + .unwrap_err(); + assert_eq!(message, format!("bad mult: MY_MULT={value:?} {reason}; set it to a whole number above zero")); + assert!(!*called.lock().unwrap(), "parse ran before the bad value {value:?} was reported"); + } + for name in ["", "A=B", "A\0B"] { + assert_eq!(config("x", 1).with_multiplier_variable(name).rounds_with(unset), Err(HammerError::BadName { variable: name.to_owned() })); + } + } + + #[test] + fn empty_seed_runs_once() { + assert_eq!(inputs(&config("empty", 1_000), &[]), [Vec::::new()]); + } + + #[test] + fn large_seed_checks_every_prefix() { + let seed: Vec = (0..10_000u32).map(|i| i as u8).collect(); + let mut lengths = BTreeMap::new(); + for input in inputs(&config("large", 0), &seed) { + assert_eq!(input, seed[..input.len()]); + *lengths.entry(input.len()).or_insert(0usize) += 1; + } + assert_eq!(lengths.len(), 10_001); + assert!(lengths.values().all(|&n| n == 1), "a length ran more than once"); + } + + #[test] + fn iteration_product_overflow_is_error() { + let config = config("overflow", usize::MAX / 2 + 1); + let error = config.rounds_with(|_| Some(OsString::from("2"))).unwrap_err(); + assert_eq!(error, HammerError::Overflow { iterations: usize::MAX / 2 + 1, variable: UNSET.to_owned(), multiplier: 2 }); + let message = hammer_with(&config, &[1], |_| {}, |_| Some(OsString::from("2"))).unwrap_err(); + assert!(message.starts_with("overflow: ") && message.ends_with("is more than a usize holds"), "{message}"); + } + + #[test] + fn too_many_cases_fail_before_any_parse() { + let called = Arc::new(Mutex::new(false)); + let flag = Arc::clone(&called); + // The seed and its two truncations make three cases more. + let message = hammer_with(&config("budget", MAX_CASES - 2), &[1, 2], move |_| *flag.lock().unwrap() = true, unset).unwrap_err(); + assert_eq!(message, format!("budget: {} cases is more than the limit of {MAX_CASES}", MAX_CASES + 1)); + assert!(!*called.lock().unwrap()); + } + + #[test] + fn mutations_are_deterministic_and_count_rounds() { + let seed = b"a seed of some length"; + let first: Vec<_> = mutations(seed, 50).collect(); + assert_eq!(first.len(), 50); + assert_eq!(first, mutations(seed, 50).collect::>()); + assert_eq!(mutations(seed, 50).len(), 50); + assert_eq!(mutations(&[], 50).count(), 0); + } +} diff --git a/crates/testkit/src/lib.rs b/crates/testkit/src/lib.rs new file mode 100644 index 000000000..020938371 --- /dev/null +++ b/crates/testkit/src/lib.rs @@ -0,0 +1,48 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] + +//! Source-level platform regression guards and verification utilities for the Craft application suite. +//! +//! This crate provides non-panicking source analysis guards that detect known platform hazards +//! and lifecycle regressions across Craft applications: +//! +//! * [`guards::predefined_quit`]: flags direct calls to `muda`'s predefined Quit item that bypass +//! dirty document save prompts and window teardown on macOS. +//! * [`guards::wgsl_float_literals`]: flags WGSL float literals above the finite range of `f32` +//! (or of `f16` for an `h` suffix), which browser WebGPU compilers reject. +//! * [`guards::std_instant`]: flags uses of `std::time::Instant` in code paths targeting the web, +//! where `std::time::Instant::now()` panics on `wasm32`. +//! * [`guards::rust_sources`]: directory crawler collecting `.rs` sources while excluding tests, with +//! size limits ([`guards::rust_sources_with_limits`]). It is not built for `wasm32`. +//! +//! On targets other than `wasm32`, [`deadline::with_deadline`] runs a test body on its own thread +//! and fails the test when the body does not finish within its limit, and [`deadline::wait_until`] +//! polls a condition until it holds and fails the test when the limit passes first. Both read an +//! optional limit variable that the caller names, `CRAFT_TEST_TIMEOUT_SECS` by default. +//! +//! [`hostile::mutations`] yields a fixed sequence of damaged copies of a valid seed, on every +//! target. On targets other than `wasm32`, [`hostile::hammer`] runs a parser on the seed, every +//! truncation of it and those copies, one after another on a worker thread with a time limit for +//! each, and fails the test with the case that panicked or did not finish. +//! +//! ### Epistemic Scope: What Source Guards Establish vs What They Cannot +//! +//! Source-level guards provide deterministic syntactic evidence about codebase structure. +//! They establish that checked source files do not contain forbidden symbol names, known invalid +//! literal patterns, or unsafe platform invocations. +//! +//! They do **not** establish runtime correctness, protocol concurrency safety, or platform behavior +//! under foreign host environments. They are lightweight syntactic regression gates designed to complement, +//! rather than replace, platform integration tests and CI execution. + +#[cfg(not(target_arch = "wasm32"))] +pub mod deadline; +pub mod guards; +pub mod hostile; + +#[cfg(not(target_arch = "wasm32"))] +pub use deadline::{DeadlineLimit, wait_until, with_deadline}; +pub use guards::{AsFileSource, Finding, predefined_quit, std_instant, wgsl_float_literals, wgsl_float_literals_in}; + +#[cfg(not(target_arch = "wasm32"))] +pub use guards::{SourceLimits, rust_sources, rust_sources_with_limits}; diff --git a/crates/testkit/tests/guards.rs b/crates/testkit/tests/guards.rs new file mode 100644 index 000000000..64f54bfc5 --- /dev/null +++ b/crates/testkit/tests/guards.rs @@ -0,0 +1,1846 @@ +use craft_testkit::{Finding, predefined_quit, std_instant, wgsl_float_literals, wgsl_float_literals_in}; + +/// A scratch folder under the system temporary folder that this test made and removes on drop, +/// also when the test panics. A folder that already exists is never emptied or reused. +#[cfg(not(target_arch = "wasm32"))] +struct ScratchDir(std::path::PathBuf); + +#[cfg(not(target_arch = "wasm32"))] +impl ScratchDir { + fn new(tag: &str) -> Self { + let base = std::env::temp_dir(); + for n in 0..1000u32 { + let path = base.join(format!("craft_testkit_{tag}_{}_{n}", std::process::id())); + match std::fs::create_dir(&path) { + Ok(()) => return Self(path), + Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue, + Err(e) => panic!("create scratch folder {}: {e}", path.display()), + } + } + panic!("no free scratch folder name for {tag}"); + } + + fn path(&self) -> &std::path::Path { + &self.0 + } + + fn write(&self, relative: &str, content: &str) { + let path = self.0.join(relative); + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent).expect("create parent folder"); + } + std::fs::write(path, content).expect("write file"); + } +} + +#[cfg(not(target_arch = "wasm32"))] +impl Drop for ScratchDir { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +#[cfg(not(target_arch = "wasm32"))] +fn file_names(sources: &[(String, String)]) -> Vec { + sources.iter().map(|(p, _)| std::path::Path::new(p).file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default()).collect() +} + +fn lines(findings: &[Finding]) -> Vec { + findings.iter().map(|f| f.line).collect() +} + +#[test] +fn test_finding_display() { + let f1 = Finding::new("src/menu.rs", 42, "PredefinedMenuItem::quit()"); + assert_eq!(f1.to_string(), "src/menu.rs:42: PredefinedMenuItem::quit()"); + + let f2 = Finding::new("", 156, "3.40282347e38"); + assert_eq!(f2.to_string(), "156: 3.40282347e38"); +} + +#[test] +fn test_predefined_quit_positive() { + let source = r#" +fn setup_menu() { + let quit = PredefinedMenuItem::quit(Some("Quit")); + bar.add(quit); +} +"#; + let findings = predefined_quit([("src/menu.rs", source)]); + assert_eq!(findings.len(), 1); + assert_eq!(findings[0].path, "src/menu.rs"); + assert_eq!(findings[0].line, 3); + assert_eq!(findings[0].text, "let quit = PredefinedMenuItem::quit(Some(\"Quit\"));"); + assert_eq!(findings[0].to_string(), "src/menu.rs:3: let quit = PredefinedMenuItem::quit(Some(\"Quit\"));"); +} + +#[test] +fn test_predefined_quit_negative_and_comments() { + let source = r#" +// PredefinedMenuItem::quit(None) - do not use this! +/* + * PredefinedMenuItem::quit is hazardous + */ +fn setup_menu() { + let sep = PredefinedMenuItem::separator(); + let hide = PredefinedMenuItem::hide(Some("Hide")); + let note = "PredefinedMenuItem::quit in string should not trigger"; +} +"#; + let findings = predefined_quit([("src/safe_menu.rs", source)]); + assert!(findings.is_empty(), "expected zero findings for comments, separators, and strings: {findings:?}"); +} + +/// Historical failure: FilmCraft `apps/filmcraft/src/native_menu.rs:56` +/// used `PredefinedMenuItem::quit`, routing directly to `NSApplication terminate:` and bypassing save prompts. +#[test] +fn test_historical_filmcraft_native_menu_quit_regression() { + let problematic_source = r#" + let predefined = [ + (hide_label, PredefinedMenuItem::hide(Some(app.ui.language.tr(hide_label)))), + (hide_others_label, PredefinedMenuItem::hide_others(Some(app.ui.language.tr(hide_others_label)))), + (quit_label, PredefinedMenuItem::quit(Some(app.ui.language.tr(quit_label)))), + ]; +"#; + let findings = predefined_quit([("apps/filmcraft/src/native_menu.rs", problematic_source)]); + assert_eq!(findings.len(), 1); + assert_eq!(findings[0].line, 5); + assert_eq!(findings[0].text, "(quit_label, PredefinedMenuItem::quit(Some(app.ui.language.tr(quit_label)))),"); + + // Corrected source wires Quit via MenuItem::with_id and craft-quit lifecycle + let corrected_source = r#" + let quit = MenuItem::with_id("app.quit", label("app.quit", "Quit FilmCraft"), true, None); + let predefined = [ + (hide_label, PredefinedMenuItem::hide(Some(app.ui.language.tr(hide_label)))), + (hide_others_label, PredefinedMenuItem::hide_others(Some(app.ui.language.tr(hide_others_label)))), + ]; +"#; + let corrected_findings = predefined_quit([("apps/filmcraft/src/native_menu.rs", corrected_source)]); + assert!(corrected_findings.is_empty()); +} + +#[test] +fn test_std_instant_positive() { + let source = r#" +use std::time::Instant; +use std::time::{Duration, Instant as StdInstant}; + +fn measure() { + let t0 = std::time::Instant::now(); +} +"#; + let findings = std_instant([("src/clock.rs", source)]); + assert_eq!(findings.len(), 3); + assert_eq!(findings[0].line, 2); + assert_eq!(findings[1].line, 3); + assert_eq!(findings[2].line, 6); +} + +#[test] +fn test_std_instant_negative_and_web_time() { + let source = r#" +// std::time::Instant::now() causes wasm panic +/* + use std::time::Instant; +*/ +use web_time::Instant; +use std::time::Duration; + +fn measure() { + let t0 = web_time::Instant::now(); + let d = Duration::from_millis(100); +} +"#; + let findings = std_instant([("src/safe_clock.rs", source)]); + assert!(findings.is_empty(), "expected zero findings for web_time, duration, and comments: {findings:?}"); +} + +/// Historical failure: FilmCraft `crates/engine/src/wasm_clock_tests.rs` +/// jobs running synchronously on wasm32 called `std::time::Instant::now()`, panicking at runtime. +#[test] +fn test_historical_filmcraft_wasm_clock_instant_regression() { + let problematic_source = r#" + use std::time::Instant; + + pub fn run_job() { + let t0 = std::time::Instant::now(); + } +"#; + let findings = std_instant([("crates/engine/src/job.rs", problematic_source)]); + assert_eq!(findings.len(), 2); + + let corrected_source = r#" + use web_time::Instant; + + pub fn run_job() { + let t0 = web_time::Instant::now(); + } +"#; + let corrected_findings = std_instant([("crates/engine/src/job.rs", corrected_source)]); + assert!(corrected_findings.is_empty()); + + // User's specific conditional compilation test case: + let native_guarded_inline = r#" +#[cfg(not(target_arch = "wasm32"))] fn timestamp() -> std::time::Instant { std::time::Instant::now() } +"#; + assert!(std_instant([("src/native.rs", native_guarded_inline)]).is_empty()); + + let native_guarded_multiline = r#" +#[cfg(not(target_arch = "wasm32"))] +fn timestamp() -> std::time::Instant { + std::time::Instant::now() +} +"#; + assert!(std_instant([("src/native.rs", native_guarded_multiline)]).is_empty()); +} + +/// Historical failure: PhotoCraft PR #1722 / #1982 `crates/gpu/src/compose.wgsl:156` +/// `const F32_MAX: f32 = 3.40282347e38;` is slightly above f32::MAX. Naga rounds it natively, +/// but Chromium WebGPU compiler (Tint) rejects it, disabling the GPU compositor. +#[test] +fn test_historical_photocraft_compose_wgsl_regression() { + let problematic_shader = r#" +// line 156 of compose.wgsl +const F32_MAX: f32 = 3.40282347e38; +"#; + let findings = wgsl_float_literals(problematic_shader); + assert_eq!(findings.len(), 1); + assert_eq!(findings[0].line, 3); + assert_eq!(findings[0].text, "3.40282347e38"); + + // Corrected shader uses exact hexadecimal float representation + let corrected_shader = r#" +// exact f32::MAX bit for bit +const F32_MAX: f32 = 0x1.fffffep+127f; +"#; + let corrected_findings = wgsl_float_literals(corrected_shader); + assert!(corrected_findings.is_empty()); +} + +#[test] +fn test_wgsl_float_literals_controls() { + // 1. Scientific notation and signed values + let signed_and_sci = r#" +const OVER_POS: f32 = 1e39; +const OVER_NEG: f32 = -1e39; +const VALID_POS: f32 = 1.5e10; +const VALID_NEG: f32 = -1.5e10; +const VALID_TINY: f32 = 1e-40; +"#; + let findings = wgsl_float_literals(signed_and_sci); + assert_eq!(findings.len(), 2); + assert_eq!(findings[0].text, "1e39"); + assert_eq!(findings[1].text, "1e39"); // Scanned magnitude of -1e39 + + // 2. Hexadecimal floating-point representations + let hex_floats = r#" +const EXACT_MAX: f32 = 0x1.fffffep+127f; +const ONE_P0: f32 = 0x1.0p0; +const HALF_HEX: f32 = 0x1.0p-1h; +"#; + assert!(wgsl_float_literals(hex_floats).is_empty()); + + // 3. Literals appearing inside comments + let in_comments = r#" +// const F32_MAX = 3.40282347e38; +/* + const OVERFLOW = 1e40; +*/ +"#; + assert!(wgsl_float_literals(in_comments).is_empty()); + + // 4. Numeric suffixes (f, h) + let suffixes = r#" +const BAD_F: f32 = 3.40282347e38f; +const GOOD_F: f32 = 1.0f; +const GOOD_H: f16 = 0.5h; +"#; + let suffix_findings = wgsl_float_literals(suffixes); + assert_eq!(suffix_findings.len(), 1); + assert_eq!(suffix_findings[0].text, "3.40282347e38"); + + // 5. Embedded in identifiers or other tokens + let idents = r#" +let var_1 = 1.0; +let layer2 = 2.0; +let coord_0 = 0.0; +"#; + assert!(wgsl_float_literals(idents).is_empty()); +} + +#[test] +fn test_wgsl_float_literals_in_multiple_files() { + let s1 = "const A: f32 = 1.0;\nconst B: f32 = 3.40282347e38;\n"; + let s2 = "const OK: f32 = 0x1.fffffep+127f;\n"; + let s3 = "const BAD: f32 = 9.99e38;\n"; + + let files = [("shaders/compose.wgsl", s1), ("shaders/clean.wgsl", s2), ("shaders/fx.wgsl", s3)]; + let findings = wgsl_float_literals_in(files); + assert_eq!(findings.len(), 2); + assert_eq!(findings[0].path, "shaders/compose.wgsl"); + assert_eq!(findings[0].line, 2); + assert_eq!(findings[0].text, "3.40282347e38"); + assert_eq!(findings[1].path, "shaders/fx.wgsl"); + assert_eq!(findings[1].line, 1); + assert_eq!(findings[1].text, "9.99e38"); +} + +#[cfg(not(target_arch = "wasm32"))] +#[test] +fn test_predefined_quit_qualified_and_whitespace() { + let source = r#" +fn setup() { + let q1 = muda::PredefinedMenuItem::quit(None); + let q2 = PredefinedMenuItem :: quit(Some("Quit")); + let q3 = ::muda::PredefinedMenuItem::Quit; +} +"#; + let findings = predefined_quit([("src/menu.rs", source)]); + assert_eq!(findings.len(), 3); + assert_eq!(findings[0].line, 3); + assert_eq!(findings[1].line, 4); + assert_eq!(findings[2].line, 5); +} + +#[test] +fn test_std_instant_module_alias() { + let source = r#" +use std::time; + +fn run() { + let t0 = time::Instant::now(); +} +"#; + let findings = std_instant([("src/worker.rs", source)]); + assert_eq!(findings.len(), 1); + assert_eq!(findings[0].line, 5); +} + +#[test] +fn test_wgsl_exact_f32_max_boundary() { + // 3.4028234663852886e38 rounds to f32::MAX, as an f32 and as an f64 + let exact_valid = r#" +const EXACT_MAX: f32 = 3.4028234663852886e38; +const NEG_EXACT_MAX: f32 = -3.4028234663852886e38; +"#; + assert!(wgsl_float_literals(exact_valid).is_empty()); + + // 3.40282347e38 is slightly above f32::MAX + let just_over = r#" +const OVER_POS: f32 = 3.40282347e38; +const OVER_NEG: f32 = -3.40282347e38; +"#; + let findings = wgsl_float_literals(just_over); + assert_eq!(findings.len(), 2); + assert_eq!(findings[0].text, "3.40282347e38"); + assert_eq!(findings[1].text, "3.40282347e38"); +} + +#[test] +fn character_literals_do_not_hide_the_code_after_them() { + let source = r#" +fn menu<'a>(label: &'a str) { + let quote = '"'; + let quit = PredefinedMenuItem::quit(None); + let apostrophe = '\''; + let t0 = std::time::Instant::now(); + let b = b'"'; + let later = PredefinedMenuItem::quit(Some(label)); +} +"#; + assert_eq!(lines(&predefined_quit([("src/menu.rs", source)])), vec![4, 8]); + assert_eq!(lines(&std_instant([("src/menu.rs", source)])), vec![6]); +} + +#[test] +fn strings_hold_comment_markers_without_hiding_code() { + let source = r##" +fn menu() { + let a = "/* not a comment"; + let quit = PredefinedMenuItem::quit(None); + let b = b"// not a comment either"; + let c = r#"*/ " still a raw string"#; + let t0 = std::time::Instant::now(); + let d = "PredefinedMenuItem::quit std::time::Instant"; +} +"##; + assert_eq!(lines(&predefined_quit([("src/menu.rs", source)])), vec![4]); + assert_eq!(lines(&std_instant([("src/menu.rs", source)])), vec![7]); +} + +#[test] +fn nested_block_comments_stay_masked() { + let source = "/* outer /* inner */ PredefinedMenuItem::quit(None); std::time::Instant::now(); */\nlet q = PredefinedMenuItem::quit(None);\n"; + assert_eq!(lines(&predefined_quit([("src/menu.rs", source)])), vec![2]); + assert!(std_instant([("src/menu.rs", source)]).is_empty()); +} + +#[test] +fn predefined_quit_sees_tabs_and_line_breaks_around_the_path_separator() { + let source = "fn menu() {\n let a = PredefinedMenuItem\t::\tquit(None);\n let b = muda::PredefinedMenuItem\n ::quit(None);\n}\n"; + let findings = predefined_quit([("src/menu.rs", source)]); + assert_eq!(lines(&findings), vec![2, 3]); + assert_eq!(findings[1].text, "let b = muda::PredefinedMenuItem"); +} + +#[test] +fn predefined_quit_matches_whole_names_only() { + let other_names = r#" +fn menu() { + let a = MyPredefinedMenuItem::quit(None); + let b = PredefinedMenuItem::quitter(); + let c = PredefinedMenuItem::quit_label(); +} +"#; + assert!(predefined_quit([("src/menu.rs", other_names)]).is_empty()); + + let aliased = r#" +use muda::{PredefinedMenuItem as Item, MenuItem}; +fn menu() { + let a = Item::quit(None); + let b = other::Item::quit(None); +} +"#; + assert_eq!(lines(&predefined_quit([("src/menu.rs", aliased)])), vec![4]); + + let other_crate = r#" +use other_menu::PredefinedMenuItem as Item; +fn menu() { + let a = Item::quit(None); +} +"#; + assert!(predefined_quit([("src/menu.rs", other_crate)]).is_empty()); +} + +#[test] +fn predefined_quit_reports_a_qualified_path() { + let source = r#" +use muda::PredefinedMenuItem as Item; +fn menu() { + let a = ::quit(None); + let b = < PredefinedMenuItem >::quit(None); + let c = ::quit(None); + let d = Vec::::quit(None); + let e = Wrapper::quit(None); +} +"#; + assert_eq!(lines(&predefined_quit([("src/menu.rs", source)])), vec![4, 5, 6]); +} + +#[test] +fn predefined_quit_ignores_another_crates_type_in_a_qualified_path() { + let source = r#" +use other_menu::PredefinedMenuItem as Other; +fn menu() { + let a = other_crate::PredefinedMenuItem::quit(None); + let b = ::quit(None); + let c = crate::menu::PredefinedMenuItem::Quit; + let d = other::muda::PredefinedMenuItem::quit(None); + let e = ::PredefinedMenuItem::quit(None); + let f = Other::quit(None); + let g = muda::PredefinedMenuItem::quit(None); + let h = ::quit(None); + let i = PredefinedMenuItem::quit(None); +} +"#; + assert_eq!(lines(&predefined_quit([("src/menu.rs", source)])), vec![10, 11, 12]); +} + +#[test] +fn predefined_quit_ignores_a_muda_path_that_a_local_binding_of_muda_names() { + let source = r#" +use other_menu as muda; +fn menu() { + let a = muda::PredefinedMenuItem::quit(None); + let b = ::quit(None); + let c = ::muda::PredefinedMenuItem::quit(None); +} +mod inner { + use ::muda; + fn menu() { let d = muda::PredefinedMenuItem::quit(None); } +} +mod defined { + mod muda {} + fn menu() { let e = muda::PredefinedMenuItem::quit(None); } +} +mod gated { + #[cfg(unix)] + use other_menu as muda; + fn menu() { let f = muda::PredefinedMenuItem::quit(None); } +} +"#; + assert_eq!(lines(&predefined_quit([("src/menu.rs", source)])), vec![6, 10, 19]); +} + +#[test] +fn predefined_quit_ignores_a_rename_through_a_local_binding_of_muda() { + let source = r#" +use other_menu as muda; +use muda::PredefinedMenuItem as Item; +type Alias = muda::PredefinedMenuItem; +fn menu() { + let a = Item::quit(None); + let b = Alias::quit(None); +} +mod absolute { + use other_menu as muda; + use ::muda::PredefinedMenuItem as Item; + type Alias = ::muda::PredefinedMenuItem; + use ::{muda::PredefinedMenuItem as Grouped}; + fn menu() { let c = Item::quit(None); let d = Alias::quit(None); let e = Grouped::quit(None); } +} +mod crate_root { + use muda::PredefinedMenuItem as Item; + type Alias = muda::PredefinedMenuItem; + fn menu() { let f = Item::quit(None); let g = Alias::quit(None); } +} +"#; + assert_eq!(lines(&predefined_quit([("src/menu.rs", source)])), vec![14, 19]); +} + +#[test] +fn predefined_quit_follows_a_name_that_the_muda_crate_is_imported_under() { + let source = r#" +use muda as menu; +fn menu_bar() { + let a = menu::PredefinedMenuItem::quit(None); + let b = ::quit(None); + let c = ::menu::PredefinedMenuItem::quit(None); +} +mod grouped { + use muda::{self as m}; + fn menu_bar() { let d = m::PredefinedMenuItem::quit(None); } +} +mod renamed { + extern crate muda as native; + type Item = native::PredefinedMenuItem; + fn menu_bar() { let e = native::PredefinedMenuItem::quit(None); let f = Item::quit(None); } +} +mod imported { + use muda::{self as m}; + use m::PredefinedMenuItem as Quit; + fn menu_bar() { let g = Quit::quit(None); } +} +mod unbound { + fn menu_bar() { let h = m::PredefinedMenuItem::quit(None); } +} +mod shadowed { + use other_menu as menu; + fn menu_bar() { let i = menu::PredefinedMenuItem::quit(None); } +} +"#; + assert_eq!(lines(&predefined_quit([("src/menu.rs", source)])), vec![4, 5, 10, 15, 20]); +} + +#[test] +fn predefined_quit_reads_a_crate_name_in_an_import_where_the_import_is() { + let source = r#" +mod native { + use muda as menu; + use menu::PredefinedMenuItem as Item; + type Alias = menu::PredefinedMenuItem; + fn menu_bar() { let a = Item::quit(None); let b = Alias::quit(None); } +} +mod other { + use other_menu as menu; + use menu::PredefinedMenuItem as Item; + type Alias = menu::PredefinedMenuItem; + fn menu_bar() { let c = Item::quit(None); let d = Alias::quit(None); } +} +mod external { + use muda as menu; + use ::menu::PredefinedMenuItem as Item; + type Alias = ::menu::PredefinedMenuItem; + fn menu_bar() { let e = Item::quit(None); let f = Alias::quit(None); } +} +mod grouped { + use muda as menu; + use {::menu::PredefinedMenuItem as Item}; + fn menu_bar() { let g = Item::quit(None); } +} +mod shadowed { + use muda as menu; + fn menu_bar() { + extern crate other_menu as menu; + let h = menu::PredefinedMenuItem::quit(None); + } +} +mod renamed_module { + use other_menu as muda; + use muda as menu; + fn menu_bar() { let i = menu::PredefinedMenuItem::quit(None); } +} +mod renamed_crate { + mod muda {} + use ::muda as menu; + fn menu_bar() { let j = menu::PredefinedMenuItem::quit(None); } +} +"#; + assert_eq!(lines(&predefined_quit([("src/menu.rs", source)])), vec![6, 40]); +} + +#[test] +fn predefined_quit_ignores_a_bare_name_that_another_import_or_a_local_type_binds_in_its_scope() { + let imported = r#" +use other_menu::PredefinedMenuItem; +fn menu() { + let a = PredefinedMenuItem::quit(None); + let b = muda::PredefinedMenuItem::quit(None); +} +"#; + let grouped = "use other_menu::{PredefinedMenuItem, Menu};\nfn menu() { let a = PredefinedMenuItem::quit(None); }\n"; + let local = r#" +struct PredefinedMenuItem; +fn menu() { + let a = PredefinedMenuItem::quit(None); + let b = ::quit(None); +} +"#; + let both = r#" +use muda::PredefinedMenuItem; +mod other { pub struct PredefinedMenuItem; } +fn menu() { + let a = PredefinedMenuItem::quit(None); +} +"#; + let scoped = r#" +use muda::*; +mod other { + use other_menu::PredefinedMenuItem; + fn menu() { let a = PredefinedMenuItem::quit(None); } +} +mod local { struct PredefinedMenuItem; fn menu() { let b = PredefinedMenuItem::quit(None); } } +fn menu() { + let c = PredefinedMenuItem::quit(None); + { use other_menu::PredefinedMenuItem; let d = PredefinedMenuItem::quit(None); } + let e = PredefinedMenuItem::quit(None); +} +"#; + assert_eq!(lines(&predefined_quit([("src/imported.rs", imported)])), vec![5]); + assert!(predefined_quit([("src/grouped.rs", grouped)]).is_empty()); + assert!(predefined_quit([("src/local.rs", local)]).is_empty()); + assert_eq!(lines(&predefined_quit([("src/both.rs", both)])), vec![5]); + assert_eq!(lines(&predefined_quit([("src/scoped.rs", scoped)])), vec![9, 11]); + let child = r#" +use other_menu::PredefinedMenuItem; +mod child { + use muda::*; + fn menu() { let a = PredefinedMenuItem::quit(None); } +} +fn menu() { let b = PredefinedMenuItem::quit(None); } +"#; + assert_eq!(lines(&predefined_quit([("src/child.rs", child)])), vec![5]); + let renamed = r#" +mod a { + use muda::PredefinedMenuItem as Item; + fn menu() { let a = Item::quit(None); } +} +mod b { + struct Item; + fn menu() { let b = Item::quit(None); } +} +mod c { fn menu() { let c = Item::quit(None); } } +mod d { type Quit = muda::PredefinedMenuItem; fn menu() { let d = Quit::quit(None); } } +"#; + assert_eq!(lines(&predefined_quit([("src/renamed.rs", renamed)])), vec![4, 11]); + let aliased_or_gated = r#" +mod alias { + type PredefinedMenuItem = ::muda::PredefinedMenuItem; + fn menu() { let a = PredefinedMenuItem::quit(None); } +} +mod gated { + use muda::*; + #[cfg(windows)] + struct PredefinedMenuItem; + #[cfg(windows)] use other_menu::PredefinedMenuItem; + fn menu() { let b = PredefinedMenuItem::quit(None); } +} +mod other { type PredefinedMenuItem = other_menu::PredefinedMenuItem; fn menu() { let c = PredefinedMenuItem::quit(None); } } +mod assoc { + use muda::PredefinedMenuItem; + trait Menu { type PredefinedMenuItem; fn menu() { let d = PredefinedMenuItem::quit(None); } } + #[allow(dead_code)] unsafe impl Menu for Wrap<{ N }> { + fn menu() { let e = PredefinedMenuItem::quit(None); } + type PredefinedMenuItem = u8; + } +} +mod reexported { + use crate::PredefinedMenuItem; + fn menu() { let f = PredefinedMenuItem::quit(None); } + mod inner { use super::super::{self as up, PredefinedMenuItem}; fn menu() { let g = PredefinedMenuItem::quit(None); } } + mod aliased { type PredefinedMenuItem = crate::menu::PredefinedMenuItem; fn menu() { let h = PredefinedMenuItem::quit(None); } } +} +"#; + assert_eq!(lines(&predefined_quit([("src/aliased.rs", aliased_or_gated)])), vec![4, 11, 16, 18, 24, 25, 26]); +} + +#[test] +fn std_instant_reads_a_std_time_alias_only_in_its_scope() { + let source = r#" +mod native { + use std::time as clock; + fn now() { let a = clock::Instant::now(); } + use clock::Instant as A; +} +mod web { + use web_time as clock; + fn now() { let b = clock::Instant::now(); } + use clock::Instant as B; + use {clock::*, std::time::*}; +} +mod child { fn now() { let c = clock::Instant::now(); } } +fn run() { + use std::time as t; + let d = t::Instant::now(); + { mod t {} let e = t::Instant::now(); } +} +"#; + assert_eq!(lines(&std_instant([("src/lib.rs", source)])), vec![4, 5, 11, 16]); +} + +#[test] +fn std_instant_keeps_an_alias_that_a_cfg_gated_import_may_shadow() { + let source = r#" +use std::time as clock; +fn now() { + #[cfg(feature = "web-clock")] + use web_time as clock; + let a = clock::Instant::now(); +} +fn gated() { + #[cfg(feature = "web-clock")] + mod clock {} + let b = clock::Instant::now(); +} +#[cfg(feature = "web-clock")] +fn web() { + use web_time as clock; + let c = clock::Instant::now(); +} +fn wasm() { + #[cfg(target_arch = "wasm32")] + use web_time as clock; + let d = clock::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/lib.rs", source)])), vec![6, 11]); +} + +#[test] +fn std_instant_ignores_an_alias_that_only_a_native_cfg_imports() { + let source = r#" +#[cfg(not(target_arch = "wasm32"))] +use std::time as clock; +#[cfg(target_arch = "wasm32")] +use web_time as clock; + +fn now() { + let t = clock::Instant::now(); +} +"#; + assert!(std_instant([("src/clock.rs", source)]).is_empty()); +} + +#[test] +fn std_instant_reads_cfg_from_code_not_from_strings_or_comments() { + let cfg_in_string = r##" +fn now() -> u64 { let _s = r#"cfg(target_os = "linux")"#; + let t = std::time::Instant::now(); + 0 +} +"##; + assert_eq!(lines(&std_instant([("src/a.rs", cfg_in_string)])), vec![3]); + + let cfg_in_comment = r#" +fn web() { // cfg(target_os = "linux") + let t = std::time::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/b.rs", cfg_in_comment)])), vec![3]); +} + +#[test] +fn std_instant_skips_only_the_item_a_native_cfg_covers() { + let source = r#" +#[cfg(not(target_arch = "wasm32"))] +fn native() -> std::time::Instant { std::time::Instant::now() } +fn web() -> std::time::Instant { std::time::Instant::now() } + +#[cfg(all(unix, not(target_arch = "wasm32")))] +#[inline] +fn unix_only() { + let t = std::time::Instant::now(); +} + +#[cfg(feature = "native-clock")] +fn by_feature() { let t = std::time::Instant::now(); } + +#[cfg(any(target_arch = "wasm32", windows))] +fn also_web() { let t = std::time::Instant::now(); } + +#[cfg(target_os = "unknown")] +fn unknown_os() { let t = std::time::Instant::now(); } + +#[cfg(target_os = "macos")] +use std::time::Instant as MacInstant; +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![4, 13, 16, 19]); +} + +#[test] +fn std_instant_decodes_escapes_in_cfg_values() { + let source = r#" +#[cfg(target_arch = "\x77asm32")] +fn web() { let t = std::time::Instant::now(); } +#[cfg(target_arch = "w\u{61}sm32")] +fn web_two() { let t = std::time::Instant::now(); } +#[cfg(target_arch = r"\x77asm32")] +fn native() { let t = std::time::Instant::now(); } +#[cfg(not(target_arch = "\q"))] +fn unknown() { let t = std::time::Instant::now(); } +#[cfg(target_os = "lin\ + ux")] +fn native_two() { let t = std::time::Instant::now(); } +fn after() { let t = std::time::Instant::now(); } +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![3, 5, 9, 13]); +} + +#[test] +fn std_instant_reads_cfg_true_and_false() { + let source = r#" +#[cfg(false)] +fn disabled() { let t = std::time::Instant::now(); } +#[cfg(true)] +fn enabled() { let t = std::time::Instant::now(); } +#[cfg(not(true))] +fn never() { let t = std::time::Instant::now(); } +#[cfg(r#false)] +fn named_option() { let t = std::time::Instant::now(); } +#[cfg(not(r#true))] +fn other_option() { let t = std::time::Instant::now(); } +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![5, 9, 11]); +} + +#[test] +fn std_instant_checks_an_item_whose_cfg_is_nested_past_the_limit() { + let source = format!( + "#[cfg({}target_arch = \"wasm32\"{})]\nfn web() {{ let t = std::time::Instant::now(); }}\n#[cfg({}unix{})]\nfn native() {{ let t = std::time::Instant::now(); }}\n", + "any(".repeat(65), + ")".repeat(65), + "all(".repeat(10), + ")".repeat(10), + ); + assert_eq!(lines(&std_instant([("src/clock.rs", source.as_str())])), vec![2]); +} + +#[test] +fn std_instant_checks_the_fields_after_a_native_cfg_function_pointer_field() { + let source = r#" +struct S { + #[cfg(unix)] + callback: fn(), + clock: std::time::Instant, + #[cfg(unix)] + native: fn() -> std::time::Instant, + #[cfg(unix)] + pub(crate) boxed: Box, + other: std::time::Instant, +} +fn run() { + #[cfg(unix)] + 'outer: loop { let _a = std::time::Instant::now(); } + let t = std::time::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![5, 10, 15]); +} + +#[test] +fn std_instant_ends_a_native_cfg_block_statement_at_its_closing_brace() { + let source = r#" +fn run() { + #[cfg(unix)] { + let _a = std::time::Instant::now(); + } + let t = std::time::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![6]); +} + +#[test] +fn std_instant_skips_a_method_call_after_a_native_cfg_block() { + let source = r#" +fn run(x: Option) -> Option { + #[cfg(unix)] + { 0u64 }.saturating_add(std::time::Instant::now().elapsed().as_nanos() as u64); + #[cfg(unix)] + unsafe { x }.map(|_| std::time::Instant::now())?; + let t = std::time::Instant::now(); + x +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![7]); +} + +#[test] +fn std_instant_skips_an_operator_after_a_block_inside_a_native_cfg_expression() { + let source = r#" +fn run(flag: bool) -> u64 { + #[cfg(unix)] + let _ = if flag { 1 } else { 2 } + std::time::Instant::now().elapsed().as_secs(); + #[cfg(unix)] + return if flag { 1 } else { 2 } * std::time::Instant::now().elapsed().as_secs(); + let t = std::time::Instant::now(); + 0 +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![7]); +} + +#[test] +fn std_instant_skips_a_cast_after_a_match_inside_a_native_cfg_expression() { + let source = r#" +fn run(x: Option) -> u64 { + #[cfg(unix)] + let n = match x { Some(v) => v, None => 0 } as u64 + std::time::Instant::now().elapsed().as_secs(); + let t = std::time::Instant::now(); + 0 +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![5]); +} + +#[test] +fn std_instant_runs_a_native_cfg_match_arm_to_its_comma_when_a_block_is_inside_its_value() { + let source = r#" +fn run(x: Option, y: bool) -> u64 { + match x { + #[cfg(unix)] + Some(v) => v as u64 + match y { true => 1, false => 0 } + std::time::Instant::now().elapsed().as_secs(), + #[cfg(unix)] + None => if y { 1 } else { 0 }, + #[cfg(unix)] Some(0) => { 0 } _ => std::time::Instant::now().elapsed().as_secs(), + } +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![8]); +} + +#[test] +fn std_instant_ends_a_native_cfg_const_or_labeled_block_at_its_closing_brace() { + let source = r#" +fn run(x: Option) -> u64 { + #[cfg(unix)] + const { assert!(true) } + let a = std::time::Instant::now(); + #[cfg(unix)] + 'done: { let _ = std::time::Instant::now(); break 'done; } + let b = std::time::Instant::now(); + match x { + #[cfg(unix)] + Some(_) => 'arm: { let _ = std::time::Instant::now(); break 'arm; } + _ => { let c = std::time::Instant::now(); } + } + 0 +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![5, 8, 12]); +} + +#[test] +fn std_instant_ends_a_native_cfg_if_let_at_its_body_not_at_a_struct_pattern() { + let source = r#" +enum State { Ready { at: u64 }, Idle } +fn run(state: State, other: State) { + #[cfg(unix)] + if let State::Ready { .. } = state { let _a = std::time::Instant::now(); } + let b = std::time::Instant::now(); + #[cfg(unix)] + while let State::Ready { at } = other { let _c = std::time::Instant::now(); } + let d = std::time::Instant::now(); + #[cfg(unix)] + if let State::Idle = state { 0 } else if let State::Ready { at: 0..=9 } = state { let _e = std::time::Instant::now(); } else { let _f = std::time::Instant::now(); } + let g = std::time::Instant::now(); + #[cfg(unix)] + if let State::Ready { .. } = state && let State::Ready { at } = other { let _h = std::time::Instant::now(); } + let i = std::time::Instant::now(); + #[cfg(unix)] + for State::Ready { at } in [state] { let _j = std::time::Instant::now(); } + let k = std::time::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![6, 9, 12, 15, 18]); +} + +#[test] +fn std_instant_ends_a_native_cfg_if_at_its_body_not_at_a_block_in_its_condition() { + let source = r#" +fn run(ready: bool, items: Vec) { + #[cfg(unix)] + if { ready } { let _a = std::time::Instant::now(); } + let b = std::time::Instant::now(); + #[cfg(unix)] + while !{ ready } { let _c = std::time::Instant::now(); } + let d = std::time::Instant::now(); + #[cfg(unix)] + if ready && unsafe { check() } { let _e = std::time::Instant::now(); } + let f = std::time::Instant::now(); + #[cfg(unix)] + for item in { items } { let _g = std::time::Instant::now(); } + let h = std::time::Instant::now(); + #[cfg(unix)] + match { 1 } { _ => { let _i = std::time::Instant::now(); } } + let j = std::time::Instant::now(); + #[cfg(unix)] + if let true = { ready } { let _k = std::time::Instant::now(); } + let l = std::time::Instant::now(); + #[cfg(unix)] + if loop { break ready } { let _m = std::time::Instant::now(); } + let n = std::time::Instant::now(); + #[cfg(unix)] + if async move { ready }.await { let _o = std::time::Instant::now(); } + let p = std::time::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![5, 8, 11, 14, 17, 20, 23, 26]); +} + +#[test] +fn std_instant_ends_a_native_cfg_let_else_and_match_with_struct_patterns_where_they_end() { + let source = r#" +enum State { Ready { at: u64 }, Idle } +fn run(state: State, other: State) -> u64 { + #[cfg(unix)] + let State::Ready { at } = state else { let _a = std::time::Instant::now(); return 0; }; + let b = std::time::Instant::now(); + #[cfg(unix)] + match other { State::Ready { at } => { let _c = std::time::Instant::now(); } State::Idle => {} } + let d = std::time::Instant::now(); + match state { + #[cfg(unix)] + State::Ready { at } => if let State::Ready { .. } = other { let _e = std::time::Instant::now(); }, + _ => { let f = std::time::Instant::now(); } + } + 0 +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![6, 9, 13]); +} + +#[test] +fn std_instant_reads_raw_identifiers_as_names_not_keywords() { + let source = r#" +fn run(r#let: bool, r#in: [u8; 1]) { + #[cfg(unix)] + if r#let { let _a = std::time::Instant::now(); } + let b = std::time::Instant::now(); + #[cfg(unix)] + for x in r#in { let _c = std::time::Instant::now(); } + let d = std::time::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![5, 8]); + + let lib = "#[cfg(unix)]\nmod r#match;\nmod r#loop;\n"; + let native = "use std::time::Instant;\n"; + let web = "use std::time::Instant;\n"; + assert_eq!(finding_paths(&std_instant([("src/lib.rs", lib), ("src/match.rs", native), ("src/loop.rs", web)])), vec!["src/loop.rs"]); +} + +#[test] +fn std_instant_runs_a_native_cfg_async_block_statement_to_its_semicolon() { + let source = r#" +async fn run() { + #[cfg(unix)] + async { std::time::Instant::now() } + .await; + #[cfg(unix)] + async move { std::time::Instant::now() }; + let a = std::time::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![8]); +} + +#[test] +fn std_instant_checks_code_before_and_after_a_native_cfg_item_on_the_same_line() { + let source = "fn run() { + let a = std::time::Instant::now(); #[cfg(unix)] let b = std::time::Instant::now(); let c = std::time::Instant::now(); + let d = 1; #[cfg(unix)] let e = std::time::Instant::now(); + #[cfg(unix)] let f = std::time::Instant::now(); let g = std::time::Instant::now(); +} +"; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![2, 4]); +} + +#[test] +fn std_instant_checks_an_item_after_a_native_cfg_item_on_the_same_line() { + let source = r#"#[cfg(target_os="linux")] fn native() {} fn web() { std::time::Instant::now(); } +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![1]); +} + +#[test] +fn std_instant_skips_gated_code_that_follows_a_native_cfg_item_on_the_same_line() { + let source = r#"#[cfg(target_os = "linux")] fn a() {} #[cfg(target_os = "macos")] fn b() { std::time::Instant::now(); } +#[cfg(unix)] fn c() {} #[cfg(windows)] use std::time::Instant as Native; +"#; + assert!(std_instant([("src/clock.rs", source)]).is_empty()); +} + +#[test] +fn std_instant_ends_native_cfg_impl_mod_and_struct_items_where_they_end_on_the_line() { + let source = r#"struct S; #[cfg(unix)] impl S { fn now() { std::time::Instant::now(); } } fn web() { std::time::Instant::now(); } +#[cfg(unix)] mod native { fn now() { std::time::Instant::now(); } } fn web_two() { std::time::Instant::now(); } +#[cfg(unix)] struct P { at: std::time::Instant } struct Q { at: std::time::Instant } +#[cfg(unix)] struct T(std::time::Instant); struct U(std::time::Instant); +#[cfg(unix)] impl S { fn a() {} } #[cfg(unix)] mod m { fn b() { std::time::Instant::now(); } } +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![1, 2, 3, 4]); +} + +#[test] +fn std_instant_reads_blocks_in_generic_brackets_as_part_of_a_native_cfg_item_head() { + let source = r#"#[cfg(unix)] struct Native { clock: std::time::Instant } +#[cfg(unix)] enum E { A(std::time::Instant) } +#[cfg(unix)] trait Tr: Sized where Self: Into> { fn now() -> std::time::Instant { std::time::Instant::now() } } +#[cfg(unix)] impl Tr<{ N }> for Native<{ N }> { fn now() -> std::time::Instant { std::time::Instant::now() } } +#[cfg(unix)] fn native() -> W<{ 1 + 1 }> where T: Into> { std::time::Instant::now(); W } +#[cfg(unix)] fn arrow u8>(f: F) -> impl Fn() -> W<{ 3 }> where F: Copy { let _t = std::time::Instant::now(); f } +struct Web { clock: std::time::Instant } +fn web() -> W<{ 1 }> where u8: Into> { std::time::Instant::now(); W } +#[cfg(unix)] struct A { a: std::time::Instant } fn after() { std::time::Instant::now(); } +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![7, 8, 9]); +} + +#[test] +fn std_instant_reads_paths_split_over_lines_and_comments_with_crlf() { + let source = "use std::time::\r\n Instant;\r\nfn run() {\r\n let t = std::time\r\n ::Instant::now();\r\n let u = std /* a */ :: time // b\r\n :: Instant::now();\r\n}\r\n"; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![1, 4, 6]); +} + +#[test] +fn std_instant_reports_a_use_on_the_line_where_its_path_starts() { + let source = "use std::time::\n Instant as Clock;\nuse std::time::{\n Duration,\n Instant,\n};\nuse std::\n time::*;\n"; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![1, 5, 7]); +} + +#[test] +fn std_instant_ignores_other_time_modules_longer_names_and_a_renamed_duration() { + let source = r#" +use tokio::time::Instant; +use std::time::{Duration as Instant}; +fn run() { + let a = my_time::Instant::now(); + let b = runtime::Instant::now(); + let c = crate::time::Instant::now(); + let d = tokio::time::Instant::now(); + let e = core::time::Instant::now(); + let f = std::time::InstantLike::now(); + let g = mystd::time::Instant::now(); + let h = std::time::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![12]); +} + +#[test] +fn std_instant_ignores_paths_in_literals_and_comments_and_reads_labels_as_code() { + let source = r##" +fn run<'a>(s: &'a str) -> char { + let _x = "std::time::Instant"; let _r = r#"std::time::Instant"#; let _b = b"std::time::Instant"; let _c = c"std::time::Instant"; + // std::time::Instant + /* std::time::Instant */ + 'outer: loop { break 'outer; } + let q = '"'; let t = std::time::Instant::now(); + 'x' +} +"##; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![7]); +} + +#[test] +fn std_instant_scans_a_large_source_once() { + let mut source = String::from("fn run() {\n"); + for i in 0..20_000 { + if i % 2 == 0 { + source.push_str(" #[cfg(unix)] let a = std::time::Instant::now();\n"); + } else { + source.push_str(" let b = std::time::Instant::now();\n"); + } + } + source.push_str("}\n"); + let found = lines(&std_instant([("src/run.rs", source.as_str())])); + assert_eq!(found.len(), 10_000); + assert_eq!(found.first(), Some(&3)); + assert_eq!(found.last(), Some(&20_001)); +} + +#[test] +fn std_instant_inner_cfg_covers_the_whole_file() { + let source = r#" +#![cfg(not(target_arch = "wasm32"))] +use std::time::Instant; + +fn now() -> Instant { + std::time::Instant::now() +} +"#; + assert!(std_instant([("src/native.rs", source)]).is_empty()); +} + +#[test] +fn std_instant_reports_a_std_use_on_a_line_that_also_names_web_time() { + let source = "fn pair() {\n let p = (web_time::Instant::now(), std::time::Instant::now());\n}\n"; + assert_eq!(lines(&std_instant([("src/pair.rs", source)])), vec![2]); +} + +#[test] +fn std_instant_needs_std_behind_a_bare_time_path() { + let source = r#" +use crate::time; + +fn tick() { + let t = time::Instant::new(); +} +"#; + assert!(std_instant([("src/tick.rs", source)]).is_empty()); +} + +#[test] +fn std_instant_follows_module_and_type_aliases() { + let source = r#" +use std::time as t; +use std::time::{self as clock, Duration}; +use std::{time::Instant as I, fmt}; +use web_time as wt; + +fn run() { + let a = t::Instant::now(); + let b = clock::Instant::now(); + let c = wt::Instant::now(); + let d = x::t::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/run.rs", source)])), vec![4, 8, 9]); +} + +#[test] +fn std_instant_reads_a_use_group_split_over_several_lines() { + let source = r#" +use std::time::{ + Instant +}; +use std::time::{ + Duration, + Instant as Clock, +}; +"#; + let findings = std_instant([("src/clock.rs", source)]); + assert_eq!(lines(&findings), vec![3, 7]); + assert_eq!(findings[0].text, "Instant"); +} + +#[test] +fn std_instant_reads_a_use_after_a_precise_capturing_bound() { + let source = "fn clock() -> impl Fn() + use<> {\n use std::{time::Instant};\n || { let _ = Instant::now(); }\n}\n"; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![2]); +} + +#[test] +fn std_instant_does_not_count_brace_character_literals_as_braces() { + let source = r#" +#[cfg(unix)] +fn native() { let open = '{'; let b = b'{'; let t = std::time::Instant::now(); } +fn web() { let close = '}'; let t = std::time::Instant::now(); } +#[cfg(unix)] +fn native_two() { let close = '}'; let t = std::time::Instant::now(); } +fn web_two() { let t = std::time::Instant::now(); } +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![4, 7]); +} + +#[test] +fn an_escaped_line_break_in_a_string_keeps_line_numbers() { + let source = + "fn web() {\n let s = \"one \\\n two\";\n let t = std::time::Instant::now();\n let q = PredefinedMenuItem::quit(None);\n}\n"; + assert_eq!(lines(&std_instant([("src/web.rs", source)])), vec![4]); + assert_eq!(lines(&predefined_quit([("src/web.rs", source)])), vec![5]); +} + +#[test] +fn deeply_nested_use_groups_and_cfg_predicates_do_not_exhaust_the_stack() { + let depth = 100_000; + let use_groups = format!("use std::time::{}Instant{};\nfn f() {{}}\n", "{".repeat(depth), "}".repeat(depth)); + assert!(std_instant([("src/deep.rs", use_groups.as_str())]).is_empty()); + assert!(predefined_quit([("src/deep.rs", use_groups.as_str())]).is_empty()); + + let cfg = format!("#[cfg({}unix{})]\nfn f() {{ let t = std::time::Instant::now(); }}\n", "not(".repeat(depth), ")".repeat(depth)); + assert_eq!(lines(&std_instant([("src/deep.rs", cfg.as_str())])), vec![2]); + + let shallow = "use std::time::{{{Instant}}};\n"; + assert_eq!(lines(&std_instant([("src/shallow.rs", shallow)])), vec![1]); +} + +#[test] +fn a_long_use_path_shared_by_many_names_is_read_without_copying_it_to_each() { + // 10,000 path segments shared by 10,000 names, followed by a `use` the guard reports. + let names: Vec = (0..10_000).map(|n| format!("x{n}")).collect(); + let source = format!("use {}{{{}}};\nuse std::time::Instant;\n", "a::".repeat(10_000), names.join(", ")); + assert_eq!(lines(&std_instant([("src/wide.rs", source.as_str())])), vec![2]); + assert!(predefined_quit([("src/wide.rs", source.as_str())]).is_empty()); +} + +#[test] +fn a_long_name_shared_by_many_use_leaves_is_read_without_copying_it_to_each() { + // A 40,000-byte name shared by 10,000 leaves, followed by a `use` the guard reports. + let source = format!("use {}::{{{}}};\nuse std::time::Instant;\n", "n".repeat(40_000), ["self"; 10_000].join(", ")); + assert_eq!(lines(&std_instant([("src/wide.rs", source.as_str())])), vec![2]); + assert!(predefined_quit([("src/wide.rs", source.as_str())]).is_empty()); +} + +#[test] +fn std_instant_reports_a_grouped_import_through_a_long_alias_of_std_time() { + let source = r#" +use std::time as standard_time_module_with_a_long_name; +use standard_time_module_with_a_long_name::{Instant as Clock}; +fn now() { + let _ = Clock::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![3]); +} + +#[test] +fn std_instant_reports_a_glob_through_a_long_alias_of_std_time() { + let source = r#" +use std::time as standard_time_module_with_a_long_name; +use standard_time_module_with_a_long_name::*; +use standard_time_module_with_a_long_name::{Duration, *}; +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![3, 4]); +} + +#[test] +fn std_instant_reports_a_path_of_nine_or_more_segments_that_starts_at_std_time() { + let source = r#" +use std::time as standard_time_module_with_a_long_name; +use std::time::Instant::a::b::c::d::e::f; +use standard_time_module_with_a_long_name::Instant::a::b::c::d::e::f::g; +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![3, 4]); +} + +#[test] +fn the_guards_read_an_absolute_path_after_a_return_arrow_or_a_match_arrow() { + let clock = r#" +fn now() -> ::std::time::Instant { + match 0 { _ => ::std::time::Instant::now() } +} +fn closure() { let _ = || -> ::std::time::Instant { todo() }; } +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", clock)])), vec![2, 3, 5]); + + let menu = r#" +fn item() -> Item { + match 0 { _ => ::muda::PredefinedMenuItem::quit(None) } +} +"#; + assert_eq!(lines(&predefined_quit([("src/menu.rs", menu)])), vec![3]); +} + +#[test] +fn a_long_alias_of_std_time_shared_by_many_use_leaves_is_read_without_copying_it_to_each() { + // A 40,000-byte alias of `std::time` shared by 10,000 leaves. + let alias = "n".repeat(40_000); + let source = format!("use std::time as {alias};\nuse {alias}::{{{}}};\n", ["Instant"; 10_000].join(", ")); + assert_eq!(lines(&std_instant([("src/wide.rs", source.as_str())])), vec![2]); +} + +#[test] +fn a_use_past_the_path_limits_still_binds_its_name() { + let segment = r#" +use other_menu::MenuItemWithAnExceptionallyLongName as PredefinedMenuItem; +fn quit() { PredefinedMenuItem::quit(None); } +"#; + let length = r#" +use a::b::c::d::e::f::g::h::Item as PredefinedMenuItem; +fn quit() { PredefinedMenuItem::quit(None); } +"#; + let shared = r#" +use other_menu::MenuItemWithAnExceptionallyLongName::{self as PredefinedMenuItem}; +fn quit() { PredefinedMenuItem::quit(None); } +"#; + assert!(predefined_quit([("src/menu.rs", segment), ("src/len.rs", length), ("src/shared.rs", shared)]).is_empty()); + + // A path into this crate past the limits may still be a re-export of muda's type. + let local = r#" +use crate::module_with_an_exceptionally_long_name::PredefinedMenuItem; +fn quit() { PredefinedMenuItem::quit(None); } +"#; + assert_eq!(lines(&predefined_quit([("src/local.rs", local)])), vec![3]); + + let clock = r#" +use std::time as t; +fn now() { + use other_clock::ClockModuleWithAnExceptionallyLongName as t; + let _ = t::Instant::now(); +} +fn later() { + use other_clock::ClockModuleWithAnExceptionallyLongName::{self as t}; + let _ = t::Instant::now(); +} +fn web() { let _ = t::Instant::now(); } +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", clock)])), vec![11]); +} + +#[test] +fn std_instant_reports_an_underscore_import_of_instant_in_a_group() { + let source = r#" +use std::{time::Instant as _}; +use std::time::{Instant as _}; +use std::time::Instant as _; +use std::time::{self as _}; +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![2, 3, 4]); + assert!(predefined_quit([("src/menu.rs", "use muda::{PredefinedMenuItem as _};\nfn f() { _::quit(); }\n")]).is_empty()); +} + +#[test] +fn std_instant_keeps_an_import_that_an_alias_in_a_nested_module_shares_a_name_with() { + let source = r#" +mod unrelated { use ::std::time as std; } +use std::{time::Instant}; +"#; + assert_eq!(lines(&std_instant([("src/clock.rs", source)])), vec![3]); +} + +fn finding_paths(findings: &[Finding]) -> Vec<&str> { + findings.iter().map(|f| f.path.as_str()).collect() +} + +#[test] +fn std_instant_skips_module_files_a_native_cfg_declares() { + let lib = r#" +#[cfg(not(target_arch = "wasm32"))] +mod native; +mod web; +#[cfg(feature = "extra")] +mod extra; +"#; + let native = "mod clock;\npub fn now() -> std::time::Instant { std::time::Instant::now() }\n"; + let native_clock = "use std::time::Instant;\n"; + let web = "#[cfg(unix)]\nmod imp;\npub fn now() { let _t = std::time::Instant::now(); }\n"; + let web_imp = "use std::time::Instant;\n"; + let sibling_imp = "use std::time::Instant;\n"; + let extra = "use std::time::Instant;\n"; + let files = [ + ("src/lib.rs", lib), + ("src/native.rs", native), + ("src/native/clock.rs", native_clock), + ("src/web.rs", web), + ("src/web/imp.rs", web_imp), + ("src/imp.rs", sibling_imp), + ("src/extra.rs", extra), + ]; + assert_eq!(finding_paths(&std_instant(files)), vec!["src/web.rs", "src/imp.rs", "src/extra.rs"]); +} + +#[test] +fn std_instant_skips_native_module_files_by_mod_rs_path_attribute_and_inline_module() { + let main = r#" +#[cfg(unix)] +pub(crate) mod sys; +#[cfg(target_os = "macos")] +#[path = "platform/mac_clock.rs"] +mod mac; +#[cfg(windows)] +mod outer { + mod inner; +} +#[cfg(unix)] +#[path = "platform/native.rs"] +pub(in crate) mod native; +"#; + let clock = "use std::time::Instant;\n"; + let files = [ + ("C:\\app\\src\\main.rs", main), + ("C:\\app\\src\\platform\\native.rs", clock), + ("C:\\app\\src\\sys\\mod.rs", "mod detail;\n"), + ("C:\\app\\src\\sys\\detail.rs", clock), + ("C:\\app\\src\\platform\\mac_clock.rs", clock), + ("C:\\app\\src\\outer\\inner.rs", clock), + ("C:\\app\\src\\mac.rs", clock), + ]; + assert_eq!(finding_paths(&std_instant(files)), vec!["C:\\app\\src\\mac.rs"]); +} + +#[test] +fn std_instant_checks_a_module_file_that_a_web_declaration_also_names() { + let lib = r#" +#[cfg(windows)] +mod imp; +#[cfg(target_arch = "wasm32")] +mod imp; +#[cfg(unix)] +mod sys; +"#; + let files = [ + ("src/lib.rs", lib), + ("src/imp.rs", "mod detail;\n"), + ("src/imp/detail.rs", "use std::time::Instant;\n"), + ("src/sys.rs", "#[path = \"imp/detail.rs\"]\nmod shared;\n"), + ]; + assert_eq!(finding_paths(&std_instant(files)), vec!["src/imp/detail.rs"]); +} + +#[test] +fn std_instant_reads_an_inline_module_path_attribute_as_the_folder_of_its_modules() { + let lib = r#" +#[cfg(unix)] +#[path = "native"] +mod platform { + mod clock; +} +mod web; +"#; + let web = r#" +#[path = "shared"] +mod inner { + #[cfg(windows)] + mod tick; +} +"#; + let clock = "use std::time::Instant;\n"; + let files = [ + ("src/lib.rs", lib), + ("src/native/clock.rs", clock), + ("src/platform/clock.rs", clock), + ("src/web.rs", web), + ("src/shared/tick.rs", clock), + ("src/web/shared/tick.rs", clock), + ]; + assert_eq!(finding_paths(&std_instant(files)), vec!["src/platform/clock.rs", "src/web/shared/tick.rs"]); +} + +#[test] +fn std_instant_reads_top_level_path_attributes_of_a_non_mod_rs_file_from_its_folder() { + let a = r#" +#[cfg(unix)] +#[path = "native.rs"] +mod imp; +#[cfg(unix)] +#[path = "native"] +mod platform { + mod clock; +} +"#; + let clock = "use std::time::Instant;\n"; + let files = [ + ("src/lib.rs", "mod a;\n"), + ("src/a.rs", a), + ("src/native.rs", clock), + ("src/native/clock.rs", clock), + ("src/a/native.rs", clock), + ("src/a/native/clock.rs", clock), + ]; + assert_eq!(finding_paths(&std_instant(files)), vec!["src/a/native.rs", "src/a/native/clock.rs"]); +} + +#[test] +fn std_instant_finds_the_modules_of_a_path_attribute_file_next_to_it() { + let lib = r#" +#[cfg(not(target_arch = "wasm32"))] +#[path = "platform/native.rs"] +mod native; +"#; + let clock = "use std::time::Instant;\n"; + let files = [("src/lib.rs", lib), ("src/platform/native.rs", "mod clock;\n"), ("src/platform/clock.rs", clock), ("src/web.rs", clock)]; + assert_eq!(finding_paths(&std_instant(files)), vec!["src/web.rs"]); +} + +#[test] +fn std_instant_resolves_a_file_loaded_both_plainly_and_by_path_attribute_once_for_each() { + // `platform.rs` is a web module, and a native-only `#[path]` declaration loads it again. Its + // `mod clock;` is `src/platform/clock.rs` for the first and `src/clock.rs` for the second. + let lib = "mod platform;\n#[cfg(unix)]\n#[path = \"platform.rs\"]\nmod native;\n"; + let clock = "use std::time::Instant;\n"; + let files = [("src/lib.rs", lib), ("src/platform.rs", "mod clock;\n"), ("src/platform/clock.rs", clock), ("src/clock.rs", clock)]; + assert_eq!(finding_paths(&std_instant(files)), vec!["src/platform/clock.rs"]); +} + +#[test] +fn std_instant_checks_a_file_that_a_path_attribute_module_names_for_the_web_build() { + // The web module `entry.rs`, loaded through `#[path]`, names `src/clock.rs`, which a native-only + // module also names through `#[path]`. + let lib = "#[path = \"entry.rs\"]\nmod web;\n#[cfg(unix)]\nmod native;\n"; + let clock = "use std::time::Instant;\n"; + let files = + [("src/lib.rs", lib), ("src/entry.rs", "mod clock;\n"), ("src/native.rs", "#[path = \"clock.rs\"]\nmod clock;\n"), ("src/clock.rs", clock)]; + assert_eq!(finding_paths(&std_instant(files)), vec!["src/clock.rs"]); +} + +#[test] +fn std_instant_checks_module_files_declared_deeper_than_its_nesting_limit() { + let lib = format!("{}#[cfg(unix)]\nmod deep;\n{}", "mod m {\n".repeat(70), "}\n".repeat(70)); + let shallow_lib = format!("{}#[cfg(unix)]\nmod deep;\n{}", "mod m {\n".repeat(3), "}\n".repeat(3)); + let deep_path = format!("src/{}deep.rs", "m/".repeat(70)); + let shallow_path = format!("src/{}deep.rs", "m/".repeat(3)); + let clock = "use std::time::Instant;\n"; + let files = [("src/lib.rs", lib.as_str()), (deep_path.as_str(), clock)]; + assert_eq!(finding_paths(&std_instant(files)), vec![deep_path.as_str()]); + let files = [("src/lib.rs", shallow_lib.as_str()), (shallow_path.as_str(), clock)]; + assert!(std_instant(files).is_empty()); +} + +#[test] +fn std_instant_checks_a_crate_root_that_a_disabled_declaration_names() { + let lib = r#" +#[cfg(any())] +#[path = "lib.rs"] +mod never; + +fn web() { + std::time::Instant::now(); +} +"#; + assert_eq!(lines(&std_instant([("src/lib.rs", lib)])), vec![7]); + + // A cycle of two files that only each other name, through declarations the web build leaves out. + let a = "#[cfg(unix)]\n#[path = \"b.rs\"]\nmod b;\nfn web() { std::time::Instant::now(); }\n"; + let b = "#[cfg(unix)]\n#[path = \"a.rs\"]\nmod a;\n"; + assert_eq!(finding_paths(&std_instant([("src/a.rs", a), ("src/b.rs", b)])), vec!["src/a.rs"]); + + // In a cycle with `lib.rs`, only `lib.rs` is a crate root, so its native-only module stays out. + let lib = "#[cfg(unix)]\n#[path = \"a.rs\"]\nmod a;\nfn web() {}\n"; + let a = "#[cfg(any())]\n#[path = \"lib.rs\"]\nmod root;\nuse std::time::Instant;\n"; + assert!(std_instant([("src/lib.rs", lib), ("src/a.rs", a)]).is_empty()); + + // A cycle that a crate root reaches keeps its native-only member out. + let lib = "mod a;\n"; + let a = "#[cfg(unix)]\nmod b;\n"; + let b = "#[path = \"../a.rs\"]\nmod again;\nuse std::time::Instant;\n"; + assert!(std_instant([("src/lib.rs", lib), ("src/a.rs", a), ("src/a/b.rs", b)]).is_empty()); +} + +#[test] +fn wgsl_integer_literals_are_not_floats() { + let shader = r#" +const BIG_ABSTRACT = 400000000000000000000000000000000000000000; +const BIG_U = 1000000000000000000000000000000000000000u; +const BIG_I = 1000000000000000000000000000000000000000i; +const HEX_INT = 0xFFFFFFFFu; +const HEX_F_DIGIT = 0x1f; +const FLOAT_DOT: f32 = 340282356779733661637539395458142568448.0; +const FLOAT_SUFFIX: f32 = 400000000000000000000000000000000000000f; +const NEG_EXP: f32 = -4e38; +"#; + let findings = wgsl_float_literals(shader); + assert_eq!(lines(&findings), vec![7, 8, 9]); + assert_eq!(findings[0].text, "340282356779733661637539395458142568448.0"); + assert_eq!(findings[1].text, "400000000000000000000000000000000000000"); + assert_eq!(findings[2].text, "4e38"); +} + +#[test] +fn wgsl_hex_floats_outside_the_range_are_reported() { + let shader = r#" +const EXACT_MAX: f32 = 0x1.fffffep+127f; +const HUGE: f32 = 0x1p+500f; +const JUST_OVER: f32 = 0x1.000002p+128; +const UPPER: f32 = 0X1P128; +const TINY: f32 = 0x1p-500; +const ZERO: f32 = 0x0.0p99999; +const F16_MAX: f16 = 0x1.ffcp15h; +const F16_OVER: f16 = 0x1.0p16h; +"#; + let findings = wgsl_float_literals(shader); + assert_eq!(lines(&findings), vec![3, 4, 5, 9]); + assert_eq!(findings[0].text, "0x1p+500"); + assert_eq!(findings[3].text, "0x1.0p16"); +} + +#[test] +fn wgsl_literals_after_a_hex_literal_and_an_operator_are_checked() { + let shader = "const A = 0x1.0p0+1e39;\nconst B = 0xFF+1e39;\nconst C = 0x1f-4e38;\nconst D = 0xAu*2.0+5e38;\nconst E = 0x1p1-0x1p+500;\n"; + let findings = wgsl_float_literals(shader); + assert_eq!(lines(&findings), vec![1, 2, 3, 4, 5]); + let texts: Vec<&str> = findings.iter().map(|f| f.text.as_str()).collect(); + assert_eq!(texts, vec!["1e39", "1e39", "4e38", "5e38", "0x1p+500"]); +} + +#[test] +fn wgsl_block_comment_markers_inside_line_comments_do_not_open_a_comment() { + let shader = "// a /* inside a line comment\nconst BAD: f32 = 4e38;\n/* block // with a line marker */ const ALSO_BAD: f32 = 5e38;\n"; + let findings = wgsl_float_literals(shader); + assert_eq!(lines(&findings), vec![2, 3]); +} + +#[test] +fn wgsl_half_floats_use_the_f16_range() { + let shader = "const OK: f16 = 65504.0h;\nconst OVER: f16 = 70000.0h;\nconst F32_OK: f32 = 70000.0f;\n"; + let findings = wgsl_float_literals(shader); + assert_eq!(lines(&findings), vec![2]); + assert_eq!(findings[0].text, "70000.0"); +} + +#[test] +fn wgsl_line_comments_end_and_lines_count_at_every_line_break() { + let shader = "// note\rconst A: f32 = 4e38;\r\nconst B: f32 = 5e38;\n// x\u{2028}const C: f32 = 6e38;\u{2029}const D: f32 = 7e38;\u{000B}// y\u{0085}const E: f32 = 8e38;\u{000C}const F: f32 = 9e38;"; + let findings = wgsl_float_literals(shader); + assert_eq!(lines(&findings), vec![2, 3, 5, 6, 8, 9]); + assert_eq!(findings[0].text, "4e38"); +} + +#[test] +fn wgsl_digits_inside_unicode_identifiers_are_not_literals() { + let shader = "const π1e39 = 1.0;\nconst é2e40: f32 = 2.0;\nconst A: f32 =\u{200E}1e39;\n"; + let findings = wgsl_float_literals(shader); + assert_eq!(lines(&findings), vec![3]); + assert_eq!(findings[0].text, "1e39"); +} + +#[cfg(not(target_arch = "wasm32"))] +#[test] +fn test_rust_sources_filtering() { + use craft_testkit::rust_sources; + + let dir = ScratchDir::new("filtering"); + dir.write("src/lib.rs", "pub fn lib() {}"); + dir.write("src/sub/mod.rs", "pub fn sub() {}"); + dir.write("src/tests.rs", "// should exclude"); + dir.write("src/tests_foo.rs", "// should exclude"); + dir.write("src/foo_tests.rs", "// should exclude"); + dir.write("src/foo_test.rs", "// should exclude"); + dir.write("tests/integ.rs", "// should exclude"); + dir.write("target/gen.rs", "// should exclude"); + dir.write(".github/action.rs", "// should exclude dot-dir"); + dir.write("src/README.md", "# Not a rust source"); + + let sources = rust_sources(dir.path()).expect("rust_sources"); + assert_eq!(file_names(&sources), vec!["lib.rs", "mod.rs"]); + + // Test passing &[(String, String)] to guards + let findings = predefined_quit(&sources); + assert!(findings.is_empty()); +} + +#[cfg(not(target_arch = "wasm32"))] +#[test] +fn rust_sources_lists_a_root_inside_a_folder_named_tests() { + let dir = ScratchDir::new("root_in_tests"); + dir.write("tests/app/src/lib.rs", "pub fn lib() {}"); + let sources = craft_testkit::rust_sources(dir.path().join("tests").join("app")).expect("rust_sources"); + assert_eq!(file_names(&sources), vec!["lib.rs"]); +} + +#[cfg(not(target_arch = "wasm32"))] +#[test] +fn rust_sources_skips_build_output_folders_marked_with_cachedir_tag() { + let dir = ScratchDir::new("cachedir"); + dir.write("src/lib.rs", "pub fn lib() {}"); + dir.write("out/CACHEDIR.TAG", "Signature: 8a477f597d28d172789f06886806bc55\n# build output\n"); + dir.write("out/debug/build/gen.rs", "pub fn generated() {}"); + dir.write("notes/CACHEDIR.TAG", "not a cache tag\n"); + dir.write("notes/kept.rs", "pub fn kept() {}"); + let sources = craft_testkit::rust_sources(dir.path()).expect("rust_sources"); + assert_eq!(file_names(&sources), vec!["kept.rs", "lib.rs"]); +} + +#[cfg(unix)] +#[test] +fn rust_sources_does_not_read_a_cachedir_tag_through_a_symlink() { + let outside = ScratchDir::new("cachedir_link_target"); + outside.write("CACHEDIR.TAG", "Signature: 8a477f597d28d172789f06886806bc55\n"); + let dir = ScratchDir::new("cachedir_link"); + dir.write("src/lib.rs", "pub fn lib() {}"); + dir.write("linked/kept.rs", "pub fn kept() {}"); + std::os::unix::fs::symlink(outside.path().join("CACHEDIR.TAG"), dir.path().join("linked").join("CACHEDIR.TAG")).expect("symlink marker"); + let sources = craft_testkit::rust_sources(dir.path()).expect("rust_sources"); + assert_eq!(file_names(&sources), vec!["kept.rs", "lib.rs"]); +} + +#[cfg(unix)] +#[test] +fn rust_sources_does_not_open_a_cachedir_tag_fifo() { + let dir = ScratchDir::new("cachedir_fifo"); + dir.write("src/lib.rs", "pub fn lib() {}"); + dir.write("piped/kept.rs", "pub fn kept() {}"); + let fifo = dir.path().join("piped").join("CACHEDIR.TAG"); + match std::process::Command::new("mkfifo").arg(&fifo).status() { + Ok(status) if status.success() => {} + other => { + eprintln!("skipped: mkfifo is not available here ({other:?})"); + return; + } + } + // Opening the FIFO for reading and writing does not wait for another end on Linux or macOS. The + // signature waits in the pipe, so a scan that opened the FIFO would read it and leave out `kept.rs` + // without blocking. + let mut pipe = std::fs::OpenOptions::new().read(true).write(true).open(&fifo).expect("open FIFO"); + std::io::Write::write_all(&mut pipe, b"Signature: 8a477f597d28d172789f06886806bc55\n").expect("write signature"); + let sources = craft_testkit::rust_sources(dir.path()).expect("rust_sources"); + drop(pipe); + assert_eq!(file_names(&sources), vec!["kept.rs", "lib.rs"]); +} + +#[cfg(unix)] +#[test] +fn rust_sources_does_not_follow_a_symlink_out_of_the_root() { + let outside = ScratchDir::new("symlink_outside"); + outside.write("evil.rs", "pub fn evil() {}"); + let dir = ScratchDir::new("symlink_root"); + dir.write("src/lib.rs", "pub fn lib() {}"); + std::os::unix::fs::symlink(outside.path(), dir.path().join("src").join("linked")).expect("symlink folder"); + std::os::unix::fs::symlink(outside.path().join("evil.rs"), dir.path().join("src").join("evil.rs")).expect("symlink file"); + let sources = craft_testkit::rust_sources(dir.path()).expect("rust_sources"); + assert_eq!(file_names(&sources), vec!["lib.rs"]); +} + +#[cfg(unix)] +#[test] +fn rust_sources_does_not_loop_on_a_symlink_cycle() { + let dir = ScratchDir::new("symlink_cycle"); + dir.write("src/lib.rs", "pub fn lib() {}"); + std::os::unix::fs::symlink(dir.path().join("src"), dir.path().join("src").join("again")).expect("symlink cycle"); + let sources = craft_testkit::rust_sources(dir.path()).expect("rust_sources"); + assert_eq!(file_names(&sources), vec!["lib.rs"]); +} + +#[cfg(unix)] +#[test] +fn rust_sources_skips_a_broken_symlink() { + let dir = ScratchDir::new("symlink_broken"); + dir.write("src/lib.rs", "pub fn lib() {}"); + std::os::unix::fs::symlink(dir.path().join("missing.rs"), dir.path().join("src").join("gone.rs")).expect("symlink file"); + std::os::unix::fs::symlink(dir.path().join("missing"), dir.path().join("src").join("gone")).expect("symlink folder"); + let sources = craft_testkit::rust_sources(dir.path()).expect("rust_sources"); + assert_eq!(file_names(&sources), vec!["lib.rs"]); +} + +#[cfg(not(target_arch = "wasm32"))] +#[test] +fn scratch_dirs_leave_existing_folders_alone_and_clean_up_on_panic() { + let taken = std::env::temp_dir().join(format!("craft_testkit_sentinel_{}_0", std::process::id())); + std::fs::create_dir(&taken).expect("create the folder the helper would pick first"); + std::fs::write(taken.join("sentinel"), "keep").expect("write sentinel"); + + let made = std::panic::catch_unwind(|| { + let dir = ScratchDir::new("sentinel"); + let path = dir.path().to_path_buf(); + assert!(path.exists()); + std::panic::panic_any(path); + }); + let payload = made.expect_err("the closure panics"); + let path = payload.downcast_ref::().expect("panic payload is the path").clone(); + + assert_ne!(path, taken); + assert!(!path.exists(), "the scratch folder is removed when the test panics"); + assert_eq!(std::fs::read_to_string(taken.join("sentinel")).expect("sentinel survives"), "keep"); + std::fs::remove_dir_all(&taken).expect("remove the pre-made folder"); +} diff --git a/crates/testkit/tests/source_limits.rs b/crates/testkit/tests/source_limits.rs new file mode 100644 index 000000000..a90b7f4cf --- /dev/null +++ b/crates/testkit/tests/source_limits.rs @@ -0,0 +1,99 @@ +#![cfg(not(target_arch = "wasm32"))] + +use craft_testkit::{SourceLimits, rust_sources_with_limits}; +use std::io::ErrorKind; +use std::path::{Path, PathBuf}; + +/// A scratch folder that this test made and removes on drop, also when the test panics. +struct ScratchDir(PathBuf); + +impl ScratchDir { + fn new(tag: &str) -> Self { + let base = std::env::temp_dir(); + for n in 0..1000u32 { + let path = base.join(format!("craft_testkit_limits_{tag}_{}_{n}", std::process::id())); + match std::fs::create_dir(&path) { + Ok(()) => return Self(path), + Err(e) if e.kind() == ErrorKind::AlreadyExists => continue, + Err(e) => panic!("create scratch folder {}: {e}", path.display()), + } + } + panic!("no free scratch folder name for {tag}"); + } + + fn path(&self) -> &Path { + &self.0 + } + + fn write(&self, relative: &str, content: &str) { + let path = self.0.join(relative); + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent).expect("create parent folder"); + } + std::fs::write(path, content).expect("write file"); + } +} + +impl Drop for ScratchDir { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +fn three_files(tag: &str) -> ScratchDir { + let dir = ScratchDir::new(tag); + dir.write("src/a.rs", "0123456789"); + dir.write("src/b.rs", "0123456789"); + dir.write("src/c.rs", "0123456789"); + dir +} + +#[test] +fn defaults_are_documented_values() { + let limits = SourceLimits::default(); + assert_eq!(limits.max_file_bytes, 8 << 20); + assert_eq!(limits.max_total_bytes, 256 << 20); + assert_eq!(limits.max_files, 50_000); +} + +#[test] +fn files_within_the_limits_are_read() { + let dir = three_files("within"); + let limits = SourceLimits { max_file_bytes: 10, max_total_bytes: 30, max_files: 3 }; + let sources = rust_sources_with_limits(dir.path(), limits).expect("within limits"); + assert_eq!(sources.len(), 3); + assert!(sources.iter().all(|(_, content)| content == "0123456789")); +} + +#[test] +fn a_file_over_the_size_limit_is_an_error() { + let dir = three_files("file"); + let limits = SourceLimits { max_file_bytes: 9, ..SourceLimits::default() }; + let err = rust_sources_with_limits(dir.path(), limits).expect_err("file over the limit"); + assert_eq!(err.kind(), ErrorKind::FileTooLarge); +} + +#[test] +fn files_over_the_total_limit_are_an_error() { + let dir = three_files("total"); + let limits = SourceLimits { max_total_bytes: 29, ..SourceLimits::default() }; + let err = rust_sources_with_limits(dir.path(), limits).expect_err("total over the limit"); + assert_eq!(err.kind(), ErrorKind::QuotaExceeded); +} + +#[test] +fn more_files_than_the_count_limit_is_an_error() { + let dir = three_files("count"); + let limits = SourceLimits { max_files: 2, ..SourceLimits::default() }; + let err = rust_sources_with_limits(dir.path(), limits).expect_err("too many files"); + assert_eq!(err.kind(), ErrorKind::QuotaExceeded); +} + +#[test] +fn files_the_filter_skips_do_not_count_against_the_limits() { + let dir = three_files("skipped"); + dir.write("src/tests.rs", &"x".repeat(100)); + dir.write("tests/big.rs", &"x".repeat(100)); + let limits = SourceLimits { max_file_bytes: 10, max_total_bytes: 30, max_files: 3 }; + assert_eq!(rust_sources_with_limits(dir.path(), limits).expect("skipped files are not read").len(), 3); +} diff --git a/crates/texture/Cargo.toml b/crates/texture/Cargo.toml index 173abb0b0..964fafa41 100644 --- a/crates/texture/Cargo.toml +++ b/crates/texture/Cargo.toml @@ -24,5 +24,6 @@ dds = { version = "0.2.0", default-features = false, optional = true } bytemuck = { workspace = true, optional = true } [dev-dependencies] +half = "2" dds = { version = "0.2.0", default-features = false } bytemuck = { workspace = true } diff --git a/crates/texture/README.md b/crates/texture/README.md index 8c82e5d0b..c5b10eac1 100644 --- a/crates/texture/README.md +++ b/crates/texture/README.md @@ -40,9 +40,31 @@ network I/O and has no `unsafe` code. `to_rgba8_display` encodes 8-bit sRGB RGBA. `linear_to_srgb`, `srgb_to_linear` and `luminance` (Rec. 709) are scalar helpers. `resource_key` and `split_resource_key` tag a bitmap name with its color space. +- **Height to normal and ORM packing.** Both read a `ScalarSource`: a plane of linear scalar + samples that gives its size and one row at a time, so an adapter can decode a tiled or encoded + surface in place. Besides the output, each worker keeps at most three rows for the normal map + and one row for each given plane for ORM packing, never a full `f32` copy of the input. Both + check the output size against `Limits` before reading. An `Image` is a + `ScalarSource` of its gray value, or its Rec. 709 luminance for a color image. + - `normal::try_height_to_normal` returns an RGBA tangent-space normal map. It takes the 3×3 + Sobel gradient of the height, scales it by `strength` and normalizes `(-gx × s, gy × s, 1)`, + then stores `0.5 × n + 0.5` with alpha 1, as glTF 2.0 encodes normal textures. OpenGL + normals have green up the image; `NormalConvention::DirectX` negates green. Neighbors clamp + to the image, or with `BoundaryMode::ClampToBlock` to the `block × block` UV tile of the + center sample. A neighbor that `ScalarSource::covered` reports as not covered takes the + center height. `HeightNormalOptions::uv_tiles(height_strength, tile_res, block_scale)` gives + the strength `height_strength × tile_res × block_scale / 16` and clamps to UV tiles of + `tile_res`. A strength of 0 gives flat normals `[0.5, 0.5, 1]`. + - `packing::try_pack_orm` returns RGBA `[occlusion, roughness, metallic, 1]`, the channels + glTF 2.0 reads occlusion from (red) and metallic-roughness from (green and blue). A plane + that is not given takes 1, 0.5 or 0. `occlusion_multiplier` multiplies a second occlusion + plane, such as baked occlusion, into red. Every plane must have the same size, and `size` + gives it when no plane is given. + - Values are linear data with no transfer curve. A NaN or infinite strength, sample or block + scale, a block of 0, an occlusion product that overflows `f32`, mismatched sizes and a + failed row read return a `TextureOpError`. -Mirrored repeat, mip chains, height to normal, channel packing, decoding and texture-set -recognition are not in the crate yet. +Mirrored repeat, mip chains, decoding and texture-set recognition are not in the crate yet. ## Cargo features @@ -50,7 +72,7 @@ No default features. | Feature | Provides | Pulls in | |---|---|---| -| `parallel` | generated images and display conversion fill rows on several threads; the results are the same | `rayon` | +| `parallel` | generated images, display conversion, height to normal and ORM packing fill rows on several threads; the results are the same | `rayon` | Without `parallel` the crate builds for `wasm32-unknown-unknown`. @@ -58,7 +80,7 @@ Without `parallel` the crate builds for `wasm32-unknown-unknown`. | Field | Default | Checked by | |---|---|---| -| `max_side` | 8192 | every `try_` constructor and `from_data` | +| `max_side` | 8192 | every `try_` constructor, `from_data`, `try_height_to_normal` and `try_pack_orm` | | `max_pixels` | 2^26 (8192 × 8192) | the same | | `max_bytes` | 1 GiB (an 8192 × 8192 RGBA plane) | the same | @@ -69,6 +91,8 @@ Without `parallel` the crate builds for `wasm32-unknown-unknown`. | `Image`, `Kind`, sampling, resizing, conversions, sRGB helpers, resource keys and the six tests `sample_survives_huge_coordinates`, `resource_keys_round_trip`, `sample_wraps_and_clamps`, `resize_box_and_bilinear`, `hostile_sizes_are_clamped`, `conversions` | MaterialCraft `crates/image/src/lib.rs` at [3133062](https://github.com/storytold/materialcraft/commit/3133062968b8a1566eda12a357cb06062db16687) | | `get_axes`, `sample_axes`, `sample_nearest_axes`, `sample_stored` and the integer-sampling flag | MaterialCraft `crates/image/src/lib.rs` at [6c3b35c](https://github.com/storytold/materialcraft/commit/6c3b35c39632feafcda3d7a90ff18242f3ad910f), on this crate's coordinate reduction and `f64` bilinear sum | | `Limits`, the `try_` constructors, `from_data`, private fields with getters, the `parallel` feature, `with_integer_sampling` and `integer_sampling` | written here | +| The Sobel normal, its strength scale, UV-tile clamp and uncovered-neighbor rule, the ORM channels and defaults, and the tests `gltf_png_matches_the_composite`, `directx_flips_green`, `height_becomes_normal_detail`, `ao_mixes_baked_and_channel`, `converted_maps_invert_and_derive_normals` and `uv_tiles_export_one_file_per_tile_without_padding_across`, with assertions on the new functions | TextureCraft `crates/formats/src/export/mod.rs`, `presets.rs` and `tests.rs` and `crates/core/src/channel.rs` at [b89badc](https://github.com/storytold/texturecraft/commit/b89badcd6f883751f79960f93c554fb77f063885) | +| `ScalarSource`, row-at-a-time reading, the limit and non-finite checks, and the tiled-input tests | written here | ## Migration @@ -76,6 +100,7 @@ Without `parallel` the crate builds for `wasm32-unknown-unknown`. |---|---| | MaterialCraft | `materialcraft-image` is the source. The app switches to this crate in its own pull request. | | EffectCraft | Its texture sampling moves into this crate later, with mirrored repeat. | +| TextureCraft | Its export's height normal and ORM packing are the source of `normal` and `packing`. The app switches to them in its own pull request. | For MaterialCraft: diff --git a/crates/texture/src/lib.rs b/crates/texture/src/lib.rs index baaabee66..54dffcb17 100644 --- a/crates/texture/src/lib.rs +++ b/crates/texture/src/lib.rs @@ -30,6 +30,10 @@ //! resampler of [`Image::try_resize`]. The forms without `try_` allocate like `Vec`. A failed //! infallible allocation ends the process. Rows are generated on several threads only with the //! `parallel` feature. +//! +//! [`normal`] makes tangent-space normal maps from a height plane, and [`packing`] packs +//! occlusion, roughness and metallic into one RGBA image. Both read a [`ScalarSource`] one row at +//! a time, so a tiled surface is read in place instead of copied into a float plane. #![forbid(unsafe_code)] #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] @@ -41,6 +45,14 @@ use std::sync::Arc; #[cfg(feature = "parallel")] use rayon::prelude::*; +pub mod normal; +pub mod packing; +mod source; +#[cfg(test)] +mod tiled_tests; + +pub use source::{ScalarSource, SourceError, TextureOpError}; + /// Largest side the clamping constructors make, and the default [`Limits::max_side`]. pub const MAX_SIDE: u32 = 8192; diff --git a/crates/texture/src/normal.rs b/crates/texture/src/normal.rs new file mode 100644 index 000000000..070740fd7 --- /dev/null +++ b/crates/texture/src/normal.rs @@ -0,0 +1,432 @@ +//! Tangent-space normal maps from a height plane. +//! +//! [`try_height_to_normal`] takes the 3×3 Sobel gradient of the height around each sample, scales +//! it by [`HeightNormalOptions::strength`] and normalizes `(-gx × s, gy × s, 1)`. Image `y` grows +//! downward, so height that rises toward the bottom of the image gives a positive OpenGL `y`. +//! Each unit normal is stored as `0.5 × n + 0.5` in red, green and blue, the encoding glTF 2.0 +//! section 3.9.3 gives for normal textures +//! (), with alpha 1. The output is +//! linear data. [`NormalConvention::DirectX`] negates `y` before the encoding. + +use crate::source::{ScalarSource, TextureOpError, read_checked, try_buffer, try_color_image}; +use crate::{Image, Limits}; + +/// Divisor of the slope scale in [`HeightNormalOptions::uv_tiles`]: the strength is +/// `height_strength × tile_res × block_scale / HEIGHT_SPAN`. +pub const HEIGHT_SPAN: f32 = 16.0; + +/// The direction of the green channel of a normal map. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +pub enum NormalConvention { + /// Green points up the image (X+, Y+, Z+), as glTF 2.0 normal textures do. + #[default] + OpenGl, + /// Green points down the image (X+, Y-, Z+). + DirectX, +} + +/// Which samples a neighbor of a sample may be read from. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +pub enum BoundaryMode { + /// A neighbor outside the image takes the nearest edge sample. + #[default] + ClampToImage, + /// The plane is a grid of `block × block` material blocks, the top-left block at `(0, 0)`. A + /// neighbor outside the block of the center sample, or outside the image, takes the nearest + /// sample inside both. `block` is at least 1. + ClampToBlock { block: u32 }, +} + +/// How [`try_height_to_normal`] turns heights into normals. +/// `#[non_exhaustive]`: start from [`HeightNormalOptions::default`] or +/// [`HeightNormalOptions::uv_tiles`] and set the fields you change. +#[derive(Clone, Copy, Debug, PartialEq)] +#[non_exhaustive] +pub struct HeightNormalOptions { + /// Multiplier of the Sobel gradient. 0 gives flat normals; a negative value inverts the + /// relief. Default 1. + pub strength: f32, + /// Default [`NormalConvention::OpenGl`]. + pub convention: NormalConvention, + /// Default [`BoundaryMode::ClampToImage`]. + pub boundary: BoundaryMode, +} + +impl Default for HeightNormalOptions { + fn default() -> Self { + Self { strength: 1.0, convention: NormalConvention::OpenGl, boundary: BoundaryMode::ClampToImage } + } +} + +impl HeightNormalOptions { + /// Options for a plane of `tile_res × tile_res` UV tiles: strength + /// `height_strength × tile_res × block_scale / HEIGHT_SPAN`, neighbors clamped to the UV tile + /// of the center sample, and OpenGL normals. `height_strength` must be finite, `tile_res` at + /// least 1 and `block_scale` finite and above 0. + pub fn uv_tiles(height_strength: f32, tile_res: u32, block_scale: f32) -> Result { + if !height_strength.is_finite() { + return Err(TextureOpError::BadParameter { name: "height_strength", value: f64::from(height_strength) }); + } + if tile_res == 0 { + return Err(TextureOpError::BadParameter { name: "tile_res", value: 0.0 }); + } + if !(block_scale.is_finite() && block_scale > 0.0) { + return Err(TextureOpError::BadParameter { name: "block_scale", value: f64::from(block_scale) }); + } + let strength = height_strength * tile_res as f32 * block_scale / HEIGHT_SPAN; + if !strength.is_finite() { + return Err(TextureOpError::BadParameter { name: "strength", value: f64::from(strength) }); + } + Ok(Self { strength, convention: NormalConvention::OpenGl, boundary: BoundaryMode::ClampToBlock { block: tile_res } }) + } +} + +/// The unit OpenGL normal of the height neighborhood `h`, rows top to bottom and columns left to +/// right with the center at `h[1][1]`. The Sobel gradients are +/// `gx = (h[0][2] + 2 h[1][2] + h[2][2] - h[0][0] - 2 h[1][0] - h[2][0]) / 8` and +/// `gy = (h[2][0] + 2 h[2][1] + h[2][2] - h[0][0] - 2 h[0][1] - h[0][2]) / 8`, and the result is +/// `(-gx × strength, gy × strength, 1)` normalized, computed in `f64`. NaN or infinite input +/// gives `[0, 0, 1]`. +pub fn normal_from_neighborhood(h: [[f32; 3]; 3], strength: f32) -> [f32; 3] { + let h = h.map(|row| row.map(f64::from)); + let gx = (h[0][2] + 2.0 * h[1][2] + h[2][2] - h[0][0] - 2.0 * h[1][0] - h[2][0]) / 8.0; + let gy = (h[2][0] + 2.0 * h[2][1] + h[2][2] - h[0][0] - 2.0 * h[0][1] - h[0][2]) / 8.0; + let s = f64::from(strength); + let (x, y) = (-gx * s, gy * s); + let len = (x * x + y * y + 1.0).sqrt(); + if !len.is_finite() { + return [0.0, 0.0, 1.0]; + } + [(x / len) as f32, (y / len) as f32, (1.0 / len) as f32] +} + +/// A unit OpenGL normal stored as `0.5 × n + 0.5` per component, with `y` negated first for +/// [`NormalConvention::DirectX`]. +pub fn encode_normal(n: [f32; 3], convention: NormalConvention) -> [f32; 3] { + let y = match convention { + NormalConvention::OpenGl => n[1], + NormalConvention::DirectX => -n[1], + }; + [n[0] * 0.5 + 0.5, y * 0.5 + 0.5, n[2] * 0.5 + 0.5] +} + +/// The RGBA normal map of the height plane `source`, the same size. +/// +/// Each sample's neighbors are clamped as [`HeightNormalOptions::boundary`] says, and a neighbor +/// that [`ScalarSource::covered`] reports as not covered takes the center height. Rows are read +/// from `source` one at a time, and at most three rows are kept per worker besides the output. +/// +/// Returns [`TextureOpError::BadParameter`] for a non-finite strength or a block of 0, an +/// [`crate::ImageError`] when the size is outside `limits` or memory runs out, both before any +/// row is read, [`TextureOpError::NonFiniteSample`] for a NaN or infinite height, and +/// [`TextureOpError::Source`] when a row cannot be read. +pub fn try_height_to_normal(source: &S, options: &HeightNormalOptions, limits: &Limits) -> Result { + if !options.strength.is_finite() { + return Err(TextureOpError::BadParameter { name: "strength", value: f64::from(options.strength) }); + } + let block = match options.boundary { + BoundaryMode::ClampToImage => None, + BoundaryMode::ClampToBlock { block: 0 } => return Err(TextureOpError::BadParameter { name: "block", value: 0.0 }), + BoundaryMode::ClampToBlock { block } => Some(block), + }; + let (w, h) = source.dimensions(); + let pass = Pass { source, strength: options.strength, convention: options.convention, block, w, h }; + try_color_image(w, h, limits, |y0, rows| pass.fill(y0, rows)) +} + +/// The first and last index on an axis of `n` samples that a neighbor of index `i` may take. +fn span(i: u32, n: u32, block: Option) -> (u32, u32) { + let last = n.saturating_sub(1); + match block { + None => (0, last), + Some(b) => { + let first = i / b * b; + (first, first.saturating_add(b - 1).min(last)) + } + } +} + +/// The indices of the previous sample, `i` and the next sample, clamped to `span`. +fn neighbors(i: u32, (first, last): (u32, u32)) -> [u32; 3] { + [i.saturating_sub(1).max(first), i, i.saturating_add(1).min(last)] +} + +struct Pass<'a, S: ?Sized> { + source: &'a S, + strength: f32, + convention: NormalConvention, + block: Option, + w: u32, + h: u32, +} + +impl Pass<'_, S> { + /// Fill the RGBA rows starting at row `y0`. + fn fill(&self, y0: u32, rows: &mut [f32]) -> Result<(), TextureOpError> { + let mut cache = RowCache::new(self.w, self.h)?; + for (y, out) in (y0..).zip(rows.chunks_exact_mut(self.w as usize * 4)) { + let ys = neighbors(y, span(y, self.h, self.block)); + cache.load(self.source, ys)?; + let input = ys.map(|y| cache.row(y)); + for (x, px) in (0u32..).zip(out.as_chunks_mut::<4>().0) { + let n = normal_from_neighborhood(self.neighborhood(x, y, ys, input), self.strength); + let [r, g, b] = encode_normal(n, self.convention); + *px = [r, g, b, 1.0]; + } + } + Ok(()) + } + + /// The 3×3 heights around `(x, y)`, read from the rows `ys`, whose samples are `rows`. + fn neighborhood(&self, x: u32, y: u32, ys: [u32; 3], rows: [&[f32]; 3]) -> [[f32; 3]; 3] { + let xs = neighbors(x, span(x, self.w, self.block)); + let center = rows[1].get(x as usize).copied().unwrap_or(0.0); + let mut h = [[center; 3]; 3]; + for ((hr, row), sy) in h.iter_mut().zip(rows).zip(ys) { + for (hv, sx) in hr.iter_mut().zip(xs) { + if (sx, sy) != (x, y) && self.source.covered(sx, sy) { + *hv = row.get(sx as usize).copied().unwrap_or(center); + } + } + } + h + } +} + +/// Up to three decoded rows, each tagged with its row index. +struct RowCache { + slots: [(Option, Vec); 3], +} + +impl RowCache { + fn new(w: u32, h: u32) -> Result { + let row = || try_buffer(w as usize, w, h); + Ok(RowCache { slots: [(None, row()?), (None, row()?), (None, row()?)] }) + } + + /// Read each row of `ys` that is not held yet into a slot that holds none of `ys`. + fn load(&mut self, source: &S, ys: [u32; 3]) -> Result<(), TextureOpError> { + for y in ys { + if self.slots.iter().any(|(k, _)| *k == Some(y)) { + continue; + } + if let Some((k, row)) = self.slots.iter_mut().find(|(k, _)| !k.is_some_and(|k| ys.contains(&k))) { + *k = None; + read_checked(source, y, row)?; + *k = Some(y); + } + } + Ok(()) + } + + /// The samples of row `y`, empty when it is not held. + fn row(&self, y: u32) -> &[f32] { + self.slots.iter().find(|(k, _)| *k == Some(y)).map_or(&[], |(_, row)| row.as_slice()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::{ImageError, Kind, SourceError}; + use std::sync::atomic::{AtomicUsize, Ordering}; + + /// An 8-bit channel value, as an 8-bit PNG stores it. + fn byte(v: f32) -> i32 { + (v.clamp(0.0, 1.0) * 255.0).round() as i32 + } + + fn normals(src: &Image, options: &HeightNormalOptions) -> Image { + match try_height_to_normal(src, options, &Limits::default()) { + Ok(img) => img, + Err(e) => panic!("normal map failed: {e}"), + } + } + + fn close(a: [f32; 3], b: [f32; 3], tol: f32) -> bool { + a.iter().zip(b).all(|(a, b)| (a - b).abs() <= tol) + } + + fn rgb(img: &Image, x: i64, y: i64) -> [f32; 3] { + let p = img.get(x, y, false); + [p[0], p[1], p[2]] + } + + #[test] + fn height_becomes_normal_detail() { + // Height rises to the right and down the image. + let height = Image::gray(64, 64, |x, y| (x as f32 + y as f32) / 160.0); + let Ok(options) = HeightNormalOptions::uv_tiles(8.0, 64, 1.0) else { panic!("valid options") }; + let n = normals(&height, &options); + let p = n.get(30, 30, false).map(byte); + assert!(p[0] < 120, "slope up to the right tilts the normal left: {p:?}"); + assert!(p[1] > 136, "slope up toward the image bottom tilts an OpenGL normal up: {p:?}"); + assert_eq!(n.get(30, 30, false)[3], 1.0); + let Ok(flat) = HeightNormalOptions::uv_tiles(0.0, 64, 1.0) else { panic!("valid options") }; + assert_eq!(normals(&height, &flat).get(30, 30, false).map(byte), [128, 128, 255, 255]); + } + + #[test] + fn directx_flips_green() { + let (x, y) = (0.3f32, 0.4f32); + let n = [x, y, (1.0 - x * x - y * y).sqrt()]; + let (a, b) = (encode_normal(n, NormalConvention::OpenGl).map(byte), encode_normal(n, NormalConvention::DirectX).map(byte)); + assert_eq!(a[0], byte(x * 0.5 + 0.5)); + assert_eq!(a[1], byte(y * 0.5 + 0.5), "{a:?}"); + assert_eq!(a[0], b[0]); + assert!((a[1] + b[1] - 255).abs() <= 1, "{a:?} vs {b:?}"); + assert_eq!(a[2], b[2]); + } + + #[test] + fn converted_maps_invert_and_derive_normals() { + let height = Image::gray(64, 64, |x, y| (x as f32 + y as f32) / 160.0); + let Ok(gl) = HeightNormalOptions::uv_tiles(8.0, 64, 1.0) else { panic!("valid options") }; + let dx = HeightNormalOptions { convention: NormalConvention::DirectX, ..gl }; + let (a, b) = (normals(&height, &gl).get(30, 30, false), normals(&height, &dx).get(30, 30, false)); + assert_eq!(a[0], b[0]); + assert_eq!(a[2], b[2]); + assert!(byte(a[1]) > 136 && (byte(a[1]) + byte(b[1]) - 255).abs() <= 1, "DirectX flips green: {a:?} vs {b:?}"); + assert!((a[1] + b[1] - 1.0).abs() < 1e-6); + } + + #[test] + fn uv_tiles_export_one_file_per_tile_without_padding_across() { + // Two 16-sample UV tiles side by side: a slope in the left one, a cliff of 100 in the right. + let atlas = Image::gray(32, 16, |x, y| if x < 16 { 0.05 * x as f32 + 0.02 * y as f32 } else { 100.0 }); + let left = Image::gray(16, 16, |x, y| 0.05 * x as f32 + 0.02 * y as f32); + let Ok(options) = HeightNormalOptions::uv_tiles(1.0, 16, 1.0) else { panic!("valid options") }; + let (a, l) = (normals(&atlas, &options), normals(&left, &HeightNormalOptions { boundary: BoundaryMode::ClampToImage, ..options })); + for y in 0..16 { + for x in 0..16 { + assert_eq!(rgb(&a, x, y), rgb(&l, x, y), "({x}, {y}) reads only its own tile"); + } + // The right tile is flat at its own left edge although the left tile is lower. + assert_eq!(rgb(&a, 16, y), [0.5, 0.5, 1.0]); + } + // Without the tile clamp the cliff tilts the last column of the left tile. + let open = normals(&atlas, &HeightNormalOptions { boundary: BoundaryMode::ClampToImage, ..options }); + assert!(open.get(15, 5, false)[0] < 0.1); + } + + #[test] + fn a_plane_gives_the_sobel_normal() { + let (a, b, s) = (0.03f32, -0.07f32, 5.0f32); + let plane = Image::gray(9, 7, |x, y| a * x as f32 + b * y as f32); + let len = ((a * s).powi(2) + (b * s).powi(2) + 1.0).sqrt(); + let want = [-a * s / len, b * s / len, 1.0 / len]; + let h = |x: i64, y: i64| plane.get(x, y, false)[0]; + let hood = [[h(3, 2), h(4, 2), h(5, 2)], [h(3, 3), h(4, 3), h(5, 3)], [h(3, 4), h(4, 4), h(5, 4)]]; + assert!(close(normal_from_neighborhood(hood, s), want, 1e-6)); + let n = normals(&plane, &HeightNormalOptions { strength: s, ..HeightNormalOptions::default() }); + let enc = want.map(|c| 0.5 * c + 0.5); + for (x, y) in [(1, 1), (4, 3), (7, 5)] { + assert!(close(rgb(&n, x, y), enc, 1e-6), "({x}, {y}): {:?} vs {enc:?}", rgb(&n, x, y)); + } + // At the image edge the outside neighbors repeat the edge, halving that axis's slope. + let edge = normal_from_neighborhood([[h(0, 2), h(0, 2), h(1, 2)], [h(0, 3), h(0, 3), h(1, 3)], [h(0, 4), h(0, 4), h(1, 4)]], s); + assert!(close(rgb(&n, 0, 3), encode_normal(edge, NormalConvention::OpenGl), 1e-6)); + } + + /// A height plane whose samples in columns `x >= 2` are not covered. + struct Island(Image); + + impl ScalarSource for Island { + fn dimensions(&self) -> (u32, u32) { + self.0.dimensions() + } + fn read_row(&self, y: u32, x0: u32, out: &mut [f32]) -> Result<(), SourceError> { + self.0.read_row(y, x0, out) + } + fn covered(&self, x: u32, _y: u32) -> bool { + x < 2 + } + } + + #[test] + fn uncovered_neighbors_take_the_center_height() { + let island = Island(Image::gray(4, 3, |x, _| [0.0, 1.0, 50.0, 50.0][x as usize])); + let Ok(n) = try_height_to_normal(&island, &HeightNormalOptions::default(), &Limits::default()) else { panic!("normal map") }; + // At x = 1 the right neighbors are not covered and read as 1, so gx = (1 - 0) / 2. + let want = normal_from_neighborhood([[0.0, 1.0, 1.0]; 3], 1.0); + assert!(close(rgb(&n, 1, 1), encode_normal(want, NormalConvention::OpenGl), 1e-6)); + } + + #[test] + fn zero_and_one_sample_planes() { + let one = Image::gray(1, 1, |_, _| 7.0); + assert_eq!(normals(&one, &HeightNormalOptions { strength: 100.0, ..HeightNormalOptions::default() }).data(), &[0.5, 0.5, 1.0, 1.0]); + let empty = Empty { reads: AtomicUsize::new(0) }; + assert_eq!(try_height_to_normal(&empty, &HeightNormalOptions::default(), &Limits::default()), Err(ImageError::BadSize(0, 0).into())); + assert_eq!(empty.reads.load(Ordering::Relaxed), 0); + } + + /// A source with no samples that counts its reads. + struct Empty { + reads: AtomicUsize, + } + + impl ScalarSource for Empty { + fn dimensions(&self) -> (u32, u32) { + (0, 0) + } + fn read_row(&self, _y: u32, _x0: u32, _out: &mut [f32]) -> Result<(), SourceError> { + self.reads.fetch_add(1, Ordering::Relaxed); + Ok(()) + } + } + + /// A source of any claimed size that fails every read. + struct Failing(u32, u32); + + impl ScalarSource for Failing { + fn dimensions(&self) -> (u32, u32) { + (self.0, self.1) + } + fn read_row(&self, _y: u32, _x0: u32, _out: &mut [f32]) -> Result<(), SourceError> { + Err(SourceError("tile unavailable".into())) + } + } + + #[test] + fn sizes_outside_the_limits_are_rejected_before_reading() { + let open = Limits { max_side: u32::MAX, max_pixels: u64::MAX, max_bytes: u64::MAX }; + let huge = Failing(u32::MAX, u32::MAX); + let o = HeightNormalOptions::default(); + assert_eq!(try_height_to_normal(&huge, &o, &open), Err(ImageError::TooLarge(u32::MAX, u32::MAX).into())); + let small = Limits { max_pixels: 15, ..Limits::default() }; + assert_eq!(try_height_to_normal(&Failing(4, 4), &o, &small), Err(ImageError::TooLarge(4, 4).into())); + assert_eq!(try_height_to_normal(&Failing(9000, 1), &o, &Limits::default()), Err(ImageError::BadSize(9000, 1).into())); + } + + #[test] + fn read_failures_and_non_finite_input_are_errors() { + let o = HeightNormalOptions::default(); + let l = Limits::default(); + assert!(matches!(try_height_to_normal(&Failing(3, 3), &o, &l), Err(TextureOpError::Source { .. }))); + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let Ok(img) = Image::from_data(3, 2, Kind::Gray, vec![0.0, 0.0, 0.0, 0.0, bad, 0.0], &l) else { panic!("valid image") }; + assert_eq!(try_height_to_normal(&img, &o, &l), Err(TextureOpError::NonFiniteSample { x: 1, y: 1 })); + let strength = HeightNormalOptions { strength: bad, ..o }; + assert!(matches!(try_height_to_normal(&Failing(3, 3), &strength, &l), Err(TextureOpError::BadParameter { name: "strength", .. }))); + assert!(matches!(HeightNormalOptions::uv_tiles(bad, 16, 1.0), Err(TextureOpError::BadParameter { name: "height_strength", .. }))); + assert!(matches!(HeightNormalOptions::uv_tiles(1.0, 16, bad), Err(TextureOpError::BadParameter { name: "block_scale", .. }))); + assert_eq!(normal_from_neighborhood([[bad; 3]; 3], 1.0), [0.0, 0.0, 1.0]); + } + assert!(HeightNormalOptions::uv_tiles(1.0, 16, 0.0).is_err()); + assert!(HeightNormalOptions::uv_tiles(1.0, 0, 1.0).is_err()); + assert!(matches!(HeightNormalOptions::uv_tiles(f32::MAX, 16, 1.0), Err(TextureOpError::BadParameter { name: "strength", .. }))); + let block0 = HeightNormalOptions { boundary: BoundaryMode::ClampToBlock { block: 0 }, ..o }; + assert!(matches!(try_height_to_normal(&Failing(3, 3), &block0, &l), Err(TextureOpError::BadParameter { name: "block", .. }))); + } + + #[test] + fn huge_finite_heights_give_unit_normals() { + let l = Limits::default(); + let Ok(img) = Image::from_data(3, 1, Kind::Gray, vec![-f32::MAX, 0.0, f32::MAX], &l) else { panic!("valid image") }; + let n = normals(&img, &HeightNormalOptions { strength: f32::MAX, ..HeightNormalOptions::default() }); + let p = rgb(&n, 1, 0); + assert!(p.iter().all(|c| c.is_finite() && (0.0..=1.0).contains(c)), "{p:?}"); + assert!(p[0] < 1e-6, "the slope points the normal along -x: {p:?}"); + } +} diff --git a/crates/texture/src/packing.rs b/crates/texture/src/packing.rs new file mode 100644 index 000000000..6013c512a --- /dev/null +++ b/crates/texture/src/packing.rs @@ -0,0 +1,230 @@ +//! Occlusion, roughness and metallic packed into one RGBA image. +//! +//! [`try_pack_orm`] writes occlusion to red, roughness to green and metallic to blue, with alpha +//! 1, the channels glTF 2.0 section 3.9 reads its occlusion and metallic-roughness textures from +//! (). Values are linear data copied +//! as the sources give them, with no transfer curve and no clamping. + +use crate::source::{ScalarSource, TextureOpError, read_checked, try_buffer, try_color_image}; +use crate::{Image, Limits}; + +/// Red where no occlusion source is given. +pub const DEFAULT_OCCLUSION: f32 = 1.0; +/// Green where no roughness source is given. +pub const DEFAULT_ROUGHNESS: f32 = 0.5; +/// Blue where no metallic source is given. +pub const DEFAULT_METALLIC: f32 = 0.0; + +/// The planes [`try_pack_orm`] reads. Every given plane has the same size. +/// `#[non_exhaustive]`: start from [`OrmSources::default`], which gives none, and set the fields +/// you use. +#[derive(Clone, Copy, Default)] +#[non_exhaustive] +pub struct OrmSources<'a> { + /// Occlusion, written to red. + pub occlusion: Option<&'a dyn ScalarSource>, + /// A second occlusion plane, such as baked occlusion, multiplied into red when given. Without + /// [`OrmSources::occlusion`], red is this plane alone. + pub occlusion_multiplier: Option<&'a dyn ScalarSource>, + /// Roughness, written to green. + pub roughness: Option<&'a dyn ScalarSource>, + /// Metallic, written to blue. + pub metallic: Option<&'a dyn ScalarSource>, + /// The output size. Required when no plane is given; otherwise every plane must have it. + pub size: Option<(u32, u32)>, +} + +/// The RGBA image `[occlusion, roughness, metallic, 1]` of `sources`. A plane that is not given +/// takes [`DEFAULT_OCCLUSION`], [`DEFAULT_ROUGHNESS`] or [`DEFAULT_METALLIC`]. Rows are read one +/// at a time. +/// +/// Returns [`TextureOpError::SizeMismatch`] when the planes and [`OrmSources::size`] differ in +/// size, [`TextureOpError::NoSize`] when nothing gives a size, an [`crate::ImageError`] when the +/// size is outside `limits` or memory runs out, all before any row is read, +/// [`TextureOpError::NonFiniteSample`] for a NaN or infinite sample, +/// [`TextureOpError::NonFiniteResult`] when the occlusion product overflows, and +/// [`TextureOpError::Source`] when a row cannot be read. +pub fn try_pack_orm(sources: &OrmSources<'_>, limits: &Limits) -> Result { + let mut size = sources.size; + for source in [sources.occlusion, sources.occlusion_multiplier, sources.roughness, sources.metallic].into_iter().flatten() { + let found = source.dimensions(); + match size { + None => size = Some(found), + Some(expected) if expected != found => return Err(TextureOpError::SizeMismatch { expected, found }), + Some(_) => {} + } + } + let (w, h) = size.ok_or(TextureOpError::NoSize)?; + try_color_image(w, h, limits, |y0, rows| fill(sources, w, h, y0, rows)) +} + +/// One plane's current row, or its default when the plane is not given. +struct Plane<'a> { + source: Option<&'a dyn ScalarSource>, + row: Vec, + default: f32, +} + +impl<'a> Plane<'a> { + fn new(source: Option<&'a dyn ScalarSource>, default: f32, w: u32, h: u32) -> Result, TextureOpError> { + let row = if source.is_some() { try_buffer(w as usize, w, h)? } else { Vec::new() }; + Ok(Plane { source, row, default }) + } + + fn load(&mut self, y: u32) -> Result<(), TextureOpError> { + match self.source { + Some(source) => read_checked(source, y, &mut self.row), + None => Ok(()), + } + } + + fn at(&self, x: usize) -> f32 { + self.row.get(x).copied().unwrap_or(self.default) + } +} + +/// Fill the RGBA rows starting at row `y0`. +fn fill(sources: &OrmSources<'_>, w: u32, h: u32, y0: u32, rows: &mut [f32]) -> Result<(), TextureOpError> { + let mut occlusion = Plane::new(sources.occlusion, DEFAULT_OCCLUSION, w, h)?; + let mut multiplier = Plane::new(sources.occlusion_multiplier, 1.0, w, h)?; + let mut roughness = Plane::new(sources.roughness, DEFAULT_ROUGHNESS, w, h)?; + let mut metallic = Plane::new(sources.metallic, DEFAULT_METALLIC, w, h)?; + for (y, out) in (y0..).zip(rows.chunks_exact_mut(w as usize * 4)) { + for plane in [&mut occlusion, &mut multiplier, &mut roughness, &mut metallic] { + plane.load(y)?; + } + for (x, px) in out.as_chunks_mut::<4>().0.iter_mut().enumerate() { + let ao = if sources.occlusion_multiplier.is_some() { occlusion.at(x) * multiplier.at(x) } else { occlusion.at(x) }; + if !ao.is_finite() { + return Err(TextureOpError::NonFiniteResult { x: x as u32, y }); + } + *px = [ao, roughness.at(x), metallic.at(x), 1.0]; + } + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::normal::{HeightNormalOptions, try_height_to_normal}; + use crate::{ImageError, Kind, SourceError}; + + /// An 8-bit channel value, as an 8-bit PNG stores it. + fn byte(v: f32) -> i32 { + (v.clamp(0.0, 1.0) * 255.0).round() as i32 + } + + fn pack(sources: &OrmSources<'_>) -> Image { + match try_pack_orm(sources, &Limits::default()) { + Ok(img) => img, + Err(e) => panic!("packing failed: {e}"), + } + } + + fn constant(v: f32) -> Image { + Image::filled(64, 64, Kind::Gray, [v; 4]) + } + + #[test] + fn gltf_png_matches_the_composite() { + let (rough, metal) = (constant(0.25), constant(0.75)); + let s = OrmSources { roughness: Some(&rough), metallic: Some(&metal), ..OrmSources::default() }; + let orm = pack(&s).get(5, 5, false).map(byte); + assert_eq!(orm[0], 255, "no AO anywhere → white"); + assert!((orm[1] - 64).abs() <= 1 && (orm[2] - 191).abs() <= 1, "{orm:?}"); + assert_eq!(orm[3], 255); + // A flat height gives the flat normal. + let Ok(n) = try_height_to_normal(&constant(0.0), &HeightNormalOptions::default(), &Limits::default()) else { panic!("normal map") }; + let n = n.get(5, 5, false).map(byte); + assert!((n[0] - 128).abs() <= 1 && (n[1] - 128).abs() <= 1 && n[2] == 255, "{n:?}"); + } + + #[test] + fn ao_mixes_baked_and_channel() { + let (channel, baked) = (constant(0.5), constant(0.5)); + let mut s = OrmSources { occlusion: Some(&channel), occlusion_multiplier: Some(&baked), ..OrmSources::default() }; + assert!((byte(pack(&s).get(3, 3, false)[0]) - 64).abs() <= 1); + // Without the multiplier the channel is used alone; without the channel the multiplier is. + s.occlusion_multiplier = None; + assert_eq!(pack(&s).get(3, 3, false)[0], 0.5); + s.occlusion = None; + s.occlusion_multiplier = Some(&baked); + assert_eq!(pack(&s).get(3, 3, false)[0], 0.5); + } + + #[test] + fn each_plane_goes_to_its_own_channel() { + let ao = Image::gray(3, 2, |x, y| 0.1 * (x + 3 * y) as f32); + let rough = Image::gray(3, 2, |x, _| 0.2 + 0.01 * x as f32); + let metal = Image::gray(3, 2, |_, y| 0.9 - 0.5 * y as f32); + let s = OrmSources { occlusion: Some(&ao), roughness: Some(&rough), metallic: Some(&metal), ..OrmSources::default() }; + let orm = pack(&s); + for y in 0..2 { + for x in 0..3 { + let want = [ao.get(x, y, false)[0], rough.get(x, y, false)[0], metal.get(x, y, false)[0], 1.0]; + assert_eq!(orm.get(x, y, false), want, "({x}, {y})"); + } + } + // Values outside 0..=1 are kept. + let hdr = Image::filled(1, 1, Kind::Gray, [-0.5; 4]); + let s = OrmSources { metallic: Some(&hdr), ..OrmSources::default() }; + assert_eq!(pack(&s).data(), &[1.0, 0.5, -0.5, 1.0]); + } + + #[test] + fn missing_planes_take_the_defaults() { + let mut s = OrmSources::default(); + assert_eq!(try_pack_orm(&s, &Limits::default()), Err(TextureOpError::NoSize)); + s.size = Some((2, 1)); + assert_eq!(pack(&s).data(), &[1.0, 0.5, 0.0, 1.0, 1.0, 0.5, 0.0, 1.0]); + s.size = Some((0, 0)); + assert_eq!(try_pack_orm(&s, &Limits::default()), Err(ImageError::BadSize(0, 0).into())); + } + + /// A source of any claimed size that fails every read. + struct Failing(u32, u32); + + impl ScalarSource for Failing { + fn dimensions(&self) -> (u32, u32) { + (self.0, self.1) + } + fn read_row(&self, _y: u32, _x0: u32, _out: &mut [f32]) -> Result<(), SourceError> { + Err(SourceError("tile unavailable".into())) + } + } + + #[test] + fn sizes_are_checked_before_reading() { + let (a, b) = (Failing(4, 4), Failing(4, 5)); + let mut s = OrmSources { roughness: Some(&a), metallic: Some(&b), ..OrmSources::default() }; + assert_eq!(try_pack_orm(&s, &Limits::default()), Err(TextureOpError::SizeMismatch { expected: (4, 4), found: (4, 5) })); + s.metallic = None; + s.size = Some((5, 4)); + assert_eq!(try_pack_orm(&s, &Limits::default()), Err(TextureOpError::SizeMismatch { expected: (5, 4), found: (4, 4) })); + s.size = None; + let tiny = Limits { max_bytes: 63, ..Limits::default() }; + assert_eq!(try_pack_orm(&s, &tiny), Err(ImageError::TooLarge(4, 4).into())); + let huge = Failing(u32::MAX, u32::MAX); + s.roughness = Some(&huge); + let open = Limits { max_side: u32::MAX, max_pixels: u64::MAX, max_bytes: u64::MAX }; + assert_eq!(try_pack_orm(&s, &open), Err(ImageError::TooLarge(u32::MAX, u32::MAX).into())); + s.roughness = Some(&a); + assert!(matches!(try_pack_orm(&s, &Limits::default()), Err(TextureOpError::Source { y: 0, .. }))); + } + + #[test] + fn non_finite_samples_are_errors() { + let l = Limits::default(); + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let Ok(img) = Image::from_data(2, 2, Kind::Gray, vec![0.0, 0.0, 0.0, bad], &l) else { panic!("valid image") }; + let s = OrmSources { occlusion_multiplier: Some(&img), ..OrmSources::default() }; + assert_eq!(try_pack_orm(&s, &l), Err(TextureOpError::NonFiniteSample { x: 1, y: 1 })); + } + // Finite occlusion values whose product overflows. + let Ok(big) = Image::from_data(2, 1, Kind::Gray, vec![1.0, f32::MAX], &l) else { panic!("valid image") }; + let Ok(two) = Image::from_data(2, 1, Kind::Gray, vec![1.0, 2.0], &l) else { panic!("valid image") }; + let s = OrmSources { occlusion: Some(&big), occlusion_multiplier: Some(&two), ..OrmSources::default() }; + assert_eq!(try_pack_orm(&s, &l), Err(TextureOpError::NonFiniteResult { x: 1, y: 0 })); + } +} diff --git a/crates/texture/src/source.rs b/crates/texture/src/source.rs new file mode 100644 index 000000000..f2cf36f68 --- /dev/null +++ b/crates/texture/src/source.rs @@ -0,0 +1,143 @@ +//! Row access to a plane of linear scalar samples, and the errors of the operations that read it. + +use std::sync::Arc; + +#[cfg(feature = "parallel")] +use rayon::prelude::*; + +use crate::{Image, ImageError, Kind, Limits}; + +/// A plane of linear scalar samples that an operation reads one row at a time. +/// +/// An operation keeps a few rows of samples and its output, never a full `f32` copy of the +/// source, so a tiled or encoded image can be read in place: an adapter decodes the samples of a +/// row from whatever storage it has. Samples are data values, such as heights or roughness, read +/// without any transfer curve. +pub trait ScalarSource: Sync { + /// Width and height in samples. + fn dimensions(&self) -> (u32, u32); + + /// Write the samples of row `y` from column `x0` on into `out`, one per element. Operations + /// ask only for rows inside [`ScalarSource::dimensions`] and for `x0 + out.len()` no greater + /// than the width. + fn read_row(&self, y: u32, x0: u32, out: &mut [f32]) -> Result<(), SourceError>; + + /// Whether the sample at `(x, y)` holds data. [`crate::normal::try_height_to_normal`] reads + /// the center sample in place of a neighbor that is not covered. Every sample is covered by + /// default. + fn covered(&self, _x: u32, _y: u32) -> bool { + true + } +} + +/// Why a [`ScalarSource`] could not give a row. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +#[error("{0}")] +pub struct SourceError(pub String); + +/// Why an operation over [`ScalarSource`]s could not make its image. +#[derive(Debug, Clone, PartialEq, thiserror::Error)] +#[non_exhaustive] +pub enum TextureOpError { + /// The output size is outside the limits, or its memory could not be reserved. + #[error(transparent)] + Image(#[from] ImageError), + /// Two sources, or a source and the requested size, differ in size. + #[error("source size {found:?} differs from {expected:?}")] + SizeMismatch { expected: (u32, u32), found: (u32, u32) }, + /// No source is given and no output size either. + #[error("no source or size gives the output size")] + NoSize, + /// A parameter is NaN, infinite or outside its range. + #[error("parameter {name} is {value}, which is not finite or is out of range")] + BadParameter { name: &'static str, value: f64 }, + /// A source gave a NaN or infinite sample. + #[error("sample at ({x}, {y}) is not finite")] + NonFiniteSample { x: u32, y: u32 }, + /// Finite samples gave a NaN or infinite result, such as two occlusion values whose product + /// overflows `f32`. + #[error("result at ({x}, {y}) is not finite")] + NonFiniteResult { x: u32, y: u32 }, + /// A source could not give a row. + #[error("reading row {y}: {error}")] + Source { y: u32, error: SourceError }, +} + +/// An [`Image`] read as a scalar plane: the gray value, or the Rec. 709 luminance of a color +/// image, as [`Image::get_gray`] gives it. +impl ScalarSource for Image { + fn dimensions(&self) -> (u32, u32) { + (self.w, self.h) + } + + fn read_row(&self, y: u32, x0: u32, out: &mut [f32]) -> Result<(), SourceError> { + let end = u64::from(x0) + out.len() as u64; + if y >= self.h || end > u64::from(self.w) { + return Err(SourceError(format!("row {y} from column {x0} for {} samples is outside the {}x{} image", out.len(), self.w, self.h))); + } + for (x, o) in (x0..).zip(out.iter_mut()) { + *o = self.get_gray(i64::from(x), i64::from(y), false); + } + Ok(()) + } +} + +/// Read row `y` of `source` in full into `out`, which holds one row, and reject a non-finite +/// sample. +pub(crate) fn read_checked(source: &S, y: u32, out: &mut [f32]) -> Result<(), TextureOpError> { + source.read_row(y, 0, out).map_err(|error| TextureOpError::Source { y, error })?; + match out.iter().position(|v| !v.is_finite()) { + Some(x) => Err(TextureOpError::NonFiniteSample { x: x as u32, y }), + None => Ok(()), + } +} + +/// A zeroed buffer of `len` floats, reserved fallibly for a `w × h` operation. +pub(crate) fn try_buffer(len: usize, w: u32, h: u32) -> Result, TextureOpError> { + let mut v = Vec::new(); + v.try_reserve_exact(len).map_err(|_| ImageError::OutOfMemory(w, h))?; + v.resize(len, 0.0); + Ok(v) +} + +/// Rows in each band that a worker fills when rows are filled on several threads. +#[cfg(feature = "parallel")] +const BAND_ROWS: usize = 64; + +/// A `w × h` RGBA image whose rows `fill` writes. `fill(y0, rows)` gets the first row index and +/// the floats of whole rows: every row at once without the `parallel` feature, bands of rows on +/// several threads with it. The size is checked against `limits` and the buffer reserved first. +pub(crate) fn try_color_image(w: u32, h: u32, limits: &Limits, fill: F) -> Result +where + F: Fn(u32, &mut [f32]) -> Result<(), TextureOpError> + Sync, +{ + let len = limits.check(w, h, Kind::Color)?; + let mut data = try_buffer(len, w, h)?; + #[cfg(feature = "parallel")] + { + let band = (w as usize * Kind::Color.channels()).saturating_mul(BAND_ROWS); + data.par_chunks_mut(band).enumerate().try_for_each(|(i, rows)| fill((i * BAND_ROWS) as u32, rows))?; + } + #[cfg(not(feature = "parallel"))] + fill(0, &mut data)?; + Ok(Image { w, h, kind: Kind::Color, integer_sampling: false, data: Arc::new(data) }) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn images_read_as_gray_rows() { + let gray = Image::gray(3, 2, |x, y| (x + 10 * y) as f32); + let mut row = [0.0; 2]; + assert_eq!(gray.read_row(1, 1, &mut row), Ok(())); + assert_eq!(row, [11.0, 12.0]); + assert!(gray.read_row(2, 0, &mut row).is_err()); + assert!(gray.read_row(0, 2, &mut row).is_err()); + let color = Image::filled(1, 1, Kind::Color, [1.0, 0.0, 0.0, 1.0]); + let mut one = [0.0]; + assert_eq!(color.read_row(0, 0, &mut one), Ok(())); + assert!((one[0] - 0.2126).abs() < 1e-6); + } +} diff --git a/crates/texture/src/tiled_tests.rs b/crates/texture/src/tiled_tests.rs new file mode 100644 index 000000000..42724a918 --- /dev/null +++ b/crates/texture/src/tiled_tests.rs @@ -0,0 +1,231 @@ +//! Height to normal and ORM packing over a read-only adapter of 256 × 256 copy-on-write tiles of +//! interleaved two-channel U8, U16, F16 or F32 samples, with absent tiles reading a default pixel. + +use std::collections::BTreeMap; +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; + +use crate::normal::{HeightNormalOptions, NormalConvention, encode_normal, normal_from_neighborhood, try_height_to_normal}; +use crate::packing::{OrmSources, try_pack_orm}; +use crate::{Image, Limits, ScalarSource, SourceError}; + +const TILE: u32 = 256; +/// Channels per stored pixel; the adapter reads channel 0. +const CHANNELS: usize = 2; + +#[derive(Clone, Copy, Debug)] +enum SampleType { + U8, + U16, + F16, + F32, +} + +impl SampleType { + fn size(self) -> usize { + match self { + SampleType::U8 => 1, + SampleType::U16 | SampleType::F16 => 2, + SampleType::F32 => 4, + } + } + + fn encode(self, v: f32, out: &mut Vec) { + match self { + SampleType::U8 => out.push((v.clamp(0.0, 1.0) * 255.0).round() as u8), + SampleType::U16 => out.extend(((v.clamp(0.0, 1.0) * 65535.0).round() as u16).to_le_bytes()), + SampleType::F16 => out.extend(half::f16::from_f32(v).to_bits().to_le_bytes()), + SampleType::F32 => out.extend(v.to_le_bytes()), + } + } + + /// The linear value of one stored sample, without a transfer curve. + fn decode(self, b: &[u8]) -> f32 { + match (self, b) { + (SampleType::U8, [v, ..]) => f32::from(*v) / 255.0, + (SampleType::U16, [a, b, ..]) => f32::from(u16::from_le_bytes([*a, *b])) / 65535.0, + (SampleType::F16, [a, b, ..]) => half::f16::from_bits(u16::from_le_bytes([*a, *b])).to_f32(), + (SampleType::F32, [a, b, c, d, ..]) => f32::from_le_bytes([*a, *b, *c, *d]), + _ => panic!("short sample"), + } + } +} + +/// A tiled surface read through [`ScalarSource`] without copying it. +struct Tiled { + w: u32, + h: u32, + ty: SampleType, + tiles: BTreeMap<(u32, u32), Arc>>, + /// One stored pixel, read where a tile is absent. + default: Vec, + reads: AtomicUsize, +} + +impl Tiled { + /// A `w × h` surface whose channel 0 holds `f(x, y)` and channel 1 holds a value that must not + /// be read. The tiles in `absent` are not stored. + fn new(w: u32, h: u32, ty: SampleType, f: impl Fn(u32, u32) -> f32, absent: &[(u32, u32)], default: f32) -> Tiled { + let mut tiles = BTreeMap::new(); + for ty_ in 0..h.div_ceil(TILE) { + for tx in 0..w.div_ceil(TILE) { + if absent.contains(&(tx, ty_)) { + continue; + } + let mut bytes = Vec::with_capacity((TILE * TILE) as usize * CHANNELS * ty.size()); + for y in ty_ * TILE..(ty_ + 1) * TILE { + for x in tx * TILE..(tx + 1) * TILE { + ty.encode(if x < w && y < h { f(x, y) } else { 0.0 }, &mut bytes); + ty.encode(0.37, &mut bytes); + } + } + tiles.insert((tx, ty_), Arc::new(bytes)); + } + } + let mut px = Vec::new(); + ty.encode(default, &mut px); + ty.encode(0.37, &mut px); + Tiled { w, h, ty, tiles, default: px, reads: AtomicUsize::new(0) } + } + + /// The sample at `(x, y)`, looked up on its own. + fn value(&self, x: u32, y: u32) -> f32 { + match self.tiles.get(&(x / TILE, y / TILE)) { + Some(t) => { + let i = (((y % TILE) * TILE + x % TILE) as usize) * CHANNELS * self.ty.size(); + self.ty.decode(&t[i..]) + } + None => self.ty.decode(&self.default), + } + } + + /// The same samples as one untiled gray image. + fn untiled(&self) -> Image { + Image::gray(self.w, self.h, |x, y| self.value(x, y)) + } +} + +impl ScalarSource for Tiled { + fn dimensions(&self) -> (u32, u32) { + (self.w, self.h) + } + + /// Walk the tile segments of the row, holding each tile while its segment is decoded. + fn read_row(&self, y: u32, x0: u32, out: &mut [f32]) -> Result<(), SourceError> { + self.reads.fetch_add(1, Ordering::Relaxed); + if y >= self.h || x0 as usize + out.len() > self.w as usize { + return Err(SourceError("outside the surface".into())); + } + let stride = CHANNELS * self.ty.size(); + let mut x = x0; + let mut rest = out; + while !rest.is_empty() { + let n = ((TILE - x % TILE) as usize).min(rest.len()); + let (seg, tail) = rest.split_at_mut(n); + match self.tiles.get(&(x / TILE, y / TILE)) { + Some(tile) => { + let start = (((y % TILE) * TILE + x % TILE) as usize) * stride; + for (o, px) in seg.iter_mut().zip(tile[start..start + n * stride].chunks_exact(stride)) { + *o = self.ty.decode(px); + } + } + None => seg.fill(self.ty.decode(&self.default)), + } + x += n as u32; + rest = tail; + } + Ok(()) + } +} + +fn normals(src: &S, options: &HeightNormalOptions) -> Image { + match try_height_to_normal(src, options, &Limits::default()) { + Ok(img) => img, + Err(e) => panic!("normal map failed: {e}"), + } +} + +/// A rough, non-planar height in `0..=1`. +fn bumpy(x: u32, y: u32) -> f32 { + ((x * 7 + y * 13 + x * y) % 17) as f32 / 16.0 +} + +/// Normals and ORM values over tiles of `ty` match the same samples untiled, and the samples +/// decode to `0.2`, `0.6` and `1.0` within `tol`. +fn check_sample_type(ty: SampleType, tol: f32) { + let height = Tiled::new(300, 270, ty, bumpy, &[(1, 1)], 0.5); + let opts = HeightNormalOptions { strength: 3.0, ..HeightNormalOptions::default() }; + let tiled = normals(&height, &opts); + assert_eq!(tiled, normals(&height.untiled(), &opts), "{ty:?}"); + // An absent tile reads its default pixel, which is flat. + assert_eq!(tiled.get(280, 260, false), [0.5, 0.5, 1.0, 1.0]); + + let ao = Tiled::new(300, 270, ty, |_, _| 0.2, &[], 0.0); + let rough = Tiled::new(300, 270, ty, |_, _| 0.6, &[], 0.0); + let metal = Tiled::new(300, 270, ty, |_, _| 1.0, &[(0, 0)], 0.6); + let s = OrmSources { occlusion: Some(&ao), roughness: Some(&rough), metallic: Some(&metal), ..OrmSources::default() }; + let Ok(orm) = try_pack_orm(&s, &Limits::default()) else { panic!("packing {ty:?}") }; + // Metallic's tile (0, 0) is absent and reads its default, 0.6. + for (x, y, m) in [(0u32, 0u32, 0.6f32), (299, 269, 1.0), (256, 3, 1.0)] { + let p = orm.get(i64::from(x), i64::from(y), false); + let want = [0.2, 0.6, m, 1.0]; + assert!(p.iter().zip(want).all(|(a, b)| (a - b).abs() <= tol), "{ty:?} ({x}, {y}): {p:?} vs {want:?}"); + assert_eq!(p, [ao.value(x, y), rough.value(x, y), metal.value(x, y), 1.0], "{ty:?} ({x}, {y})"); + } + assert!((orm.get(1, 1, false)[0] - 0.2).abs() <= tol && (orm.get(1, 1, false)[1] - 0.6).abs() <= tol); +} + +#[test] +fn u8_tiles_give_the_untiled_normal_and_orm() { + check_sample_type(SampleType::U8, 1e-7); +} + +#[test] +fn u16_tiles_give_the_untiled_normal_and_orm() { + check_sample_type(SampleType::U16, 1e-7); +} + +#[test] +fn f16_tiles_give_the_untiled_normal_and_orm() { + check_sample_type(SampleType::F16, 1e-3); + // Binary16 rounds 0.2 to 0.199951171875. + assert_eq!(SampleType::F16.decode(&half::f16::from_f32(0.2).to_bits().to_le_bytes()), 0.199_951_17); +} + +#[test] +fn f32_tiles_give_the_untiled_normal_and_orm() { + check_sample_type(SampleType::F32, 0.0); +} + +#[test] +fn storage_tile_seams_read_the_neighbor_tile() { + let (a, b, s) = (0.011f32, -0.004f32, 4.0f32); + let plane = |x: u32, y: u32| a * x as f32 + b * y as f32; + let height = Tiled::new(300, 300, SampleType::F32, plane, &[], 0.0); + let n = normals(&height, &HeightNormalOptions { strength: s, ..HeightNormalOptions::default() }); + let untiled = normals(&height.untiled(), &HeightNormalOptions { strength: s, ..HeightNormalOptions::default() }); + let len = ((a * s).powi(2) + (b * s).powi(2) + 1.0).sqrt(); + let want = [-a * s / len, b * s / len, 1.0 / len].map(|c| 0.5 * c + 0.5); + for (x, y) in [(255, 100), (256, 100), (100, 255), (100, 256), (255, 255), (256, 256), (255, 256), (256, 255)] { + let p = n.get(x, y, false); + assert!(p.iter().zip(want).all(|(p, w)| (p - w).abs() < 1e-4), "({x}, {y}): {p:?} vs {want:?}"); + assert_eq!(p, untiled.get(x, y, false), "({x}, {y})"); + let h = |dx: i64, dy: i64| height.value((x + dx) as u32, (y + dy) as u32); + let hood = [[h(-1, -1), h(0, -1), h(1, -1)], [h(-1, 0), h(0, 0), h(1, 0)], [h(-1, 1), h(0, 1), h(1, 1)]]; + let [r, g, b] = encode_normal(normal_from_neighborhood(hood, s), NormalConvention::OpenGl); + assert_eq!(p, [r, g, b, 1.0], "({x}, {y}) reads both tiles"); + } +} + +#[test] +fn rows_are_read_as_needed_without_a_full_copy() { + let height = Tiled::new(300, 270, SampleType::U16, bumpy, &[], 0.0); + let _ = normals(&height, &HeightNormalOptions::default()); + let reads = height.reads.load(Ordering::Relaxed); + // Each row once; with the `parallel` feature each band of 64 rows also reads the row on + // either side of it. + #[cfg(not(feature = "parallel"))] + assert_eq!(reads, 270); + #[cfg(feature = "parallel")] + assert!((270..=270 + 2 * 270usize.div_ceil(64)).contains(&reads), "{reads}"); +} 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()); + } +} diff --git a/crates/ui/Cargo.toml b/crates/ui/Cargo.toml index e7df43f46..29d7f29f2 100644 --- a/crates/ui/Cargo.toml +++ b/crates/ui/Cargo.toml @@ -51,8 +51,8 @@ color_fonts = ["epaint/color_fonts"] system_fonts = ["dep:fontique", "dep:unicode-script"] # `docking::testing`: a headless driver for application docking tests. testing = [] -# craft_ui::testing: per-language screenshot tests and IME smoke tests with egui_kittest -# (desktop only). +# craft_ui::testing: per-language screenshot tests, IME smoke tests, input steps and review +# screenshots with egui_kittest (desktop only). screen-testing = ["dep:egui_kittest"] [dev-dependencies] diff --git a/crates/ui/README.md b/crates/ui/README.md index f2ae27b0f..a48e49476 100644 --- a/crates/ui/README.md +++ b/crates/ui/README.md @@ -546,6 +546,38 @@ documentation has the recipe for a shortcut smoke test on a non-Latin layout thr letters such as ổ, so an app relying on it fails the `vi` screens until its own face covers them. The per-release manual checks are in [language-testing.md](../../docs/language-testing.md). +### Input steps and review screenshots + +`testing::input` drives any egui_kittest `Harness` with a fixed number of frames per step: +`move_to` (1), `press` and `release` (2 each), `click` (3), `drag` (`steps` + 3, primary button, +1 to `MAX_DRAG_STEPS` moves), `key` (2), `type_text` (2) and `wheel` (2, in points). The modifiers +given to a step are held from its first frame and released in its last; `press` keeps them held +until the matching `release`. A drag with another button is `press`, `move_to` and `release`. The +module documentation lists the events of each frame. The counts hold when no events queued with +`Harness::event` are waiting, so run the harness after queuing events. `docking::testing::DockDriver` runs its own +egui context and keeps its own `window_click` and `window_hold`. + +`testing::snapshot` writes screenshots for review and compares nothing. `snapshot_dir(var)` reads +the folder from the environment variable `var`: `DEFAULT_DIR_VAR` (`CRAFT_UI_SNAPSHOT_DIR`), or an +app's own variable name. With no folder, `with_snapshot_renderer` leaves the builder unchanged and +no GPU is set up; with one, it sets up wgpu and returns `SnapshotError::Render` on a machine that +can't render. `save(harness, dir, name)` renders the last frame to `{dir}/{name}.png`, creating the +folder, and runs no frames, so settle the screen and set the theme first. Names are plain file +names (ASCII letters, digits, `-`, `_`, `.`, `@`). + +```rust,ignore +use craft_ui::testing::{input, snapshot}; +use egui::{Modifiers, PointerButton, pos2}; + +let dir = snapshot::snapshot_dir("CRAFT_EXPORT_SNAPSHOTS"); +let mut harness = snapshot::with_snapshot_renderer(Harness::builder(), dir.as_deref())?.build_ui_state(export_ui, state); +input::click(&mut harness, pos2(40.0, 20.0), PointerButton::Primary, Modifiers::NONE); +harness.run(); +if let Some(dir) = &dir { + snapshot::save(&mut harness, dir, "export-dialog")?; +} +``` + ## Print settings and feedback `printing::State` holds the transient printer selection, copies, duplex and grayscale settings, @@ -678,7 +710,8 @@ verify the actual pixels as well as callback routing. The crate uses egui 0.37 and Rust 1.95 or later. Its production dependency disables egui's default features, so egui's bundled fonts and rendering features remain the application's choice. It has no default features; see [UI fonts](#ui-fonts) for `color_fonts` and `system_fonts`, and -[Testing screens in each language](#testing-screens-in-each-language) for `screen-testing`; +[Testing screens in each language](#testing-screens-in-each-language) for `screen-testing`, which +also adds `testing::input` and `testing::snapshot`; `testing` adds the headless docking driver `docking::testing`. See the [suite audit](../../docs/ui-components-audit.md) for candidates, policies and adoption order. diff --git a/crates/ui/src/combo.rs b/crates/ui/src/combo.rs index 91d70f52b..564875eb7 100644 --- a/crates/ui/src/combo.rs +++ b/crates/ui/src/combo.rs @@ -16,8 +16,8 @@ use std::ops::Range; use egui::{ Align, Align2, AsIdSalt, Atom, AtomExt as _, Atoms, Context, Direction, Frame, Id, IdSalt, InnerResponse, IntoAtoms, LayerId, NumExt as _, Order, - Painter, Popup, PopupCloseBehavior, Rect, RectAlign, Response, Role, ScrollArea, Sense, Shape, TextStyle, TextWrapMode, Ui, Vec2, WidgetAtom, - WidgetInfo, + Painter, Popup, PopupCloseBehavior, Rect, RectAlign, Response, Role, ScrollArea, Sense, Shape, SizedAtomKind, SizedContainerAtom, TextStyle, + TextWrapMode, Ui, Vec2, WidgetAtom, WidgetInfo, class::{ClassName, Classes, HasClasses}, style::{StyleModifier, WidgetVisuals}, vec2, @@ -28,10 +28,12 @@ pub use egui::IconPainter; /// egui's [`egui::ComboBox`] with a menu that grows when its contents do. /// -/// The builder, the button and what the methods return are egui 0.37's. The one difference is -/// the menu: its scroll area is offered the full [`Self::height`] on every pass instead of the +/// The builder, the button's look and what the methods return are egui 0.37's. It differs in two +/// ways. The menu's scroll area is offered the full [`Self::height`] on every pass instead of the /// menu's height on the previous pass, so a menu whose contents shrink and grow again while it -/// is open (a filtered list) grows back. It adds [`Self::show_ui_with_header`] and +/// is open (a filtered list) grows back. When the button cuts the selected text short, hovering +/// it shows the full text in a tooltip, as a truncated [`egui::Label`] does (see +/// [`Self::show_tooltip_when_elided`]). It adds [`Self::show_ui_with_header`] and /// [`Self::show_rows_with_header`] for menus with a search field. /// /// ``` @@ -49,6 +51,7 @@ pub struct ComboBox<'a> { height: Option, icon: Option, wrap_mode: Option, + show_tooltip_when_elided: bool, close_behavior: Option, popup_style: StyleModifier, classes: Classes, @@ -72,6 +75,7 @@ impl<'a> ComboBox<'a> { height: None, icon: None, wrap_mode: None, + show_tooltip_when_elided: true, close_behavior: None, popup_style: StyleModifier::default(), classes: Classes::default(), @@ -146,6 +150,15 @@ impl<'a> ComboBox<'a> { self } + /// Whether hovering the button shows the full selected text in a tooltip when the button cuts + /// it short, as [`egui::Label::show_tooltip_when_elided`] does. Default: `true`. A caller that + /// puts its own tooltip on the button can turn this off so the two do not stack. + #[inline] + pub fn show_tooltip_when_elided(mut self, show: bool) -> Self { + self.show_tooltip_when_elided = show; + self + } + /// When the menu closes. Default: [`PopupCloseBehavior::CloseOnClick`]. #[inline] pub fn close_behavior(mut self, close_behavior: PopupCloseBehavior) -> Self { @@ -268,7 +281,7 @@ fn show(ui: &mut Ui, button_id: Id, mut combo: ComboBox<'_>, open: impl FnOnc let wrap_mode = combo.wrap_mode.unwrap_or_else(|| ui.wrap_mode()); let close_behavior = combo.close_behavior.unwrap_or(PopupCloseBehavior::CloseOnClick); combo.set_class(ComboBox::CLASS_OPEN, is_popup_open); - let ComboBox { label, selected_text, width, height, icon, popup_style, classes, .. } = combo; + let ComboBox { label, selected_text, width, height, icon, show_tooltip_when_elided, popup_style, classes, .. } = combo; // Built from the same atoms and style as a `Button`, so the two line up when put side by side. let ButtonStyle { atom_layout: atom_layout_style } = ui.widget_style(button_id, &classes); @@ -311,16 +324,33 @@ fn show(ui: &mut Ui, button_id: Id, mut combo: ComboBox<'_>, open: impl FnOnc ) .min_size(min_size); - let (button_response, label_response) = match label { + let (button_response, label_response, elided) = match label { Some(label) => { let label_text = label.text().map(String::from).unwrap_or_default(); - let outer_response = - WidgetAtom::new((Atom::widget(button), label)).gap(ui.spacing().item_spacing.x).direction(direction).show(ui).response; + let outer = + WidgetAtom::new((Atom::widget(button), label)).gap(ui.spacing().item_spacing.x).direction(direction).measure(ui, ui.available_size()); + let elided = outer.container.iter_kinds().any(|kind| matches!(kind, SizedAtomKind::Widget(button) if cut_short(&button.container))); + let outer_response = outer.allocate(ui).paint(ui).response; outer_response.widget_info(|| WidgetInfo::labeled(Role::Label, ui.is_enabled(), &label_text)); let button_response = ui.ctx().read_response(button_id).unwrap_or_else(|| outer_response.clone()); - (button_response, Some((outer_response, !label_text.is_empty()))) + (button_response, Some((outer_response, !label_text.is_empty())), elided) } - None => (button.show(ui).response, None), + None => { + let button = button.measure(ui, ui.available_size()); + let elided = cut_short(&button.container); + (button.allocate(ui).paint(ui).response, None, elided) + } + }; + // A selected text cut short shows in full on hover, as a truncated `Label`'s does: all of + // its text atoms, as screen readers receive them. `on_hover_ui` rather than `on_hover_text`, + // which would also make the text the button's accessible name and description. + let button_response = if show_tooltip_when_elided && elided { + button_response.on_hover_ui(|ui| { + ui.set_max_width(ui.spacing().tooltip_width); + ui.add(egui::Label::new(accessible_text.as_str()).wrap()); + }) + } else { + button_response }; button_response.widget_info(|| { @@ -348,6 +378,11 @@ fn show(ui: &mut Ui, button_id: Id, mut combo: ComboBox<'_>, open: impl FnOnc } } +/// Whether the button cut any of its selected text short. +fn cut_short(button: &SizedContainerAtom<'_>) -> bool { + button.iter_texts().any(|galley| galley.elided) +} + fn paint_default_icon(painter: &Painter, rect: Rect, visuals: &WidgetVisuals) { let rect = Rect::from_center_size(rect.center(), vec2(rect.width() * 0.7, rect.height() * 0.45)); painter.add(Shape::rotated_triangle(rect, 0.0, visuals.fg_stroke.color)); diff --git a/crates/ui/src/combo/tests.rs b/crates/ui/src/combo/tests.rs index fbef2413a..8cc754f2d 100644 --- a/crates/ui/src/combo/tests.rs +++ b/crates/ui/src/combo/tests.rs @@ -1,4 +1,7 @@ -use egui_kittest::{Harness, kittest::Queryable as _}; +use egui_kittest::{ + Harness, + kittest::{NodeT as _, Queryable as _}, +}; use super::ComboBox; @@ -142,6 +145,117 @@ fn show_index_picks_a_choice_and_marks_the_response_changed() { assert!(h.query_by_label("Medium").is_none(), "picking closes the menu"); } +const LONG_NAME: &str = "Artboard 12, back cover with the bleed and the fold marks"; + +/// A combo box with `LONG_NAME` selected, in room `width` wide, built by `combo`. +fn long_name_with(labeled: bool, width: f32, combo: impl Fn(ComboBox<'static>) -> ComboBox<'static> + 'static) -> Harness<'static> { + let mut h = Harness::builder().with_size(egui::vec2(600.0, 200.0)).with_accessibility_check(false).build_ui(move |ui| { + ui.set_max_width(width); + let plain = if labeled { ComboBox::new("board", "Board") } else { ComboBox::from_id_salt("board") }; + let _ = combo(plain.selected_text(LONG_NAME).width(100.0)).show_ui(ui, |ui| ui.label(LONG_NAME)); + }); + h.ctx.all_styles_mut(|style| style.interaction.tooltip_delay = 0.0); + h.run(); + h +} + +/// A truncating combo box with `LONG_NAME` selected, in room `width` wide. +fn long_name(labeled: bool, width: f32) -> Harness<'static> { + long_name_with(labeled, width, ComboBox::truncate) +} + +/// Whether a tooltip shows `LONG_NAME` in full. +fn shows_in_full(h: &Harness<'_>) -> bool { + h.query_all_by_role(egui::Role::Label).any(|node| node.accesskit_node().value().as_deref() == Some(LONG_NAME)) +} + +#[test] +fn a_selected_text_cut_short_shows_in_full_on_hover() { + for labeled in [true, false] { + for (width, cut) in [(200.0, true), (600.0, false)] { + let mut h = long_name(labeled, width); + assert!(!shows_in_full(&h), "labeled {labeled}, {width}: no tooltip before the hover"); + h.get_by_role(egui::Role::ComboBox).hover(); + h.run(); + assert_eq!(shows_in_full(&h), cut, "labeled {labeled}, {width}: a tooltip shows the full text only when it is cut short"); + let node = h.get_by_role(egui::Role::ComboBox); + let node = node.accesskit_node(); + assert_eq!(node.value().as_deref(), Some(LONG_NAME), "labeled {labeled}, {width}: screen readers receive the full text"); + assert_eq!(node.description(), None, "labeled {labeled}, {width}: the tooltip does not describe the combo box"); + if !labeled { + assert_eq!(node.label(), None, "{width}: the tooltip does not name an unlabeled combo box"); + } + } + } +} + +#[test] +fn a_selected_text_cut_short_by_the_uis_wrap_mode_shows_in_full_on_hover() { + let text = [LONG_NAME; 3].join(", "); + let shown = text.clone(); + let mut h = Harness::builder().with_size(egui::vec2(600.0, 300.0)).with_accessibility_check(false).build_ui(move |ui| { + ui.set_max_width(200.0); + let _ = ComboBox::new("board", "Board").selected_text(shown.as_str()).width(100.0).show_ui(ui, |ui| ui.label("Other")); + }); + h.ctx.all_styles_mut(|style| { + style.interaction.tooltip_delay = 0.0; + style.wrap_mode = Some(egui::TextWrapMode::Truncate); + }); + h.run(); + h.get_by_role(egui::Role::ComboBox).hover(); + h.run(); + let button = h.get_by_role(egui::Role::ComboBox).rect(); + let tooltip = h.query_all_by_role(egui::Role::Label).find(|node| node.accesskit_node().value().as_deref() == Some(text.as_str())); + let tooltip = tooltip.map(|node| node.rect()); + assert!(tooltip.is_some(), "a combo box in a truncating Ui shows its cut text on hover"); + assert!( + tooltip.is_some_and(|rect| rect.height() > button.height()), + "the tooltip wraps the text onto several lines rather than cutting it short again: {tooltip:?}, button {button:?}" + ); +} + +#[test] +fn the_tooltip_for_a_cut_selected_text_can_be_turned_off() { + let mut h = long_name_with(false, 200.0, |combo| combo.truncate().show_tooltip_when_elided(false)); + h.get_by_role(egui::Role::ComboBox).hover(); + h.run(); + assert!(!shows_in_full(&h), "no tooltip when it is turned off"); +} + +#[test] +fn a_callers_tooltip_still_names_and_describes_a_cut_combo_box() { + let mut h = Harness::builder().with_size(egui::vec2(600.0, 200.0)).with_accessibility_check(false).build_ui(|ui| { + ui.set_max_width(200.0); + let combo = ComboBox::from_id_salt("board").selected_text(LONG_NAME).width(100.0).truncate().show_ui(ui, |ui| ui.label(LONG_NAME)); + let _ = combo.response.on_hover_text("Artboard"); + }); + h.ctx.all_styles_mut(|style| style.interaction.tooltip_delay = 0.0); + h.run(); + h.get_by_role(egui::Role::ComboBox).hover(); + h.run(); + let node = h.get_by_role(egui::Role::ComboBox); + let node = node.accesskit_node(); + assert_eq!(node.label().as_deref(), Some("Artboard"), "the caller's tooltip names the combo box"); + assert_eq!(node.description().as_deref(), Some("Artboard"), "the caller's tooltip describes the combo box"); +} + +#[test] +fn a_selected_text_of_several_atoms_shows_all_of_them_on_hover() { + let mut h = Harness::builder().with_size(egui::vec2(600.0, 200.0)).build_ui(|ui| { + ui.set_max_width(200.0); + let _ = ComboBox::new("board", "Board").selected_text(("12", LONG_NAME)).width(100.0).truncate().show_ui(ui, |ui| ui.label(LONG_NAME)); + }); + h.ctx.all_styles_mut(|style| style.interaction.tooltip_delay = 0.0); + h.run(); + h.get_by_role(egui::Role::ComboBox).hover(); + h.run(); + let full = format!("12 {LONG_NAME}"); + assert!( + h.query_all_by_role(egui::Role::Label).any(|node| node.accesskit_node().value().as_deref() == Some(full.as_str())), + "the tooltip shows {full:?}" + ); +} + fn sizes(ui: &mut egui::Ui, rows: usize) { for n in 0..rows { let size = SIZES.get(n).map_or_else(|| format!("Row {n}"), |s| (*s).to_owned()); diff --git a/crates/ui/src/docking/model.rs b/crates/ui/src/docking/model.rs index 75cd3cfa9..944b61ff1 100644 --- a/crates/ui/src/docking/model.rs +++ b/crates/ui/src/docking/model.rs @@ -108,6 +108,11 @@ pub struct Monitor { pub rect: [f32; 4], /// Physical pixels per logical point. pub scale: f32, + /// The part of `rect` windows may use, without the taskbar, Dock or menu bar: + /// `[x, y, width, height]` on the desktop. Restored native windows keep their bar in it. + /// None, or an area outside `rect`: all of `rect`. + #[cfg_attr(feature = "serde", serde(default, skip_serializing_if = "Option::is_none"))] + pub work_area: Option<[f32; 4]>, } /// A window id no other window of this process has drawn, from a random start so ids saved @@ -583,7 +588,7 @@ pub(super) fn valid_rect(rect: [f32; 4]) -> bool { /// A floating window's saved monitor and monitor size, each where given. fn valid_monitor(monitor: Option<&Monitor>, monitor_size: Option<[f32; 2]>) -> bool { - monitor.is_none_or(|m| valid_rect(m.rect) && m.scale.is_finite() && m.scale > 0.0) + monitor.is_none_or(|m| valid_rect(m.rect) && m.scale.is_finite() && m.scale > 0.0 && m.work_area.is_none_or(valid_rect)) && monitor_size.is_none_or(|[w, h]| valid_rect([0.0, 0.0, w, h])) } diff --git a/crates/ui/src/docking/model_tests.rs b/crates/ui/src/docking/model_tests.rs index 3c541f101..7019eaa6b 100644 --- a/crates/ui/src/docking/model_tests.rs +++ b/crates/ui/src/docking/model_tests.rs @@ -452,8 +452,12 @@ fn dock_validation_rejects_two_docks_per_side_nested_docks_empty_columns_and_bad native.floating[0].native = Some([0.0, 0.0, -1.0, 10.0]); assert_eq!(native.validate(), Err(DockError::InvalidGeometry)); let mut monitor = docked(); - monitor.floating[0].monitor = Some(super::Monitor { name: None, rect: [0.0, 0.0, 1920.0, 1080.0], scale: f32::NAN }); + monitor.floating[0].monitor = Some(super::Monitor { name: None, rect: [0.0, 0.0, 1920.0, 1080.0], scale: f32::NAN, work_area: None }); assert_eq!(monitor.validate(), Err(DockError::InvalidGeometry)); + let mut work_area = docked(); + work_area.floating[0].monitor = + Some(super::Monitor { name: None, rect: [0.0, 0.0, 1920.0, 1080.0], scale: 1.0, work_area: Some([0.0, 0.0, f32::NAN, 1040.0]) }); + assert_eq!(work_area.validate(), Err(DockError::InvalidGeometry)); let mut monitor_size = docked(); monitor_size.floating[0].monitor_size = Some([f32::NAN, 1080.0]); assert_eq!(monitor_size.validate(), Err(DockError::InvalidGeometry)); diff --git a/crates/ui/src/docking/native_tests.rs b/crates/ui/src/docking/native_tests.rs index 70d69498a..5a947ef79 100644 --- a/crates/ui/src/docking/native_tests.rs +++ b/crates/ui/src/docking/native_tests.rs @@ -334,13 +334,14 @@ fn a_window_keeps_its_id_and_os_window_when_its_first_panel_moves_out() { #[test] fn a_moved_window_reports_its_place_and_monitor() { let mut d = driver(layout(true)); - d.monitors = vec![Monitor { name: Some("left".into()), rect: [0.0, 0.0, 1920.0, 1080.0], scale: 1.0 }]; + let left = Monitor { name: Some("left".into()), rect: [0.0, 0.0, 1920.0, 1080.0], scale: 1.0, work_area: Some([0.0, 0.0, 1920.0, 1040.0]) }; + d.monitors = vec![left.clone()]; let viewport = d.viewport(window(&d, 5).id); d.host().windows.get_mut(&viewport).unwrap().rect = Rect::from_min_size(pos2(700.0, 200.0), vec2(240.0, 300.0)); let out = d.step(vec![]); assert!(out.actions.contains(&Action::SetNative { panel: 5, rect: Some([700.0, 200.0, 240.0, 300.0]) }), "{:?}", out.actions); assert_eq!(window(&d, 5).rect, [600.0, 150.0, 240.0, 300.0], "the in-window rect follows"); - assert_eq!(window(&d, 5).monitor.as_ref().and_then(|m| m.name.as_deref()), Some("left")); + assert_eq!(window(&d, 5).monitor, Some(left)); // Without a monitor list, the size egui reports. let mut d = driver(layout(true)); @@ -351,8 +352,8 @@ fn a_moved_window_reports_its_place_and_monitor() { #[test] fn a_restored_window_opens_on_a_connected_monitor() { - let left = Monitor { name: Some("left".into()), rect: [0.0, 0.0, 1920.0, 1080.0], scale: 1.0 }; - let right = Monitor { name: Some("right".into()), rect: [1920.0, 0.0, 2560.0, 1440.0], scale: 2.0 }; + let left = Monitor { name: Some("left".into()), rect: [0.0, 0.0, 1920.0, 1080.0], scale: 1.0, work_area: None }; + let right = Monitor { name: Some("right".into()), rect: [1920.0, 0.0, 2560.0, 1440.0], scale: 2.0, work_area: None }; let mut saved = layout(true); saved.floating[0].native = Some([3000.0, 100.0, 240.0, 300.0]); saved.floating[0].monitor = Some(right.clone()); @@ -366,12 +367,23 @@ fn a_restored_window_opens_on_a_connected_monitor() { // Unplugged: the main window's monitor, at the same offset. let mut d = DockDriver::new(Layout::default(), Content::default()).with_native_host(ORIGIN); - d.monitors = vec![left]; - d.layout = saved; + d.monitors = vec![left.clone()]; + d.layout = saved.clone(); d.settle(); assert_eq!(os_window(&d, 5).unwrap().0.min, pos2(1080.0, 100.0)); assert_eq!(window(&d, 5).native, Some([1080.0, 100.0, 240.0, 300.0])); assert_eq!(window(&d, 5).monitor.as_ref().and_then(|m| m.name.as_deref()), Some("left")); + + // Its bar under the taskbar: up into the monitor's work area. + let left = Monitor { work_area: Some([0.0, 0.0, 1920.0, 1040.0]), ..left }; + saved.floating[0].native = Some([500.0, 1050.0, 240.0, 300.0]); + saved.floating[0].monitor = Some(left.clone()); + let mut d = DockDriver::new(Layout::default(), Content::default()).with_native_host(ORIGIN); + d.monitors = vec![left]; + d.layout = saved; + d.settle(); + assert_eq!(os_window(&d, 5).unwrap().0.min, pos2(500.0, 740.0)); + assert_eq!(window(&d, 5).native, Some([500.0, 740.0, 240.0, 300.0])); } /// The last `InnerSize`, `MinInnerSize` and `MaxInnerSize` sent to `viewport`. @@ -577,6 +589,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}; @@ -678,7 +734,8 @@ fn unused_keys_in_a_native_window_reach_the_app() { #[test] fn a_native_window_saves_its_id_place_and_monitor() { let mut layout = layout(true); - let monitor = Monitor { name: Some("DP-1".into()), rect: [-1920.0, 0.0, 1920.0, 1080.0], scale: 1.5 }; + let monitor = + Monitor { name: Some("DP-1".into()), rect: [-1920.0, 0.0, 1920.0, 1080.0], scale: 1.5, work_area: Some([-1920.0, 25.0, 1920.0, 1055.0]) }; layout.floating[0].native = Some([-1500.0, 100.0, 240.0, 300.0]); layout.floating[0].monitor = Some(monitor); layout.floating.push(Floating { @@ -690,6 +747,10 @@ fn a_native_window_saves_its_id_place_and_monitor() { let back: Layout = serde_json::from_str(&json).unwrap(); assert_eq!(back, layout); assert_eq!(back.floating.iter().map(|w| w.id).collect::>(), layout.floating.iter().map(|w| w.id).collect::>()); + // A monitor saved without a work area reads as one without, and writes none. + let old: Monitor = serde_json::from_str(r#"{"name": "DP-1", "rect": [0, 0, 1920, 1080], "scale": 1}"#).unwrap(); + assert_eq!(old.work_area, None); + assert!(!serde_json::to_string(&old).unwrap().contains("work_area")); // Old layouts get fresh ids, and copies of one id unique ones. let old = r#"{"root": null, "floating": [{"panels": [5], "active": 0, "rect": [0, 0, 100, 100]}, {"panels": [6], "active": 0, "rect": [0, 0, 100, 100]}]}"#; @@ -1200,7 +1261,7 @@ fn a_changed_layout_moves_the_os_window() { assert_eq!(window(&d, 5).native, Some([700.0, 200.0, 260.0, 320.0])); // Off every monitor: onto the nearest, and the layout follows. - d.monitors = vec![Monitor { name: Some("left".into()), rect: [0.0, 0.0, 1920.0, 1080.0], scale: 1.0 }]; + d.monitors = vec![Monitor { name: Some("left".into()), rect: [0.0, 0.0, 1920.0, 1080.0], scale: 1.0, work_area: None }]; d.layout.floating[0].native = Some([5000.0, 200.0, 260.0, 320.0]); d.settle(); assert_eq!(d.host().windows[&viewport].rect.min, pos2(1660.0, 200.0)); diff --git a/crates/ui/src/docking/placement.rs b/crates/ui/src/docking/placement.rs index 82856c8d4..c0c666f6c 100644 --- a/crates/ui/src/docking/placement.rs +++ b/crates/ui/src/docking/placement.rs @@ -37,6 +37,15 @@ fn to_rect([x, y, w, h]: [f32; 4]) -> Rect { Rect::from_min_size(pos2(x, y), Vec2::new(w, h)) } +/// The part of `monitor` windows may use: its work area where that lies on it, else all of it. +fn area(monitor: &Monitor) -> [f32; 4] { + let work = monitor.work_area.filter(|work| work.iter().all(|v| v.is_finite())); + match work.map(|work| to_rect(work).intersect(to_rect(monitor.rect))) { + Some(on) if on.is_finite() && on.width() > 0.0 && on.height() > 0.0 => [on.left(), on.top(), on.width(), on.height()], + _ => monitor.rect, + } +} + /// The monitor holding the center of `rect`, else the one nearest to it. None for an empty /// list. pub(super) fn monitor_of(monitors: &[Monitor], rect: [f32; 4]) -> Option<&Monitor> { @@ -47,24 +56,27 @@ pub(super) fn monitor_of(monitors: &[Monitor], rect: [f32; 4]) -> Option<&Monito .or_else(|| monitors().min_by(|a, b| to_rect(a.rect).distance_sq_to_pos(center).total_cmp(&to_rect(b.rect).distance_sq_to_pos(center)))) } -/// Whether enough of the bar along the top of `rect` lies on one of `monitors` to grab it. -fn reachable(rect: [f32; 4], monitors: &[Monitor]) -> bool { +/// Whether enough of the bar along the top of `rect` lies in `area` to grab it. +fn reachable_in(rect: [f32; 4], area: [f32; 4]) -> bool { let [x, y, w, _] = rect; - let bar = to_rect([x, y, w, BAR_HEIGHT]); - monitors.iter().filter(|m| usable(m)).any(|m| { - let on = bar.intersect(to_rect(m.rect)); - on.width() >= REACHABLE[0].min(w) && on.height() >= REACHABLE[1] - }) + let on = to_rect([x, y, w, BAR_HEIGHT]).intersect(to_rect(area)); + on.width() >= REACHABLE[0].min(w) && on.height() >= REACHABLE[1] } -/// `rect` made safe, and moved wholly onto the nearest of `monitors` when too little of its -/// bar lies on any to grab it. Without a monitor list, only made safe. +/// Whether enough of the bar along the top of `rect` lies in the work area of one of +/// `monitors` to grab it. +fn reachable(rect: [f32; 4], monitors: &[Monitor]) -> bool { + monitors.iter().filter(|m| usable(m)).any(|m| reachable_in(rect, area(m))) +} + +/// `rect` made safe, and moved wholly into the work area of the nearest of `monitors` when +/// too little of its bar lies in any to grab it. Without a monitor list, only made safe. pub(super) fn kept_reachable(rect: [f32; 4], monitors: &[Monitor]) -> [f32; 4] { let rect = sanitized(rect); if !monitors.iter().any(usable) || reachable(rect, monitors) { return rect; } - monitor_of(monitors, rect).map_or(rect, |m| clamp_onto(rect, m.rect)) + monitor_of(monitors, rect).map_or(rect, |m| clamp_onto(rect, area(m))) } /// `rect` moved, and shrunk if it must be, to lie wholly on `area`. @@ -78,13 +90,18 @@ fn clamp_onto(rect: [f32; 4], area: [f32; 4]) -> [f32; 4] { /// Where a native window from a saved layout opens. /// +/// - Enough of its bar lies in the work area of a connected monitor to grab it: the saved +/// rect, whatever monitor it was saved on. /// - Its saved monitor (`monitor`), found in `monitors` by name or else by rect, is connected: -/// the saved rect, moved in proportion if that monitor's rect changed, and onto it if too -/// little of its bar lies on a monitor to grab it. -/// - It is not: the main window's monitor, at the same offset from its origin. +/// the saved rect, moved in proportion if that monitor's rect changed, and into its work +/// area. +/// - It is not: the main window's monitor, at the same offset from its origin, and into its +/// work area. /// - No monitor list: the main window's monitor as egui reports it, by its size alone. Its /// origin is taken as the multiple of that size nearest below the main window's center, -/// which holds for a row or grid of monitors of one size. +/// which holds for a row or grid of monitors of one size. When that area does not hold the +/// main window, the guess is wrong: a window whose bar lies on the main window stays, and +/// any other moves onto the main window, no larger than the monitor. /// /// A window that moves to another monitor ends up wholly on it. pub(super) fn restore(saved: [f32; 4], monitor: Option<&Monitor>, monitors: &[Monitor], main: Option, monitor_size: Option) -> [f32; 4] { @@ -94,7 +111,22 @@ pub(super) fn restore(saved: [f32; 4], monitor: Option<&Monitor>, monitors: &[Mo let (Some(main), Some(size)) = (main, monitor_size.filter(|s| s.is_finite() && s.x >= 1.0 && s.y >= 1.0)) else { return saved }; let center = to_rect(main).center(); let origin = Pos2::new((center.x / size.x).floor() * size.x, (center.y / size.y).floor() * size.y); - return clamp_onto(saved, [origin.x, origin.y, size.x, size.y]); + let guess = [origin.x, origin.y, size.x, size.y]; + if to_rect(guess).contains_rect(to_rect(main)) { + return clamp_onto(saved, guess); + } + if reachable_in(saved, main) { + return saved; + } + let [x, y, w, h] = saved; + let [mx, my, mw, mh] = main; + let (w, h) = (w.min(size.x), h.min(size.y)); + // As in `clamp_onto`, but the window shrinks only to the monitor's size, not the main + // window's. + return sanitized([x.min(mx + mw - w).max(mx), y.min(my + mh - h).max(my), w, h]); + } + if reachable(saved, monitors) { + return saved; } let main_monitor = main.and_then(|main| monitor_of(monitors, main)).or_else(|| monitors.iter().find(|m| usable(m))); let connected = monitor.and_then(|old| { @@ -103,33 +135,21 @@ pub(super) fn restore(saved: [f32; 4], monitor: Option<&Monitor>, monitors: &[Mo }); let [x, y, w, h] = saved; match (connected, monitor) { - (Some((old, now)), _) if old.rect == now.rect => { - if reachable(saved, monitors) { - saved - } else { - clamp_onto(saved, now.rect) - } - } + (Some((old, now)), _) if old.rect == now.rect => clamp_onto(saved, area(now)), (Some((old, now)), _) => { let [ox, oy, ow, oh] = old.rect; let [nx, ny, nw, nh] = now.rect; let (sx, sy) = if usable(old) { (nw / ow, nh / oh) } else { (1.0, 1.0) }; - clamp_onto([nx + (x - ox) * sx, ny + (y - oy) * sy, w, h], now.rect) + clamp_onto([nx + (x - ox) * sx, ny + (y - oy) * sy, w, h], area(now)) } (None, Some(old)) => { let Some(target) = main_monitor else { return saved }; let [ox, oy, ..] = old.rect; let [tx, ty, ..] = target.rect; let (dx, dy) = if usable(old) { (x - ox, y - oy) } else { (0.0, 0.0) }; - clamp_onto([tx + dx, ty + dy, w, h], target.rect) - } - // No saved monitor: the window stays where its bar can be grabbed. - (None, None) => { - if reachable(saved, monitors) { - return saved; - } - main_monitor.map_or(saved, |target| clamp_onto(saved, target.rect)) + clamp_onto([tx + dx, ty + dy, w, h], area(target)) } + (None, None) => main_monitor.map_or(saved, |target| clamp_onto(saved, area(target))), } } @@ -139,7 +159,7 @@ mod tests { use egui::vec2; fn monitor(name: &str, rect: [f32; 4], scale: f32) -> Monitor { - Monitor { name: Some(name.into()), rect, scale } + Monitor { name: Some(name.into()), rect, scale, work_area: None } } fn main_at(x: f32, y: f32) -> Option { @@ -238,6 +258,55 @@ mod tests { assert!((x - area[0]).abs() < 0.01, "{x}"); } + #[test] + fn a_bar_under_the_taskbar_moves_into_the_work_area() { + let work = Monitor { work_area: Some([0.0, 0.0, 1920.0, 1040.0]), ..monitor("left", LEFT, 1.0) }; + let monitors = [work.clone()]; + let under = [100.0, 1045.0, 400.0, 300.0]; + assert_eq!(restore(under, Some(&work), &monitors, main_at(100.0, 100.0), None), [100.0, 740.0, 400.0, 300.0]); + assert_eq!(restore(under, None, &monitors, main_at(100.0, 100.0), None), [100.0, 740.0, 400.0, 300.0]); + assert_eq!(kept_reachable(under, &monitors), [100.0, 740.0, 400.0, 300.0]); + // A bar in the work area stays, the body below it too. + let low = [100.0, 1000.0, 400.0, 300.0]; + assert_eq!(restore(low, Some(&work), &monitors, main_at(100.0, 100.0), None), low); + // Unplugged: the main window's monitor, into its work area. + let gone = monitor("gone", RIGHT, 2.0); + assert_eq!(restore([2000.0, 1300.0, 400.0, 300.0], Some(&gone), &monitors, main_at(100.0, 100.0), None), [80.0, 740.0, 400.0, 300.0]); + // A work area that is not finite or lies off the monitor: all of the monitor. + for area in [[f32::NAN, 0.0, 1920.0, 1040.0], [3000.0, 0.0, 100.0, 100.0], [0.0, 0.0, -5.0, 1040.0]] { + let monitors = [Monitor { work_area: Some(area), ..monitor("left", LEFT, 1.0) }]; + assert_eq!(kept_reachable(under, &monitors), under, "{area:?}"); + assert_eq!(kept_reachable([100.0, 1075.0, 400.0, 300.0], &monitors), [100.0, 780.0, 400.0, 300.0], "{area:?}"); + } + // Part of the work area off the monitor: only the part on it. + let monitors = [Monitor { work_area: Some([-100.0, 0.0, 2020.0, 1040.0]), ..monitor("left", LEFT, 1.0) }]; + assert_eq!(kept_reachable([-300.0, 100.0, 300.0, 300.0], &monitors), [0.0, 100.0, 300.0, 300.0]); + } + + #[test] + fn a_visible_window_stays_when_its_monitor_moves() { + let old = monitor("left", LEFT, 1.0); + let monitors = [monitor("left", [100.0, 0.0, 1920.0, 1080.0], 1.0)]; + let saved = [200.0, 200.0, 400.0, 300.0]; + assert_eq!(restore(saved, Some(&old), &monitors, main_at(100.0, 100.0), None), saved); + // Off the moved monitor: moved with it. + assert_eq!(restore([2100.0, 200.0, 400.0, 300.0], Some(&old), &monitors, main_at(100.0, 100.0), None), [1620.0, 200.0, 400.0, 300.0]); + } + + #[test] + fn without_a_monitor_list_a_wrong_guess_puts_the_window_on_the_main_window() { + // The real monitor is [2500, 0, 1000, 800]; the multiple of its size below the main + // window's center is 2000, which does not hold the main window. + let main = Some(Rect::from_min_size(pos2(2600.0, 100.0), vec2(600.0, 400.0))); + let size = Some(vec2(1000.0, 800.0)); + assert_eq!(restore([0.0, 100.0, 400.0, 300.0], None, &[], main, size), [2600.0, 100.0, 400.0, 300.0]); + // Its bar on the main window: it stays. + let on = [3000.0, 300.0, 400.0, 300.0]; + assert_eq!(restore(on, None, &[], main, size), on); + // Larger than the main window: at its top-left corner, no larger than the monitor. + assert_eq!(restore([0.0, 0.0, 900.0, 1000.0], None, &[], main, size), [2600.0, 100.0, 900.0, 800.0]); + } + #[test] fn a_window_without_a_saved_monitor_stays_on_screen() { let monitors = [monitor("left", LEFT, 1.0), monitor("right", RIGHT, 2.0)]; 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..9d54a0e71 100644 --- a/crates/ui/src/docking/surface.rs +++ b/crates/ui/src/docking/surface.rs @@ -1137,7 +1137,8 @@ impl<'a, P: Clone + Eq + Hash + Debug + Send + Sync + 'static> DockArea<'a, P> { /// The connected monitors (feature `native-windows`). A native floating window stores the /// one it is on, and a restored layout puts each window back on its monitor, or on the - /// main window's when that monitor is gone. egui 0.36 reports no monitors; without a list + /// main window's when that monitor is gone, with its bar in the monitor's + /// [`Monitor::work_area`] where one is given. egui 0.36 reports no monitors; without a list /// windows store the monitor size egui reports and restore onto the main window's monitor. /// eframe 0.36 keeps winit's event loop, and with it `available_monitors`, to itself, so an /// eframe application builds the list from the platform's own display API. @@ -1164,6 +1165,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) { diff --git a/crates/ui/src/testing/input.rs b/crates/ui/src/testing/input.rs new file mode 100644 index 000000000..80309b84f --- /dev/null +++ b/crates/ui/src/testing/input.rs @@ -0,0 +1,115 @@ +//! Pointer, key, text and wheel input for an egui_kittest [`Harness`], with a fixed number of +//! frames per step so a test can count on when the app sees each event. +//! +//! Each function puts its events straight into the harness's input for the frame it belongs to +//! and runs exactly the frames listed below. The counts hold only when no events are waiting in +//! the harness's queue: [`Harness::step`] gives each event queued with [`Harness::event`] (or a +//! kittest node action) a frame of its own, so a step's first frame then runs once per queued +//! event, with the step's own events in the first of them. Run the harness after queuing events +//! and before calling these functions. +//! +//! | Step | Frames | Events, frame by frame | +//! |------|--------|------------------------| +//! | [`move_to`] | 1 | pointer moved | +//! | [`press`] | 2 | modifiers, pointer moved, button down; nothing | +//! | [`release`] | 2 | modifiers, pointer moved, button up; modifiers released | +//! | [`click`] | 3 | modifiers, pointer moved, button down; button up; modifiers released | +//! | [`drag`] | `steps` + 3 | modifiers, pointer moved, primary down; one move per step; primary up; modifiers released | +//! | [`key`] | 2 | modifiers, key down, key up; modifiers released | +//! | [`type_text`] | 2 | text; nothing | +//! | [`wheel`] | 2 | modifiers, wheel; modifiers released | +//! +//! The modifiers are sent as [`Event::ModifiersChanged`] and in each pointer, key and wheel event. +//! [`press`] leaves them held, so moves between a [`press`] and its [`release`] see them too; the +//! other steps release them in their last frame. A drag with another button is a [`press`], some +//! [`move_to`] calls and a [`release`]. +//! +//! ```no_run +//! use craft_ui::testing::input; +//! use egui::{Modifiers, PointerButton, pos2, vec2}; +//! +//! let mut harness = egui_kittest::Harness::new_ui(|ui| _ = ui.button("Open")); +//! input::click(&mut harness, pos2(20.0, 12.0), PointerButton::Primary, Modifiers::NONE); +//! input::drag(&mut harness, pos2(20.0, 40.0), pos2(120.0, 40.0), 4, Modifiers::SHIFT); +//! input::wheel(&mut harness, vec2(0.0, -48.0), Modifiers::COMMAND); +//! ``` + +#[cfg(test)] +mod tests; + +use egui::{Event, Key, Modifiers, MouseWheelSource, MouseWheelUnit, PointerButton, Pos2, TouchPhase, Vec2}; +use egui_kittest::Harness; + +/// The most moves [`drag`] sends; a larger `steps` is reduced to this. +pub const MAX_DRAG_STEPS: usize = 1024; + +/// Run one frame with `events` as its input. +fn frame(harness: &mut Harness<'_, State>, events: impl IntoIterator) { + harness.input_mut().events.extend(events); + harness.step(); +} + +fn button(pos: Pos2, button: PointerButton, pressed: bool, modifiers: Modifiers) -> Event { + Event::PointerButton { pos, button, pressed, modifiers } +} + +/// Move the pointer to `pos`. 1 frame. +pub fn move_to(harness: &mut Harness<'_, State>, pos: Pos2) { + frame(harness, [Event::PointerMoved(pos)]); +} + +/// Press `pointer` at `pos` with `modifiers` held, and keep both held. 2 frames. +pub fn press(harness: &mut Harness<'_, State>, pos: Pos2, pointer: PointerButton, modifiers: Modifiers) { + frame(harness, [Event::ModifiersChanged(modifiers), Event::PointerMoved(pos), button(pos, pointer, true, modifiers)]); + frame(harness, []); +} + +/// Release `pointer` at `pos`, then release the modifiers. 2 frames. +pub fn release(harness: &mut Harness<'_, State>, pos: Pos2, pointer: PointerButton, modifiers: Modifiers) { + frame(harness, [Event::ModifiersChanged(modifiers), Event::PointerMoved(pos), button(pos, pointer, false, modifiers)]); + frame(harness, [Event::ModifiersChanged(Modifiers::NONE)]); +} + +/// Click `pointer` at `pos` with `modifiers` held. 3 frames. +pub fn click(harness: &mut Harness<'_, State>, pos: Pos2, pointer: PointerButton, modifiers: Modifiers) { + frame(harness, [Event::ModifiersChanged(modifiers), Event::PointerMoved(pos), button(pos, pointer, true, modifiers)]); + frame(harness, [button(pos, pointer, false, modifiers)]); + frame(harness, [Event::ModifiersChanged(Modifiers::NONE)]); +} + +/// Drag with the primary button from `from` to `to` in `steps` even moves, the last one at `to`. +/// `steps` is at least 1 and at most [`MAX_DRAG_STEPS`]. `steps` + 3 frames. +pub fn drag(harness: &mut Harness<'_, State>, from: Pos2, to: Pos2, steps: usize, modifiers: Modifiers) { + let steps = steps.clamp(1, MAX_DRAG_STEPS); + let primary = PointerButton::Primary; + frame(harness, [Event::ModifiersChanged(modifiers), Event::PointerMoved(from), button(from, primary, true, modifiers)]); + for step in 1..=steps { + let pos = if step == steps { to } else { from.lerp(to, step as f32 / steps as f32) }; + frame(harness, [Event::PointerMoved(pos)]); + } + frame(harness, [button(to, primary, false, modifiers)]); + frame(harness, [Event::ModifiersChanged(Modifiers::NONE)]); +} + +/// Press and release `key` with `modifiers` held, in one frame, as a platform reports a quick +/// key press. The events carry no physical key and are not repeats. 2 frames. +pub fn key(harness: &mut Harness<'_, State>, key: Key, modifiers: Modifiers) { + let event = |pressed| Event::Key { key, physical_key: None, pressed, repeat: false, modifiers }; + frame(harness, [Event::ModifiersChanged(modifiers), event(true), event(false)]); + frame(harness, [Event::ModifiersChanged(Modifiers::NONE)]); +} + +/// Type `text` into the focused widget as one text event. Empty text sends no event. 2 frames. +pub fn type_text(harness: &mut Harness<'_, State>, text: &str) { + frame(harness, (!text.is_empty()).then(|| Event::Text(text.to_owned()))); + frame(harness, []); +} + +/// Turn the wheel by `delta` points with `modifiers` held. The event's phase is +/// [`TouchPhase::Move`] and its source [`MouseWheelSource::Unknown`]. A positive `y` moves the +/// content down, as egui defines it. 2 frames. +pub fn wheel(harness: &mut Harness<'_, State>, delta: Vec2, modifiers: Modifiers) { + let event = Event::MouseWheel { unit: MouseWheelUnit::Point, delta, phase: TouchPhase::Move, source: MouseWheelSource::Unknown, modifiers }; + frame(harness, [Event::ModifiersChanged(modifiers), event]); + frame(harness, [Event::ModifiersChanged(Modifiers::NONE)]); +} diff --git a/crates/ui/src/testing/input/tests.rs b/crates/ui/src/testing/input/tests.rs new file mode 100644 index 000000000..0dd80f310 --- /dev/null +++ b/crates/ui/src/testing/input/tests.rs @@ -0,0 +1,235 @@ +use egui::{Event, Key, Modifiers, PointerButton, Pos2, Sense, Vec2, pos2, vec2}; +use egui_kittest::Harness; + +use super::{MAX_DRAG_STEPS, click, drag, key, move_to, press, release, type_text, wheel}; + +/// The input events and held modifiers of every frame the app ran. +#[derive(Default)] +struct Frames { + events: Vec>, + modifiers: Vec, +} + +impl Frames { + fn count(&self) -> usize { + self.events.len() + } + + fn pointer_buttons(&self) -> Vec<(Pos2, PointerButton, bool, Modifiers)> { + let events = self.events.iter().flatten(); + events + .filter_map(|event| match event { + Event::PointerButton { pos, button, pressed, modifiers } => Some((*pos, *button, *pressed, *modifiers)), + _ => None, + }) + .collect() + } + + fn moves(&self) -> Vec { + self.events.iter().flatten().filter_map(|event| if let Event::PointerMoved(pos) = event { Some(*pos) } else { None }).collect() + } +} + +/// A harness that records its frames, with the frame `build` runs already cleared. +fn recorder() -> Harness<'static, Frames> { + let mut harness = Harness::builder().with_size([200.0, 100.0]).build_ui_state( + |ui, frames: &mut Frames| { + let (events, modifiers) = ui.input(|i| (i.raw.events.clone(), i.modifiers)); + frames.events.push(events); + frames.modifiers.push(modifiers); + }, + Frames::default(), + ); + *harness.state_mut() = Frames::default(); + harness +} + +type Step = dyn Fn(&mut Harness<'static, Frames>); + +#[test] +fn each_step_runs_its_documented_frames() { + const AT: Pos2 = Pos2::new(40.0, 30.0); + let cases: [(&str, usize, &Step); 9] = [ + ("move_to", 1, &|h| move_to(h, AT)), + ("press", 2, &|h| press(h, AT, PointerButton::Primary, Modifiers::NONE)), + ("release", 2, &|h| release(h, AT, PointerButton::Primary, Modifiers::NONE)), + ("click", 3, &|h| click(h, AT, PointerButton::Primary, Modifiers::NONE)), + ("drag 4", 7, &|h| drag(h, AT, pos2(80.0, 30.0), 4, Modifiers::NONE)), + ("drag 0", 4, &|h| drag(h, AT, pos2(80.0, 30.0), 0, Modifiers::NONE)), + ("key", 2, &|h| key(h, Key::A, Modifiers::NONE)), + ("type_text", 2, &|h| type_text(h, "abc")), + ("wheel", 2, &|h| wheel(h, vec2(0.0, -10.0), Modifiers::NONE)), + ]; + for (name, frames, step) in cases { + let mut harness = recorder(); + step(&mut harness); + assert_eq!(harness.state().count(), frames, "{name}"); + } +} + +#[test] +fn queued_events_add_frames_to_the_first_frame() { + let mut harness = recorder(); + harness.event(Event::Text("a".to_owned())); + harness.event(Event::Text("b".to_owned())); + click(&mut harness, pos2(40.0, 30.0), PointerButton::Primary, Modifiers::NONE); + let frames = harness.state(); + assert_eq!(frames.count(), 4); + assert!(frames.events[0].contains(&Event::Text("a".to_owned()))); + assert!(frames.events[0].contains(&Event::PointerMoved(pos2(40.0, 30.0)))); + assert_eq!(frames.events[1], vec![Event::Text("b".to_owned())]); +} + +#[test] +fn click_moves_presses_and_releases_in_order() { + let at = pos2(40.0, 30.0); + let mut harness = recorder(); + click(&mut harness, at, PointerButton::Primary, Modifiers::CTRL); + let frames = harness.state(); + assert_eq!( + frames.events[0], + vec![ + Event::ModifiersChanged(Modifiers::CTRL), + Event::PointerMoved(at), + Event::PointerButton { pos: at, button: PointerButton::Primary, pressed: true, modifiers: Modifiers::CTRL }, + ] + ); + assert_eq!(frames.events[1], vec![Event::PointerButton { pos: at, button: PointerButton::Primary, pressed: false, modifiers: Modifiers::CTRL }]); + assert_eq!(frames.events[2], vec![Event::ModifiersChanged(Modifiers::NONE)]); + assert_eq!(frames.modifiers, [Modifiers::CTRL, Modifiers::CTRL, Modifiers::NONE]); +} + +#[test] +fn click_reaches_a_button() { + let mut harness = Harness::builder().with_size([200.0, 100.0]).build_ui_state( + |ui, clicks: &mut (u32, u32)| { + let response = ui.add_sized([100.0, 40.0], egui::Button::new("Open")); + clicks.0 += u32::from(response.clicked()); + clicks.1 += u32::from(response.secondary_clicked()); + }, + (0, 0), + ); + click(&mut harness, pos2(50.0, 20.0), PointerButton::Primary, Modifiers::NONE); + click(&mut harness, pos2(50.0, 20.0), PointerButton::Secondary, Modifiers::NONE); + press(&mut harness, pos2(50.0, 20.0), PointerButton::Secondary, Modifiers::NONE); + release(&mut harness, pos2(50.0, 20.0), PointerButton::Secondary, Modifiers::NONE); + assert_eq!(*harness.state(), (1, 2)); +} + +#[test] +fn press_keeps_buttons_and_modifiers_until_release() { + let (from, to) = (pos2(10.0, 10.0), pos2(90.0, 50.0)); + let mut harness = recorder(); + press(&mut harness, from, PointerButton::Secondary, Modifiers::ALT); + move_to(&mut harness, to); + release(&mut harness, to, PointerButton::Secondary, Modifiers::ALT); + let frames = harness.state(); + assert_eq!( + frames.pointer_buttons(), + [(from, PointerButton::Secondary, true, Modifiers::ALT), (to, PointerButton::Secondary, false, Modifiers::ALT)] + ); + assert_eq!(frames.moves(), [from, to, to]); + assert_eq!(frames.modifiers, [Modifiers::ALT, Modifiers::ALT, Modifiers::ALT, Modifiers::ALT, Modifiers::NONE]); +} + +#[test] +fn drag_moves_evenly_and_ends_at_the_target() { + let (from, to) = (pos2(10.0, 20.0), pos2(90.0, 60.0)); + let mut harness = recorder(); + drag(&mut harness, from, to, 4, Modifiers::SHIFT); + let frames = harness.state(); + assert_eq!(frames.moves(), [from, pos2(30.0, 30.0), pos2(50.0, 40.0), pos2(70.0, 50.0), to]); + assert_eq!( + frames.pointer_buttons(), + [(from, PointerButton::Primary, true, Modifiers::SHIFT), (to, PointerButton::Primary, false, Modifiers::SHIFT)] + ); + // Held through the moves and the release, released in the last frame. + assert_eq!(frames.modifiers[..6], [Modifiers::SHIFT; 6]); + assert_eq!(frames.modifiers[6], Modifiers::NONE); +} + +#[test] +fn drag_with_zero_steps_moves_once() { + let (from, to) = (pos2(10.0, 20.0), pos2(90.0, 60.0)); + let mut harness = recorder(); + drag(&mut harness, from, to, 0, Modifiers::NONE); + assert_eq!(harness.state().moves(), [from, to]); +} + +#[test] +fn drag_steps_are_capped() { + let mut harness = recorder(); + drag(&mut harness, pos2(0.0, 0.0), pos2(100.0, 0.0), usize::MAX, Modifiers::NONE); + assert_eq!(harness.state().count(), MAX_DRAG_STEPS + 3); + assert_eq!(harness.state().moves().last(), Some(&pos2(100.0, 0.0))); +} + +#[test] +fn drag_moves_a_draggable_area() { + let mut harness = Harness::builder().with_size([200.0, 100.0]).build_ui_state( + |ui, moved: &mut Vec2| { + let response = ui.allocate_response(vec2(200.0, 100.0), Sense::drag()); + *moved += response.drag_delta(); + }, + Vec2::ZERO, + ); + drag(&mut harness, pos2(20.0, 20.0), pos2(120.0, 60.0), 5, Modifiers::NONE); + let moved = *harness.state(); + assert!((moved - vec2(100.0, 40.0)).length() < 0.01, "{moved:?}"); +} + +#[test] +fn key_sends_down_and_up_with_modifiers() { + let mut harness = recorder(); + key(&mut harness, Key::S, Modifiers::COMMAND); + let frames = harness.state(); + let event = |pressed| Event::Key { key: Key::S, physical_key: None, pressed, repeat: false, modifiers: Modifiers::COMMAND }; + assert_eq!(frames.events[0], vec![Event::ModifiersChanged(Modifiers::COMMAND), event(true), event(false)]); + assert_eq!(frames.modifiers, [Modifiers::COMMAND, Modifiers::NONE]); +} + +#[test] +fn type_text_reaches_the_focused_field() { + let mut harness = Harness::builder().with_size([200.0, 100.0]).build_ui_state( + |ui, text: &mut String| { + let label = ui.label("Name"); + let response = ui.text_edit_singleline(text).labelled_by(label.id); + if ui.memory(|m| m.focused().is_none()) { + response.request_focus(); + } + }, + String::new(), + ); + harness.run(); + type_text(&mut harness, "Craft"); + type_text(&mut harness, ""); + assert_eq!(harness.state(), "Craft"); +} + +#[test] +fn empty_text_sends_no_event() { + let mut harness = recorder(); + type_text(&mut harness, ""); + assert!(harness.state().events.iter().all(Vec::is_empty)); +} + +#[test] +fn wheel_sends_points_with_its_modifiers() { + let mut harness = recorder(); + wheel(&mut harness, vec2(0.0, -24.0), Modifiers::COMMAND); + let frames = harness.state(); + assert_eq!( + frames.events[0], + vec![ + Event::ModifiersChanged(Modifiers::COMMAND), + Event::MouseWheel { + unit: egui::MouseWheelUnit::Point, + delta: vec2(0.0, -24.0), + phase: egui::TouchPhase::Move, + source: egui::MouseWheelSource::Unknown, + modifiers: Modifiers::COMMAND, + }, + ] + ); + assert_eq!(frames.modifiers, [Modifiers::COMMAND, Modifiers::NONE]); +} diff --git a/crates/ui/src/testing/mod.rs b/crates/ui/src/testing/mod.rs index 9cab5bbd6..61d72b17d 100644 --- a/crates/ui/src/testing/mod.rs +++ b/crates/ui/src/testing/mod.rs @@ -55,7 +55,15 @@ //! On Russian, the `с` key reports `C` at physical `C` and must run Ctrl+C. The app's dispatcher //! (`craft_keymap::egui::Dispatcher`) turns the event into a `KeyInput` with //! `KeyInput::from_egui`. +//! +//! # Input steps and review screenshots +//! +//! [`input`] clicks, drags, presses keys, types and turns the wheel in any [`Harness`], each step +//! taking a fixed number of frames. [`snapshot`] writes screenshots for review to a folder named +//! by an environment variable, and nothing when it is unset. +pub mod input; +pub mod snapshot; #[cfg(test)] mod tests; diff --git a/crates/ui/src/testing/snapshot.rs b/crates/ui/src/testing/snapshot.rs new file mode 100644 index 000000000..aec648004 --- /dev/null +++ b/crates/ui/src/testing/snapshot.rs @@ -0,0 +1,137 @@ +//! Screenshots of a test's screens for a person to review, written to a folder named by an +//! environment variable. Nothing is compared: [`Screens::snapshots`](super::Screens::snapshots) +//! is the comparing test. +//! +//! With the variable unset, [`snapshot_dir`] returns `None`, [`with_snapshot_renderer`] leaves the +//! builder alone (no GPU setup), and the test skips its [`save`] calls. With it set, +//! [`with_snapshot_renderer`] sets up wgpu rendering and [`save`] writes `{dir}/{name}.png` from the +//! last frame. [`save`] runs no frames: settle the screen first (for example `harness.run()`, or +//! the two or three steps an app's own test takes), and set the theme on the builder. +//! +//! ```no_run +//! use craft_ui::testing::snapshot; +//! +//! let dir = snapshot::snapshot_dir(snapshot::DEFAULT_DIR_VAR); +//! let builder = snapshot::with_snapshot_renderer(egui_kittest::Harness::builder(), dir.as_deref())?; +//! let mut harness = builder.with_theme(egui::Theme::Light).build_ui(|ui| _ = ui.label("Export")); +//! harness.run(); +//! if let Some(dir) = &dir { +//! snapshot::save(&mut harness, dir, "export-light")?; +//! } +//! # Ok::<(), snapshot::SnapshotError>(()) +//! ``` + +#[cfg(test)] +mod tests; + +use std::any::Any; +use std::ffi::OsString; +use std::fmt; +use std::panic::{AssertUnwindSafe, catch_unwind}; +use std::path::{Path, PathBuf}; + +use egui_kittest::{Harness, HarnessBuilder}; + +/// The variable [`snapshot_dir`] reads when an app has no name of its own for it. +pub const DEFAULT_DIR_VAR: &str = "CRAFT_UI_SNAPSHOT_DIR"; + +/// The longest name [`save`] takes, in bytes. +pub const MAX_NAME_LEN: usize = 120; + +/// Why a screenshot was not written. +#[derive(Debug)] +pub enum SnapshotError { + /// The name is empty, too long, or not a plain file name (see [`save`]). + InvalidName(String), + /// The renderer could not be set up or could not draw the frame, for example on a machine + /// with no GPU adapter and no software renderer. + Render(String), + /// The folder could not be created. + CreateDir { path: PathBuf, source: std::io::Error }, + /// The PNG could not be encoded or written. + Write { path: PathBuf, message: String }, +} + +impl fmt::Display for SnapshotError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::InvalidName(name) => write!(f, "invalid screenshot name {name:?}"), + Self::Render(message) => write!(f, "couldn't render the screenshot: {message}"), + Self::CreateDir { path, source } => write!(f, "couldn't create {}: {source}", path.display()), + Self::Write { path, message } => write!(f, "couldn't write {}: {message}", path.display()), + } + } +} + +impl std::error::Error for SnapshotError { + fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { + match self { + Self::CreateDir { source, .. } => Some(source), + _ => None, + } + } +} + +/// The screenshot folder named by the environment variable `var`, such as [`DEFAULT_DIR_VAR`] or +/// an app's own variable. `None` when the variable is unset or empty, and when `var` is not a +/// usable variable name (empty, or containing `=` or a NUL). +pub fn snapshot_dir(var: &str) -> Option { + if var.is_empty() || var.contains(['=', '\0']) { + return None; + } + dir_from(std::env::var_os(var)) +} + +fn dir_from(value: Option) -> Option { + value.filter(|value| !value.is_empty()).map(PathBuf::from) +} + +/// `builder` with wgpu rendering when `dir` is a screenshot folder, and unchanged when it is +/// `None`. The renderer is created here, so a machine that can't render fails here with +/// [`SnapshotError::Render`] rather than panicking inside the test. +pub fn with_snapshot_renderer(builder: HarnessBuilder, dir: Option<&Path>) -> Result, SnapshotError> { + if dir.is_none() { + return Ok(builder); + } + catch_unwind(AssertUnwindSafe(move || builder.wgpu())).map_err(|payload| SnapshotError::Render(panic_message(payload.as_ref()))) +} + +/// Render the harness's last frame and write it to `{dir}/{name}.png`, creating `dir` when it is +/// missing, and return the file's path. `name` is a plain file name of at most [`MAX_NAME_LEN`] +/// bytes: ASCII letters, digits, `-`, `_`, `.` and `@`, not starting with `.`, and not a Windows +/// device name such as `con` or `nul`. Runs no frames. +pub fn save(harness: &mut Harness<'_, State>, dir: &Path, name: &str) -> Result { + check_name(name)?; + let image = catch_unwind(AssertUnwindSafe(|| harness.render())) + .map_err(|payload| SnapshotError::Render(panic_message(payload.as_ref())))? + .map_err(SnapshotError::Render)?; + std::fs::create_dir_all(dir).map_err(|source| SnapshotError::CreateDir { path: dir.to_owned(), source })?; + let path = dir.join(format!("{name}.png")); + image.save(&path).map_err(|error| SnapshotError::Write { path: path.clone(), message: error.to_string() })?; + Ok(path) +} + +const DEVICE_NAMES: [&str; 24] = [ + "con", "prn", "aux", "nul", "com0", "com1", "com2", "com3", "com4", "com5", "com6", "com7", "com8", "com9", "lpt0", "lpt1", "lpt2", "lpt3", + "lpt4", "lpt5", "lpt6", "lpt7", "lpt8", "lpt9", +]; + +fn check_name(name: &str) -> Result<(), SnapshotError> { + let stem = name.split('.').next().unwrap_or(name); + let valid = !name.is_empty() + && name.len() <= MAX_NAME_LEN + && !name.starts_with('.') + && name.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.' | b'@')) + && !DEVICE_NAMES.iter().any(|device| stem.eq_ignore_ascii_case(device)); + if valid { Ok(()) } else { Err(SnapshotError::InvalidName(name.to_owned())) } +} + +fn panic_message(payload: &(dyn Any + Send)) -> String { + if let Some(message) = payload.downcast_ref::<&str>() { + (*message).to_owned() + } else if let Some(message) = payload.downcast_ref::() { + message.clone() + } else { + "the renderer panicked".to_owned() + } +} diff --git a/crates/ui/src/testing/snapshot/tests.rs b/crates/ui/src/testing/snapshot/tests.rs new file mode 100644 index 000000000..df90f4a85 --- /dev/null +++ b/crates/ui/src/testing/snapshot/tests.rs @@ -0,0 +1,153 @@ +use std::ffi::OsString; +use std::path::{Path, PathBuf}; + +use egui::TexturesDelta; +use egui_kittest::{Harness, HarnessBuilder, TestRenderer}; +use image::{Rgba, RgbaImage}; + +use super::{DEFAULT_DIR_VAR, MAX_NAME_LEN, SnapshotError, dir_from, save, snapshot_dir, with_snapshot_renderer}; + +/// Draws a fixed 3 × 2 image, fails, or panics, without a GPU. +enum Fake { + Image, + Fails, + Panics, +} + +impl TestRenderer for Fake { + fn handle_delta(&mut self, delta: &mut TexturesDelta) { + delta.clear(); + } + + fn render(&mut self, _ctx: &egui::Context, _output: &egui::FullOutput) -> Result { + match self { + Self::Image => Ok(RgbaImage::from_pixel(3, 2, Rgba([10, 20, 30, 255]))), + Self::Fails => Err("no adapter".to_owned()), + Self::Panics => panic!("Failed to create render state"), + } + } +} + +/// A folder of this test's own under the system temp folder, removed first. +fn temp_dir(test: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!("craft-ui-snapshot-{}-{test}", std::process::id())); + _ = std::fs::remove_dir_all(&dir); + dir +} + +fn harness(builder: HarnessBuilder<()>) -> Harness<'static> { + builder.with_size([60.0, 30.0]).build_ui(|ui| _ = ui.label("Export")) +} + +fn assert_png(path: &Path, width: u32, height: u32) { + let bytes = std::fs::read(path).unwrap(); + assert!(bytes.starts_with(b"\x89PNG\r\n\x1a\n"), "{}", path.display()); + let image = image::load_from_memory_with_format(&bytes, image::ImageFormat::Png).unwrap(); + assert_eq!((image.width(), image.height()), (width, height)); +} + +#[test] +fn an_unset_or_empty_variable_is_no_folder() { + assert_eq!(dir_from(None), None); + assert_eq!(dir_from(Some(OsString::new())), None); + assert_eq!(dir_from(Some("shots".into())), Some(PathBuf::from("shots"))); + assert_eq!(snapshot_dir("CRAFT_UI_SNAPSHOT_DIR_TEST_UNSET_8F3A"), None); + assert_eq!(DEFAULT_DIR_VAR, "CRAFT_UI_SNAPSHOT_DIR"); +} + +#[test] +fn an_unusable_variable_name_is_no_folder() { + for var in ["", "A=B", "A\0B", "="] { + assert_eq!(snapshot_dir(var), None, "{var:?}"); + } +} + +#[test] +fn the_caller_names_the_variable() { + // Cargo sets this one for every test run. + assert_eq!(snapshot_dir("CARGO_MANIFEST_DIR"), Some(PathBuf::from(env!("CARGO_MANIFEST_DIR")))); +} + +#[test] +fn no_folder_leaves_the_renderer_alone() { + let builder = with_snapshot_renderer(Harness::builder().renderer(Fake::Image), None).unwrap(); + let mut harness = harness(builder); + // The fake renderer is still the one drawing: no wgpu renderer replaced it. + assert_eq!(harness.render().unwrap().dimensions(), (3, 2)); +} + +#[test] +fn save_writes_one_png_named_after_the_screen() { + let dir = temp_dir("save").join("nested"); + let mut harness = harness(Harness::builder().renderer(Fake::Image)); + let path = save(&mut harness, &dir, "export-light@2x").unwrap(); + assert_eq!(path, dir.join("export-light@2x.png")); + assert_png(&path, 3, 2); + assert_eq!(std::fs::read_dir(&dir).unwrap().count(), 1); + _ = std::fs::remove_dir_all(dir.parent().unwrap()); +} + +#[test] +fn save_runs_no_frames() { + let dir = temp_dir("frames"); + let mut harness = Harness::builder().renderer(Fake::Image).build_ui_state(|_, frames: &mut u32| *frames += 1, 0); + let before = *harness.state(); + save(&mut harness, &dir, "frames").unwrap(); + assert_eq!(*harness.state(), before); + _ = std::fs::remove_dir_all(dir); +} + +#[test] +fn save_refuses_names_that_leave_the_folder() { + let dir = temp_dir("names"); + let mut harness = harness(Harness::builder().renderer(Fake::Image)); + let long = "a".repeat(MAX_NAME_LEN + 1); + for name in [ + "", ".", "..", "../up", "a/b", "a\\b", "/abs", "C:x", ".hidden", "con", "NUL", "com1.x", "lpt9", "COM0", "lpt0.png", "a b", "é", "a\0", &long, + ] { + assert!(matches!(save(&mut harness, &dir, name), Err(SnapshotError::InvalidName(_))), "{name:?}"); + } + assert!(!dir.exists()); + assert!(save(&mut harness, &dir, &"a".repeat(MAX_NAME_LEN)).is_ok()); + _ = std::fs::remove_dir_all(dir); +} + +#[test] +fn a_render_failure_is_an_error_and_writes_nothing() { + let dir = temp_dir("render"); + for fake in [Fake::Fails, Fake::Panics] { + let mut harness = harness(Harness::builder().renderer(fake)); + assert!(matches!(save(&mut harness, &dir, "screen"), Err(SnapshotError::Render(_)))); + } + assert!(!dir.exists()); +} + +#[test] +fn a_folder_that_cannot_be_made_is_an_error() { + let dir = temp_dir("blocked"); + std::fs::create_dir_all(&dir).unwrap(); + let file = dir.join("file"); + std::fs::write(&file, b"").unwrap(); + let mut harness = harness(Harness::builder().renderer(Fake::Image)); + let error = save(&mut harness, &file.join("sub"), "screen").unwrap_err(); + assert!(matches!(error, SnapshotError::CreateDir { .. }), "{error}"); + _ = std::fs::remove_dir_all(dir); +} + +#[test] +fn a_folder_sets_up_wgpu_and_saves_the_frame() { + let dir = temp_dir("wgpu"); + let builder = match with_snapshot_renderer(Harness::builder(), Some(&dir)) { + Ok(builder) => builder, + Err(SnapshotError::Render(message)) => { + eprintln!("skipped: this machine can't render with wgpu ({message})"); + return; + } + Err(error) => panic!("{error}"), + }; + let mut harness = harness(builder); + harness.run(); + let path = save(&mut harness, &dir, "label").unwrap(); + assert_png(&path, 60, 30); + _ = std::fs::remove_dir_all(dir); +} diff --git a/crates/update/src/install.rs b/crates/update/src/install.rs index 3b3513294..6cf91868a 100644 --- a/crates/update/src/install.rs +++ b/crates/update/src/install.rs @@ -681,12 +681,18 @@ fn prepare_home(home: &Path) { } } +/// The start of the name of the folder [`staging_dir`] makes. Six random letters and digits +/// follow it. +#[cfg(target_os = "linux")] +const STAGING: &str = ".artcraft-launcher-"; + /// A new folder of our own inside `dir`, removed when dropped: a predictable name there may be /// the user's. #[cfg(target_os = "linux")] fn staging_dir(dir: &Path) -> Result { tempfile::Builder::new() - .prefix(".artcraft-launcher-") + .prefix(STAGING) + .rand_bytes(6) .tempdir_in(dir) .map_err(|e| format!("couldn't create a staging folder in {} ({e})", dir.display())) } @@ -1333,6 +1339,7 @@ pub mod linux { if std::fs::symlink_metadata(&dest).is_ok_and(|m| m.is_dir() || !(replace || ours && m.is_file())) { return Err(format!("{} already exists and wasn't installed by ArtCraft Launcher", dest.display())); } + clear_staging(&dir, std::time::SystemTime::now()); let staging = super::staging_dir(&dir)?; let partial = staging.path().join(name); std::fs::copy(file, &partial).map_err(|e| format!("couldn't copy the AppImage ({e})"))?; @@ -1349,6 +1356,53 @@ pub mod linux { Ok((dest, removed)) } + /// How long a staging folder stays unchanged before it counts as left by an AppImage install + /// that ended partway. + const STAGING_AGE: Duration = Duration::from_secs(24 * 60 * 60); + + /// Removes the staging folders in `dir` of AppImage installs that ended partway, with the + /// partial copies in them: folders named as [`super::STAGING`] describes that hold nothing or + /// only one regular file named `*.AppImage`, and have not changed for [`STAGING_AGE`] before + /// `now`. Other folders, backup folders included, are left alone. Failures are logged and the + /// install goes on. + pub(crate) fn clear_staging(dir: &Path, now: std::time::SystemTime) { + let Ok(entries) = std::fs::read_dir(dir) else { return }; + let random = |rest: &str| rest.len() == 6 && rest.bytes().all(|b| b.is_ascii_alphanumeric()); + for folder in entries.flatten() { + let path = folder.path(); + let ours = folder.file_name().to_str().and_then(|n| n.strip_prefix(super::STAGING)).is_some_and(random); + if !ours || !folder.file_type().is_ok_and(|t| t.is_dir()) || !left_by_install(&path, now) { + continue; + } + match std::fs::remove_dir_all(&path) { + Ok(()) => log::info!("removed {}, left by an install that ended partway", path.display()), + Err(e) if e.kind() == std::io::ErrorKind::NotFound => {} + Err(e) => log::warn!("couldn't remove {}, left by an install that ended partway ({e})", path.display()), + } + } + } + + /// Whether `folder` holds nothing or only one regular file named `*.AppImage`, and neither the + /// folder nor that file has changed for [`STAGING_AGE`] before `now`. + fn left_by_install(folder: &Path, now: std::time::SystemTime) -> bool { + let unchanged = |path: &Path| { + std::fs::symlink_metadata(path).and_then(|m| m.modified()).is_ok_and(|at| now.duration_since(at).is_ok_and(|age| age >= STAGING_AGE)) + }; + let Ok(entries) = std::fs::read_dir(folder) else { return false }; + let names: Vec<_> = entries.take(2).map(|e| e.map(|e| e.file_name())).collect(); + let partial = match names.as_slice() { + [] => true, + [Ok(only)] => { + let copy = folder.join(only); + Path::new(only).extension().is_some_and(|ext| ext.eq_ignore_ascii_case("AppImage")) + && std::fs::symlink_metadata(©).is_ok_and(|m| m.is_file()) + && unchanged(©) + } + _ => false, + }; + partial && unchanged(folder) + } + /// Unpacks a release tarball (`bin/`, `share/…`) into `/apps/`, a folder /// only the launcher owns, and returns the app's binary. This is the fallback for the /// Flatpak launcher when the host has no usable Flatpak: the app then runs inside the @@ -1605,6 +1659,37 @@ pub mod macos { /// `hdiutil create` too), since it turns concurrent requests away. pub(crate) static DISK_IMAGES: std::sync::Mutex<()> = std::sync::Mutex::new(()); + /// Blocks until no other test process (nor another thread here) holds the lock file that the + /// tests take around their disk-image work, and holds it until the file is dropped. + #[cfg(test)] + pub(crate) fn other_test_processes_wait() -> std::fs::File { + let file = std::fs::OpenOptions::new() + .create(true) + .truncate(false) + .write(true) + .open(std::env::temp_dir().join("craft-update-tests-disk-images.lock")) + .unwrap(); + file.lock().unwrap(); + file + } + + /// A test's turn at the disk-image helper, taken from other test processes and from the + /// other threads of this one, until dropped. + #[cfg(test)] + pub(crate) struct DiskImageTurn { + _in_process: std::sync::MutexGuard<'static, ()>, + _other_processes: std::fs::File, + } + + /// Waits for [`DiskImageTurn`]. The lock file comes first: a test that holds only the file + /// around an install waits for [`DISK_IMAGES`] inside it. + #[cfg(test)] + pub(crate) fn disk_image_turn() -> DiskImageTurn { + let other_processes = other_test_processes_wait(); + let in_process = DISK_IMAGES.lock().unwrap_or_else(std::sync::PoisonError::into_inner); + DiskImageTurn { _in_process: in_process, _other_processes: other_processes } + } + /// Deep signature checks wait their turn here. `codesign --deep` reads every file of the /// bundle, so checks that overlap compete for the disk and all slow down. The time limit /// starts when a check's turn comes. @@ -2747,6 +2832,51 @@ mod tests { assert_eq!(std::fs::read_dir(&folder).unwrap().count(), 2, "staging was left behind"); } + #[cfg(target_os = "linux")] + #[test] + fn appimage_staging_left_by_an_install_that_ended_partway_is_removed() { + let dir = tempfile::tempdir().unwrap(); + let folder = dir.path(); + let staging = |name: &str, files: &[&str]| { + let path = folder.join(name); + std::fs::create_dir(&path).unwrap(); + for file in files { + std::fs::write(path.join(file), "partial").unwrap(); + } + path + }; + let left = [ + staging(".artcraft-launcher-Ab12Cd", &["photocraft-0.6.0-linux-x86_64.AppImage"]), + staging(".artcraft-launcher-Ef34Gh", &["pdfcraft.appimage"]), + staging(".artcraft-launcher-Ij56Kl", &[]), + ]; + let link = staging(".artcraft-launcher-Fg78Hi", &[]); + std::os::unix::fs::symlink(folder.join("elsewhere.AppImage"), link.join("linked.AppImage")).unwrap(); + let file = folder.join(".artcraft-launcher-Jk90Lm"); + std::fs::write(&file, "the user's").unwrap(); + let now = std::time::SystemTime::now(); + let day = std::time::Duration::from_secs(24 * 60 * 60); + // An install still copying: its folder is old, its partial copy changed later. + let copying = staging(".artcraft-launcher-No12Pq", &["vectorcraft.AppImage"]); + std::fs::File::options().write(true).open(copying.join("vectorcraft.AppImage")).unwrap().set_modified(now + day).unwrap(); + let kept = [ + staging(".artcraft-launcher-Mn78Op", &["a.AppImage", "notes.txt"]), + staging(".artcraft-launcher-Qr90St", &["notes.txt"]), + staging(".artcraft-launcher-backup-Uv12Wx", &["old"]), + staging(".artcraft-launcher-Yz34A", &["a.AppImage"]), + staging(".artcraft-launcher-Bc56De7", &["a.AppImage"]), + staging("Cd78Ef", &["a.AppImage"]), + link, + file, + copying, + ]; + linux::clear_staging(folder, now); + assert!(left.iter().chain(&kept).all(|p| p.exists()), "a folder changed within a day was removed"); + linux::clear_staging(folder, now + day + std::time::Duration::from_secs(60)); + assert!(left.iter().all(|p| !p.exists()), "a partial copy was left behind"); + assert!(kept.iter().all(|p| p.exists()), "a folder that isn't a partial install was removed"); + } + #[test] fn a_new_install_reports_what_it_would_write_over() { let dir = tempfile::tempdir().unwrap(); @@ -4143,6 +4273,7 @@ exit 0 expect: &Expect<'_>, ) -> Result { let stop = Stop::default(); + let _other_processes = macos::other_test_processes_wait(); macos::install_dmg(app, dmg, existing, destination, replace, paths, expect, CheckTurn { stop: &stop, phase: &mut |_| {} }) } @@ -4195,33 +4326,23 @@ exit 0 app } - /// A release-style disk image holding a `PhotoCraft.app` that reports `version`. The - /// disk-image helper turns requests away while it is busy (`attach` retries for the same - /// reason), so `hdiutil create` is tried a few times, and what it said is kept for the - /// failure message. + /// A release-style disk image holding a `PhotoCraft.app` that reports `version`. The tests, + /// in this process and in others, ask the disk-image helper one at a time; when a program + /// that is not one of these tests keeps it busy, the test fails with what `hdiutil create` + /// said. fn dmg(dir: &Path, version: &str) -> PathBuf { let src = dir.join(format!("src-{version}")); bundle(&src, version); let dmg = dir.join(format!("photocraft-{version}-macos-universal.dmg")); - let _one_at_a_time = super::macos::DISK_IMAGES.lock().unwrap_or_else(std::sync::PoisonError::into_inner); - let mut said = String::new(); - for attempt in 0..5u64 { - if attempt > 0 { - std::thread::sleep(std::time::Duration::from_millis(400 * attempt)); - let _ = std::fs::remove_file(&dmg); - } - let output = std::process::Command::new("hdiutil") - .args(["create", "-quiet", "-format", "UDZO", "-volname", "PhotoCraft", "-srcfolder"]) - .arg(&src) - .arg(&dmg) - .output() - .unwrap(); - if output.status.success() { - return dmg; - } - said = String::from_utf8_lossy(&output.stderr).trim().to_string(); - } - panic!("hdiutil create failed after 5 tries: {said}"); + let _one_at_a_time = macos::disk_image_turn(); + let output = std::process::Command::new("hdiutil") + .args(["create", "-quiet", "-format", "UDZO", "-volname", "PhotoCraft", "-srcfolder"]) + .arg(&src) + .arg(&dmg) + .output() + .unwrap(); + assert!(output.status.success(), "hdiutil create failed: {}", String::from_utf8_lossy(&output.stderr).trim()); + dmg } #[test] @@ -4598,31 +4719,18 @@ exit 0 ended.wait().unwrap(); let mount = paths.cache.join(format!("mount-photocraft-{pid}-1")); std::fs::create_dir_all(&mount).unwrap(); - // The disk-image helper turns requests away while it is busy, as in `dmg`. - let attached = { - let _one_at_a_time = super::macos::DISK_IMAGES.lock().unwrap_or_else(std::sync::PoisonError::into_inner); - let mut said = String::new(); - let mut attached = false; - for attempt in 0..5u64 { - if attempt > 0 { - std::thread::sleep(std::time::Duration::from_millis(400 * attempt)); - } - let output = std::process::Command::new("hdiutil") - .args(["attach", "-nobrowse", "-readonly", "-noautoopen", "-noverify", "-mountpoint"]) - .arg(&mount) - .arg(&image) - .output() - .unwrap(); - if output.status.success() { - attached = true; - break; - } - said = String::from_utf8_lossy(&output.stderr).trim().to_string(); - } - attached.then_some(()).ok_or(said) + // One request at a time, as in `dmg`. + let output = { + let _one_at_a_time = macos::disk_image_turn(); + std::process::Command::new("hdiutil") + .args(["attach", "-nobrowse", "-readonly", "-noautoopen", "-noverify", "-mountpoint"]) + .arg(&mount) + .arg(&image) + .output() + .unwrap() }; let _attached = Attached(mount.clone()); - assert_eq!(attached, Ok(()), "hdiutil attach failed after 5 tries"); + assert!(output.status.success(), "hdiutil attach failed: {}", String::from_utf8_lossy(&output.stderr).trim()); let staging = apps.join(format!(".artcraft-launcher-staging-{pid}-Ab12Cd")); bundle(&staging, "0.6.0"); std::fs::write(staging.join(".artcraft-launcher-staging"), "").unwrap(); @@ -4690,7 +4798,12 @@ exit 0 other }, ]; - let now = std::time::SystemTime::now(); + // The earlier launcher versions' folders last changed at a fixed time, which stands + // for now. + let now = std::time::UNIX_EPOCH + std::time::Duration::from_secs(1_800_000_000); + for copy in [&old].into_iter().chain(&old_kept) { + std::fs::File::open(copy.parent().unwrap()).unwrap().set_modified(now).unwrap(); + } super::macos::clear_staging(photocraft(), &apps, |pid| pid == ended, now); assert!(!left.exists(), "the partial copy of an install that ended is still there"); @@ -4700,8 +4813,11 @@ exit 0 } assert_eq!(std::fs::read_to_string(elsewhere.join("Contents/MacOS/PhotoCraft")).unwrap(), "0.4.0"); - // A day later, with every process still in the same state. + // A minute short of a day later, and then a day later, with every process still in the + // same state. let day = std::time::Duration::from_secs(24 * 60 * 60); + super::macos::clear_staging(photocraft(), &apps, |pid| pid == ended, now + day - std::time::Duration::from_secs(60)); + assert!(old.exists(), "the copy of an earlier launcher version's install was removed before a day had passed"); super::macos::clear_staging(photocraft(), &apps, |pid| pid == ended, now + day + std::time::Duration::from_secs(60)); assert!(!old.exists(), "the partial copy of an earlier launcher version's install is still there"); for path in kept.iter().chain([&file, &link]).chain(&old_kept) { diff --git a/crates/update/src/process.rs b/crates/update/src/process.rs index c20c3bc45..c7be99ef1 100644 --- a/crates/update/src/process.rs +++ b/crates/update/src/process.rs @@ -90,7 +90,41 @@ pub fn run_command(cmd: Command, program: &str, timeout: Duration) -> Result Result { +fn run_command_detailed(cmd: Command, program: &str, timeout: Duration) -> Result { + let mut start = None; + run_command_until(cmd, program, timeout, move |_| { + let start = *start.get_or_insert_with(Instant::now); + let more = within(start, Instant::now(), timeout); + if more { + std::thread::sleep(Duration::from_millis(15)); + } + more + }) +} + +/// Whether a helper run that started waiting at `start` may still wait at `now`. +fn within(start: Instant, now: Instant, timeout: Duration) -> bool { + now.saturating_duration_since(start) < timeout +} + +/// What a helper run still waits for when it asks whether to keep waiting. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Pending { + /// The helper is still running. + Helper, + /// The helper has exited, and a process it started still holds its output open. + Output, +} + +/// [`run_command_detailed`], asking `keep_waiting` each time the run finds the helper or its +/// output unfinished. `keep_waiting` returns `false` when the time limit has passed; `timeout` is +/// the limit the error message names. +fn run_command_until( + mut cmd: Command, + program: &str, + timeout: Duration, + mut keep_waiting: impl FnMut(Pending) -> bool, +) -> Result { let mut child = cmd .stdin(Stdio::null()) .stdout(Stdio::piped()) @@ -108,11 +142,10 @@ fn run_command_detailed(mut cmd: Command, program: &str, timeout: Duration) -> R } }; let timed_out = || HelperFailure::Unfinished(format!("{program} didn't finish within {} seconds", timeout.as_secs())); - let start = Instant::now(); let status = loop { match child.try_wait() { Ok(Some(status)) => break status, - Ok(None) if start.elapsed() < timeout => std::thread::sleep(Duration::from_millis(15)), + Ok(None) if keep_waiting(Pending::Helper) => {} _ => { let _ = child.kill(); let _ = child.wait(); @@ -123,10 +156,9 @@ fn run_command_detailed(mut cmd: Command, program: &str, timeout: Duration) -> R // A descendant may retain a pipe after the direct child exits. Keep reader completion // under the same deadline; on timeout the readers detach, as in the child timeout path. while !stdout.is_finished() || !stderr.is_finished() { - if start.elapsed() >= timeout { + if !keep_waiting(Pending::Output) { return Err(timed_out()); } - std::thread::sleep(Duration::from_millis(15)); } let text = |pipe: std::thread::JoinHandle>| String::from_utf8_lossy(&pipe.join().unwrap_or_default()).into_owned(); let (out, err) = (text(stdout), text(stderr)); @@ -561,10 +593,19 @@ mod run_tests { #[cfg(windows)] #[test] fn waiting_for_a_process_ends_when_it_exits() { - let mut child = Command::new("ping").args(["-n", "3", "127.0.0.1"]).stdout(Stdio::null()).spawn().unwrap(); - assert!(!wait_for_exit(child.id(), Duration::from_millis(200)), "it's still running"); - assert!(wait_for_exit(child.id(), Duration::from_secs(30)), "it has exited"); + use std::io::BufRead; + // Says it is ready, then waits for a line on its standard input, which ends at EOF. + let mut child = Command::new("cmd").args(["/C", "echo ready& set /p line="]).stdin(Stdio::piped()).stdout(Stdio::piped()).spawn().unwrap(); + let mut ready = String::new(); + std::io::BufReader::new(child.stdout.take().unwrap()).read_line(&mut ready).unwrap(); + assert_eq!(ready.trim_end(), "ready"); + assert!(!wait_for_exit(child.id(), Duration::ZERO), "it's still running"); + drop(child.stdin.take()); + // The process exits as soon as its input ends; the longest limit `wait_for_exit` takes + // waits for that without a time bound of the test's own. + assert!(wait_for_exit(child.id(), Duration::MAX), "it has exited"); child.wait().unwrap(); + assert!(wait_for_exit(child.id(), Duration::ZERO), "it has exited"); } #[test] @@ -596,11 +637,27 @@ mod run_tests { #[cfg(unix)] #[test] fn a_helper_past_its_time_limit_gives_no_answer() { - // A time limit of zero expires at the first look, so the test doesn't wait for it. + // The limit passes at the first look that finds the helper running. let mut cmd = command("/bin/sh"); cmd.args(["-c", "exec sleep 86400"]); - let timed_out = run_command_detailed(cmd, "the helper", Duration::ZERO); - assert_eq!(timed_out, Err(HelperFailure::Unfinished("the helper didn't finish within 0 seconds".into()))); + let mut looks = Vec::new(); + let timed_out = run_command_until(cmd, "the helper", Duration::from_secs(5), |pending| { + looks.push(pending); + false + }); + assert_eq!(timed_out, Err(HelperFailure::Unfinished("the helper didn't finish within 5 seconds".into()))); + assert_eq!(looks, [Pending::Helper]); + } + + #[test] + fn a_time_limit_ends_when_its_length_has_passed() { + let start = Instant::now(); + let second = Duration::from_secs(1); + assert!(within(start, start, second)); + assert!(within(start, start + Duration::from_millis(999), second)); + assert!(!within(start, start + second, second)); + assert!(!within(start, start + Duration::from_secs(60), second)); + assert!(!within(start, start, Duration::ZERO)); } #[cfg(unix)] @@ -640,10 +697,26 @@ mod run_tests { #[cfg(unix)] #[test] fn a_helper_that_keeps_writing_still_times_out() { - let start = Instant::now(); - let err = run("yes", &[], Duration::from_millis(100)).unwrap_err(); - assert!(err.contains("didn't finish within"), "{err}"); - assert!(start.elapsed() < Duration::from_secs(5)); + let dir = tempfile::tempdir().unwrap(); + let writing = dir.path().join("writing"); + // More than a pipe holds, so the marker appears only while its output is being read. + let mut cmd = command("/bin/sh"); + cmd.args(["-c", "yes | head -c 1048576; : > \"$1\"; exec yes", "sh"]).arg(&writing); + let (mut output_pending, mut marked) = (false, false); + // Only stops a broken test. + let guard = Instant::now(); + let timed_out = run_command_until(cmd, "yes", Duration::from_secs(5), |pending| { + output_pending |= pending == Pending::Output; + marked = writing.exists(); + if marked || guard.elapsed() > Duration::from_secs(120) { + return false; + } + std::thread::yield_now(); + true + }); + assert!(marked, "the helper never wrote its marker"); + assert_eq!(timed_out, Err(HelperFailure::Unfinished("yes didn't finish within 5 seconds".into()))); + assert!(!output_pending, "yes exited"); } /// The thread that starts a detached process waits for it, so the process is reaped when it @@ -739,104 +812,95 @@ mod explorer_tests { #[cfg(test)] mod inherited_pipe_tests { use super::*; - use std::io::Write; + use std::io::{BufRead, BufReader, Read, Write}; + use std::net::{TcpListener, TcpStream}; fn fixture_args(name: &str, marker: &str) -> Vec { let (_, module) = module_path!().split_once("::").unwrap(); - // libtest accepts arbitrary skip filters; this one carries our private fixture path. + // libtest accepts arbitrary skip filters; this one carries the test's address. vec!["--ignored".into(), "--exact".into(), format!("{module}::{name}"), "--nocapture".into(), "--skip".into(), marker.into()] } - fn fixture_dir() -> std::path::PathBuf { + fn fixture_address() -> String { let args: Vec = std::env::args().collect(); - std::path::PathBuf::from(&args[args.iter().position(|arg| arg == "--skip").unwrap() + 1]) + args[args.iter().position(|arg| arg == "--skip").unwrap() + 1].clone() } + /// Stops a broken test: how long the descendant holds the pipes when the test neither answers + /// nor closes its connection, as when a capture waits for the pipes instead of timing out, and + /// how long the test waits for each step of the fixtures. + const HOLD: Duration = Duration::from_secs(60); + #[test] #[ignore = "self-spawned subprocess fixture"] fn pipe_holder() { - let dir = fixture_dir(); + let mut test = TcpStream::connect(fixture_address()).unwrap(); let buffer = [b'x'; 64 << 10]; - // Both streams exceed the capture cap before the direct child exits. + // Both streams exceed the capture cap before the test lets the time limit pass. for _ in 0..144 { std::io::stdout().write_all(&buffer).unwrap(); std::io::stderr().write_all(&buffer).unwrap(); } - std::fs::write(dir.join("ready"), []).unwrap(); - // Hold the pipes far longer than any deadline the test tries, so a capture that waited - // for them would show; the test's guard stops this early. - let start = Instant::now(); - while !dir.join("stop").exists() && start.elapsed() < HOLD { - std::thread::sleep(Duration::from_millis(10)); - } - std::fs::write(dir.join("done"), []).unwrap(); + std::io::stdout().flush().unwrap(); + test.write_all(b"ready\n").unwrap(); + // Holds the pipes until the test closes its side of the connection. Closing this side + // tells the test that the pipes are about to close. + test.set_read_timeout(Some(HOLD)).unwrap(); + let _ = test.read(&mut [0; 1]); + drop(test); } #[test] #[ignore = "self-spawned subprocess fixture"] fn pipe_parent() { - let dir = fixture_dir(); - let descendant = command(std::env::current_exe().unwrap()).args(fixture_args("pipe_holder", dir.to_str().unwrap())).spawn().unwrap(); - std::fs::write(dir.join("spawned"), []).unwrap(); - // No deadline of its own: run() kills this process at its deadline if it is too slow. - let start = Instant::now(); - while !dir.join("ready").exists() && start.elapsed() < HOLD { - std::thread::sleep(Duration::from_millis(10)); - } - assert!(dir.join("ready").exists(), "descendant did not fill both captured pipes"); - std::fs::write(dir.join("parent-returning"), []).unwrap(); - // Dropping Child leaves the finite fixture running with inherited stdout/stderr. - drop(descendant); - } - - /// How long the descendant holds the pipes when nothing stops it. - const HOLD: Duration = Duration::from_secs(120); - - struct StopHolder(tempfile::TempDir); - - impl Drop for StopHolder { - fn drop(&mut self) { - let _ = std::fs::write(self.0.path().join("stop"), []); - if !self.0.path().join("spawned").exists() { - return; - } - let start = Instant::now(); - while !self.0.path().join("done").exists() && start.elapsed() < Duration::from_secs(30) { - std::thread::sleep(Duration::from_millis(10)); - } - } + let address = fixture_address(); + // Dropping Child leaves the descendant running with the inherited stdout and stderr. + drop(command(std::env::current_exe().unwrap()).args(fixture_args("pipe_holder", &address)).spawn().unwrap()); } #[test] fn exited_helper_does_not_wait_past_deadline_for_inherited_pipes() { - let exe = std::env::current_exe().unwrap(); - // The direct child has to start a second test process and fill both pipes before the - // deadline, which can take seconds on a slow or emulated machine. An attempt where it - // didn't get that far says nothing about inherited pipes: retry with a longer deadline. - let mut deadline = Duration::from_secs(1); - loop { - let holder = StopHolder(tempfile::tempdir().unwrap()); - let args = fixture_args("pipe_parent", holder.0.path().to_str().unwrap()); - let args: Vec<&str> = args.iter().map(String::as_str).collect(); - let start = Instant::now(); - let result = run(exe.to_str().unwrap(), &args, deadline); - let elapsed = start.elapsed(); - if !holder.0.path().join("parent-returning").exists() && deadline < Duration::from_secs(16) { - deadline *= 4; - continue; + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + listener.set_nonblocking(true).unwrap(); + let mut cmd = command(std::env::current_exe().unwrap()); + cmd.args(fixture_args("pipe_parent", &listener.local_addr().unwrap().to_string())); + let mut holder = None; + // Only stops a broken test: a direct child that never exits, or a descendant that never + // connects. + let guard = Instant::now(); + let result = run_command_until(cmd, "the fixture", Duration::from_secs(5), |pending| match pending { + Pending::Helper => { + std::thread::yield_now(); + guard.elapsed() < HOLD } - assert!(holder.0.path().join("parent-returning").exists(), "direct child did not exit its fixture within {deadline:?}"); - assert!( - matches!(&result, Err(error) if error.contains("didn't finish within")), - "expected a pipe deadline error; helper returned success: {}, elapsed: {elapsed:?}", - result.is_ok() - ); - // The descendant would hold the pipes for HOLD, far past this bound. - assert!(deadline * 2 < HOLD); - assert!(elapsed < deadline * 2, "capture exceeded its caller deadline {deadline:?}: {elapsed:?}"); - // The guard stops the finite descendant and waits for its completion marker on failures too. - break; - } + // The direct child has exited and the descendant holds the helper's pipes. Once the + // descendant has filled both, the time limit passes. + Pending::Output => { + assert!(holder.is_none(), "the run kept waiting after its time limit passed"); + let stream = loop { + match listener.accept() { + Ok((stream, _)) => break stream, + Err(e) if e.kind() == std::io::ErrorKind::WouldBlock && guard.elapsed() < HOLD => std::thread::yield_now(), + Err(e) => panic!("the descendant didn't connect ({e})"), + } + }; + stream.set_nonblocking(false).unwrap(); + stream.set_read_timeout(Some(HOLD)).unwrap(); + let mut ready = String::new(); + BufReader::new(&stream).read_line(&mut ready).unwrap(); + assert_eq!(ready, "ready\n"); + holder = Some(stream); + false + } + }); + // The output is more than 8 MB, so a failure shows only its length. + assert_eq!(result.map(|output| output.len()), Err(HelperFailure::Unfinished("the fixture didn't finish within 5 seconds".into()))); + // Lets the descendant go and waits until it has closed its end. The read time limit only + // stops a broken test. + let mut holder = holder.expect("the direct child didn't exit while the descendant held its output"); + holder.shutdown(std::net::Shutdown::Write).unwrap(); + holder.set_read_timeout(Some(HOLD)).unwrap(); + assert_eq!(holder.read_to_end(&mut Vec::new()).unwrap(), 0); } } diff --git a/crates/update/src/self_update.rs b/crates/update/src/self_update.rs index f96c3af63..7cadb507d 100644 --- a/crates/update/src/self_update.rs +++ b/crates/update/src/self_update.rs @@ -2389,7 +2389,7 @@ mod tests { let (src, image, mount) = (dir.path().join("src"), dir.path().join("test.dmg"), dir.path().join("mount")); launcher_bundle(&src); std::fs::create_dir(&mount).unwrap(); - let _one_at_a_time = crate::install::macos::DISK_IMAGES.lock().unwrap_or_else(std::sync::PoisonError::into_inner); + let _one_at_a_time = crate::install::macos::disk_image_turn(); let text = std::ffi::OsStr::new; let created = hdiutil( &[text("create"), text("-quiet"), text("-format"), text("UDZO"), text("-srcfolder"), src.as_os_str(), image.as_os_str()], @@ -3532,7 +3532,7 @@ mod tests { let src = dir.path().join("src"); bundle(&src, "0.2.0"); let dmg = dir.path().join("artcraft-launcher-0.2.0-macos-universal.dmg"); - let one_at_a_time = install::macos::DISK_IMAGES.lock().unwrap_or_else(std::sync::PoisonError::into_inner); + let one_at_a_time = install::macos::disk_image_turn(); let ok = std::process::Command::new("hdiutil") .args(["create", "-quiet", "-format", "UDZO", "-volname", "ArtCraft Launcher 0.2.0", "-srcfolder"]) .arg(&src) @@ -3556,6 +3556,7 @@ mod tests { let expect = install::macos::Expect { team: None, version: None, quit_first: false }; let stop = Stop::default(); let wait = install::macos::CheckTurn { stop: &stop, phase: &mut |_| {} }; + let _other_processes = install::macos::other_test_processes_wait(); let placed = install::macos::install_dmg(&crate::suite::LAUNCHER, &dmg, Some(&existing), None, false, &Paths::under(dir.path()), &expect, wait) .unwrap(); @@ -3584,7 +3585,7 @@ mod tests { .unwrap(); std::fs::write(contents.join("MacOS/ArtCraft Launcher"), version).unwrap(); let dmg = dir.join(format!("built-{version}.dmg")); - let one_at_a_time = install::macos::DISK_IMAGES.lock().unwrap_or_else(std::sync::PoisonError::into_inner); + let one_at_a_time = install::macos::disk_image_turn(); let ok = std::process::Command::new("hdiutil") .args(["create", "-quiet", "-format", "UDZO", "-volname", "ArtCraft Launcher", "-srcfolder"]) .arg(dir.join(format!("src-{version}"))) @@ -3646,6 +3647,8 @@ mod tests { let (url, requests) = serve(body.clone(), vec![Reply::Full, Reply::Full]); let release = launcher_release("0.2.0", &body, url, dir.path()); let kept = install::download_path(&paths, &release.assets[0]); + // The updates below open the disk image. + let _other_processes = install::macos::other_test_processes_wait(); for _ in 0..2 { let error = prepare_update(&crate::suite::LAUNCHER, &install, &release, platform, &http, &paths, &stop, &mut phase, &|| Ok(()), None) .unwrap_err(); diff --git a/crates/update/src/updater.rs b/crates/update/src/updater.rs index 86ef6d996..aad1d1e8a 100644 --- a/crates/update/src/updater.rs +++ b/crates/update/src/updater.rs @@ -86,7 +86,7 @@ type Found = Result, String>; type InstallProbe = Arc bool + Send + Sync>; /// Whether this copy can install `release` itself. It reads the installed files, which can take -/// long on slow storage, so the check's thread calls it, never a frame. +/// long on slow storage, so the check's thread and the offer's thread call it, never a frame. fn can_install_itself(app: &'static App, release: &Release) -> bool { self_update::is_self_updating(app) && self_update::release_installs(app, release) } @@ -149,7 +149,19 @@ pub struct Updater { requested: bool, started: bool, check: Option>, - /// Replaces [`can_install_itself`] on the check's thread (tests). + /// A release the app offered ([`Self::offer`]) while its thread reads whether this copy can + /// install it itself; `tick` opens the prompt with the answer. + offered: Option>, + /// The newest release offered while `offered` was still being inspected; it is inspected + /// next, in place of the earlier one. + next_offer: Option, + /// An installation failed while `offered` was still being inspected: its answer opens no + /// prompt over the one that says why the installation failed. + offer_outdated: bool, + /// The app's context, from the first frame or check that passed it, so that the offer's + /// thread can ask for a frame once it has answered. + repaint: Option, + /// Replaces [`can_install_itself`] on the check's and the offer's thread (tests). probe: Option, /// Whether the copy could install the release that is installing itself, as the prompt that /// started the installation said. A failed installation reopens the prompt with it. @@ -162,7 +174,8 @@ pub struct Updater { /// An update is ready and waits for the app to exit; nothing starts a second one. installed: bool, /// [`Self::show_if`] returns [`Action::Close`] at its next frame that may close: once when an - /// installation finishes, and again for each [`Self::restart_to_update`]. + /// installation finishes, and again for each [`Self::restart_to_update`]. Later on the prompt + /// clears it. close_wanted: bool, /// The folders that hold the outcome records ([`self_update::take_outcome`]) in place of the /// app's own (tests). @@ -194,6 +207,10 @@ impl Updater { requested: false, started: false, check: None, + offered: None, + next_offer: None, + offer_outdated: false, + repaint: None, probe: None, installing_itself: false, install: None, @@ -249,8 +266,8 @@ impl Updater { self } - /// Replaces [`can_install_itself`], which the check's thread calls for a release it found - /// (tests). + /// Replaces [`can_install_itself`], which the check's thread calls for a release it found and + /// the offer's thread for a release the app offered (tests). #[cfg(test)] fn with_probe(mut self, probe: InstallProbe) -> Self { self.probe = Some(probe); @@ -342,16 +359,68 @@ impl Updater { self.close_wanted = true; } - /// Opens the startup prompt for a release the app found itself. After a failed update the - /// prompt says why it failed, like the one a check opens. Opening the prompt sets - /// [`Self::status`] to [`Status::Idle`]. It reads the installed files on the calling thread to - /// decide whether the prompt offers Update and Restart; a release found by a check is - /// inspected on the check's thread instead. + /// Offers a release the app found itself: the startup prompt opens at a later [`Self::tick`], + /// once a thread of its own has read the installed files to decide whether the prompt offers + /// Update and Restart, as a check does for a release it finds. After a failed update the + /// prompt says why it failed, like the one a check opens. An offer sets [`Self::status`] to + /// [`Status::Idle`] when it is made, and a requested check that answers afterwards reports as + /// usual. A later offer replaces one that has not opened yet; while an inspection runs, only + /// the newest offer waits for the next one, so one thread at most reads the files. An offer + /// closes the prompt for an earlier release, which calls off a Save and Update that has not + /// started its installation yet. An offer still being inspected when an installation fails + /// opens no prompt. pub fn offer(&mut self, release: Release) { + if self.install.is_some() || self.installed || self.read_choice() { + return; + } + self.status = Status::Idle; + // The prompt for an earlier release closes while this one is inspected: nothing installs + // the earlier release from it, and a save it asked for installs nothing. + self.prompt = None; + if self.offered.is_some() { + self.next_offer = Some(release); + return; + } + self.inspect_offer(release); + } + + /// Starts the thread that reads whether this copy can install the offered `release` itself. + fn inspect_offer(&mut self, release: Release) { + self.offer_outdated = false; + let (tx, rx) = channel(); + let (probe, app, repaint) = (self.probe.clone(), self.app, self.repaint.clone()); + // Kept for the prompt in case the thread cannot start. + let fallback = release.clone(); + let spawned = std::thread::Builder::new().name("update-offer".into()).spawn(move || { + let inspect = || match &probe { + Some(probe) => probe(app, &release), + None => can_install_itself(app, &release), + }; + // A panicking inspection offers Download rather than nothing. + let installs_itself = std::panic::catch_unwind(std::panic::AssertUnwindSafe(inspect)).unwrap_or(false); + let _ = tx.send((release, installs_itself)); + if let Some(ctx) = repaint { + ctx.request_repaint(); + } + }); + match spawned { + Ok(_) => self.offered = Some(rx), + Err(e) => { + // Without the thread the prompt offers Download, without reading the files here. + log::warn!("{} couldn't inspect the install for an offered update ({e})", self.app.name); + self.offered = None; + self.open_offer(fallback, false); + } + } + } + + /// Opens the prompt for an offered release once its thread has answered, unless an + /// installation started or the launcher took the app over meanwhile. The status stays as a + /// requested check left it. + fn finish_offer(&mut self, release: Release, installs_itself: bool) { + // The launcher may have pinned the app while the files were read, as during a check. if self.install.is_none() && !self.installed && !self.read_choice() { - let installs_itself = can_install_itself(self.app, &release); self.open_offer(release, installs_itself); - self.status = Status::Idle; } } @@ -371,7 +440,15 @@ impl Updater { self.prompt.is_some() } + /// Keeps the first context passed in for the offer's thread (`repaint`). + fn remember(&mut self, ctx: &egui::Context) { + if self.repaint.is_none() { + self.repaint = Some(ctx.clone()); + } + } + fn begin(&mut self, ctx: &egui::Context, requested: bool) { + self.remember(ctx); if self.install.is_some() || self.installed { if requested { self.status = self.pending_status(); @@ -479,6 +556,8 @@ impl Updater { match answer { Ok(Some((release, installs_itself))) => { match &mut self.prompt { + // An offer still being inspected opens its own prompt, with the failure's reason. + None if self.offered.is_some() => {} None => self.open_offer(release, installs_itself), // A prompt the app opened before (`offer`) says why the last update failed. Some(prompt) => { @@ -500,9 +579,10 @@ impl Updater { } } - /// Picks up a finished check or installation. Call once per frame, before [`Self::show`]. It - /// keeps the UI awake while either is running. + /// Picks up a finished check, offer or installation. Call once per frame, before + /// [`Self::show`]. It keeps the UI awake while any of them is running. pub fn tick(&mut self, ctx: &egui::Context) { + self.remember(ctx); if let Some(rx) = &self.check { match rx.try_recv() { Ok(answer) => { @@ -516,6 +596,36 @@ impl Updater { } } } + if let Some(rx) = &self.offered { + let answer = match rx.try_recv() { + Ok(answer) => Some(answer), + Err(TryRecvError::Empty) => { + ctx.request_repaint_after(Duration::from_millis(100)); + None + } + Err(TryRecvError::Disconnected) => { + log::warn!("{} stopped inspecting the install for an offered update", self.app.name); + self.offered = None; + None + } + }; + if let Some((release, installs_itself)) = answer { + self.offered = None; + // A newer offer replaces this one before its prompt opens, and an installation + // that failed meanwhile keeps its own prompt. + let outdated = std::mem::take(&mut self.offer_outdated); + if self.next_offer.is_none() && !outdated { + self.finish_offer(release, installs_itself); + } + } + // The newer offer that waited for this inspection is inspected now. + if self.offered.is_none() + && let Some(release) = self.next_offer.take() + { + self.inspect_offer(release); + ctx.request_repaint_after(Duration::from_millis(100)); + } + } if let Some((rx, _)) = &self.install { let outcome = match rx.try_recv() { Ok(outcome) => Some(outcome), @@ -551,6 +661,12 @@ impl Updater { if matches!(self.status, Status::Installing) { self.status = Status::Idle; } + // An offer made before the installation started, still being inspected or + // waiting for it, would replace the prompt that says why: it opens nothing. + if self.offered.is_some() { + self.offer_outdated = true; + } + self.next_offer = None; // The prompt may have been dismissed meanwhile: bring it back with the reason. if self.prompt.is_none() && let Some(release) = release @@ -620,8 +736,10 @@ impl Updater { action } StartupPromptResponse::Later => { - // An installation carries on and reports through `tick`. + // An installation carries on and reports through `tick`. A ready update drops the + // close it asked for: it installs at the exit, or Restart to Update asks again. self.prompt = None; + self.close_wanted = false; Action::None } } @@ -857,6 +975,27 @@ mod tests { assert!(updater.check.is_none(), "the check has reported"); } + /// Waits for each offer's thread to answer on its channel (it always sends one), then hands + /// the answer to `tick` as a frame would, until no offer is left to inspect. + pub(super) fn settle_offer(updater: &mut Updater) { + while let Some(rx) = updater.offered.take() { + let (tx, answer) = channel(); + if let Ok(offered) = rx.recv() { + assert!(tx.send(offered).is_ok()); + } + drop(tx); + updater.offered = Some(answer); + updater.tick(&egui::Context::default()); + } + assert!(updater.next_offer.is_none(), "every offer has answered"); + } + + /// Offers [`newer`] as the app would and waits for its prompt. + pub(super) fn offer_now(updater: &mut Updater) { + updater.offer(newer()); + settle_offer(updater); + } + /// #391: Download opens only a safe web link, whoever built the `Release`. #[test] fn download_opens_only_a_safe_release_page() { @@ -1060,6 +1199,126 @@ mod tests { assert_eq!(*calls.lock().unwrap_or_else(PoisonError::into_inner), 1, "the frame did not inspect the install again"); } + /// A release the app offers itself is inspected on a thread of its own, as one a check finds + /// is: `offer` and a frame that runs while reading the installed files is stalled return at + /// once, and the prompt opens with the thread's answer at the frame after it answers. + #[test] + fn a_stalled_offer_inspection_does_not_block_a_frame() { + let ctx = egui::Context::default(); + let (seen_tx, seen) = channel(); + let (resume, resumed) = channel::<()>(); + let resumed = Mutex::new(resumed); + let calls = Arc::new(Mutex::new(0_u32)); + let probe_calls = Arc::clone(&calls); + let mut u = updater(Ok(None)).with_probe(Arc::new(move |_, _| { + *probe_calls.lock().unwrap_or_else(PoisonError::into_inner) += 1; + let _ = seen_tx.send(()); + // Stalled until the test lets it go, like a read on storage that does not answer. + let _ = resumed.lock().unwrap_or_else(PoisonError::into_inner).recv(); + true + })); + u.offer(newer()); + assert!(u.prompt.is_none(), "offer returns before the install is inspected"); + assert!(seen.recv().is_ok(), "the offer's thread inspects the install"); + u.tick(&ctx); + assert!(u.prompt.is_none(), "no prompt while the inspection is stalled"); + assert!(u.offered.is_some(), "the offer is still being inspected"); + + assert!(resume.send(()).is_ok()); + settle_offer(&mut u); + assert!(u.prompt.as_ref().is_some_and(|p| p.is_self_updating), "the prompt offers Update and Restart"); + assert_eq!(u.status(), &Status::Idle); + assert_eq!(*calls.lock().unwrap_or_else(PoisonError::into_inner), 1, "the frame did not inspect the install again"); + } + + /// Offers made while a slow inspection runs start no thread of their own: the newest waits for + /// it, is inspected next, and its prompt opens in place of the earlier ones. + #[test] + fn offers_during_a_stalled_inspection_wait_for_it() { + let (seen_tx, seen) = channel(); + let (resume, resumed) = channel::<()>(); + let resumed = Mutex::new(resumed); + let inspected = Arc::new(Mutex::new(Vec::new())); + let log = Arc::clone(&inspected); + let mut u = updater(Ok(None)).with_probe(Arc::new(move |_: &'static App, release: &Release| { + log.lock().unwrap_or_else(PoisonError::into_inner).push(release.tag.clone()); + let _ = seen_tx.send(()); + let _ = resumed.lock().unwrap_or_else(PoisonError::into_inner).recv(); + true + })); + let tagged = |tag: &str| Release { tag: tag.into(), ..newer() }; + u.offer(tagged("v9.0.0")); + assert!(seen.recv().is_ok(), "the first offer is being inspected"); + u.offer(tagged("v9.0.1")); + u.offer(tagged("v9.0.2")); + // One go-ahead per offer, so that a thread started for each would not stall the test. + for _ in 0..3 { + assert!(resume.send(()).is_ok()); + } + settle_offer(&mut u); + let inspected = inspected.lock().unwrap_or_else(PoisonError::into_inner).clone(); + assert_eq!(inspected, ["v9.0.0", "v9.0.2"], "one inspection at a time, and only the newest offer waits"); + assert_eq!(u.prompt.as_ref().map(|p| p.release.tag.as_str()), Some("v9.0.2")); + } + + /// A requested check that answers while an offer is inspected keeps its answer when the + /// offer's prompt opens. + #[test] + fn an_offer_opening_after_a_requested_check_keeps_its_answer() { + let ctx = egui::Context::default(); + let mut u = updater(Ok(None)); + u.check_now(&ctx); + u.offer(newer()); + settle(&mut u, &ctx); + assert_eq!(u.status(), &Status::UpToDate); + settle_offer(&mut u); + assert!(u.prompt_open()); + assert_eq!(u.status(), &Status::UpToDate, "the offer's prompt does not close the check's result"); + } + + /// An installation that starts while an offer is inspected keeps the offer's prompt from + /// opening over it. + #[test] + fn an_offer_answering_during_an_install_opens_no_prompt() { + let mut u = updater(Ok(None)); + u.offer(newer()); + let (_tx, rx) = channel(); + u.install = Some((rx, newer())); + settle_offer(&mut u); + assert!(!u.prompt_open()); + } + + /// An installation that fails while an offer made before it is still inspected keeps the + /// prompt that says why: the offer's answer, and an offer waiting for it, open nothing. + #[test] + fn an_offer_answering_after_a_failed_install_keeps_the_failure() { + let ctx = egui::Context::default(); + let (seen_tx, seen) = channel(); + let (resume, resumed) = channel::<()>(); + let resumed = Mutex::new(resumed); + let mut u = updater(Ok(None)).with_probe(Arc::new(move |_: &'static App, _: &Release| { + let _ = seen_tx.send(()); + let _ = resumed.lock().unwrap_or_else(PoisonError::into_inner).recv(); + true + })); + u.offer(newer()); + assert!(seen.recv().is_ok(), "the offer is being inspected"); + u.offer(Release { tag: "v9.0.2".into(), ..newer() }); + let (tx, rx) = channel(); + u.install = Some((rx, newer())); + assert!(tx.send(Err("disk full".into())).is_ok()); + u.tick(&ctx); + assert_eq!(prompt_message(&u), "disk full"); + for _ in 0..2 { + assert!(resume.send(()).is_ok()); + } + settle_offer(&mut u); + assert_eq!(prompt_message(&u), "disk full", "the failure's prompt stays open"); + u.offer(newer()); + settle_offer(&mut u); + assert_eq!(prompt_message(&u), "", "a later offer opens its own prompt"); + } + #[test] fn a_failed_install_returns_to_the_prompt_even_after_it_was_dismissed() { let ctx = egui::Context::default(); @@ -1107,14 +1366,14 @@ mod tests { } let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); u.request_install(&ctx, false); let mut u = u.with_translator(shout); let message = |u: &Updater| u.prompt.as_ref().and_then(StartupPrompt::message).unwrap_or_default(); assert!(message(&u).starts_with("SAVE OR CLOSE"), "{}", message(&u)); // And the prompts it opens later. u.prompt = None; - u.offer(newer()); + offer_now(&mut u); u.request_install(&ctx, false); assert!(message(&u).starts_with("SAVE OR CLOSE"), "{}", message(&u)); } @@ -1158,14 +1417,14 @@ mod tests { u.check_now(&ctx); assert!(u.check.is_none(), "no check after an install"); u.offer(newer()); - assert!(!u.prompt_open(), "no second offer after an install"); + assert!(u.offered.is_none() && !u.prompt_open(), "no second offer after an install"); } #[test] fn an_install_waits_while_the_app_holds_unsaved_work() { let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); u.request_install(&ctx, false); assert!(u.install.is_none(), "nothing is scheduled while there is unsaved work"); assert!(u.prompt.as_ref().is_some_and(|p| !p.is_installing && p.message().is_some())); @@ -1183,7 +1442,7 @@ mod tests { } let ctx = egui::Context::default(); let mut u = updater(Ok(None)).with_translator(translate); - u.offer(newer()); + offer_now(&mut u); u.request_install(&ctx, false); let message = |u: &Updater| u.prompt.as_ref().and_then(StartupPrompt::message).unwrap_or_default(); assert!(message(&u).starts_with("Save or close"), "{}", message(&u)); @@ -1211,7 +1470,7 @@ mod tests { } let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); let (tx, rx) = channel(); u.install = Some((rx, newer())); assert!(tx.send(Ok(Restart::scheduled())).is_ok()); @@ -1231,7 +1490,7 @@ mod tests { fn a_finished_install_keeps_asking_to_close_until_the_app_can() { let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); let (tx, rx) = channel(); u.install = Some((rx, newer())); assert!(tx.send(Ok(Restart::scheduled())).is_ok()); @@ -1297,7 +1556,7 @@ mod tests { /// An updater whose install has finished and waits for the app to close. fn installed(ctx: &egui::Context) -> Updater { let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); let (tx, rx) = channel(); u.install = Some((rx, newer())); assert!(tx.send(Ok(Restart::scheduled())).is_ok()); @@ -1311,7 +1570,7 @@ mod tests { fn save_and_update_saves_first_and_then_installs() { let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); click_save(&mut u, &ctx); assert!(u.take_save_request(), "the click asks the app to save"); assert!(!u.take_save_request(), "once"); @@ -1329,7 +1588,7 @@ mod tests { fn a_note_from_an_earlier_click_goes_when_the_save_starts() { let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); u.request_install(&ctx, false); assert!(prompt_message(&u).starts_with("Save or close")); click_save(&mut u, &ctx); @@ -1341,7 +1600,7 @@ mod tests { fn a_failed_save_says_why_and_calls_the_install_off() { let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); click_save(&mut u, &ctx); u.save_stopped(Some("disk full".into())); assert!(!saving(&u)); @@ -1357,7 +1616,7 @@ mod tests { fn a_save_that_leaves_work_unsaved_goes_back_to_the_note() { let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); click_save(&mut u, &ctx); assert!(u.take_save_request()); u.save_stopped(None); @@ -1372,7 +1631,7 @@ mod tests { fn work_that_can_no_longer_be_saved_stops_the_saving() { let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); click_save(&mut u, &ctx); frame_saving(&mut u, &ctx, false, false, Vec::new()); assert!(!saving(&u)); @@ -1383,7 +1642,7 @@ mod tests { #[test] fn a_late_save_stopped_changes_nothing() { let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); u.save_stopped(Some("disk full".into())); assert_eq!(prompt_message(&u), ""); } @@ -1393,13 +1652,13 @@ mod tests { fn dismissing_during_the_save_forgets_the_install() { let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); click_save(&mut u, &ctx); let escape = egui::Event::Key { key: egui::Key::Escape, physical_key: None, pressed: true, repeat: false, modifiers: egui::Modifiers::NONE }; frame_saving(&mut u, &ctx, false, true, vec![escape]); assert!(!u.prompt_open()); assert!(!u.take_save_request()); - u.offer(newer()); + offer_now(&mut u); self_updating(&mut u); frame_saving(&mut u, &ctx, true, false, Vec::new()); assert!(u.prompt.as_ref().is_some_and(|p| !p.is_installing)); @@ -1411,9 +1670,9 @@ mod tests { fn a_new_offer_during_the_save_installs_nothing() { let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); click_save(&mut u, &ctx); - u.offer(newer()); + offer_now(&mut u); self_updating(&mut u); frame_saving(&mut u, &ctx, true, false, Vec::new()); assert!(u.prompt.as_ref().is_some_and(|p| !p.is_installing)); @@ -1421,12 +1680,46 @@ mod tests { assert!(!u.take_save_request()); } + /// A save that ends while a newer offer is still inspected installs nothing either: the save + /// was asked for the earlier release. + #[test] + fn a_save_ending_while_a_new_offer_is_inspected_installs_nothing() { + let ctx = egui::Context::default(); + let mut u = updater(Ok(None)); + offer_now(&mut u); + click_save(&mut u, &ctx); + assert!(u.take_save_request()); + u.offer(newer()); + assert!(!u.prompt_open(), "the earlier release's prompt closes while the new one is inspected"); + frame_saving(&mut u, &ctx, true, false, Vec::new()); + assert!(u.install.is_none()); + settle_offer(&mut u); + assert!(u.prompt.as_ref().is_some_and(|p| !p.is_installing && !p.is_saving)); + assert_eq!(prompt_message(&u), "", "{}", prompt_message(&u)); + assert!(u.install.is_none()); + } + + /// The prompt for an earlier release cannot install it while a newer offer is inspected. + #[test] + fn a_new_offer_closes_the_prompt_for_the_earlier_release() { + let ctx = egui::Context::default(); + let mut u = updater(Ok(None)); + offer_now(&mut u); + self_updating(&mut u); + u.offer(Release { tag: "v9.0.2".into(), ..newer() }); + u.request_install(&ctx, true); + assert!(!u.prompt_open(), "nothing is left to click for the earlier release"); + assert!(u.install.is_none()); + settle_offer(&mut u); + assert_eq!(u.prompt.as_ref().map(|p| p.release.tag.as_str()), Some("v9.0.2")); + } + /// The button only shows with unsaved work, in an app that can save it. `show_if` never offers it. #[test] fn the_button_needs_both_unsaved_work_and_an_app_that_can_save() { let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); self_updating(&mut u); let offered = |u: &Updater| u.prompt.as_ref().is_some_and(|p| p.offer_save); frame_saving(&mut u, &ctx, false, true, Vec::new()); @@ -1455,6 +1748,22 @@ mod tests { assert!(u.install.is_none()); } + /// Later on a finished install drops the close it asked for: saving the work afterwards does + /// not close the app. The update stays ready, and Restart to Update asks for the close again. + #[test] + fn later_on_a_finished_install_does_not_close_the_app_after_a_save() { + let ctx = egui::Context::default(); + let mut u = installed(&ctx); + assert_eq!(frame(&mut u, &ctx, false), Action::None, "unsaved work holds the close back"); + let escape = egui::Event::Key { key: egui::Key::Escape, physical_key: None, pressed: true, repeat: false, modifiers: egui::Modifiers::NONE }; + assert_eq!(frame_saving(&mut u, &ctx, false, false, vec![escape]).0, Action::None); + assert!(!u.prompt_open()); + assert_eq!(frame(&mut u, &ctx, true), Action::None, "the work is saved, and the user chose Later"); + assert!(u.restart.is_some(), "the update still waits for the exit"); + u.restart_to_update(); + assert_eq!(frame(&mut u, &ctx, true), Action::Close); + } + /// A stopped save on a finished install keeps saying the update is ready. #[test] fn a_stopped_save_on_a_finished_install_keeps_its_note() { @@ -1502,7 +1811,7 @@ mod tests { use std::sync::atomic::{AtomicUsize, Ordering}; let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); let starts = Arc::new(AtomicUsize::new(0)); let counter = Arc::clone(&starts); let (tx, rx) = channel(); @@ -1534,7 +1843,7 @@ mod tests { use std::sync::atomic::Ordering; let ctx = egui::Context::default(); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); let (starts, restart) = counted_restart(); let (tx, rx) = channel(); u.install = Some((rx, newer())); @@ -1824,7 +2133,7 @@ mod tests { fn a_requested_check_during_an_update_says_where_it_is() { let ctx = egui::Context::default(); let mut u = updater(Ok(Some(newer()))); - u.offer(newer()); + offer_now(&mut u); let (tx, rx) = channel(); u.install = Some((rx, newer())); for _ in 0..2 { @@ -1853,7 +2162,7 @@ mod tests { let ctx = egui::Context::default(); for answer in [Ok(None), Err("offline".to_owned()), Ok(Some((newer(), false)))] { let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); u.check_now(&ctx); assert_eq!(u.status(), &Status::Checking); let (check_tx, check_rx) = channel(); @@ -1868,7 +2177,7 @@ mod tests { assert_eq!(u.status(), &Status::Ready, "after {answer:?}"); let mut u = updater(Ok(None)); - u.offer(newer()); + offer_now(&mut u); u.check_now(&ctx); let (check_tx, check_rx) = channel(); u.check = Some(check_rx); @@ -1904,7 +2213,7 @@ mod tests { fn a_requested_check_finds_a_helper_failure_while_the_app_still_runs() { let ctx = egui::Context::default(); let (_dir, paths, mut u) = with_records("0.1.0"); - u.offer(newer()); + offer_now(&mut u); let (tx, rx) = channel(); u.install = Some((rx, newer())); assert!(tx.send(Ok(Restart::scheduled())).is_ok()); @@ -1941,7 +2250,7 @@ mod tests { use std::sync::atomic::Ordering; let ctx = egui::Context::default(); let (_dir, paths, mut u) = with_records("0.1.0"); - u.offer(newer()); + offer_now(&mut u); let (tx, rx) = channel(); u.install = Some((rx, newer())); assert!(tx.send(Ok(Restart::scheduled())).is_ok()); @@ -1977,11 +2286,11 @@ mod tests { self_update::record_failure(&paths, "disk full"); start_answered(&mut u, &ctx, Ok(None)); assert_eq!(u.status(), &Status::InstallFailed("disk full".into())); - u.offer(newer()); + offer_now(&mut u); assert_eq!(u.prompt.as_ref().and_then(StartupPrompt::message).as_deref(), Some("The update could not be installed: disk full")); assert_eq!(u.status(), &Status::Idle, "the prompt carries the reason"); u.prompt = None; - u.offer(newer()); + offer_now(&mut u); assert_eq!(u.prompt.as_ref().and_then(StartupPrompt::message), None, "the reason is shown once"); } @@ -1992,16 +2301,30 @@ mod tests { let ctx = egui::Context::default(); let (_dir, paths, mut u) = with_records("0.1.0"); self_update::record_failure(&paths, "disk full"); - u.offer(newer()); + offer_now(&mut u); assert_eq!(u.prompt.as_ref().and_then(StartupPrompt::message), None, "the failure is not read before the check at start"); start_answered(&mut u, &ctx, Ok(Some(newer()))); assert_eq!(u.status(), &Status::Idle, "the prompt carries the reason"); assert_eq!(u.prompt.as_ref().and_then(StartupPrompt::message).as_deref(), Some("The update could not be installed: disk full")); u.prompt = None; - u.offer(newer()); + offer_now(&mut u); assert_eq!(u.prompt.as_ref().and_then(StartupPrompt::message), None, "the reason is shown once"); } + /// A check at start that finds the release while the app's own offer is still inspected leaves + /// the prompt to the offer, which says why the last update failed. + #[test] + fn a_check_answering_during_an_offer_leaves_the_prompt_to_the_offer() { + let ctx = egui::Context::default(); + let (_dir, paths, mut u) = with_records("0.1.0"); + self_update::record_failure(&paths, "disk full"); + u.offer(newer()); + start_answered(&mut u, &ctx, Ok(Some(newer()))); + settle_offer(&mut u); + assert_eq!(u.status(), &Status::Idle, "the prompt carries the reason"); + assert_eq!(u.prompt.as_ref().and_then(StartupPrompt::message).as_deref(), Some("The update could not be installed: disk full")); + } + /// An installation that finishes after the updater was dropped and whose helper cannot start, /// or that failed, is recorded, and the next start says why. #[test] diff --git a/crates/update/src/updater_pin_tests.rs b/crates/update/src/updater_pin_tests.rs index 8a4b73d72..7ca3cdf88 100644 --- a/crates/update/src/updater_pin_tests.rs +++ b/crates/update/src/updater_pin_tests.rs @@ -2,7 +2,7 @@ use std::sync::Arc; -use super::tests::{newer, settle}; +use super::tests::{newer, offer_now, settle, settle_offer}; use super::*; use crate::suite::PHOTOCRAFT; @@ -33,7 +33,7 @@ fn a_pinned_app_is_not_prompted_and_the_network_is_not_asked() { assert_eq!(u.status(), &Status::Managed, "{track:?}"); assert_eq!(u.managed(), Some(&Choice::Managed(track.clone()))); u.offer(newer()); - assert!(!u.prompt_open(), "an offer is held too: {track:?}"); + assert!(u.offered.is_none() && !u.prompt_open(), "an offer is held too: {track:?}"); } } @@ -86,7 +86,7 @@ fn a_prompt_opened_before_the_pin_cannot_install_the_stable_release() { let dir = tempfile::tempdir().unwrap(); let path = dir.path().join("versions.json"); let mut u = Updater::new(&PHOTOCRAFT, "0.13.0").with_source(Arc::new(|| Ok(Some(newer())))).with_pins_path(&path); - u.offer(newer()); + offer_now(&mut u); assert!(u.prompt_open()); let mut pins = Pins::default(); pins.set(PHOTOCRAFT.id, &crate::pins::VersionTrack::Pinned("v0.13.0".into())); @@ -96,13 +96,27 @@ fn a_prompt_opened_before_the_pin_cannot_install_the_stable_release() { assert!(!u.prompt_open()); } +#[test] +fn a_pin_made_while_an_offer_is_inspected_holds_the_offer() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("versions.json"); + let mut u = Updater::new(&PHOTOCRAFT, "0.13.0").with_source(Arc::new(|| Ok(Some(newer())))).with_pins_path(&path); + u.offer(newer()); + let mut pins = Pins::default(); + pins.set(PHOTOCRAFT.id, &crate::pins::VersionTrack::Pinned("v0.13.0".into())); + pins.save(&path).unwrap(); + settle_offer(&mut u); + assert!(!u.prompt_open(), "no prompt for the stable release once the launcher pinned the app"); + assert!(u.managed().is_some()); +} + #[test] fn a_check_after_the_pin_closes_a_prompt_opened_before_it() { let ctx = egui::Context::default(); let dir = tempfile::tempdir().unwrap(); let path = dir.path().join("versions.json"); let mut u = Updater::new(&PHOTOCRAFT, "0.13.0").with_source(Arc::new(|| Ok(Some(newer())))).with_pins_path(&path); - u.offer(newer()); + offer_now(&mut u); let mut pins = Pins::default(); pins.set(PHOTOCRAFT.id, &crate::pins::VersionTrack::Nightly); pins.save(&path).unwrap(); 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..f9db3a6e6 100644 --- a/crates/video/README.md +++ b/crates/video/README.md @@ -21,8 +21,9 @@ No codec feature is on by default. | `dnx` | [`dnx`](src/dnx/README.md) | Avid DNxHD / DNxHR (SMPTE ST 2019-1 VC-3): decoder and encoder | | `apv` | [`apv`](src/apv/README.md) | APV (Advanced Professional Video, RFC 9924): decoder (`apv-decode` alone) and encoder (`apv-encode` alone) | | `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) | +| `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 and constant or variable bitrate within the VBV buffer (`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) | @@ -30,3 +31,23 @@ No codec feature is on by default. | `vp9` | [`vp9`](src/vp9/decode/README.md) | VP9: decoder (`vp9-decode` alone) and encoder (`vp9-encode` alone) | | `av1` | [`av1`](src/av1/decode/README.md) | AV1 (AOMedia Video 1): decoder (`av1-decode` alone) and clean-room encoder (`av1-encode`); tiled rav1e fallback for large frames (`av1-large-encode`) | | `threads` | — | Multi-threaded slice/row parallelism via `rayon` | + +## Decoded frames + +Each decoder returns its own picture type. `frame::VideoFrame` is a codec-agnostic form that +every decoder's output converts into with `VideoFrame::try_from` (always built; each conversion +comes with its codec's feature): + +- Planes are `[Y, Cb, Cr]`, `[R, G, B]` or `[Y]` (`ColorFamily`), plus an optional alpha plane. + DNx, VP9 and AV1 (identity matrix) store RGB as G, B, R; the conversion reorders them. +- Samples keep the decoder's storage, `u8` or `u16`, with a bit depth per plane (HEVC chroma may + differ from luma). Converting moves the buffers and copies no samples. +- Chroma subsampling is a log2 shift per axis, 0 to 3 (FFV1 codes up to 3). +- Colour is given as ITU-T H.273 code points (`ColorTags`), mapped from each codec's own + signalling. Codecs that do not signal a value leave it unspecified (2). +- `pts`, sample aspect ratio, field order and the decoder's draft flag are carried over where the + decoder reports them. ProRes signals the picture's shape (4:3 or 16:9); the sample aspect + ratio is worked out from it and the frame size. + +The constructors check that every plane's buffer, stride and size fit the frame, so a picture +with inconsistent fields is an error, not an out-of-bounds read. diff --git a/crates/video/src/frame/convert.rs b/crates/video/src/frame/convert.rs new file mode 100644 index 000000000..4089f7148 --- /dev/null +++ b/crates/video/src/frame/convert.rs @@ -0,0 +1,371 @@ +//! `TryFrom` from each decoder's own output into [`VideoFrame`]. Each conversion is built with +//! the feature of its decoder. + +// Each conversion uses some of these; a build with no decoder feature uses none. +#[allow(unused_imports)] +use super::{ColorFamily, ColorTags, FieldOrder, FrameError, Plane, Samples, Subsampling, VideoFrame}; + +/// A bit depth a decoder reports as `u32`. +#[cfg(any(feature = "hevc-decode", feature = "vp9-decode"))] +fn depth(bits: u32) -> Result { + u8::try_from(bits).map_err(|_| FrameError::Plane("bit depth does not fit the sample storage")) +} + +/// A sample aspect ratio with 0 meaning not signalled. +#[cfg(any(feature = "h264-decode", feature = "hevc-decode", feature = "mpeg2-decode", feature = "dnx"))] +fn sar(num: u32, den: u32) -> Option<(u32, u32)> { + (num != 0 && den != 0).then_some((num, den)) +} + +/// The sample aspect ratio of a ProRes `aspect_ratio_information` code: 1 is square pixels, 2 and +/// 3 give the picture's shape (4:3 and 16:9), 0 and the reserved codes say nothing. +#[cfg(feature = "prores")] +pub(super) fn prores_sar(code: u8, width: u32, height: u32) -> Option<(u32, u32)> { + let (dar_w, dar_h): (u64, u64) = match code { + 1 => return Some((1, 1)), + 2 => (4, 3), + 3 => (16, 9), + _ => return None, + }; + // sar = dar * height / width, in lowest terms. Neither product can overflow `u64`. + let (mut num, mut den) = (dar_w * u64::from(height), dar_h * u64::from(width)); + let (mut a, mut b) = (num, den); + while b != 0 { + (a, b) = (b, a % b); + } + if a == 0 { + return None; + } + num /= a; + den /= a; + match (u32::try_from(num), u32::try_from(den)) { + (Ok(n), Ok(d)) if n != 0 && d != 0 => Some((n, d)), + _ => None, + } +} + +/// ProRes stores `0` for "unspecified" where H.273 uses `2`. +#[cfg(feature = "prores")] +fn h273(code: u8) -> u8 { + if code == 0 { 2 } else { code } +} + +#[cfg(feature = "h264-decode")] +impl TryFrom for VideoFrame { + type Error = FrameError; + + /// An 8-bit 4:2:0 frame. + fn try_from(p: crate::h264::decode::Picture) -> Result { + let planes = vec![ + Plane::new(p.width, p.height, p.y_stride, 8, Samples::U8(p.y))?, + Plane::new(p.chroma_width, p.chroma_height, p.uv_stride, 8, Samples::U8(p.u))?, + Plane::new(p.chroma_width, p.chroma_height, p.uv_stride, 8, Samples::U8(p.v))?, + ]; + let mut f = VideoFrame::new(p.width, p.height, ColorFamily::YCbCr, Subsampling::S420, planes, None)?; + f.color = ColorTags { primaries: p.color.primaries, transfer: p.color.transfer, matrix: p.color.matrix, full_range: p.color.full_range }; + f.pts = Some(p.pts); + f.sar = sar(p.sar.0.into(), p.sar.1.into()); + f.draft = p.draft; + Ok(f) + } +} + +#[cfg(feature = "hevc-decode")] +impl TryFrom for VideoFrame { + type Error = FrameError; + + /// A 4:2:0 or 4:2:2 frame, 8-bit storage at bit depth 8 and 16-bit above. The chroma planes + /// carry the stream's chroma bit depth, which may differ from the luma depth. + fn try_from(p: crate::hevc::decode::Picture) -> Result { + use crate::hevc::decode::{ChromaFormat, Plane as P}; + let bits = depth(p.bit_depth)?; + let chroma_bits = depth(p.bit_depth_chroma)?; + let samples = |pl: P| match pl { + P::U8(v) => Samples::U8(v), + P::U16(v) => Samples::U16(v), + }; + let planes = vec![ + Plane::new(p.width, p.height, p.y_stride, bits, samples(p.y))?, + Plane::new(p.chroma_width, p.chroma_height, p.uv_stride, chroma_bits, samples(p.u))?, + Plane::new(p.chroma_width, p.chroma_height, p.uv_stride, chroma_bits, samples(p.v))?, + ]; + let sub = match p.chroma { + ChromaFormat::C420 => Subsampling::S420, + ChromaFormat::C422 => Subsampling::S422, + }; + let mut f = VideoFrame::new(p.width, p.height, ColorFamily::YCbCr, sub, planes, None)?; + f.color = ColorTags { primaries: p.color.primaries, transfer: p.color.transfer, matrix: p.color.matrix, full_range: p.color.full_range }; + f.pts = Some(p.pts); + f.sar = sar(p.sar.0.into(), p.sar.1.into()); + f.draft = p.draft; + Ok(f) + } +} + +/// VP9 `color_space` as an H.273 matrix: 1 BT.601 (625-line), 2 BT.709, 3 SMPTE 170M, +/// 4 SMPTE 240M, 5 BT.2020 non-constant luminance, 7 RGB. +#[cfg(feature = "vp9-decode")] +pub(super) fn vp9_matrix(color_space: u8) -> u8 { + match color_space { + 1 => 5, + 2 => 1, + 3 => 6, + 4 => 7, + 5 => 9, + 7 => 0, + _ => 2, + } +} + +#[cfg(feature = "vp9-decode")] +impl TryFrom for VideoFrame { + type Error = FrameError; + + /// A YCbCr frame, or an RGB one for `color_space` 7, whose coded G, B, R planes are reordered + /// to R, G, B. VP9 signals only the matrix, so primaries and transfer are unspecified. + fn try_from(p: crate::vp9::decode::Picture) -> Result { + use crate::vp9::decode::Plane as P; + let bits = depth(p.bit_depth)?; + let samples = |pl: P| match pl { + P::U8(v) => Samples::U8(v), + P::U16(v) => Samples::U16(v), + }; + let y = Plane::new(p.width, p.height, p.y_stride, bits, samples(p.y))?; + let u = Plane::new(p.chroma_width, p.chroma_height, p.uv_stride, bits, samples(p.u))?; + let v = Plane::new(p.chroma_width, p.chroma_height, p.uv_stride, bits, samples(p.v))?; + let sub = Subsampling { x: u8::from(p.subsampling_x), y: u8::from(p.subsampling_y) }; + let rgb = p.color.color_space == 7; + let (family, planes) = if rgb { (ColorFamily::Rgb, vec![v, y, u]) } else { (ColorFamily::YCbCr, vec![y, u, v]) }; + let mut f = VideoFrame::new(p.width, p.height, family, sub, planes, None)?; + f.color = ColorTags { matrix: vp9_matrix(p.color.color_space), full_range: p.color.full_range, ..ColorTags::UNSPECIFIED }; + f.pts = Some(p.pts); + f.draft = p.draft; + Ok(f) + } +} + +#[cfg(feature = "av1-decode")] +impl TryFrom for VideoFrame { + type Error = FrameError; + + /// A YCbCr frame, a gray one for a monochrome stream, or an RGB one for a 4:4:4 stream with + /// the identity matrix (`matrix_coefficients` 0), whose coded G, B, R planes are reordered to + /// R, G, B; 16-bit storage at every bit depth. + fn try_from(p: crate::av1::decode::Picture) -> Result { + let [y, u, v] = p.planes; + let y = Plane::packed(p.width, p.height, p.bit_depth, Samples::U16(y))?; + let (family, sub, planes) = if p.mono_chrome { + (ColorFamily::Gray, Subsampling::S444, vec![y]) + } else { + let sub = Subsampling { x: p.subsampling_x, y: p.subsampling_y }; + let (cw, ch) = sub.chroma_size(p.width, p.height); + let u = Plane::packed(cw, ch, p.bit_depth, Samples::U16(u))?; + let v = Plane::packed(cw, ch, p.bit_depth, Samples::U16(v))?; + // AV1 requires 4:4:4 with the identity matrix; a subsampled picture tagged with it + // cannot be RGB and stays as coded. + if p.matrix_coefficients == 0 && sub == Subsampling::S444 { + (ColorFamily::Rgb, sub, vec![v, y, u]) + } else { + (ColorFamily::YCbCr, sub, vec![y, u, v]) + } + }; + let mut f = VideoFrame::new(p.width, p.height, family, sub, planes, None)?; + f.color = + ColorTags { primaries: p.color_primaries, transfer: p.transfer_characteristics, matrix: p.matrix_coefficients, full_range: p.full_range }; + f.pts = Some(p.pts); + f.draft = p.draft; + Ok(f) + } +} + +#[cfg(feature = "mpeg2-decode")] +impl TryFrom for VideoFrame { + type Error = FrameError; + + /// An 8-bit frame. MPEG-1 and MPEG-2 have no full-range flag, so the range is limited. + fn try_from(p: crate::mpeg2::Picture) -> Result { + use crate::mpeg2::{ChromaFormat, FieldOrder as F}; + let sub = match p.chroma { + ChromaFormat::Yuv420 => Subsampling::S420, + ChromaFormat::Yuv422 => Subsampling::S422, + ChromaFormat::Yuv444 => Subsampling::S444, + }; + let (cw, ch) = (p.chroma_width(), p.chroma_height()); + let field_order = match p.field_order() { + None => FieldOrder::Progressive, + Some(F::TopFirst) => FieldOrder::TopFieldFirst, + Some(F::BottomFirst) => FieldOrder::BottomFieldFirst, + }; + let planes = vec![ + Plane::packed(p.width, p.height, 8, Samples::U8(p.y))?, + Plane::packed(cw, ch, 8, Samples::U8(p.cb))?, + Plane::packed(cw, ch, 8, Samples::U8(p.cr))?, + ]; + let mut f = VideoFrame::new(p.width, p.height, ColorFamily::YCbCr, sub, planes, None)?; + if let Some((primaries, transfer, matrix)) = p.info.colour { + f.color = ColorTags { primaries, transfer, matrix, full_range: false }; + } + f.pts = Some(p.pts); + f.sar = sar(p.info.sar.0, p.info.sar.1); + f.field_order = field_order; + Ok(f) + } +} + +#[cfg(feature = "vp8-decode")] +impl TryFrom for VideoFrame { + type Error = FrameError; + + /// An 8-bit 4:2:0 frame. `color_space` 0 (BT.601 YCbCr) maps to matrix 6; VP8 signals no + /// primaries, transfer or range. + fn try_from(p: crate::vp8::Picture) -> Result { + let planes = vec![ + Plane::packed(p.width, p.height, 8, Samples::U8(p.y))?, + Plane::packed(p.chroma_width, p.chroma_height, 8, Samples::U8(p.u))?, + Plane::packed(p.chroma_width, p.chroma_height, 8, Samples::U8(p.v))?, + ]; + let mut f = VideoFrame::new(p.width, p.height, ColorFamily::YCbCr, Subsampling::S420, planes, None)?; + if p.color_space == 0 { + f.color.matrix = 6; + } + f.pts = Some(p.pts); + Ok(f) + } +} + +#[cfg(feature = "prores")] +impl TryFrom for VideoFrame { + type Error = FrameError; + + /// A 4:2:2 or 4:4:4 frame with optional alpha, 16-bit storage. The range is limited. The + /// sample aspect ratio follows from `aspect_ratio` and the frame size. + fn try_from(p: crate::prores::Frame) -> Result { + use crate::prores::{ChromaFormat, Interlace}; + let sub = match p.chroma { + ChromaFormat::Yuv422 => Subsampling::S422, + ChromaFormat::Yuv444 => Subsampling::S444, + }; + let (cw, ch) = sub.chroma_size(p.width, p.height); + let planes = vec![ + Plane::packed(p.width, p.height, p.bit_depth, Samples::U16(p.y))?, + Plane::packed(cw, ch, p.bit_depth, Samples::U16(p.cb))?, + Plane::packed(cw, ch, p.bit_depth, Samples::U16(p.cr))?, + ]; + let alpha = p.alpha.map(|a| Plane::packed(p.width, p.height, p.bit_depth, Samples::U16(a))).transpose()?; + let mut f = VideoFrame::new(p.width, p.height, ColorFamily::YCbCr, sub, planes, alpha)?; + f.color = ColorTags { primaries: h273(p.color.primaries), transfer: h273(p.color.transfer), matrix: h273(p.color.matrix), full_range: false }; + f.sar = prores_sar(p.aspect_ratio, p.width, p.height); + f.field_order = match p.interlace { + Interlace::Progressive => FieldOrder::Progressive, + Interlace::TopFieldFirst => FieldOrder::TopFieldFirst, + Interlace::BottomFieldFirst => FieldOrder::BottomFieldFirst, + }; + Ok(f) + } +} + +#[cfg(feature = "dnx")] +impl TryFrom for VideoFrame { + type Error = FrameError; + + /// A YCbCr frame, or an RGB one whose stored G, B, R planes are reordered to R, G, B; optional + /// alpha, 16-bit storage. The colour volume (`CLV`) gives only the matrix; primaries, transfer + /// and range are not signalled. + fn try_from(p: crate::dnx::Frame) -> Result { + use crate::dnx::{ChromaFormat, ColorVolume, Interlace}; + let sub = match p.chroma { + ChromaFormat::Yuv420 => Subsampling::S420, + ChromaFormat::Yuv422 => Subsampling::S422, + ChromaFormat::Yuv444 => Subsampling::S444, + }; + let (cw, ch) = sub.chroma_size(p.width, p.height); + let y = Plane::packed(p.width, p.height, p.bit_depth, Samples::U16(p.y))?; + let cb = Plane::packed(cw, ch, p.bit_depth, Samples::U16(p.cb))?; + let cr = Plane::packed(cw, ch, p.bit_depth, Samples::U16(p.cr))?; + let (family, planes) = if p.rgb { (ColorFamily::Rgb, vec![cr, y, cb]) } else { (ColorFamily::YCbCr, vec![y, cb, cr]) }; + let alpha = p.alpha.map(|a| Plane::packed(p.width, p.height, p.bit_depth, Samples::U16(a))).transpose()?; + let mut f = VideoFrame::new(p.width, p.height, family, sub, planes, alpha)?; + f.color.matrix = match p.color_volume { + _ if p.rgb => 0, + ColorVolume::Bt709 => 1, + ColorVolume::Bt2020Ncl => 9, + ColorVolume::Bt2020Cl => 10, + ColorVolume::OutOfBand => 2, + }; + f.sar = sar(p.par.0.into(), p.par.1.into()); + f.field_order = match p.interlace { + Interlace::Progressive => FieldOrder::Progressive, + Interlace::TopFieldFirst => FieldOrder::TopFieldFirst, + Interlace::BottomFieldFirst => FieldOrder::BottomFieldFirst, + }; + Ok(f) + } +} + +#[cfg(any(feature = "apv-decode", feature = "apv-encode"))] +impl TryFrom for VideoFrame { + type Error = FrameError; + + /// A YCbCr or gray frame, 16-bit storage. 4:4:4:4 is 4:4:4 with its fourth component as alpha. + fn try_from(p: crate::apv::Frame) -> Result { + use crate::apv::ChromaFormat; + let y = Plane::packed(p.width, p.height, p.bit_depth, Samples::U16(p.y))?; + let (family, sub, planes) = match p.chroma { + ChromaFormat::Monochrome => (ColorFamily::Gray, Subsampling::S444, vec![y]), + c => { + let sub = if c == ChromaFormat::Yuv422 { Subsampling::S422 } else { Subsampling::S444 }; + let (cw, ch) = sub.chroma_size(p.width, p.height); + let cb = Plane::packed(cw, ch, p.bit_depth, Samples::U16(p.cb))?; + let cr = Plane::packed(cw, ch, p.bit_depth, Samples::U16(p.cr))?; + (ColorFamily::YCbCr, sub, vec![y, cb, cr]) + } + }; + let alpha = p.alpha.map(|a| Plane::packed(p.width, p.height, p.bit_depth, Samples::U16(a))).transpose()?; + let mut f = VideoFrame::new(p.width, p.height, family, sub, planes, alpha)?; + f.color = ColorTags { primaries: p.color.primaries, transfer: p.color.transfer, matrix: p.color.matrix, full_range: p.color.full_range }; + Ok(f) + } +} + +#[cfg(feature = "ffv1")] +impl TryFrom for VideoFrame { + type Error = FrameError; + + /// A YCbCr, RGB or gray frame with optional transparency, 16-bit storage. FFV1 carries no + /// colour description; RGB frames are tagged with the identity matrix and full range. + fn try_from(p: crate::ffv1::Frame) -> Result { + use crate::ffv1::Colorspace; + let (w, h, bits) = (p.width, p.height, p.bit_depth); + let full = |v: Vec| Plane::packed(w, h, bits, Samples::U16(v)); + let mut it = p.planes.into_iter(); + let count = it.len(); + let mut next = || it.next().ok_or(FrameError::Shape("plane count does not fit the colour family")); + let (family, sub, planes, alpha) = match (p.colorspace, count) { + (Colorspace::YCbCr, 1 | 2) => { + let y = full(next()?)?; + let a = if count == 2 { Some(full(next()?)?) } else { None }; + (ColorFamily::Gray, Subsampling::S444, vec![y], a) + } + (Colorspace::YCbCr, 3 | 4) => { + let sub = Subsampling { x: p.chroma_shift.0, y: p.chroma_shift.1 }; + let (cw, ch) = sub.chroma_size(w, h); + let y = full(next()?)?; + let cb = Plane::packed(cw, ch, bits, Samples::U16(next()?))?; + let cr = Plane::packed(cw, ch, bits, Samples::U16(next()?))?; + let a = if count == 4 { Some(full(next()?)?) } else { None }; + (ColorFamily::YCbCr, sub, vec![y, cb, cr], a) + } + (Colorspace::Rgb, 3 | 4) => { + let planes = vec![full(next()?)?, full(next()?)?, full(next()?)?]; + let a = if count == 4 { Some(full(next()?)?) } else { None }; + (ColorFamily::Rgb, Subsampling::S444, planes, a) + } + _ => return Err(FrameError::Shape("plane count does not fit the colour family")), + }; + let mut f = VideoFrame::new(w, h, family, sub, planes, alpha)?; + if family == ColorFamily::Rgb { + f.color = ColorTags { matrix: 0, full_range: true, ..ColorTags::UNSPECIFIED }; + } + Ok(f) + } +} diff --git a/crates/video/src/frame/mod.rs b/crates/video/src/frame/mod.rs new file mode 100644 index 000000000..4ac896cdb --- /dev/null +++ b/crates/video/src/frame/mod.rs @@ -0,0 +1,344 @@ +//! A codec-agnostic decoded video frame. +//! +//! Each decoder in this crate returns its own picture type. [`VideoFrame`] holds what they have in +//! common: planar samples at their stored width (`u8` or `u16`), per-plane bit depth, chroma +//! subsampling, an optional alpha plane, colour tags as ITU-T H.273 code points, and timing. +//! Every decoder output converts into it with `VideoFrame::try_from`, behind the codec's feature. +//! A conversion moves the sample buffers; it does not copy or rescale samples. +//! +//! Plane order is fixed by [`ColorFamily`]: `[Y, Cb, Cr]`, `[R, G, B]` or `[Y]`. Decoders that +//! store RGB in another order (DNx, VP9 and identity-matrix AV1 store G, B, R) are reordered by +//! the conversion. +//! +//! The constructors check that the planes and their buffers agree in size, so reading a row +//! never goes out of bounds. They do not check that sample values fit the bit depth. + +mod convert; + +/// Why a frame or plane was rejected. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum FrameError { + /// A plane's buffer, stride or bit depth does not fit its size. + #[error("invalid plane: {0}")] + Plane(&'static str), + /// The planes do not fit the frame size, colour family or subsampling. + #[error("invalid frame: {0}")] + Shape(&'static str), +} + +/// The samples of one plane, at the width the decoder stores them. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Samples { + /// 8-bit storage (bit depth 1 to 8). + U8(Vec), + /// 16-bit storage (bit depth 1 to 16), values below `1 << bit_depth`. + U16(Vec), +} + +impl Samples { + /// Number of stored samples. + pub fn len(&self) -> usize { + match self { + Samples::U8(v) => v.len(), + Samples::U16(v) => v.len(), + } + } + + /// Whether no samples are stored. + pub fn is_empty(&self) -> bool { + self.len() == 0 + } +} + +/// One plane of samples: `height` rows of `width` samples, each row starting `stride` samples +/// after the previous one. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Plane { + width: u32, + height: u32, + stride: usize, + bit_depth: u8, + samples: Samples, +} + +impl Plane { + /// A plane with the given row stride. Fails when `stride < width`, when `bit_depth` is 0, above + /// 16, or above 8 for [`Samples::U8`], or when `samples` is shorter than the rows need. + pub fn new(width: u32, height: u32, stride: usize, bit_depth: u8, samples: Samples) -> Result { + let w = usize::try_from(width).map_err(|_| FrameError::Plane("width does not fit in usize"))?; + let h = usize::try_from(height).map_err(|_| FrameError::Plane("height does not fit in usize"))?; + if stride < w { + return Err(FrameError::Plane("stride is less than the width")); + } + let max_depth = match samples { + Samples::U8(_) => 8, + Samples::U16(_) => 16, + }; + if bit_depth == 0 || bit_depth > max_depth { + return Err(FrameError::Plane("bit depth does not fit the sample storage")); + } + let needed = match h.checked_sub(1) { + None => 0, + Some(last) => last.checked_mul(stride).and_then(|n| n.checked_add(w)).ok_or(FrameError::Plane("plane size overflows"))?, + }; + if samples.len() < needed { + return Err(FrameError::Plane("buffer is shorter than the plane")); + } + Ok(Plane { width, height, stride, bit_depth, samples }) + } + + /// A plane whose rows are packed (`stride == width`). + pub fn packed(width: u32, height: u32, bit_depth: u8, samples: Samples) -> Result { + let stride = usize::try_from(width).map_err(|_| FrameError::Plane("width does not fit in usize"))?; + Plane::new(width, height, stride, bit_depth, samples) + } + + /// Samples per row. + pub fn width(&self) -> u32 { + self.width + } + + /// Rows. + pub fn height(&self) -> u32 { + self.height + } + + /// Distance between the starts of two rows, in samples. + pub fn stride(&self) -> usize { + self.stride + } + + /// Significant bits per sample. + pub fn bit_depth(&self) -> u8 { + self.bit_depth + } + + /// The stored samples, rows `stride` apart. + pub fn samples(&self) -> &Samples { + &self.samples + } + + /// The stored samples, giving up the plane. + pub fn into_samples(self) -> Samples { + self.samples + } + + /// Row `y` of an 8-bit plane: `None` for a 16-bit plane or a row past the end. + pub fn row_u8(&self, y: u32) -> Option<&[u8]> { + match &self.samples { + Samples::U8(v) => v.get(self.row_range(y)?), + Samples::U16(_) => None, + } + } + + /// Row `y` of a 16-bit plane: `None` for an 8-bit plane or a row past the end. + pub fn row_u16(&self, y: u32) -> Option<&[u16]> { + match &self.samples { + Samples::U16(v) => v.get(self.row_range(y)?), + Samples::U8(_) => None, + } + } + + fn row_range(&self, y: u32) -> Option> { + if y >= self.height { + return None; + } + let start = usize::try_from(y).ok()?.checked_mul(self.stride)?; + Some(start..start.checked_add(usize::try_from(self.width).ok()?)?) + } +} + +/// What the colour planes hold, and in which order. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum ColorFamily { + /// `[Y, Cb, Cr]`, chroma subsampled by [`VideoFrame::subsampling`]. + YCbCr, + /// `[R, G, B]`, all at full size. + Rgb, + /// `[Y]` alone. + Gray, +} + +/// Chroma subsampling as log2 factors: the chroma planes are `width.div_ceil(1 << x)` by +/// `height.div_ceil(1 << y)`. FFV1 codes shifts up to 3; the other codecs stop at 1. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub struct Subsampling { + /// log2 of the horizontal factor (0 to 3). + pub x: u8, + /// log2 of the vertical factor (0 to 3). + pub y: u8, +} + +impl Subsampling { + /// 4:2:0. + pub const S420: Subsampling = Subsampling { x: 1, y: 1 }; + /// 4:2:2. + pub const S422: Subsampling = Subsampling { x: 1, y: 0 }; + /// 4:4:4, also used for RGB and gray frames. + pub const S444: Subsampling = Subsampling { x: 0, y: 0 }; + + /// Largest shift a frame accepts. + pub const MAX_SHIFT: u8 = 3; + + /// Chroma plane size for a luma size. A shift above [`Subsampling::MAX_SHIFT`] counts as that. + pub fn chroma_size(self, width: u32, height: u32) -> (u32, u32) { + (width.div_ceil(1 << self.x.min(Self::MAX_SHIFT)), height.div_ceil(1 << self.y.min(Self::MAX_SHIFT))) + } +} + +/// Colour description as ITU-T H.273 code points. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub struct ColorTags { + /// `ColourPrimaries` (2 = unspecified). + pub primaries: u8, + /// `TransferCharacteristics` (2 = unspecified). + pub transfer: u8, + /// `MatrixCoefficients` (0 = identity, used for RGB; 2 = unspecified). + pub matrix: u8, + /// `VideoFullRangeFlag`: full range when true. False when the stream does not say. + pub full_range: bool, +} + +impl ColorTags { + /// Nothing signalled. + pub const UNSPECIFIED: ColorTags = ColorTags { primaries: 2, transfer: 2, matrix: 2, full_range: false }; +} + +impl Default for ColorTags { + fn default() -> Self { + ColorTags::UNSPECIFIED + } +} + +/// Scan structure of a frame. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)] +pub enum FieldOrder { + /// Progressive, or not signalled. + #[default] + Progressive, + /// Two interlaced fields; the top field (even rows) comes first. + TopFieldFirst, + /// Two interlaced fields; the bottom field (odd rows) comes first. + BottomFieldFirst, +} + +/// A decoded frame in planar form, independent of the codec. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct VideoFrame { + width: u32, + height: u32, + family: ColorFamily, + subsampling: Subsampling, + planes: Vec, + alpha: Option, + /// Colour description. + pub color: ColorTags, + /// The timestamp passed to the decoder with the packet that produced the frame; `None` for + /// codecs whose decoders take no timestamp (the intra-only codecs). + pub pts: Option, + /// Sample aspect ratio, `None` when not signalled. + pub sar: Option<(u32, u32)>, + /// Field order. + pub field_order: FieldOrder, + /// Decoded in a decoder's draft mode (some filtering skipped): the samples are approximate. + pub draft: bool, +} + +impl VideoFrame { + /// A frame from its planes, in the order [`ColorFamily`] gives. Fails when the number of planes + /// does not fit `family`, a plane's size does not follow from `width`, `height` and + /// `subsampling`, a shift is above 3, or an RGB or gray frame is subsampled. The alpha plane is + /// full size. The colour tags and timing start unset. + pub fn new( + width: u32, + height: u32, + family: ColorFamily, + subsampling: Subsampling, + planes: Vec, + alpha: Option, + ) -> Result { + if subsampling.x > Subsampling::MAX_SHIFT || subsampling.y > Subsampling::MAX_SHIFT { + return Err(FrameError::Shape("subsampling shift above 3")); + } + if family != ColorFamily::YCbCr && subsampling != Subsampling::S444 { + return Err(FrameError::Shape("only YCbCr frames are subsampled")); + } + let expected = if family == ColorFamily::Gray { 1 } else { 3 }; + if planes.len() != expected { + return Err(FrameError::Shape("plane count does not fit the colour family")); + } + let chroma = subsampling.chroma_size(width, height); + for (i, p) in planes.iter().enumerate() { + let size = if i == 0 { (width, height) } else { chroma }; + if (p.width, p.height) != size { + return Err(FrameError::Shape("plane size does not fit the frame")); + } + } + if let Some(a) = &alpha + && (a.width, a.height) != (width, height) + { + return Err(FrameError::Shape("alpha plane size does not fit the frame")); + } + Ok(VideoFrame { + width, + height, + family, + subsampling, + planes, + alpha, + color: ColorTags::UNSPECIFIED, + pts: None, + sar: None, + field_order: FieldOrder::Progressive, + draft: false, + }) + } + + /// Luma width (the size of plane 0). + pub fn width(&self) -> u32 { + self.width + } + + /// Luma height. + pub fn height(&self) -> u32 { + self.height + } + + /// What the planes hold. + pub fn family(&self) -> ColorFamily { + self.family + } + + /// Chroma subsampling ([`Subsampling::S444`] for RGB and gray). + pub fn subsampling(&self) -> Subsampling { + self.subsampling + } + + /// The colour planes, in the order [`ColorFamily`] gives. + pub fn planes(&self) -> &[Plane] { + &self.planes + } + + /// Colour plane `i`, `None` past the last one. + pub fn plane(&self, i: usize) -> Option<&Plane> { + self.planes.get(i) + } + + /// The alpha plane (0 = transparent, the bit depth's maximum = opaque). + pub fn alpha(&self) -> Option<&Plane> { + self.alpha.as_ref() + } + + /// Bit depth of plane 0. Chroma may differ; see [`Plane::bit_depth`]. + pub fn bit_depth(&self) -> u8 { + self.planes.first().map_or(0, Plane::bit_depth) + } + + /// The colour planes and the alpha plane, giving up the frame. + pub fn into_planes(self) -> (Vec, Option) { + (self.planes, self.alpha) + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/video/src/frame/tests.rs b/crates/video/src/frame/tests.rs new file mode 100644 index 000000000..cba664af4 --- /dev/null +++ b/crates/video/src/frame/tests.rs @@ -0,0 +1,404 @@ +use super::*; + +fn u8_plane(w: u32, h: u32, fill: u8) -> Plane { + Plane::packed(w, h, 8, Samples::U8(vec![fill; (w * h) as usize])).unwrap() +} + +#[test] +fn plane_checks_buffer_stride_and_depth() { + assert_eq!(Plane::new(4, 2, 3, 8, Samples::U8(vec![0; 8])), Err(FrameError::Plane("stride is less than the width"))); + // Two rows at stride 6 need 6 + 4 samples: the last row's padding is not required. + assert!(Plane::new(4, 2, 6, 8, Samples::U8(vec![0; 10])).is_ok()); + assert_eq!(Plane::new(4, 2, 6, 8, Samples::U8(vec![0; 9])), Err(FrameError::Plane("buffer is shorter than the plane"))); + assert!(Plane::packed(4, 2, 9, Samples::U8(vec![0; 8])).is_err()); + assert!(Plane::packed(4, 2, 0, Samples::U16(vec![0; 8])).is_err()); + assert!(Plane::packed(4, 2, 17, Samples::U16(vec![0; 8])).is_err()); + assert!(Plane::packed(4, 2, 16, Samples::U16(vec![0; 8])).is_ok()); + assert!(Plane::packed(0, 0, 8, Samples::U8(Vec::new())).is_ok()); +} + +#[test] +fn plane_size_overflow_is_an_error() { + assert_eq!(Plane::new(1, u32::MAX, usize::MAX, 8, Samples::U8(Vec::new())), Err(FrameError::Plane("plane size overflows"))); +} + +#[test] +fn rows_honour_the_stride() { + let p = Plane::new(2, 3, 4, 8, Samples::U8(vec![0, 1, 9, 9, 2, 3, 9, 9, 4, 5])).unwrap(); + assert_eq!(p.row_u8(0), Some(&[0, 1][..])); + assert_eq!(p.row_u8(1), Some(&[2, 3][..])); + assert_eq!(p.row_u8(2), Some(&[4, 5][..])); + assert_eq!(p.row_u8(3), None); + assert_eq!(p.row_u16(0), None); + let q = Plane::packed(1, 2, 10, Samples::U16(vec![7, 1023])).unwrap(); + assert_eq!(q.row_u16(1), Some(&[1023][..])); + assert_eq!(q.row_u8(0), None); +} + +#[test] +fn frame_checks_planes_against_its_shape() { + let planes = || vec![u8_plane(5, 3, 0), u8_plane(3, 2, 0), u8_plane(3, 2, 0)]; + // Odd sizes round the chroma up. + let f = VideoFrame::new(5, 3, ColorFamily::YCbCr, Subsampling::S420, planes(), None).unwrap(); + assert_eq!((f.width(), f.height(), f.bit_depth()), (5, 3, 8)); + assert_eq!(f.color, ColorTags::UNSPECIFIED); + assert_eq!(f.pts, None); + assert!(VideoFrame::new(5, 3, ColorFamily::YCbCr, Subsampling::S422, planes(), None).is_err()); + assert!(VideoFrame::new(5, 3, ColorFamily::Gray, Subsampling::S444, planes(), None).is_err()); + assert!(VideoFrame::new(5, 3, ColorFamily::Rgb, Subsampling::S420, planes(), None).is_err()); + assert_eq!( + VideoFrame::new(5, 3, ColorFamily::YCbCr, Subsampling { x: 4, y: 0 }, planes(), None), + Err(FrameError::Shape("subsampling shift above 3")) + ); + assert!(VideoFrame::new(5, 3, ColorFamily::YCbCr, Subsampling::S420, planes(), Some(u8_plane(3, 2, 0))).is_err()); + let a = VideoFrame::new(5, 3, ColorFamily::YCbCr, Subsampling::S420, planes(), Some(u8_plane(5, 3, 255))).unwrap(); + assert_eq!(a.alpha().map(Plane::width), Some(5)); + let g = VideoFrame::new(5, 3, ColorFamily::Gray, Subsampling::S444, vec![u8_plane(5, 3, 0)], None).unwrap(); + assert_eq!(g.planes().len(), 1); + assert!(g.plane(1).is_none()); +} + +#[test] +fn chroma_planes_may_have_their_own_depth() { + let y = Plane::packed(2, 2, 10, Samples::U16(vec![0; 4])).unwrap(); + let c = || Plane::packed(1, 1, 8, Samples::U16(vec![0])).unwrap(); + let f = VideoFrame::new(2, 2, ColorFamily::YCbCr, Subsampling::S420, vec![y, c(), c()], None).unwrap(); + assert_eq!(f.bit_depth(), 10); + assert_eq!(f.planes()[1].bit_depth(), 8); +} + +#[cfg(feature = "h264-decode")] +fn h264_picture(y_len: usize) -> crate::h264::decode::Picture { + crate::h264::decode::Picture { + width: 4, + height: 2, + chroma_width: 2, + chroma_height: 1, + y: vec![16; y_len], + u: vec![128; 2], + v: vec![128; 2], + y_stride: 4, + uv_stride: 2, + pts: 7, + poc: 0, + key: true, + color: crate::h264::decode::ColorInfo { full_range: true, primaries: 1, transfer: 1, matrix: 1 }, + sar: (0, 0), + draft: false, + } +} + +#[cfg(feature = "h264-decode")] +#[test] +fn h264_picture_converts() { + let f = VideoFrame::try_from(h264_picture(8)).unwrap(); + assert_eq!((f.family(), f.subsampling()), (ColorFamily::YCbCr, Subsampling::S420)); + assert_eq!(f.color, ColorTags { primaries: 1, transfer: 1, matrix: 1, full_range: true }); + assert_eq!((f.pts, f.sar), (Some(7), None)); + let mut p = h264_picture(8); + p.sar = (4, 3); + assert_eq!(VideoFrame::try_from(p).unwrap().sar, Some((4, 3))); +} + +/// The decoder's pictures have public fields; one whose buffer does not fit its size is an error, +/// not an out-of-bounds read later. +#[cfg(feature = "h264-decode")] +#[test] +fn h264_picture_with_a_short_buffer_is_an_error() { + assert_eq!(VideoFrame::try_from(h264_picture(7)), Err(FrameError::Plane("buffer is shorter than the plane"))); +} + +#[cfg(feature = "hevc-decode")] +#[test] +fn hevc_picture_converts() { + use crate::hevc::decode::{ChromaFormat, ColorInfo, Picture, Plane as P}; + let p = Picture { + width: 4, + height: 2, + chroma_width: 2, + chroma_height: 2, + chroma: ChromaFormat::C422, + bit_depth: 10, + bit_depth_chroma: 10, + y: P::U16(vec![64; 8]), + u: P::U16(vec![512; 4]), + v: P::U16(vec![512; 4]), + y_stride: 4, + uv_stride: 2, + pts: 3, + poc: 0, + key: true, + color: ColorInfo { full_range: false, primaries: 9, transfer: 16, matrix: 9 }, + sar: (1, 1), + draft: true, + }; + let f = VideoFrame::try_from(p.clone()).unwrap(); + assert_eq!((f.subsampling(), f.bit_depth()), (Subsampling::S422, 10)); + assert_eq!(f.planes()[2].row_u16(1), Some(&[512, 512][..])); + assert_eq!(f.color, ColorTags { primaries: 9, transfer: 16, matrix: 9, full_range: false }); + assert_eq!((f.sar, f.draft), (Some((1, 1)), true)); + + // 10-bit luma with 8-bit chroma: both stored as `u16`, each plane with its own depth. + let mixed = VideoFrame::try_from(Picture { bit_depth_chroma: 8, u: P::U16(vec![128; 4]), v: P::U16(vec![128; 4]), ..p }).unwrap(); + assert_eq!(mixed.planes().iter().map(Plane::bit_depth).collect::>(), [10, 8, 8]); + assert_eq!(mixed.planes()[1].row_u16(0), Some(&[128, 128][..])); +} + +#[cfg(feature = "av1-decode")] +#[test] +fn av1_monochrome_is_gray() { + let p = crate::av1::decode::Picture { + width: 3, + height: 2, + bit_depth: 8, + subsampling_x: 1, + subsampling_y: 1, + mono_chrome: true, + planes: [vec![1; 6], Vec::new(), Vec::new()], + color_primaries: 1, + transfer_characteristics: 13, + matrix_coefficients: 1, + full_range: true, + pts: 5, + draft: false, + }; + let f = VideoFrame::try_from(p).unwrap(); + assert_eq!((f.family(), f.subsampling(), f.planes().len()), (ColorFamily::Gray, Subsampling::S444, 1)); + assert_eq!(f.color, ColorTags { primaries: 1, transfer: 13, matrix: 1, full_range: true }); +} + +#[cfg(feature = "av1-decode")] +#[test] +fn av1_420_rounds_chroma_up() { + let p = crate::av1::decode::Picture { + width: 3, + height: 3, + bit_depth: 10, + subsampling_x: 1, + subsampling_y: 1, + mono_chrome: false, + planes: [vec![0; 9], vec![0; 4], vec![0; 4]], + color_primaries: 2, + transfer_characteristics: 2, + matrix_coefficients: 2, + full_range: false, + pts: 0, + draft: false, + }; + let f = VideoFrame::try_from(p).unwrap(); + assert_eq!((f.planes()[1].width(), f.planes()[1].height()), (2, 2)); +} + +/// The identity matrix codes G, B, R in the Y, U, V planes. +#[cfg(feature = "av1-decode")] +#[test] +fn av1_identity_matrix_is_rgb_reordered_to_r_g_b() { + let p = crate::av1::decode::Picture { + width: 2, + height: 2, + bit_depth: 8, + subsampling_x: 0, + subsampling_y: 0, + mono_chrome: false, + planes: [vec![1; 4], vec![2; 4], vec![3; 4]], + color_primaries: 1, + transfer_characteristics: 13, + matrix_coefficients: 0, + full_range: true, + pts: 0, + draft: false, + }; + let f = VideoFrame::try_from(p.clone()).unwrap(); + assert_eq!(f.family(), ColorFamily::Rgb); + let first = |f: &VideoFrame, i: usize| f.planes()[i].row_u16(0).and_then(|r| r.first().copied()); + assert_eq!([first(&f, 0), first(&f, 1), first(&f, 2)], [Some(3), Some(1), Some(2)]); + assert_eq!(f.color, ColorTags { primaries: 1, transfer: 13, matrix: 0, full_range: true }); + + // Any other matrix keeps the coded order. + let y = VideoFrame::try_from(crate::av1::decode::Picture { matrix_coefficients: 1, ..p }).unwrap(); + assert_eq!(y.family(), ColorFamily::YCbCr); + assert_eq!([first(&y, 0), first(&y, 1), first(&y, 2)], [Some(1), Some(2), Some(3)]); +} + +#[cfg(feature = "vp9-decode")] +#[test] +fn vp9_color_space_maps_to_a_matrix() { + assert_eq!([0, 1, 2, 3, 4, 5, 6, 7].map(convert::vp9_matrix), [2, 5, 1, 6, 7, 9, 2, 0]); +} + +#[cfg(feature = "mpeg2-decode")] +#[test] +fn mpeg2_picture_converts() { + use crate::mpeg2::{ChromaFormat, Picture, PictureType, SequenceInfo}; + let info = SequenceInfo { + mpeg2: true, + width: 5, + height: 4, + chroma: ChromaFormat::Yuv420, + profile_and_level: None, + progressive_sequence: false, + low_delay: false, + frame_rate: None, + sar: (16, 15), + dar: None, + colour: Some((5, 5, 5)), + video_format: None, + bit_rate: 0, + }; + let p = Picture { + width: 5, + height: 4, + chroma: ChromaFormat::Yuv420, + y: vec![16; 20], + cb: vec![128; 6], + cr: vec![128; 6], + pts: 9, + picture_type: PictureType::I, + temporal_reference: 0, + progressive_frame: false, + top_field_first: false, + repeat_first_field: false, + field_pictures: false, + info: std::sync::Arc::new(info), + }; + let f = VideoFrame::try_from(p).unwrap(); + assert_eq!(f.field_order, FieldOrder::BottomFieldFirst); + assert_eq!(f.color, ColorTags { primaries: 5, transfer: 5, matrix: 5, full_range: false }); + assert_eq!((f.sar, f.pts), (Some((16, 15)), Some(9))); +} + +#[cfg(feature = "vp8-decode")] +#[test] +fn vp8_picture_converts() { + let p = crate::vp8::Picture { + width: 3, + height: 3, + chroma_width: 2, + chroma_height: 2, + y: vec![0; 9], + u: vec![0; 4], + v: vec![0; 4], + pts: 1, + key: true, + color_space: 0, + }; + let f = VideoFrame::try_from(p).unwrap(); + assert_eq!(f.color, ColorTags { matrix: 6, ..ColorTags::UNSPECIFIED }); + assert_eq!(f.pts, Some(1)); +} + +#[cfg(feature = "prores")] +#[test] +fn prores_frame_converts() { + use crate::prores::{ChromaFormat, ColorInfo, Frame, Interlace}; + let mut p = Frame::new(5, 2, ChromaFormat::Yuv422, 10, true).unwrap(); + p.color = ColorInfo { primaries: 0, transfer: 1, matrix: 0 }; + p.interlace = Interlace::TopFieldFirst; + let f = VideoFrame::try_from(p).unwrap(); + assert_eq!((f.planes()[1].width(), f.planes()[1].height()), (3, 2)); + assert_eq!(f.alpha().map(Plane::bit_depth), Some(10)); + assert_eq!(f.color, ColorTags { primaries: 2, transfer: 1, matrix: 2, full_range: false }); + assert_eq!((f.field_order, f.pts), (FieldOrder::TopFieldFirst, None)); + assert_eq!(f.sar, None); +} + +#[cfg(feature = "prores")] +#[test] +fn prores_aspect_ratio_gives_the_sample_aspect_ratio() { + use crate::prores::{ChromaFormat, Frame}; + let sar = |code: u8, w: u32, h: u32| { + let mut p = Frame::new(w, h, ChromaFormat::Yuv422, 10, false).unwrap(); + p.aspect_ratio = code; + VideoFrame::try_from(p).unwrap().sar + }; + // 0 is unknown and 4 to 15 are reserved. + assert_eq!([sar(0, 720, 486), sar(4, 720, 486)], [None, None]); + assert_eq!(sar(1, 720, 486), Some((1, 1))); + // 720 x 486 shown at 4:3 and at 16:9. + assert_eq!(sar(2, 720, 486), Some((9, 10))); + assert_eq!(sar(3, 720, 486), Some((6, 5))); + // 1920 x 1080 at 16:9 has square pixels. + assert_eq!(sar(3, 1920, 1080), Some((1, 1))); + assert_eq!(convert::prores_sar(2, u32::MAX, u32::MAX), Some((4, 3))); + assert_eq!(convert::prores_sar(2, 0, 4), None); +} + +#[cfg(feature = "dnx")] +#[test] +fn dnx_rgb_is_reordered_to_r_g_b() { + use crate::dnx::{ChromaFormat, Frame}; + let mut p = Frame::new(2, 2, ChromaFormat::Yuv444, 10, false); + p.rgb = true; + // Stored G, B, R. + p.y = vec![1; 4]; + p.cb = vec![2; 4]; + p.cr = vec![3; 4]; + let f = VideoFrame::try_from(p).unwrap(); + assert_eq!(f.family(), ColorFamily::Rgb); + let first = |i: usize| f.planes()[i].row_u16(0).and_then(|r| r.first().copied()); + assert_eq!([first(0), first(1), first(2)], [Some(3), Some(1), Some(2)]); + assert_eq!(f.color, ColorTags { matrix: 0, ..ColorTags::UNSPECIFIED }); +} + +#[cfg(feature = "dnx")] +#[test] +fn dnx_ycbcr_keeps_its_order() { + use crate::dnx::{ChromaFormat, ColorVolume, Frame}; + let mut p = Frame::new(4, 2, ChromaFormat::Yuv420, 8, true); + p.color_volume = ColorVolume::Bt2020Ncl; + p.par = (0, 0); + let f = VideoFrame::try_from(p).unwrap(); + assert_eq!((f.family(), f.subsampling()), (ColorFamily::YCbCr, Subsampling::S420)); + assert_eq!(f.color, ColorTags { matrix: 9, ..ColorTags::UNSPECIFIED }); + assert_eq!(f.sar, None); + assert!(f.alpha().is_some()); +} + +#[cfg(any(feature = "apv-decode", feature = "apv-encode"))] +#[test] +fn apv_frames_convert() { + use crate::apv::{ChromaFormat, Frame}; + let mono = VideoFrame::try_from(Frame::new(3, 2, ChromaFormat::Monochrome, 10, false)).unwrap(); + assert_eq!((mono.family(), mono.planes().len()), (ColorFamily::Gray, 1)); + let rgba = VideoFrame::try_from(Frame::new(3, 2, ChromaFormat::Yuv4444, 12, false)).unwrap(); + assert_eq!((rgba.family(), rgba.subsampling()), (ColorFamily::YCbCr, Subsampling::S444)); + assert!(rgba.alpha().is_some()); + assert_eq!(rgba.color, ColorTags { primaries: 1, transfer: 1, matrix: 1, full_range: false }); + let c422 = VideoFrame::try_from(Frame::new(3, 2, ChromaFormat::Yuv422, 10, false)).unwrap(); + assert_eq!(c422.planes()[1].width(), 2); +} + +#[cfg(feature = "ffv1")] +fn ffv1_frame(colorspace: crate::ffv1::Colorspace, shift: (u8, u8), sizes: &[usize]) -> crate::ffv1::Frame { + crate::ffv1::Frame { width: 3, height: 3, colorspace, bit_depth: 8, chroma_shift: shift, planes: sizes.iter().map(|&n| vec![0; n]).collect() } +} + +#[cfg(feature = "ffv1")] +#[test] +fn ffv1_frames_convert() { + use crate::ffv1::Colorspace; + let g = VideoFrame::try_from(ffv1_frame(Colorspace::YCbCr, (0, 0), &[9, 9])).unwrap(); + assert_eq!((g.family(), g.alpha().is_some()), (ColorFamily::Gray, true)); + let y = VideoFrame::try_from(ffv1_frame(Colorspace::YCbCr, (1, 1), &[9, 4, 4])).unwrap(); + assert_eq!((y.family(), y.subsampling(), y.alpha().is_some()), (ColorFamily::YCbCr, Subsampling::S420, false)); + assert_eq!(y.color, ColorTags::UNSPECIFIED); + let r = VideoFrame::try_from(ffv1_frame(Colorspace::Rgb, (0, 0), &[9, 9, 9, 9])).unwrap(); + assert_eq!((r.family(), r.alpha().is_some()), (ColorFamily::Rgb, true)); + assert_eq!(r.color, ColorTags { matrix: 0, full_range: true, ..ColorTags::UNSPECIFIED }); + assert!(VideoFrame::try_from(ffv1_frame(Colorspace::Rgb, (0, 0), &[9])).is_err()); + assert!(VideoFrame::try_from(ffv1_frame(Colorspace::YCbCr, (0, 0), &[])).is_err()); + // FFV1 codes shifts up to 3: an 8 x 1 frame at (3, 0) has one chroma sample per plane. + let wide = crate::ffv1::Frame { + width: 8, + height: 1, + colorspace: Colorspace::YCbCr, + bit_depth: 8, + chroma_shift: (3, 0), + planes: vec![vec![0; 8], vec![0; 1], vec![0; 1]], + }; + let wide = VideoFrame::try_from(wide).unwrap(); + assert_eq!(wide.subsampling(), Subsampling { x: 3, y: 0 }); + assert_eq!((wide.planes()[1].width(), wide.planes()[1].height(), wide.planes()[2].samples().len()), (1, 1, 1)); + // A 2 x 2 chroma plane needs 4 samples. + assert!(VideoFrame::try_from(ffv1_frame(Colorspace::YCbCr, (1, 1), &[9, 3, 4])).is_err()); +} 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/hevc/decode/decoder.rs b/crates/video/src/hevc/decode/decoder.rs index a09e87ab9..2f226d571 100644 --- a/crates/video/src/hevc/decode/decoder.rs +++ b/crates/video/src/hevc/decode/decoder.rs @@ -710,6 +710,7 @@ fn make_picture(o: &Output) -> Picture { chroma_height: cch as u32, chroma, bit_depth: bd, + bit_depth_chroma: o.frame.bit_depth_c, y, u, v, diff --git a/crates/video/src/hevc/decode/mod.rs b/crates/video/src/hevc/decode/mod.rs index 00ec97738..9a731d3b9 100644 --- a/crates/video/src/hevc/decode/mod.rs +++ b/crates/video/src/hevc/decode/mod.rs @@ -150,6 +150,8 @@ pub struct Picture { pub chroma: ChromaFormat, /// Luma bit depth (chroma uses the same storage type). pub bit_depth: u32, + /// Chroma bit depth; a stream may code it apart from the luma depth. + pub bit_depth_chroma: u32, pub y: Plane, pub u: Plane, pub v: Plane, diff --git a/crates/video/src/lib.rs b/crates/video/src/lib.rs index da4e32006..17b22f320 100644 --- a/crates/video/src/lib.rs +++ b/crates/video/src/lib.rs @@ -8,9 +8,10 @@ //! | `dnx` | [`dnx`] | Avid DNxHD / DNxHR (SMPTE ST 2019-1): decoder and encoder | //! | `apv` | [`apv`] | APV (RFC 9924): decoder (`apv-decode`) and encoder (`apv-encode`) | //! | `vp8` | [`vp8`] | VP8 (RFC 6386): decoder (`vp8-decode`) and key-frame encoder (`vp8-encode`) | -//! | `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`) | +//! | `mpeg2` | [`mpeg2`] | MPEG-2 video (ITU-T H.262) and MPEG-1 video: decoder (`mpeg2-decode`) and MPEG-2 I/P/B encoder with CBR / VBR (`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`) | @@ -23,10 +24,14 @@ //! //! The decoders bound the pictures they hold with a memory budget ([`budget`]). //! +//! Each decoder returns its own picture type. [`frame::VideoFrame`] is the codec-agnostic form +//! they all convert into (`VideoFrame::try_from`). +//! //! Containers and bit-level I/O are in `craft-media`; the codecs here share its `bitstream` //! module and describe their streams with `craft_media::CodecParams`. pub mod budget; +pub mod frame; #[cfg(any(feature = "apv-decode", feature = "apv-encode"))] pub mod apv; @@ -46,6 +51,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/src/mpeg2/README.md b/crates/video/src/mpeg2/README.md index 069fd67bd..bddcae904 100644 --- a/crates/video/src/mpeg2/README.md +++ b/crates/video/src/mpeg2/README.md @@ -78,14 +78,16 @@ the synthetic-stream tests confirmed against FFmpeg: ## Encoder (feature `mpeg2-encode`) The encoder is built in steps, tracked in storytold/craft-libs#1133: I and P pictures came in -#1136, B pictures in the second step. It writes valid MPEG-2 elementary streams, but not yet DVD or +#1136, B pictures in #1195, and constant and variable bitrate with a VBV guarantee in the third +step. It writes valid MPEG-2 elementary streams that meet their VBV buffer, but not yet DVD or broadcast deliverables: those need the later steps listed below. ```rust use craft_video::mpeg2::{Encoder, EncoderConfig, RateControl, YuvFrame}; let mut cfg = EncoderConfig::new(720, 576, 25, 1); -cfg.rate = RateControl::Abr { kbps: 6000 }; // or RateControl::Quantiser(1..=31) +cfg.rate = RateControl::Vbr { kbps: 6000, max_kbps: 9800 }; // or Cbr, Abr, Quantiser(1..=31) +cfg.vbv_buffer_bits = Some(1_835_008); // default: the level's maximum cfg.gop_size = 12; // pictures from one I picture to the next cfg.b_pictures = 2; // I B B P B B P ...; 0 for I and P only cfg.closed_gop = true; // or open GOPs @@ -101,7 +103,8 @@ es.extend_from_slice(enc.end_of_sequence()); What it does: - Main Profile (4:2:0) at Low, Main, High-1440 and High Level, and 4:2:2 Profile at Main and - High Level. The lowest level that holds the size, frame rate and (average) bitrate is chosen; + High Level. The lowest level that holds the size, frame rate, bitrate (the peak of a variable + bitrate) and VBV buffer size is chosen; sizes beyond High Level are refused. Any even picture size; edges are padded by repetition. - Progressive frame pictures, I, P and B. Every GOP starts with a sequence header, sequence extension and GOP header (with a time code), so every I picture is a random access point. @@ -128,17 +131,32 @@ What it does: previous macroblock's directions with the predictors), whichever costs least, or intra. Interpolated predictions are averaged in the decoder's order. - Adaptive quantisation by macroblock activity (Test Model 5 §5.2.3). -- Rate control: a constant quantiser (B pictures at 1.25 times it), or single-pass average - bitrate with Test Model 5's target bit allocation at picture level (B pictures weighted by - K_b = 1.4). Streams are signalled as variable bitrate - (`vbv_delay` 0xFFFF, the level's maximum bitrate and VBV size in the sequence header); the VBV - buffer is not modelled. +- Rate control: a constant quantiser (B pictures at 1.25 times it), or single-pass average, + constant or variable bitrate with Test Model 5's target bit allocation at picture level (B + pictures weighted by K_b = 1.4). The sequence header carries the constant bitrate, the + variable bitrate's peak, or for a constant quantiser and average bitrate the level's maximum, + rounded up to 400 bit/s, and the VBV buffer size (the level's maximum unless set). +- VBV guarantee (H.262 Annex C): the encoder models the decoder's buffer in decoding order, + exactly (fullness in 1/fps_num bit), and caps every picture at what the buffer holds at its + decoding time. Average bitrate control aims a picture at no more than 85 % of that. A + picture over its cap is coded again with a coarser quantiser (three times, then the coarsest); + an I picture still too large keeps only its DC coefficients, and as a last resort the picture + becomes the smallest there is: a grey I picture, or a P or B picture that repeats its + reference with zero vectors and no residual. That picture's size depends only on the picture + size, so `Encoder::new` codes one of each type and refuses a bitrate whose picture interval + brings fewer bits, or a buffer that cannot hold it; then the buffer cannot underflow. +- Constant bitrate: each picture header carries its `vbv_delay`; a picture that would let the + buffer overflow is padded with zero bytes before the next start code; the first picture is + decoded when the buffer is 7/8 full; the buffer used is at most what 0.728 s of the bitrate + fills (the longest `vbv_delay`), and must hold two picture intervals. Variable bitrate + (`vbv_delay` 0xFFFF): the buffer fills at the peak bitrate until full, before the first + picture too. The model takes the pictures to be decoded one picture interval apart. - The reconstruction uses the decoder's own dequantisation, mismatch control, IDCT and motion compensation, so this crate's decoder outputs exactly the encoder's reconstruction. - Slices (one per macroblock row) are coded in parallel on rayon with `threads`; the stream is identical either way. -Later steps (#1133): CBR and VBR with a VBV guarantee; DVD presets +Later steps (#1133): DVD presets (sizes, aspect, GOP length, 9.8 Mb/s, 23.976 soft telecine); interlaced coding (field/frame DCT, field prediction, alternate scan) and 4:2:2 High Level CBR for XDCAM HD422. MPEG-2 essence in the MXF writer and a program stream muxer belong to `craft-media`. @@ -213,9 +231,24 @@ fell to 77–150 fps). These are lower bounds. decodes from its I picture with its leading B pictures and an open one without them; B pictures are smaller than P pictures; uneven presentation times are refused with B pictures; quality and size follow the quantiser; repeated pictures skip; levels and aspect in the sequence header; - bad configurations and short or inconsistent planes are refused. + bad configurations and short or inconsistent planes are refused. A VBV checker that reads only + the stream (the sequence header's bit rate and buffer size, each picture's size and + `vbv_delay`) replays Annex C: constant bitrate streams (with and without B pictures, open GOPs, + intra only, a 48 kbit buffer, uniform noise, a still picture, 4:2:2 at 29.97 fps) decode one + picture interval apart, never underflow or overflow, and carry their bitrate to within one + buffer; variable bitrate, average bitrate and constant quantiser streams (noise at quantiser 1 + into a 64 kbit buffer, intra only, 4 B pictures) never underflow; all of them decode exactly to + the reconstruction, including the pictures that fell back to DC only or to the smallest + picture. Still pictures at a constant bitrate are padded; the smallest pictures are the same + size for any source; the sequence header carries the bit rate (rounded up to 400 bit/s) and + buffer size; bitrates below the smallest picture, buffers too small for it (or, at a constant + bitrate, for two picture intervals) are refused, and the lowest bitrate accepted for CIF + meets the buffer with noise. The `vbv.rs` model itself: both bounds of a constant bitrate + buffer, a full variable bitrate buffer stops filling, 29.97 fps does not drift. - `tests/mpeg2/encode.rs`: FFmpeg decodes our streams of `testsrc2` (CIF and 576-line 4:2:2; without B pictures, with 2 and 4, closed and open GOPs) without errors and within the decoder suite's tolerance of our reconstruction, ffprobe reports the profile, level, pixel format and picture types in display order, and average bitrate lands within 10 % of 800 and 2500 kbit/s - targets. + targets; constant bitrate CIF streams at 1500 and 3000 kbit/s decode and carry their bitrate + to within one buffer (1540 and 3021 kbit/s over 4 s with a 256 kbit buffer); a DVD-like + 720×576 stream (variable bitrate, 9.8 Mbit/s peak, 1835008-bit buffer) decodes. diff --git a/crates/video/src/mpeg2/encode/bitwriter.rs b/crates/video/src/mpeg2/encode/bitwriter.rs index 75b363d47..f014b4861 100644 --- a/crates/video/src/mpeg2/encode/bitwriter.rs +++ b/crates/video/src/mpeg2/encode/bitwriter.rs @@ -47,7 +47,6 @@ impl BitWriter { } /// Bits written so far. - #[cfg(test)] pub fn bits(&self) -> u64 { self.out.len() as u64 * 8 + u64::from(self.n) } diff --git a/crates/video/src/mpeg2/encode/mod.rs b/crates/video/src/mpeg2/encode/mod.rs index af32b271d..28cc6ec61 100644 --- a/crates/video/src/mpeg2/encode/mod.rs +++ b/crates/video/src/mpeg2/encode/mod.rs @@ -2,8 +2,22 @@ //! //! MPEG-2 encoding in this crate is built in steps (storytold/craft-libs#1133). So far: I, P and B //! pictures, progressive frame pictures, 4:2:0 (Main Profile) and 4:2:2 (4:2:2 Profile), closed or -//! open GOPs, constant quantiser or single-pass average bitrate. A VBV guarantee, interlaced -//! coding and DVD / broadcast presets come later. +//! open GOPs, and constant quantiser, average, constant or variable bitrate. Every stream meets +//! the VBV buffer of its sequence header (H.262 Annex C). Interlaced coding and DVD / broadcast +//! presets come later. +//! +//! ## The VBV buffer +//! +//! The encoder models the decoder's input buffer in decoding order and caps each picture at +//! what the buffer holds at its decoding time. A picture over its cap is coded again with a +//! coarser quantiser; if the coarsest is still too large, an I picture drops its AC +//! coefficients, and as a last resort the picture is replaced by the smallest one there is (a +//! grey I picture, or a P or B picture that repeats its reference). That one's size depends only +//! on the picture size, and [`Encoder::new`] refuses a bitrate that cannot carry it every +//! picture interval, so the buffer can never underflow. With [`RateControl::Cbr`] the encoder +//! also writes each picture's `vbv_delay` and pads pictures with zero bytes before the next +//! start code where the buffer would otherwise overflow. The model takes the pictures to be +//! decoded one picture interval apart, as in an elementary stream without gaps. //! //! ```no_run //! use craft_video::mpeg2::encode::{Encoder, EncoderConfig, RateControl, YuvFrame}; @@ -32,6 +46,7 @@ mod picture; mod rate; mod tables; mod transform; +mod vbv; #[cfg(test)] mod tests; @@ -43,8 +58,9 @@ use crate::mpeg2::headers::{DEFAULT_INTRA, PictureType, SCAN}; use crate::mpeg2::mc::Frame; use bitwriter::BitWriter; -use picture::{PicCtx, RowOut, RowPlanes, encode_row, qcode_for, qscale}; +use picture::{Fallback, PicCtx, RowOut, RowPlanes, encode_row, qcode_for, qscale}; use rate::RateCtl; +use vbv::Vbv; #[derive(Debug, thiserror::Error)] pub enum EncodeError { @@ -86,10 +102,19 @@ impl AspectRatio { pub enum RateControl { /// A constant quantiser_scale_code (1..=31; mapped through H.262 Table 7-6 with /// `nonlinear_quant`). Adaptive quantisation still varies it per macroblock when enabled. + /// Signalled as variable bitrate at the level's maximum; a picture too large for the VBV + /// buffer is coded coarser. Quantiser(u8), - /// Single-pass average bitrate in kbit/s. The stream is signalled as variable bitrate and - /// is not checked against the VBV buffer. + /// Single-pass average bitrate in kbit/s, signalled as variable bitrate at the level's + /// maximum. Abr { kbps: u32 }, + /// Constant bitrate in kbit/s (rounded up to a multiple of 400 bit/s, the unit of the + /// sequence header): every picture carries its `vbv_delay`, and the buffer neither + /// underflows nor overflows. + Cbr { kbps: u32 }, + /// Variable bitrate: an average of `kbps`, with the VBV buffer filled at `max_kbps` (the + /// sequence header's bit rate, rounded up to a multiple of 400 bit/s). + Vbr { kbps: u32, max_kbps: u32 }, } #[derive(Clone, Debug)] @@ -113,6 +138,10 @@ pub struct EncoderConfig { /// GOP decodes on its own. Open GOPs let them predict from the previous GOP too. pub closed_gop: bool, pub rate: RateControl, + /// VBV buffer size in bits (stored in units of 16384, rounded down); `None`: the level's + /// maximum. With a constant bitrate the encoder uses at most what 0.728 s of the bitrate + /// fills, the longest `vbv_delay` there is. + pub vbv_buffer_bits: Option, /// q_scale_type: the non-linear quantiser scale (finer steps at low quantisers). pub nonlinear_quant: bool, /// Vary the quantiser per macroblock with its activity (finer in flat areas). @@ -141,6 +170,7 @@ impl EncoderConfig { b_pictures: 2, closed_gop: true, rate: RateControl::Quantiser(4), + vbv_buffer_bits: None, nonlinear_quant: true, adaptive_quant: true, intra_dc_bits: 9, @@ -167,7 +197,7 @@ pub struct YuvFrame<'a> { #[derive(Clone, Debug)] pub struct Packet { /// Elementary stream bytes: the sequence header and GOP header before every I picture, then - /// the picture. + /// the picture, then (constant bitrate) any zero bytes of stuffing. pub data: Vec, pub pts: i64, /// Decoding timestamp: `pts` without B pictures; with them, the presentation times in @@ -243,9 +273,10 @@ fn choose_level(cfg: &EncoderConfig) -> Result { let fps = f64::from(cfg.fps_num) / f64::from(cfg.fps_den); let luma_rate = f64::from(cfg.width) * f64::from(cfg.height) * fps; let bps = match cfg.rate { - RateControl::Abr { kbps } => u64::from(kbps) * 1000, + RateControl::Abr { kbps } | RateControl::Cbr { kbps } | RateControl::Vbr { max_kbps: kbps, .. } => u64::from(kbps) * 1000, RateControl::Quantiser(_) => 0, }; + let vbv = cfg.vbv_buffer_bits.map_or(0, u64::from); levels .iter() .find(|l| { @@ -254,6 +285,7 @@ fn choose_level(cfg: &EncoderConfig) -> Result { && fps <= f64::from(l.max_fps) + 0.01 && luma_rate <= l.luma_rate as f64 && bps <= l.bit_rate + && vbv <= l.vbv_bits }) .copied() .ok_or_else(|| { @@ -263,6 +295,7 @@ fn choose_level(cfg: &EncoderConfig) -> Result { cfg.height, fps, if bps > 0 { format!(", {bps} bit/s") } else { String::new() } + + &if vbv > 0 { format!(", a {vbv}-bit VBV buffer") } else { String::new() } )) }) } @@ -287,9 +320,13 @@ fn validate(cfg: &EncoderConfig) -> Result<(), EncodeError> { } match cfg.rate { RateControl::Quantiser(q) if !(1..=31).contains(&q) => return bad(format!("quantiser_scale_code {q} (1..=31)")), - RateControl::Abr { kbps: 0 } => return bad("bitrate 0".into()), + RateControl::Abr { kbps: 0 } | RateControl::Cbr { kbps: 0 } | RateControl::Vbr { kbps: 0, .. } => return bad("bitrate 0".into()), + RateControl::Vbr { kbps, max_kbps } if max_kbps < kbps => return bad(format!("peak bitrate {max_kbps} kbit/s below the average {kbps}")), _ => {} } + if cfg.vbv_buffer_bits.is_some_and(|b| b < 16384) { + return bad(format!("VBV buffer of {} bits (at least 16384)", cfg.vbv_buffer_bits.unwrap_or(0))); + } if !(8..=10).contains(&cfg.intra_dc_bits) { return bad(format!("intra DC precision {} bits (8..=10)", cfg.intra_dc_bits)); } @@ -323,8 +360,27 @@ struct Coded { recon: Frame, mvs: Vec<[i32; 2]>, avg_q: f64, + /// Zero bits appended for the VBV buffer (constant bitrate). + stuffing: u64, } +impl Coded { + fn bits(&self) -> u64 { + self.packet.data.len() as u64 * 8 + } +} + +/// Times a picture too large for the VBV buffer is coded again with a coarser quantiser before +/// the fallbacks. +const RECODES: usize = 3; + +/// Share of the VBV buffer's fullness that average bitrate control aims a picture at, at most. +const VBV_TARGET: f64 = 0.85; + +/// Fullness, as a share of the buffer, at which a constant bitrate stream's first picture is +/// decoded. +const CBR_START: (u64, u64) = (7, 8); + /// Quantiser ratio of B to P pictures with a constant quantiser (TM5 uses 1.4 for its rate /// allocation; a constant quantiser keeps B pictures a little closer to the anchors). const B_QUANT_FACTOR: f64 = 1.25; @@ -366,6 +422,11 @@ pub struct Encoder { /// Packets waiting for the presentation time step (the decoding time offset). out: Vec, rc: Option, + /// bit_rate_value and vbv_buffer_size_value of the sequence header (units of 400 bit/s and + /// 16384 bits). + bit_rate_value: u64, + vbv_value: u64, + vbv: Vbv, recon_capture: bool, recon: Vec<(u64, ReconFrame)>, } @@ -377,10 +438,25 @@ impl Encoder { let (shx, shy) = if cfg.chroma == ChromaFormat::Yuv422 { (1, 0) } else { (1, 1) }; let nonlinear = cfg.nonlinear_quant; let q_range = (f64::from(qscale(nonlinear, 1)), f64::from(qscale(nonlinear, 31))); + let fps = f64::from(cfg.fps_num) / f64::from(cfg.fps_den); + let (peak, cbr) = match cfg.rate { + RateControl::Cbr { kbps } => (u64::from(kbps) * 1000, true), + RateControl::Vbr { max_kbps, .. } => (u64::from(max_kbps) * 1000, false), + RateControl::Quantiser(_) | RateControl::Abr { .. } => (level.bit_rate, false), + }; + let bit_rate_value = peak.div_ceil(400); + let vbv_value = cfg.vbv_buffer_bits.map_or(level.vbv_bits, u64::from) / 16384; + let (rate, mut size) = (bit_rate_value * 400, vbv_value * 16384); + if cbr { + // the longest vbv_delay (0xFFFE ticks of 90 kHz) bounds what may wait in the buffer + size = size.min(rate * 0xFFFE / 90_000); + } let rc = match cfg.rate { - RateControl::Abr { kbps } => Some(RateCtl::new(f64::from(kbps) * 1000.0, f64::from(cfg.fps_num) / f64::from(cfg.fps_den), q_range)), + RateControl::Abr { kbps } | RateControl::Vbr { kbps, .. } => Some(RateCtl::new(f64::from(kbps) * 1000.0, fps, q_range)), + RateControl::Cbr { .. } => Some(RateCtl::new(rate as f64, fps, q_range)), RateControl::Quantiser(_) => None, }; + let vbv = Vbv::new(size, rate, (cfg.fps_num, cfg.fps_den), cbr, size / CBR_START.1 * CBR_START.0); let mut enc = Encoder { level, mb_w: (cfg.width as usize).div_ceil(16), @@ -404,14 +480,50 @@ impl Encoder { pts_step: None, out: Vec::new(), rc, + bit_rate_value, + vbv_value, + vbv, recon_capture: false, recon: Vec::new(), cfg, }; enc.seq_header = enc.sequence_header_bytes(); + // every picture can shrink to the smallest one, so the buffer cannot underflow if that + // fits in it and one picture interval brings at least that many bits (the fullness at a + // decoding time is never below one interval's worth, or the whole buffer when it holds + // less). A constant bitrate also needs room to pad pictures within: two intervals. + let fill = enc.vbv.per_picture(); + let smallest = enc.smallest_picture(); + let (w, h) = (enc.cfg.width, enc.cfg.height); + if fill < smallest { + return Err(EncodeError::Config(format!( + "{rate} bit/s at {fps:.3} fps brings {fill} bits a picture; the smallest {w}x{h} picture takes {smallest}" + ))); + } + if size < smallest { + return Err(EncodeError::Config(format!("a VBV buffer of {size} bits; the smallest {w}x{h} picture takes {smallest}"))); + } + if cbr && size < 2 * fill { + return Err(EncodeError::Config(format!("a VBV buffer of {size} bits holds less than two pictures of {fill} bits at {rate} bit/s"))); + } Ok(enc) } + /// Bits of the largest of the minimal I, P and B pictures (with the I picture's sequence + /// and GOP headers). They do not depend on the source, so a grey one tells. + fn smallest_picture(&self) -> u64 { + let mut grey = Frame::new(self.mb_w * 16, self.mb_h * 16, (self.mb_w * 16) >> self.shx, (self.mb_h * 16) >> self.shy); + for p in &mut grey.planes { + p.fill(128); + } + let h = Held { src: grey.clone(), pts: 0, n: self.gop_first }; + [(PictureType::I, None, None), (PictureType::P, Some(&grey), None), (PictureType::B, Some(&grey), Some(&grey))] + .into_iter() + .map(|(t, fwd, bwd)| self.code_picture(&h, t, (fwd, bwd), [&[], &[]], 8.0, Fallback::Minimal).bits()) + .max() + .unwrap_or(0) + } + pub fn config(&self) -> &EncoderConfig { &self.cfg } @@ -467,8 +579,8 @@ impl Encoder { fn sequence_header_bytes(&self) -> Vec { let c = &self.cfg; let mut w = BitWriter::new(); - let bit_rate = self.level.bit_rate.div_ceil(400); - let vbv = self.level.vbv_bits / 16384; + let bit_rate = self.bit_rate_value; + let vbv = self.vbv_value; w.start_code(0xB3); w.put(c.width & 0xFFF, 12); w.put(c.height & 0xFFF, 12); @@ -515,8 +627,11 @@ impl Encoder { w.bit(false); // broken_link } - fn picture_header(&self, w: &mut BitWriter, ptype: PictureType, temporal_reference: u64) { + /// picture_header and picture_coding_extension. `head_bits`: the bits before the picture + /// start code (sequence and GOP headers), for the `vbv_delay`. + fn picture_header(&self, w: &mut BitWriter, ptype: PictureType, temporal_reference: u64, head_bits: u64) { w.start_code(0x00); + let delay = self.vbv.delay(head_bits + w.bits()); w.put((temporal_reference & 0x3FF) as u32, 10); // display order within the GOP w.put( match ptype { @@ -526,7 +641,7 @@ impl Encoder { }, 3, ); - w.put(0xFFFF, 16); // vbv_delay: variable bitrate + w.put(u32::from(delay), 16); // vbv_delay (0xFFFF: variable bitrate) for dir in [PictureType::P, PictureType::B] { if ptype == dir || ptype == PictureType::B { // full_pel_{forward,backward}_vector and {forward,backward}_f_code: MPEG-2 @@ -665,7 +780,7 @@ impl Encoder { } let fwd = if intra { None } else { self.latest.as_ref().map(|r| &r.0) }; let cand: &[[i32; 2]] = if intra { &[] } else { &self.anchor_mvs }; - let c = self.code_picture(&h, ptype, (fwd, None), [cand, &[]]); + let c = self.code_fitting(&h, ptype, (fwd, None), [cand, &[]]); let (recon, mvs) = self.finish(c, h.n, out); self.older = self.latest.take(); self.latest = Some((recon, h.n)); @@ -689,22 +804,74 @@ impl Encoder { }; let cf = fwd.map_or(Vec::new(), |f| scaled(b.n as i64 - f.1 as i64)); let cb = scaled(b.n as i64 - *bn as i64); - let c = self.code_picture(&b, PictureType::B, (fwd.map(|f| &f.0), Some(bwd)), [&cf, &cb]); + let c = self.code_fitting(&b, PictureType::B, (fwd.map(|f| &f.0), Some(bwd)), [&cf, &cb]); self.finish(c, b.n, out); } - /// Code one picture with the given references and search candidates. - fn code_picture(&self, h: &Held, ptype: PictureType, (fwd, bwd): (Option<&Frame>, Option<&Frame>), cand: [&[[i32; 2]]; 2]) -> Coded { - let base = match (&self.rc, self.cfg.rate) { - (Some(rc), _) => rc.qscale(ptype), + /// The picture-level quantiser_scale for the next picture of type `ptype`. + fn base_quant(&self, ptype: PictureType) -> f64 { + match (&self.rc, self.cfg.rate) { + (Some(rc), _) => rc.qscale(ptype, (self.vbv.min_bits() as f64, self.vbv.max_bits() as f64 * VBV_TARGET)), (None, RateControl::Quantiser(q)) => { let qs = f64::from(qscale(self.cfg.nonlinear_quant, q)); if ptype == PictureType::B { qs * B_QUANT_FACTOR } else { qs } } (None, _) => 8.0, - }; + } + } + + /// Code a picture to fit the VBV buffer: coarser while it is too large, then the fallbacks + /// (see the module documentation), then pad it with zero bytes if the buffer would + /// overflow. + fn code_fitting(&self, h: &Held, ptype: PictureType, refs: (Option<&Frame>, Option<&Frame>), cand: [&[[i32; 2]]; 2]) -> Coded { + let max = self.vbv.max_bits(); + let q_max = f64::from(qscale(self.cfg.nonlinear_quant, 31)); + let mut base = self.base_quant(ptype); + let mut c = self.code_picture(h, ptype, refs, cand, base, Fallback::None); + for _ in 0..RECODES { + if c.bits() <= max || base >= q_max { + break; + } + // the size goes roughly with the inverse of the quantiser; aim a little under + base = (base * c.bits() as f64 / max.max(1) as f64 * 1.1).min(q_max); + c = self.code_picture(h, ptype, refs, cand, base, Fallback::None); + } + if c.bits() > max && base < q_max { + c = self.code_picture(h, ptype, refs, cand, q_max, Fallback::None); + } + if c.bits() > max && ptype == PictureType::I { + c = self.code_picture(h, ptype, refs, cand, q_max, Fallback::DcOnly); + } + if c.bits() > max { + // fits: `Encoder::new` made sure one picture interval brings this many bits + c = self.code_picture(h, ptype, refs, cand, q_max, Fallback::Minimal); + } + let min = self.vbv.min_bits(); + if c.bits() < min { + let pad = (min - c.bits()).div_ceil(8); + c.packet.data.resize(c.packet.data.len() + pad as usize, 0); + c.stuffing = pad * 8; + } + c + } + + /// Code one picture with the given references, search candidates and picture quantiser. + fn code_picture( + &self, + h: &Held, + ptype: PictureType, + (fwd, bwd): (Option<&Frame>, Option<&Frame>), + cand: [&[[i32; 2]]; 2], + base: f64, + fallback: Fallback, + ) -> Coded { let src = &h.src; - let mb_qcode = self.mb_quant(src, base); + // the minimal picture keeps one quantiser, so its size does not depend on the source + let mb_qcode = if fallback == Fallback::Minimal { + vec![qcode_for(self.cfg.nonlinear_quant, base); self.mb_w * self.mb_h] + } else { + self.mb_quant(src, base) + }; let mut recon = Frame::new(src.w, src.h, src.cw, src.ch); let ctx = PicCtx { ptype, @@ -722,6 +889,7 @@ impl Encoder { f_code: self.f_code, search: self.cfg.search_range as i32, mb_qcode: &mb_qcode, + fallback, }; let rows = encode_rows(&ctx, &mut recon, self.cfg.threads); let intra = ptype == PictureType::I; @@ -729,7 +897,8 @@ impl Encoder { if intra { self.gop_header(&mut w, self.gop_first, self.gop_closed); } - self.picture_header(&mut w, ptype, h.n - self.gop_first); + let head = if intra { self.seq_header.len() as u64 * 8 } else { 0 }; + self.picture_header(&mut w, ptype, h.n.saturating_sub(self.gop_first), head); let mut data = if intra { self.seq_header.clone() } else { Vec::new() }; data.extend_from_slice(&w.finish()); let mut qsum = 0u64; @@ -741,16 +910,19 @@ impl Encoder { } let avg_q = qsum as f64 / (self.mb_w * self.mb_h).max(1) as f64; let packet = Packet { data, pts: h.pts, dts: h.pts, keyframe: intra, picture_type: ptype, quantiser_scale: avg_q as f32 }; - Coded { packet, recon, mvs, avg_q } + Coded { packet, recon, mvs, avg_q, stuffing: 0 } } /// Account for a coded picture (display index `n`): rate control, its decoding time, the /// reconstruction capture. Returns the reconstruction and the picture's vectors. fn finish(&mut self, c: Coded, n: u64, out: &mut Vec) -> (Frame, Vec<[i32; 2]>) { - let Coded { mut packet, recon, mvs, avg_q } = c; + let Coded { mut packet, recon, mvs, avg_q, stuffing } = c; + let bits = packet.data.len() as u64 * 8; if let Some(rc) = self.rc.as_mut() { - rc.update(packet.picture_type, packet.data.len() as u64 * 8, avg_q); + rc.update(packet.picture_type, bits - stuffing, avg_q); + rc.spend(stuffing); } + self.vbv.remove(bits); // the k-th coded picture decodes at the k-th presentation time (less the offset that // `release` subtracts); one time is queued per input picture packet.dts = self.display_pts.pop_front().unwrap_or(packet.pts); diff --git a/crates/video/src/mpeg2/encode/picture.rs b/crates/video/src/mpeg2/encode/picture.rs index 0be5dbafd..37087edff 100644 --- a/crates/video/src/mpeg2/encode/picture.rs +++ b/crates/video/src/mpeg2/encode/picture.rs @@ -33,6 +33,20 @@ pub(crate) fn qcode_for(nonlinear: bool, qs: f64) -> u8 { best.0 } +/// How far a picture gives up quality to fit the VBV buffer. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum Fallback { + /// Coded normally. + None, + /// Intra blocks keep only their DC coefficient (I pictures). + DcOnly, + /// The smallest picture there is, whatever the source: an I picture of mid-grey blocks (every + /// DC equal to its predictor, no AC), or a P or B picture whose macroblocks are skipped or + /// predicted with a zero vector and no residual (backward in a B picture), which repeats the + /// reference. Its size depends only on the picture size and the headers. + Minimal, +} + /// What every slice of one picture shares (read-only). pub(crate) struct PicCtx<'a> { /// I, P or B. @@ -58,6 +72,7 @@ pub(crate) struct PicCtx<'a> { pub search: i32, /// quantiser_scale_code per macroblock. pub mb_qcode: &'a [u8], + pub fallback: Fallback, } impl PicCtx<'_> { @@ -223,6 +238,16 @@ fn macroblock(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, (mbx, mby): (us let planes = (ctx.src.w, ctx.src.cw); let lambda = ((qs * 3 + 4) / 8).max(1) as u32; let rec = match (ctx.ptype, ctx.fwd) { + (PictureType::P, Some(reference)) if ctx.fallback == Fallback::Minimal => { + let (rec, skipped) = inter_mb(ctx, st, w, &mb, reference, [0, 0]); + ro.stats.skipped += skipped as u32; + Some(rec) + } + (PictureType::B, _) if ctx.bwd.is_some() && ctx.fallback == Fallback::Minimal => { + let (rec, skipped) = b_mb(ctx, st, w, &mb, BPred { dirs: MB_BWD, mvs: [[0; 2]; 2] }); + ro.stats.skipped += skipped as u32; + Some(rec) + } (PictureType::P, Some(reference)) => { let search = Search { reference, src: &src.y, mbx, mby, f_code: ctx.f_code, range: ctx.search, pmv: st.pmv[0], lambda }; let found = search.run(&candidates(ctx, st, addr, 0)); @@ -391,11 +416,19 @@ fn intra_mb(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, mb: &MbIn) -> MbP let mut rec = mb.src.clone(); for i in 0..ctx.blocks() { let cc = if i < 4 { 0 } else { 1 + (i & 1) }; - let f = fdct(&mb.src.block(i, cbw)); let mut levels = [0i32; 64]; - levels[0] = ((f[0] / dc_mult as f32).round() as i32).clamp(0, dc_max); - for pos in 1..64 { - levels[pos] = quant_intra(f[pos], ctx.intra_matrix[pos], qs); + // The minimal fallback repeats the DC predictor and codes no coefficients, so it needs + // no transform. + if ctx.fallback == Fallback::Minimal { + levels[0] = st.dc[cc]; + } else { + let f = fdct(&mb.src.block(i, cbw)); + levels[0] = ((f[0] / dc_mult as f32).round() as i32).clamp(0, dc_max); + if ctx.fallback == Fallback::None { + for pos in 1..64 { + levels[pos] = quant_intra(f[pos], ctx.intra_matrix[pos], qs); + } + } } let diff = levels[0] - st.dc[cc]; st.dc[cc] = levels[0]; @@ -464,6 +497,9 @@ fn residual(ctx: &PicCtx, mb: &MbIn, pred: &MbPix, qs: i32) -> ([[i32; 64]; 8], let n = ctx.blocks(); let mut levels = [[0i32; 64]; 8]; let mut cbp = 0u32; + if ctx.fallback == Fallback::Minimal { + return (levels, cbp); + } for i in 0..n { let (s, p) = (mb.src.block(i, cbw), pred.block(i, cbw)); let f = fdct(&std::array::from_fn(|k| s[k] - p[k])); @@ -617,6 +653,7 @@ mod tests { f_code: 3, search: 31, mb_qcode: &[4; 3], + fallback: Fallback::None, }; let bad = BPred { dirs: MB_FWD, mvs: [[34, 0], [0, 0]] }; // the bitstream can carry the vector (f_code 3: -64..64): only the position rules it out diff --git a/crates/video/src/mpeg2/encode/rate.rs b/crates/video/src/mpeg2/encode/rate.rs index 96c6f2aa1..7accd5172 100644 --- a/crates/video/src/mpeg2/encode/rate.rs +++ b/crates/video/src/mpeg2/encode/rate.rs @@ -58,8 +58,14 @@ impl RateCtl { self.nb = 0; } - /// quantiser_scale for the next picture of type `ptype`. - pub fn qscale(&self, ptype: PictureType) -> f64 { + /// Bits spent beyond the coded pictures (stuffing). + pub fn spend(&mut self, bits: u64) { + self.remaining -= bits as f64; + } + + /// quantiser_scale for the next picture of type `ptype`, its bit target kept within + /// `(min, max)` (the VBV buffer's bounds). + pub fn qscale(&self, ptype: PictureType, (min, max): (f64, f64)) -> f64 { let floor = self.bps / (8.0 * self.fps); let (np, nb) = (f64::from(self.np), f64::from(self.nb)); let (target, x) = match ptype { @@ -67,7 +73,7 @@ impl RateCtl { PictureType::B => (self.remaining / (nb.max(1.0) + np * KB * self.xp / self.xb), self.xb), _ => (self.remaining / (np.max(1.0) + nb * self.xb / (KB * self.xp)), self.xp), }; - (x / target.max(floor)).clamp(self.q_min, self.q_max) + (x / target.max(floor).min(max).max(min).max(1.0)).clamp(self.q_min, self.q_max) } /// A picture of type `ptype` used `bits` at average quantiser_scale `avg_q`. @@ -109,7 +115,7 @@ mod tests { for _ in 0..gops { rc.start_gop(np, 11 - np); for &t in &types { - let q = rc.qscale(t); + let q = rc.qscale(t, (0.0, f64::MAX)); let bits = c[t as usize] / q; rc.update(t, bits as u64, q); total += bits; @@ -134,7 +140,7 @@ mod tests { // a GOP of 12 that ends after its I picture and two P pictures rc.start_gop(11, 0); for t in [PictureType::I, PictureType::P, PictureType::P] { - let q = rc.qscale(t); + let q = rc.qscale(t, (0.0, f64::MAX)); rc.update(t, (1e7 / q) as u64, q); } rc.end_gop(9); @@ -150,11 +156,11 @@ mod tests { // a picture far larger than its budget pushes the next quantiser to the top rc.update(PictureType::I, 50_000_000, 10.0); rc.start_gop(1, 0); - assert_eq!(rc.qscale(PictureType::I), 62.0); + assert_eq!(rc.qscale(PictureType::I, (0.0, f64::MAX)), 62.0); // and a tiny one to the bottom let mut rc = RateCtl::new(1e6, 25.0, (2.0, 62.0)); rc.start_gop(1, 0); rc.update(PictureType::I, 10, 2.0); - assert_eq!(rc.qscale(PictureType::I), 2.0); + assert_eq!(rc.qscale(PictureType::I, (0.0, f64::MAX)), 2.0); } } diff --git a/crates/video/src/mpeg2/encode/tests.rs b/crates/video/src/mpeg2/encode/tests.rs index 01aac2b32..06b2c20fe 100644 --- a/crates/video/src/mpeg2/encode/tests.rs +++ b/crates/video/src/mpeg2/encode/tests.rs @@ -4,6 +4,7 @@ use super::*; use crate::mpeg2::{Decoder, probe}; +use picture::{Fallback, qscale}; /// A moving, textured test sequence: a gradient with a sharp pattern drifting by a fraction of a /// sample per picture, and a block moving across it. @@ -38,8 +39,34 @@ pub(crate) fn scene(w: usize, h: usize, cw: usize, ch: usize, t: usize) -> (Vec< (y, cb, cr) } +/// Uniform noise, different in every picture: as hard to code as content gets. +fn noise(w: usize, h: usize, cw: usize, ch: usize, t: usize) -> (Vec, Vec, Vec) { + let mut x = 0x9E37_79B9_7F4A_7C15u64 ^ (t as u64).wrapping_mul(0xD6E8_FEB8_6659_FD93); + let mut next = move || { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + (x >> 24) as u8 + }; + let y = (0..w * h).map(|_| next()).collect(); + let cb = (0..cw * ch).map(|_| next()).collect(); + let cr = (0..cw * ch).map(|_| next()).collect(); + (y, cb, cr) +} + +/// The scene's first picture, every time. +fn still(w: usize, h: usize, cw: usize, ch: usize, _t: usize) -> (Vec, Vec, Vec) { + scene(w, h, cw, ch, 0) +} + +type Source = fn(usize, usize, usize, usize, usize) -> (Vec, Vec, Vec); + /// Encode `frames` pictures of the scene; returns the stream and the reconstruction. fn encode(cfg: EncoderConfig, frames: usize) -> (Vec, Vec, Vec) { + encode_from(cfg, frames, scene) +} + +fn encode_from(cfg: EncoderConfig, frames: usize, source: Source) -> (Vec, Vec, Vec) { let (w, h) = (cfg.width as usize, cfg.height as usize); let (cw, ch) = (w / 2, if cfg.chroma == ChromaFormat::Yuv422 { h } else { h / 2 }); let mut enc = Encoder::new(cfg).unwrap(); @@ -47,7 +74,7 @@ fn encode(cfg: EncoderConfig, frames: usize) -> (Vec, Vec, Vec

Vec { } fn assert_decodes_to_recon(name: &str, cfg: EncoderConfig, frames: usize) -> Vec { - let (_, recon, packets) = encode(cfg, frames); + assert_decodes_to_recon_from(name, cfg, frames, scene) +} + +fn assert_decodes_to_recon_from(name: &str, cfg: EncoderConfig, frames: usize, source: Source) -> Vec { + let (_, recon, packets) = encode_from(cfg, frames, source); assert!(packets.windows(2).all(|w| w[0].dts < w[1].dts) && packets.iter().all(|p| p.dts <= p.pts), "{name}: decoding times"); let pics = decode(&packets); assert_eq!(pics.len(), frames, "{name}: picture count"); @@ -91,6 +122,81 @@ fn assert_decodes_to_recon(name: &str, cfg: EncoderConfig, frames: usize) -> Vec packets } +/// What [`check_vbv`] found. +#[derive(Debug)] +struct VbvRun { + cbr: bool, + /// Bit rate and buffer size from the sequence header. + rate: u64, + size: u64, + /// Bits of the whole stream. + bits: u64, +} + +/// Start codes in `data`: (offset of the 00 00 01, code). +fn start_codes(data: &[u8]) -> Vec<(usize, u8)> { + (0..data.len().saturating_sub(3)).filter(|&i| data[i..i + 3] == [0, 0, 1]).map(|i| (i, data[i + 3])).collect() +} + +/// Check a stream (packets in decoding order) against the VBV buffer of H.262 Annex C, using +/// nothing but its bytes: the sequence header's bit rate and buffer size, each picture's size +/// and `vbv_delay`. With a constant bitrate, data arrives at the bit rate from the first byte and +/// picture n is decoded `vbv_delay` after its start code arrives: those times must be one +/// picture interval apart, each picture complete by its time, and the buffer never over full. +/// With a variable bitrate the buffer fills at the bit rate until full and each picture must be +/// in it at its decoding time. +fn check_vbv(name: &str, packets: &[Packet], (fps_num, fps_den): (u32, u32)) -> VbvRun { + use crate::mpeg2::headers::{Extension, PictureHeader, SequenceHeader}; + let first = &packets[0].data; + let codes = start_codes(first); + let at = |code: u8| codes.iter().find(|c| c.1 == code).map(|c| c.0 + 4).unwrap(); + let seq = SequenceHeader::parse(&first[at(0xB3)..]).unwrap(); + let Extension::Sequence(ext) = Extension::parse(&first[at(0xB5)..]).unwrap() else { panic!("{name}: no sequence extension") }; + let rate = (u64::from(seq.bit_rate_value) | u64::from(ext.bit_rate_extension) << 18) * 400; + let size = (u64::from(seq.vbv_buffer_size_value) | u64::from(ext.vbv_buffer_size_extension) << 10) * 16384; + let (num, den) = (u128::from(fps_num), u128::from(fps_den)); + let (r, s) = (u128::from(rate), u128::from(size)); + let pics: Vec<(u64, u64, u16)> = packets + .iter() + .map(|p| { + let pic = start_codes(&p.data).into_iter().find(|c| c.1 == 0).unwrap().0 + 4; + (p.data.len() as u64 * 8, pic as u64 * 8, PictureHeader::parse(&p.data[pic..]).unwrap().vbv_delay) + }) + .collect(); + let cbr = pics[0].2 != 0xFFFF; + assert!(pics.iter().all(|p| (p.2 != 0xFFFF) == cbr), "{name}: some vbv_delay are 0xFFFF and some not"); + if cbr { + // in bit·ticks (bits × 90000): picture n decodes at T = (bits up to its start code) × + // 90000 + vbv_delay × rate; one interval is rate × 90000 × den / num of them + let mut before = 0u128; + let mut last: Option = None; + for (i, &(bits, head, delay)) in pics.iter().enumerate() { + let (bits, head) = (u128::from(bits), u128::from(head)); + let t = (before + head) * 90_000 + u128::from(delay) * r; + if let Some(l) = last { + // each vbv_delay is rounded down to a tick + let step = (t - l) * num; + let want = r * 90_000 * den; + assert!(step.abs_diff(want) <= 2 * r * num, "{name}: picture {i} decodes {step} after the one before, not {want}"); + } + let arrived = t + r; // within the tick the delay was rounded down by + assert!((before + bits) * 90_000 <= arrived, "{name}: picture {i} underflows ({bits} bits)"); + assert!(t <= (before + s) * 90_000, "{name}: the buffer overflows before picture {i}"); + before += bits; + last = Some(t); + } + } else { + // in 1/num bits: the buffer starts full and gains rate × den a picture, up to full + let mut full = s * num; + for (i, &(bits, _, _)) in pics.iter().enumerate() { + let b = u128::from(bits) * num; + assert!(b <= full, "{name}: picture {i} underflows ({bits} bits, {} in the buffer)", full / num); + full = (full - b + r * den).min(s * num); + } + } + VbvRun { cbr, rate, size, bits: pics.iter().map(|p| p.0).sum() } +} + fn psnr(a: &[u8], b: &[u8]) -> f64 { let sse: f64 = a.iter().zip(b).map(|(x, y)| (f64::from(*x) - f64::from(*y)).powi(2)).sum(); 10.0 * (255.0f64.powi(2) * a.len() as f64 / sse.max(1e-9)).log10() @@ -333,6 +439,165 @@ fn flushing_short_gops_keeps_the_average_bitrate() { } } +#[test] +fn constant_bitrate_streams_meet_the_vbv_buffer() { + let qcif = EncoderConfig { gop_size: 12, ..EncoderConfig::new(176, 144, 25, 1) }; + let cases: [(&str, EncoderConfig, Source); 9] = [ + ("scene", EncoderConfig { rate: RateControl::Cbr { kbps: 400 }, ..qcif.clone() }, scene), + ("scene ip", EncoderConfig { rate: RateControl::Cbr { kbps: 400 }, b_pictures: 0, ..qcif.clone() }, scene), + ("scene open b4", EncoderConfig { rate: RateControl::Cbr { kbps: 400 }, b_pictures: 4, closed_gop: false, ..qcif.clone() }, scene), + ("intra", EncoderConfig { rate: RateControl::Cbr { kbps: 1500 }, gop_size: 1, ..qcif.clone() }, scene), + ("small buffer", EncoderConfig { rate: RateControl::Cbr { kbps: 300 }, vbv_buffer_bits: Some(16384 * 3), ..qcif.clone() }, scene), + ("noise", EncoderConfig { rate: RateControl::Cbr { kbps: 600 }, ..qcif.clone() }, noise), + ("noise intra", EncoderConfig { rate: RateControl::Cbr { kbps: 600 }, gop_size: 1, ..qcif.clone() }, noise), + ("still", EncoderConfig { rate: RateControl::Cbr { kbps: 1000 }, ..qcif.clone() }, still), + ( + "422 29.97", + EncoderConfig { rate: RateControl::Cbr { kbps: 900 }, chroma: ChromaFormat::Yuv422, fps_num: 30000, fps_den: 1001, ..qcif.clone() }, + scene, + ), + ]; + for (name, cfg, source) in cases { + let (fps, frames) = ((cfg.fps_num, cfg.fps_den), 40); + // every case is a constant bitrate (0 would fail the rate check below) + let kbps = if let RateControl::Cbr { kbps } = cfg.rate { kbps } else { 0 }; + let packets = assert_decodes_to_recon_from(name, cfg, frames, source); + let run = check_vbv(name, &packets, fps); + assert!(run.cbr && run.rate == u64::from(kbps) * 1000, "{name}: {run:?}"); + // a constant bitrate: the stream is the bit rate's worth of its duration, give or take + // what the buffer held at the start and holds at the end + let want = run.rate as f64 * frames as f64 * f64::from(fps.1) / f64::from(fps.0); + assert!((run.bits as f64 - want).abs() <= run.size as f64, "{name}: {} bits for {want:.0}", run.bits); + } +} + +#[test] +fn constant_bitrate_pads_pictures_that_would_overflow_the_buffer() { + // a still picture costs next to nothing after the first: the rest must be stuffing + let cfg = EncoderConfig { rate: RateControl::Cbr { kbps: 2000 }, gop_size: 12, ..EncoderConfig::new(176, 144, 25, 1) }; + let (_, _, packets) = encode_from(cfg, 24, still); + let padded = packets.iter().filter(|p| p.data.ends_with(&[0; 64])).count(); + assert!(padded >= 12, "{padded} of {} pictures padded", packets.len()); + let run = check_vbv("still", &packets, (25, 1)); + assert!((run.bits as f64 / (2e6 * 24.0 / 25.0) - 1.0).abs() < 0.2, "{run:?}"); +} + +#[test] +fn variable_bitrate_streams_meet_the_vbv_buffer() { + let qcif = EncoderConfig { gop_size: 12, ..EncoderConfig::new(176, 144, 25, 1) }; + let small = Some(16384 * 4); + let cases: [(&str, EncoderConfig, Source); 7] = [ + ("vbr", EncoderConfig { rate: RateControl::Vbr { kbps: 300, max_kbps: 600 }, ..qcif.clone() }, scene), + ("vbr noise", EncoderConfig { rate: RateControl::Vbr { kbps: 300, max_kbps: 600 }, vbv_buffer_bits: small, ..qcif.clone() }, noise), + ("abr small buffer", EncoderConfig { rate: RateControl::Abr { kbps: 2000 }, vbv_buffer_bits: small, ..qcif.clone() }, noise), + ("quantiser 1", EncoderConfig { rate: RateControl::Quantiser(1), vbv_buffer_bits: small, ..qcif.clone() }, noise), + ("quantiser 1 intra", EncoderConfig { rate: RateControl::Quantiser(1), gop_size: 1, vbv_buffer_bits: small, ..qcif.clone() }, noise), + ("quantiser 1 b4", EncoderConfig { rate: RateControl::Quantiser(1), b_pictures: 4, vbv_buffer_bits: small, ..qcif.clone() }, noise), + ("default", qcif.clone(), scene), + ]; + for (name, cfg, source) in cases { + let packets = assert_decodes_to_recon_from(name, cfg, 30, source); + let run = check_vbv(name, &packets, (25, 1)); + assert!(!run.cbr, "{name}: {run:?}"); + } +} + +#[test] +fn pictures_too_large_for_the_buffer_are_coded_coarser() { + // noise at quantiser 1 is far beyond a 64 kbit buffer: every picture must give way, down to + // the coarsest quantiser or the fallbacks, and still decode to the reconstruction + let cfg = EncoderConfig { rate: RateControl::Quantiser(1), vbv_buffer_bits: Some(16384 * 4), ..EncoderConfig::new(176, 144, 25, 1) }; + let q_max = qscale(cfg.nonlinear_quant, 31) as f32; + let packets = assert_decodes_to_recon_from("noise", cfg, 24, noise); + assert!(packets.iter().all(|p| p.quantiser_scale > 8.0), "{:?}", packets.iter().map(|p| p.quantiser_scale).collect::>()); + // adaptive quantisation spreads the macroblocks of the coarsest pictures just under it + assert!(packets.iter().any(|p| p.quantiser_scale > 0.95 * q_max)); + check_vbv("noise", &packets, (25, 1)); +} + +#[test] +fn the_smallest_pictures_do_not_depend_on_the_source() { + let enc = Encoder::new(EncoderConfig { b_pictures: 2, ..EncoderConfig::new(176, 144, 25, 1) }).unwrap(); + let smallest = enc.smallest_picture(); + let frame = |t| { + let (y, cb, cr) = noise(176, 144, 88, 72, t); + enc.load(&YuvFrame { y: &y, cb: &cb, cr: &cr, y_stride: 176, c_stride: 88 }).unwrap() + }; + let (a, b) = (frame(1), frame(2)); + let h = Held { src: frame(3), pts: 0, n: 0 }; + let sizes: Vec = + [(PictureType::I, None, None), (PictureType::P, Some(&a), None), (PictureType::B, Some(&a), Some(&b)), (PictureType::B, None, Some(&b))] + .into_iter() + .map(|(t, fwd, bwd)| { + let c = enc.code_picture(&h, t, (fwd, bwd), [&[], &[]], 30.0, Fallback::Minimal); + // the minimal picture repeats its reference (grey for an I picture) + let want = bwd.or(fwd).map_or(128, |r| r.planes[0][5]); + assert_eq!(c.recon.planes[0][5], want, "{t:?}"); + c.bits() + }) + .collect(); + assert_eq!(sizes.iter().max().copied(), Some(smallest), "{sizes:?}"); + // the same sizes for a grey source and references + let mut grey = frame(0); + for p in &mut grey.planes { + p.fill(128); + } + let g = Held { src: grey.clone(), pts: 0, n: 0 }; + let i = enc.code_picture(&g, PictureType::I, (None, None), [&[], &[]], 30.0, Fallback::Minimal).bits(); + assert_eq!(i, sizes[0]); +} + +#[test] +fn the_sequence_header_carries_the_rate_and_buffer() { + let base = EncoderConfig::new(176, 144, 25, 1); + for (rate, vbv, want_rate, want_vbv) in [ + (RateControl::Cbr { kbps: 1000 }, None, 1_000_000, 475_136 / 16384 * 16384), + // rounded up to 400 bit/s + (RateControl::Cbr { kbps: 1001 }, None, 1_001_200, 475_136 / 16384 * 16384), + (RateControl::Vbr { kbps: 500, max_kbps: 1500 }, Some(200_000), 1_500_000, 196_608), + // the level's maximum + (RateControl::Abr { kbps: 500 }, None, 4_000_000, 475_136 / 16384 * 16384), + (RateControl::Quantiser(4), None, 4_000_000, 475_136 / 16384 * 16384), + ] { + let enc = Encoder::new(EncoderConfig { rate, vbv_buffer_bits: vbv, ..base.clone() }).unwrap(); + let info = probe(enc.sequence_header()).unwrap(); + assert_eq!(info.bit_rate, want_rate, "{rate:?}"); + assert_eq!(enc.vbv_value * 16384, want_vbv, "{rate:?}"); + } + // a larger buffer than the level holds moves to the next level + let enc = Encoder::new(EncoderConfig { vbv_buffer_bits: Some(1_000_000), ..base.clone() }).unwrap(); + assert_eq!(enc.profile_and_level(), 0x48); +} + +#[test] +fn bitrates_the_buffer_cannot_carry_are_refused() { + let base = EncoderConfig::new(352, 288, 25, 1); + let bad = [ + // 2000 bits a picture: less than the smallest CIF picture + EncoderConfig { rate: RateControl::Cbr { kbps: 50 }, ..base.clone() }, + EncoderConfig { rate: RateControl::Vbr { kbps: 40, max_kbps: 50 }, ..base.clone() }, + // a buffer of less than two pictures + EncoderConfig { rate: RateControl::Cbr { kbps: 4000 }, vbv_buffer_bits: Some(16384 * 9), ..base.clone() }, + // a buffer smaller than the smallest CIF picture + EncoderConfig { rate: RateControl::Quantiser(4), vbv_buffer_bits: Some(16384), ..base.clone() }, + EncoderConfig { vbv_buffer_bits: Some(16000), ..base.clone() }, + // beyond every level + EncoderConfig { vbv_buffer_bits: Some(10_000_000), ..base.clone() }, + EncoderConfig { rate: RateControl::Cbr { kbps: 0 }, ..base.clone() }, + EncoderConfig { rate: RateControl::Vbr { kbps: 900, max_kbps: 800 }, ..base.clone() }, + EncoderConfig { rate: RateControl::Cbr { kbps: 90_000 }, ..base.clone() }, + ]; + for cfg in bad { + let desc = format!("{cfg:?}"); + assert!(matches!(Encoder::new(cfg), Err(EncodeError::Config(_))), "{desc}"); + } + // the lowest bitrate that is accepted gives a stream that meets the buffer, noise or not + let lowest = (1..4000).find(|&kbps| Encoder::new(EncoderConfig { rate: RateControl::Cbr { kbps }, ..base.clone() }).is_ok()).unwrap(); + let cfg = EncoderConfig { rate: RateControl::Cbr { kbps: lowest }, ..base.clone() }; + let packets = assert_decodes_to_recon_from("lowest", cfg, 14, noise); + check_vbv("lowest", &packets, (25, 1)); +} + #[cfg(feature = "threads")] #[test] fn threaded_slices_give_the_same_stream() { diff --git a/crates/video/src/mpeg2/encode/vbv.rs b/crates/video/src/mpeg2/encode/vbv.rs new file mode 100644 index 000000000..ceae654d1 --- /dev/null +++ b/crates/video/src/mpeg2/encode/vbv.rs @@ -0,0 +1,118 @@ +//! The video buffering verifier (H.262 Annex C) as the encoder runs it: a model of the decoder's +//! input buffer, in decoding order, that says how large the next picture may be. +//! +//! Bits enter the buffer at `rate`. Each picture is removed whole at its decoding time, one +//! picture interval after the one before. With a constant bitrate (`vbv_delay` in every picture +//! header) the buffer must neither underflow (a picture not yet complete at its decoding time) +//! nor overflow. With a variable bitrate (`vbv_delay` 0xFFFF) the decoder fills the buffer until +//! it is full before the first picture, input stops while it is full, and only underflow is +//! possible. +//! +//! Fullness is counted in units of 1/`fps_num` bit, so one picture interval adds exactly +//! `rate · fps_den` of them and the model never rounds. + +/// `vbv_delay` for a variable bitrate stream. +pub(crate) const VBR_DELAY: u16 = 0xFFFF; + +/// The largest `vbv_delay` a constant bitrate stream can signal (0xFFFF means variable). +const MAX_DELAY: u64 = 0xFFFE; + +pub(crate) struct Vbv { + /// Buffer size in bits. + size: u64, + /// Bits per second: constant, or the peak at which the buffer fills. + rate: u64, + fps_num: u64, + fps_den: u64, + cbr: bool, + /// Fullness just before the next picture is removed, in 1/`fps_num` bits. + full: u64, +} + +impl Vbv { + /// A buffer of `size` bits filled at `rate` bit/s, `fps_num / fps_den` pictures a second. + /// With a constant bitrate the first picture is decoded once `start` bits are in. + pub fn new(size: u64, rate: u64, (fps_num, fps_den): (u32, u32), cbr: bool, start: u64) -> Self { + let (fps_num, fps_den) = (u64::from(fps_num.max(1)), u64::from(fps_den.max(1))); + let start = if cbr { start.min(size) } else { size }; + Self { size, rate, fps_num, fps_den, cbr, full: start.saturating_mul(fps_num) } + } + + /// Bits that enter the buffer in one picture interval, rounded down. + pub fn per_picture(&self) -> u64 { + self.rate.saturating_mul(self.fps_den) / self.fps_num + } + + /// The most bits the next picture may have: what is in the buffer at its decoding time. + pub fn max_bits(&self) -> u64 { + self.full / self.fps_num + } + + /// The fewest bits the next picture may have: with a constant bitrate, removing fewer would + /// let the buffer overflow before the picture after it. + pub fn min_bits(&self) -> u64 { + if !self.cbr { + return 0; + } + let next = self.full.saturating_add(self.rate.saturating_mul(self.fps_den)); + next.saturating_sub(self.size.saturating_mul(self.fps_num)).div_ceil(self.fps_num) + } + + /// `vbv_delay` of the next picture, whose data up to the end of its picture start code is + /// `head_bits` long: the 90 kHz ticks from the arrival of that start code to its decoding. + pub fn delay(&self, head_bits: u64) -> u16 { + if !self.cbr { + return VBR_DELAY; + } + let after = u128::from(self.full.saturating_sub(head_bits.saturating_mul(self.fps_num))); + let ticks = after * 90_000 / (u128::from(self.rate.max(1)) * u128::from(self.fps_num)); + ticks.min(u128::from(MAX_DELAY)) as u16 + } + + /// Remove the next picture (`bits` long, at most [`Vbv::max_bits`]). + pub fn remove(&mut self, bits: u64) { + let left = self.full.saturating_sub(bits.saturating_mul(self.fps_num)); + let next = left.saturating_add(self.rate.saturating_mul(self.fps_den)); + self.full = if self.cbr { next } else { next.min(self.size.saturating_mul(self.fps_num)) }; + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_constant_bitrate_buffer_bounds_both_sides() { + // 4000 bits a picture into 10000 bits, starting at 6000 + let mut v = Vbv::new(10_000, 100_000, (25, 1), true, 6000); + assert_eq!((v.per_picture(), v.max_bits(), v.min_bits()), (4000, 6000, 0)); + // 6000 - 1000 + 4000 = 9000: then at least 3000 must go, or 9000 - b + 4000 > 10000 + v.remove(1000); + assert_eq!((v.max_bits(), v.min_bits()), (9000, 3000)); + v.remove(3000); + assert_eq!(v.max_bits(), 10_000); + // the delay of a picture whose start code ends 100 bits in: 9900 bits at 100 kbit/s + assert_eq!(v.delay(100), 8910); + } + + #[test] + fn a_variable_bitrate_buffer_stops_filling_when_full() { + let mut v = Vbv::new(10_000, 100_000, (25, 1), false, 0); + assert_eq!((v.max_bits(), v.min_bits(), v.delay(0)), (10_000, 0, VBR_DELAY)); + v.remove(1000); + assert_eq!(v.max_bits(), 10_000); + v.remove(9000); + assert_eq!(v.max_bits(), 5000); + } + + #[test] + fn fractional_frame_rates_do_not_drift() { + // 30000/1001 pictures a second at 1 Mbit/s: 33366.67 bits a picture + let mut v = Vbv::new(2_000_000, 1_000_000, (30000, 1001), true, 1_000_000); + for _ in 0..30_000 { + v.remove(33_366); + } + // 30000 pictures leave 0.666… bit each in the buffer: exactly 20000 bits + assert_eq!(v.max_bits(), 1_020_000); + } +} 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"); + } + } +} diff --git a/crates/video/tests/mpeg2/encode.rs b/crates/video/tests/mpeg2/encode.rs index 122fe2d71..1f13d9c86 100644 --- a/crates/video/tests/mpeg2/encode.rs +++ b/crates/video/tests/mpeg2/encode.rs @@ -228,3 +228,37 @@ fn average_bitrate_reaches_its_target() { assert!(err.abs() < 0.10, "{kbps} kbit/s target: got {got:.0} kbit/s ({:+.1}%)", 100.0 * err); } } + +#[test] +fn constant_bitrate_streams_hold_their_rate() { + let Some(ff) = craft_media_testkit::ffmpeg_or_skip("mpeg2 encoder constant bitrate") else { return }; + // a small buffer, so what it holds at the start and end moves the average little + let vbv = 16384 * 16; + for (kbps, b) in [(1500u32, 2), (3000, 0)] { + let frames = 100; + let c = Case { + name: if b == 0 { "cif_cbr_3000_ip" } else { "cif_cbr_1500" }, + cfg: EncoderConfig { rate: RateControl::Cbr { kbps }, vbv_buffer_bits: Some(vbv), b_pictures: b, ..EncoderConfig::new(352, 288, 25, 1) }, + frames, + probe: "mpeg2video,Main,10,yuv420p", + min_psnr: 28.0, + }; + let (_, got) = check(&ff, &c); + // the stream is the bit rate times its duration, give or take one buffer + let slack = f64::from(vbv) / (frames as f64 / 25.0) / 1000.0; + assert!((got - f64::from(kbps)).abs() <= slack, "{kbps} kbit/s: got {got:.0} kbit/s (±{slack:.0})"); + } +} + +#[test] +fn ffmpeg_decodes_a_dvd_like_variable_bitrate_stream() { + let Some(ff) = craft_media_testkit::ffmpeg_or_skip("mpeg2 encoder variable bitrate") else { return }; + // DVD-Video's limits: 9.8 Mbit/s into a 224 KiB buffer + let cfg = EncoderConfig { + rate: RateControl::Vbr { kbps: 5000, max_kbps: 9800 }, + vbv_buffer_bits: Some(1_835_008), + gop_size: 12, + ..EncoderConfig::new(720, 576, 25, 1) + }; + check(&ff, &Case { name: "sd_vbr_dvd", cfg, frames: 13, probe: "mpeg2video,Main,8,yuv420p", min_psnr: 30.0 }); +} diff --git a/crates/video/tests/vp9_decode/common/mod.rs b/crates/video/tests/vp9_decode/common/mod.rs index 07eaeffef..e3847bdc1 100644 --- a/crates/video/tests/vp9_decode/common/mod.rs +++ b/crates/video/tests/vp9_decode/common/mod.rs @@ -44,6 +44,8 @@ pub const FIXTURES: &[Fixture] = &[ fx!("profile3_444_10bit", "testsrc2", 176, 144, 6, NOISE, "yuv444p10le", ["-b:v", "500k", "-profile:v", "3", "-frame-parallel", "0"]), fx!("profile3_422_12bit", "mandelbrot", 176, 144, 6, NOISE, "yuv422p12le", ["-b:v", "500k", "-profile:v", "3", "-frame-parallel", "0"]), fx!("lossless", "testsrc2", 176, 144, 5, NOISE, P420, ["-lossless", "1", "-frame-parallel", "0"]), + // RGB (`color_space` 7): libvpx takes it as gbrp, so the coded planes are G, B, R. + fx!("profile1_rgb", "testsrc2", 176, 144, 2, "", "gbrp", ["-lossless", "1", "-profile:v", "1", "-frame-parallel", "0"]), fx!("lossless_10bit", "mandelbrot", 176, 144, 4, NOISE, P420_10, ["-lossless", "1", "-profile:v", "2", "-frame-parallel", "0"]), fx!("tiles_cols4", "testsrc2", 1280, 720, 6, NOISE, P420, ["-b:v", "2M", "-tile-columns", "2", "-speed", "4", "-frame-parallel", "0"]), fx!( diff --git a/crates/video/tests/vp9_decode/frame.rs b/crates/video/tests/vp9_decode/frame.rs new file mode 100644 index 000000000..c8e94db57 --- /dev/null +++ b/crates/video/tests/vp9_decode/frame.rs @@ -0,0 +1,46 @@ +//! Conversion of decoded VP9 pictures into `craft_video::frame::VideoFrame`. + +use crate::common; +use craft_video::frame::{ColorFamily, Samples, VideoFrame}; + +/// An RGB stream converts to R, G, B. The reference decode is ffmpeg's `gbrp` (G, B, R), so the +/// frame's planes 0, 1, 2 must equal reference planes 2, 0, 1. +#[test] +fn rgb_planes_come_out_as_r_g_b() { + let f = common::fixture("profile1_rgb"); + let Some((ivf, yuv)) = common::ensure(f) else { return }; + let reference = std::fs::read(yuv).unwrap(); + let pics = common::decode_file_threads(&ivf, 1).map_err(|e| e.1).unwrap(); + assert_eq!(pics.len(), f.frames as usize); + let n = (f.width * f.height) as usize; + for (i, pic) in pics.into_iter().enumerate() { + assert_eq!(pic.color.color_space, 7); + let frame = VideoFrame::try_from(pic).unwrap(); + assert_eq!(frame.family(), ColorFamily::Rgb); + assert_eq!(frame.color.matrix, 0); + assert!(frame.color.full_range); + let refp = &reference[3 * n * i..3 * n * (i + 1)]; + let (g, b, r) = (&refp[..n], &refp[n..2 * n], &refp[2 * n..]); + for (plane, want, name) in [(0, r, "R"), (1, g, "G"), (2, b, "B")] { + let Samples::U8(got) = frame.planes()[plane].samples() else { panic!("8-bit storage") }; + assert_eq!(got.as_slice(), want, "frame {i} plane {name}"); + } + // The test source is not gray, so a swapped order would not pass by accident. + assert_ne!(r, g); + } +} + +/// A 4:2:2 12-bit stream keeps its subsampling and 16-bit storage. +#[test] +fn ycbcr_422_12bit() { + let f = common::fixture("profile3_422_12bit"); + let Some((ivf, _)) = common::ensure(f) else { return }; + let pics = common::decode_file_threads(&ivf, 1).map_err(|e| e.1).unwrap(); + let frame = VideoFrame::try_from(pics.into_iter().next().unwrap()).unwrap(); + assert_eq!(frame.family(), ColorFamily::YCbCr); + assert_eq!(frame.subsampling(), craft_video::frame::Subsampling::S422); + assert_eq!(frame.bit_depth(), 12); + assert_eq!((frame.planes()[1].width(), frame.planes()[1].height()), (88, 144)); + assert!(matches!(frame.planes()[0].samples(), Samples::U16(_))); + assert_eq!(frame.pts, Some(0)); +} diff --git a/crates/video/tests/vp9_decode/main.rs b/crates/video/tests/vp9_decode/main.rs index 66697e009..b05b5fdc3 100644 --- a/crates/video/tests/vp9_decode/main.rs +++ b/crates/video/tests/vp9_decode/main.rs @@ -1,5 +1,6 @@ mod common; mod conformance; +mod frame; mod fuzz_hostile; mod perf; mod robustness; diff --git a/crates/wordmodel/src/document.rs b/crates/wordmodel/src/document.rs index 5b0d1ae1a..4d9575f8d 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/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/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/lib.rs b/crates/wordmodel/src/lib.rs index 5fb2d14d8..fbe28bb98 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; @@ -143,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)] 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; } } diff --git a/crates/xls/Cargo.toml b/crates/xls/Cargo.toml index a97354581..b3df21cfc 100644 --- a/crates/xls/Cargo.toml +++ b/crates/xls/Cargo.toml @@ -10,6 +10,10 @@ repository.workspace = true [lints] workspace = true +[features] +# `testing`: a writer of small BIFF8 workbooks, plain or encrypted, for the tests of crates that read them. +test-support = [] + [dependencies] craft-cfb = { workspace = true } craft-sheet = { workspace = true } @@ -21,4 +25,5 @@ miniz_oxide = "0.9" thiserror = { workspace = true } [dev-dependencies] +craft-xls = { path = ".", features = ["test-support"] } miniz_oxide = "0.9" diff --git a/crates/xls/README.md b/crates/xls/README.md index d656e0798..13984d5fe 100644 --- a/crates/xls/README.md +++ b/crates/xls/README.md @@ -63,7 +63,8 @@ with `read_with_password` ([MS-OFFCRYPTO] 2.3.5, 2.3.6). Without a password, Exc is `Error::WrongPassword`; XOR obfuscation and CryptoAPI with AES, another cipher or hash, or an external provider are `Error::UnsupportedEncryption`. Every size in the FilePass record is checked before it is used. There is no writer -(`craft_xls::testing` builds small fixtures for tests). +(`craft_xls::testing` builds small fixtures for tests; another crate's tests get it through the +`test-support` feature). A formula that cannot be put back into text (a link to another workbook, a macro command, an unknown token) leaves its cell with the saved result, and `Warning::FormulaKept` says why. diff --git a/crates/xls/src/crypt.rs b/crates/xls/src/crypt.rs index c723341d1..1dc0e59d8 100644 --- a/crates/xls/src/crypt.rs +++ b/crates/xls/src/crypt.rs @@ -337,6 +337,7 @@ impl Rc4 { /// Encrypts a Workbook stream the way [`decrypt`] reads it, for tests: the FilePass record /// (RC4 1.1 with a fixed salt and verifier) goes right after the globals' BOF. `None` when the /// stream does not start with a record. +#[cfg(any(test, feature = "test-support"))] pub(crate) fn encrypt(stream: &[u8], password: &str) -> Option> { let salt: [u8; 16] = std::array::from_fn(|n| n as u8 + 0x40); let verifier: [u8; 16] = std::array::from_fn(|n| n as u8 + 0x60); @@ -359,6 +360,7 @@ pub(crate) fn encrypt(stream: &[u8], password: &str) -> Option> { /// The FilePass data [`encrypt_cryptoapi`] writes: RC4 CryptoAPI version 4.2, as current Excel /// writes it, with a `bits`-bit key (40 to 128) and a fixed salt and verifier. +#[cfg(any(test, feature = "test-support"))] pub(crate) fn cryptoapi_filepass(password: &str, bits: u32) -> Vec { let salt: [u8; SALT_LEN] = std::array::from_fn(|n| (n as u8).wrapping_mul(7).wrapping_add(0x11)); let verifier: [u8; SALT_LEN] = std::array::from_fn(|n| n as u8 + 0x80); @@ -381,12 +383,14 @@ pub(crate) fn cryptoapi_filepass(password: &str, bits: u32) -> Vec { } /// [`encrypt`] with RC4 CryptoAPI ([`cryptoapi_filepass`]). +#[cfg(any(test, feature = "test-support"))] pub(crate) fn encrypt_cryptoapi(stream: &[u8], password: &str, bits: u32) -> Option> { with_filepass(stream, &cryptoapi_filepass(password, bits), password) } /// `stream` with a FilePass record holding `filepass` right after its first BOF, encrypted with /// `password`. +#[cfg(any(test, feature = "test-support"))] fn with_filepass(stream: &[u8], filepass: &[u8], password: &str) -> Option> { let (_, bof) = header(stream, 0)?; let bof_len = 4 + bof; diff --git a/crates/xls/src/lib.rs b/crates/xls/src/lib.rs index 9ddfa00aa..df29cd3ef 100644 --- a/crates/xls/src/lib.rs +++ b/crates/xls/src/lib.rs @@ -24,8 +24,8 @@ //! caps, formula nesting is bounded, and nothing indexes by a number from the file. //! //! ``` -//! # fn main() -> Result<(), craft_xls::Error> { -//! # let bytes = craft_xls::testing::workbook(&[("Sheet1", vec![vec!["a".into(), "2.5".into()]])]); +//! # fn main() -> Result<(), Box> { +//! # let bytes = craft_xls::testing::workbook(&[("Sheet1", vec![vec!["a".into(), "2.5".into()]])])?; //! let read = craft_xls::read(&bytes)?; //! let sheet = &read.workbook.sheets[0]; //! assert_eq!(sheet.name, "Sheet1"); @@ -46,6 +46,7 @@ mod notes; mod read; mod records; mod styles; +#[cfg(any(test, feature = "test-support"))] #[doc(hidden)] pub mod testing; diff --git a/crates/xls/src/testing.rs b/crates/xls/src/testing.rs index 16667d4a9..1aaaf347e 100644 --- a/crates/xls/src/testing.rs +++ b/crates/xls/src/testing.rs @@ -4,6 +4,10 @@ const BOF: u16 = 0x0809; const EOF: u16 = 0x000A; /// Characters kept from one string: 4,000 UTF-16 units and the 3-byte header fit one record. const MAX_STRING: usize = 4000; +/// The last zero-based row of the BIFF8 grid ([MS-XLS] 2.2.1). +const MAX_ROW: usize = 65_535; +/// The last zero-based column of the BIFF8 grid ([MS-XLS] 2.2.1). +const MAX_COLUMN: usize = 255; fn rec(out: &mut Vec, kind: u16, data: &[u8]) { out.extend_from_slice(&kind.to_le_bytes()); @@ -30,20 +34,57 @@ fn bof(dt: u16) -> Vec { d } -/// A compound file whose root holds one stream. -pub fn compound(stream: &str, data: &[u8]) -> Vec { - craft_cfb::write_streams(craft_cfb::Version::V3, &[(stream, data)]).unwrap_or_default() +/// A compound file whose root holds one stream. A stream the file cannot hold, such as one with +/// an empty name or a name longer than 31 characters, returns the writer's error. +pub fn compound(stream: &str, data: &[u8]) -> Result, craft_cfb::Error> { + craft_cfb::write_streams(craft_cfb::Version::V3, &[(stream, data)]) +} + +/// The XF index and value of a cell written as a Number record, or `None` for a cell written as +/// text: a cell `date:` takes the date XF when `` is a number, and any other cell +/// that is a number takes the general XF. +fn number(cell: &str) -> Option<(u16, f64)> { + match cell.strip_prefix("date:") { + Some(serial) => serial.parse().ok().map(|x| (1, x)), + None => cell.parse().ok().map(|x| (0, x)), + } } /// A minimal BIFF8 workbook: one worksheet per `(name, rows)`. Cells that read as numbers are /// Number records, a cell `date:` is a Number with the date format `m/d/yyyy` (built-in -/// format 14), an empty cell is left out, and everything else goes through the shared-string -/// table (as UTF-16 when it isn't Latin-1). +/// format 14), an empty cell is left out, and everything else, including a `date:` cell whose +/// serial is not a number, goes through the shared-string table (as UTF-16 when it isn't +/// Latin-1). A nonempty cell past row 65,535 or column 255 (zero-based) returns +/// [`craft_cfb::Error::Invalid`] naming its sheet, row and column, and a compound file that cannot +/// be written returns the writer's error. /// /// shortcut: characters outside the Basic Multilingual Plane are dropped, sheet names are cut at /// 255 characters and strings at 4,000 (so each fits one record); lift when a fixture needs more. -pub fn workbook(sheets: &[(&str, Vec>)]) -> Vec { +pub fn workbook(sheets: &[(&str, Vec>)]) -> Result, craft_cfb::Error> { let mut sst: Vec<&str> = Vec::new(); + let mut references = 0usize; + for (name, rows) in sheets { + for (r, row) in rows.iter().enumerate() { + for (c, v) in row.iter().enumerate() { + if v.is_empty() { + continue; + } + if r > MAX_ROW || c > MAX_COLUMN { + return Err(craft_cfb::Error::Invalid(format!( + "fixture cell on sheet {name:?} at zero-based row {r}, column {c} is outside the BIFF8 grid" + ))); + } + if number(v).is_none() { + references += 1; + if !sst.contains(&v.as_str()) { + sst.push(v); + } + } + } + } + } + let total = i32::try_from(references) + .map_err(|_| craft_cfb::Error::Invalid(format!("{references} shared-string references do not fit the SST record")))?; let mut out = Vec::new(); rec(&mut out, BOF, &bof(0x0005)); for ifmt in [0u16, 14] { @@ -61,13 +102,10 @@ pub fn workbook(sheets: &[(&str, Vec>)]) -> Vec { chars(&mut d, &name); rec(&mut out, 0x0085, &d); } - for c in sheets.iter().flat_map(|(_, rows)| rows.iter().flatten()) { - if c.parse::().is_err() && !c.starts_with("date:") && !sst.contains(&c.as_str()) { - sst.push(c); - } - } + // cstTotal is the number of LabelSst cells and cstUnique is the number of strings in the table + // ([MS-XLS] 2.4.265). let mut d = Vec::new(); - d.extend_from_slice(&(sst.len() as u32).to_le_bytes()); + d.extend_from_slice(&total.to_le_bytes()); d.extend_from_slice(&(sst.len() as u32).to_le_bytes()); let mut sst_records = vec![d]; for s in &sst { @@ -92,18 +130,17 @@ pub fn workbook(sheets: &[(&str, Vec>)]) -> Vec { let mut d = Vec::new(); d.extend_from_slice(&(r as u16).to_le_bytes()); d.extend_from_slice(&(c as u16).to_le_bytes()); - if let Some(x) = v.strip_prefix("date:").and_then(|x| x.parse::().ok()) { - d.extend_from_slice(&1u16.to_le_bytes()); - d.extend_from_slice(&x.to_le_bytes()); - rec(&mut out, 0x0203, &d); - } else if let Ok(x) = v.parse::() { - d.extend_from_slice(&0u16.to_le_bytes()); + if let Some((xf, x)) = number(v) { + d.extend_from_slice(&xf.to_le_bytes()); d.extend_from_slice(&x.to_le_bytes()); rec(&mut out, 0x0203, &d); } else { + let i = sst + .iter() + .position(|s| s == v) + .ok_or_else(|| craft_cfb::Error::Invalid(format!("the cell text {v:?} is not in the shared-string table")))?; d.extend_from_slice(&0u16.to_le_bytes()); - let i = sst.iter().position(|s| s == v).unwrap_or(0) as u32; - d.extend_from_slice(&i.to_le_bytes()); + d.extend_from_slice(&(i as u32).to_le_bytes()); rec(&mut out, 0x00FD, &d); } } diff --git a/crates/xls/tests/read.rs b/crates/xls/tests/read.rs index f7ea37fb0..f4360b5e0 100644 --- a/crates/xls/tests/read.rs +++ b/crates/xls/tests/read.rs @@ -621,7 +621,7 @@ fn the_fixture_writer_reads_back() { let long = "é".repeat(3000); let rows = vec![vec!["Name".to_string(), "Żółw".into(), String::new(), "2.5".into()], vec!["date:45000".into(), long.clone(), long.clone() + "x"]]; - let bytes = craft_xls::testing::workbook(&[("Erste", rows), ("Second", vec![vec!["Name".into()]])]); + let bytes = craft_xls::testing::workbook(&[("Erste", rows), ("Second", vec![vec!["Name".into()]])]).unwrap(); assert!(is_xls(&bytes)); let read = craft_xls::read(&bytes).unwrap(); assert_eq!(read.warnings, []); @@ -634,6 +634,86 @@ fn the_fixture_writer_reads_back() { assert_eq!(v(&wb, 1, "A1"), text("Name")); } +#[test] +fn a_fixture_that_cannot_be_written_returns_the_writer_error() { + assert_eq!(craft_xls::testing::compound("", b"x"), Err(craft_cfb::Error::BadName(String::new()))); + let long = "S".repeat(32); + assert_eq!(craft_xls::testing::compound(&long, b"x"), Err(craft_cfb::Error::BadName(long.clone()))); +} + +/// A nonempty cell outside rows 0 to 65,535 or columns 0 to 255 is an error naming the cell, and +/// the last row and column are written where they were asked for. +#[test] +fn the_fixture_writer_rejects_a_cell_outside_the_grid() { + let mut rows = vec![Vec::new(); 65_537]; + rows[0] = vec!["first".to_string()]; + rows[65_536] = vec!["wrapped".into()]; + match craft_xls::testing::workbook(&[("Tall", rows)]) { + Err(craft_cfb::Error::Invalid(m)) => assert!(m.contains("\"Tall\"") && m.contains("row 65536, column 0"), "{m}"), + other => panic!("{:?}", other.map(|b| b.len())), + } + let mut wide = vec![String::new(); 257]; + wide[0] = "first".into(); + wide[256] = "dropped".into(); + match craft_xls::testing::workbook(&[("Wide", vec![wide])]) { + Err(craft_cfb::Error::Invalid(m)) => assert!(m.contains("\"Wide\"") && m.contains("row 0, column 256"), "{m}"), + other => panic!("{:?}", other.map(|b| b.len())), + } + // An empty cell past the grid is not written, so it is not an error. + let mut rows = vec![Vec::new(); 65_537]; + rows[0] = vec!["first".to_string(), String::new()]; + rows[65_535] = vec![String::new(); 257]; + rows[65_535][255] = "last".into(); + rows[65_536] = vec![String::new()]; + let read = craft_xls::read(&craft_xls::testing::workbook(&[("Full", rows)]).unwrap()).unwrap(); + assert_eq!(read.warnings, []); + assert_eq!((v(&read.workbook, 0, "A1"), v(&read.workbook, 0, "IV65536")), (text("first"), text("last"))); +} + +/// The SST record's cstTotal and cstUnique fields ([MS-XLS] 2.4.265) in a fixture's Workbook stream. +fn sst_counts(file: &[u8]) -> (u32, u32) { + let stream = craft_cfb::CompoundFile::open(file).unwrap().read_path("Workbook").unwrap(); + let mut at = 0; + while let Some(head) = stream.get(at..at + 4) { + let kind = u16::from_le_bytes([head[0], head[1]]); + let len = usize::from(u16::from_le_bytes([head[2], head[3]])); + if kind == 0x00FC { + let d = &stream[at + 4..at + 12]; + return (u32::from_le_bytes([d[0], d[1], d[2], d[3]]), u32::from_le_bytes([d[4], d[5], d[6], d[7]])); + } + at += 4 + len; + } + panic!("no SST record"); +} + +/// cstTotal is the number of cells that refer to the shared-string table, and cstUnique is the +/// number of strings in it. +#[test] +fn the_fixture_writer_counts_every_shared_string_reference() { + let row = |cells: &[&str]| vec![cells.iter().map(|s| s.to_string()).collect::>()]; + let one = craft_xls::testing::workbook(&[("S", row(&["same", "same"]))]).unwrap(); + assert_eq!(sst_counts(&one), (2, 1)); + let two = craft_xls::testing::workbook(&[("S", row(&["same"])), ("T", row(&["same"]))]).unwrap(); + assert_eq!(sst_counts(&two), (2, 1)); + let none = craft_xls::testing::workbook(&[("S", row(&["1", "", "date:45000"]))]).unwrap(); + assert_eq!(sst_counts(&none), (0, 0)); + let wb = craft_xls::read(&two).unwrap().workbook; + assert_eq!((v(&wb, 0, "A1"), v(&wb, 1, "A1")), (text("same"), text("same"))); +} + +/// A `date:` cell whose serial is not a number is text, whether the shared-string table holds +/// other text before it, an empty cell, or nothing else. +#[test] +fn the_fixture_writer_keeps_a_date_cell_without_a_serial_as_text() { + for (first, value) in [("first", text("first")), ("", Value::Empty), ("1", Value::Number(1.0))] { + let rows = vec![vec![first.to_string(), "date:abc".into(), "date:".into()]]; + let read = craft_xls::read(&craft_xls::testing::workbook(&[("S", rows)]).unwrap()).unwrap(); + assert_eq!(read.warnings, [], "{first:?}"); + let wb = read.workbook; + assert_eq!((v(&wb, 0, "A1"), v(&wb, 0, "B1"), v(&wb, 0, "C1")), (value, text("date:abc"), text("date:")), "{first:?}"); + } +} + #[test] fn cell_sheet_and_merge_caps_are_enforced() { let number = |r: u16| rec(0x0203, &cat(&[&cell(r, 0, 0), &1.0f64.to_le_bytes()])); diff --git a/crates/xlsx/Cargo.toml b/crates/xlsx/Cargo.toml index 0d09f79aa..18be3abe7 100644 --- a/crates/xlsx/Cargo.toml +++ b/crates/xlsx/Cargo.toml @@ -10,9 +10,16 @@ repository.workspace = true [lints] workspace = true +[features] +# `testing`: writers of small workbooks and packages, for the tests of crates that read them. +test-support = [] + [dependencies] craft-drawingml = { workspace = true } craft-opc = { workspace = true } craft-sheet = { workspace = true } craft-xml = { workspace = true } thiserror = { workspace = true } + +[dev-dependencies] +craft-xlsx = { path = ".", features = ["test-support"] } diff --git a/crates/xlsx/src/lib.rs b/crates/xlsx/src/lib.rs index 9105ba886..14d1a9f3c 100644 --- a/crates/xlsx/src/lib.rs +++ b/crates/xlsx/src/lib.rs @@ -35,7 +35,7 @@ //! //! ``` //! # fn main() -> Result<(), craft_xlsx::Error> { -//! # let bytes = craft_xlsx::testing::workbook(&[("Prices", r#"02.5"#)], &["Tea"]); +//! # let bytes = craft_xlsx::testing::workbook(&[("Prices", r#"02.5"#)], &["Tea"])?; //! let mut package = craft_xlsx::Package::open(&bytes, &craft_xlsx::Limits::default())?; //! let workbook = package.workbook()?; //! let strings = package.shared_strings()?; @@ -60,6 +60,7 @@ mod richdata; mod sheet; mod strings; mod styles; +#[cfg(any(test, feature = "test-support"))] #[doc(hidden)] pub mod testing; mod workbook; diff --git a/crates/xlsx/src/testing.rs b/crates/xlsx/src/testing.rs index 43920f42d..3f425f7ee 100644 --- a/crates/xlsx/src/testing.rs +++ b/crates/xlsx/src/testing.rs @@ -6,8 +6,9 @@ const MAIN_NS: &str = "http://schemas.openxmlformats.org/spreadsheetml/2006/main const R_NS: &str = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"; /// An `.xlsx` with the given sheets, each `(name, the rows inside )`, and shared -/// strings. Names and strings are written as given: escape them first if they need it. -pub fn workbook(sheets: &[(&str, &str)], strings: &[&str]) -> Vec { +/// strings. Names and strings are written as given: escape them first if they need it. An +/// archive that cannot be written returns the writer's error. +pub fn workbook(sheets: &[(&str, &str)], strings: &[&str]) -> Result, craft_opc::Error> { let mut out = PackageOut::default(); let mut root = RelsOut::default(); root.add("officeDocument", "xl/workbook.xml", false); @@ -40,11 +41,13 @@ pub fn workbook(sheets: &[(&str, &str)], strings: &[&str]) -> Vec { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml", format!(r#"{list}"#).into_bytes(), ); - out.finish().unwrap_or_default() + out.finish() } -/// A ZIP archive of the given entries, stored as named (no content types are added). -pub fn zip(entries: &[(&str, &[u8])]) -> Vec { +/// A ZIP archive of the given entries, stored as named (no content types are added). An entry +/// the archive cannot hold, such as a second entry under the same name, returns the writer's +/// error. +pub fn zip(entries: &[(&str, &[u8])]) -> Result, craft_opc::Error> { let entries: Vec<(String, Vec)> = entries.iter().map(|(n, b)| (n.to_string(), b.to_vec())).collect(); - craft_opc::zip_entries(&entries).unwrap_or_default() + craft_opc::zip_entries(&entries) } diff --git a/crates/xlsx/tests/pivot.rs b/crates/xlsx/tests/pivot.rs index 4d2fd00d5..efcd76e29 100644 --- a/crates/xlsx/tests/pivot.rs +++ b/crates/xlsx/tests/pivot.rs @@ -60,6 +60,7 @@ fn with_pivots() -> Vec { ("xl/pivotCache/pivotCacheRecords1.xml", RECORDS.as_bytes()), ("xl/pivotCache/pivotCacheDefinition2.xml", OLAP.as_bytes()), ]) + .unwrap() } #[test] @@ -160,7 +161,7 @@ fn pivots_round_trip() { #[test] fn a_new_pivot_table() { - let mut doc = read(&craft_xlsx::testing::workbook(&[("Data", r#"1"#), ("Report", "")], &[])); + let mut doc = read(&craft_xlsx::testing::workbook(&[("Data", r#"1"#), ("Report", "")], &[]).unwrap()); let values = [CacheValue::Number(1.0), CacheValue::Number(2.0)]; let definition = PivotCacheDefinition { refresh_on_load: Some(true), diff --git a/crates/xlsx/tests/richdata.rs b/crates/xlsx/tests/richdata.rs index a5879dcf5..4a265e290 100644 --- a/crates/xlsx/tests/richdata.rs +++ b/crates/xlsx/tests/richdata.rs @@ -12,7 +12,7 @@ fn png(w: u32, h: u32, tag: u8) -> Vec { } fn new_doc() -> Document { - Document::read(&workbook(&[("S", r#"#VALUE!"#)], &[]), &Limits::default()).unwrap() + Document::read(&workbook(&[("S", r#"#VALUE!"#)], &[]).unwrap(), &Limits::default()).unwrap() } fn part(doc: &Document, name: &str) -> String { diff --git a/crates/xlsx/tests/write.rs b/crates/xlsx/tests/write.rs index bb7cc683b..c080e7e96 100644 --- a/crates/xlsx/tests/write.rs +++ b/crates/xlsx/tests/write.rs @@ -75,6 +75,7 @@ fn excel_like() -> Vec { ("xl/drawings/vmlDrawing1.vml", VML.as_bytes()), ("xl/vbaProject.bin", &[0xD0, 0xCF, 0x11, 0xE0, 1, 2, 3]), ]) + .unwrap() } const COMMENTS: &str = "AnnAnn:\nnote"; diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index a7253df22..3611cafbb 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -114,6 +114,7 @@ fn package(book: &[u8], sheet: &[u8], strings: &[u8], roots: &str, rels: &str, t ("data/two.bin", &worksheet(&[], &[])), ("text/strings.bin", strings), ]) + .unwrap() } fn file(sheet: &[u8]) -> Vec { package(&book(false), sheet, &sst(), ROOT, RELS, TYPES) @@ -346,6 +347,7 @@ fn two_sheets(one: &[u8], two: &[u8]) -> Vec { ("data/two.bin", two), ("text/strings.bin", &sst()), ]) + .unwrap() } #[test] diff --git a/crates/xlsx/tests/xlsx.rs b/crates/xlsx/tests/xlsx.rs index ef932026e..b5ebdf2c7 100644 --- a/crates/xlsx/tests/xlsx.rs +++ b/crates/xlsx/tests/xlsx.rs @@ -42,6 +42,7 @@ fn strict() -> Vec { .as_bytes(), ), ]) + .unwrap() } #[test] @@ -101,7 +102,8 @@ fn a_strict_workbook_with_prefixes() { #[test] fn a_damaged_sheet_keeps_the_rows_before_the_damage() { - let bytes = workbook(&[("S", r#"12