[with-developer]

Purpose

A review of the docs against the code before release 0.16.0, the first since #124, after the Vulkan and Direct3D contexts (D61 to D63), RGB pictures (D65) and concealment (D66). It found one broken promise and docs that had fallen behind.

Changes

• Rust 1.87. Concealment brought a let chain into cpu::Concealer::decode. Let chains are stable from 1.88, and Cargo.toml and the READMEs promise 1.87: the build failed there with E0658. The condition is a nested if again, and a new CI job, "oldest Rust (1.87)", checks the workspace, all targets, with the locked dependencies (none asks for a newer Rust). 0.15.0 built on 1.87; no release had the chain.
• C API docs (lib.rs, the header regenerated):
  • EmberwaveTexture's ordering rules now cover Vulkan contexts, through the semaphores of the decodes that do not wait, and Direct3D ones, through the fences of the _d3d12 calls. They also name the Direct3D wrappers. The decodes into textures say which textures each takes and that shared Direct3D textures take the _d3d12 calls.
  • emberwave_context_create_vulkan named only Metal's decodes that do not wait. It said "Windows" where only 64-bit Windows has it, and its sentence on requirements read as if a bad queue family, queue index or apiVersion were undefined behaviour. They are EMBERWAVE_STATUS_INVALID_ARGUMENT.
  • emberwave_context_destroy's contract includes Direct3D contexts.
  • The ffi README says what emberwave_decoder_set_concealment's argument is, and that concealment is off by default.
• ARCHITECTURE.md: which memory a decoder makes on first use; the dequantisation of a block that a concealing frame lacks; the colour module's RGB to Y'CbCr conversion; RGB textures among the portable reads; the browser player's set_concealment.
• CONTRIBUTING.md: the two lints CI runs besides the workspace's (no gpu feature, wasm32).
• BENCHMARKS.md: the BGRA encoding table comes with the next full run.

Testing

• cargo fmt --check.
• cargo clippy --workspace --all-targets, -p emberwave-core --no-default-features --all-targets and --target wasm32-unknown-unknown -p emberwave-web -p emberwave-core, all with -D warnings.
• cargo test --release --workspace on Metal.
• The header test after regenerating the header.
• Rust 1.87 is checked by the new CI job only: it is not installed here.

Benchmark impact

None.

Review

The findings come from our review agent's read of the docs against the code at 6cd390e. It checked the Quick start and Usage commands by running them, and every C and Rust name in the docs. Each finding was checked against the code before it was fixed. The Vulkan and Direct3D docs were checked by reading, as that code does not build on this Mac.

Related issue

None; before release 0.16.0.