[with-developer]

Purpose

The Rust half of #152: an emberwave-core API that can grow without breaking callers, before 1.0 freezes it (D70). It builds on #153, the C half, merged before it.

Changes

• #[non_exhaustive] on the enums that grow: GpuError, EncodeError, ColorError, bitstream::Error, bitstream::Header, TexturePicture, TimedOutput, ColorMatrix and RgbOrder.

• The same on the structs that grow:

  • the timings, frames and planes that callers read;
  • GpuOptions, ColorParams and Signalling, which callers make from Default and change member by member.

  ColorParams::new takes its three members, and Timings derives Default.

• Names. Decoder::record_rgb, record_rgb_to_texture and record_to_plane_textures replace encode_*, which the encoders' encode_rgb overlapped.

• Options. GpuOptions::default() no longer reads the environment; from_env() does, for the CLI and the C API's NULL options.

• The share. Decoder::set_partial_share returns a Result, with a new GpuError::InvalidArgument for a share outside 0 to 1 or NaN, as the C API and the browser player refuse it. The C API and the player now take the decoder's error.

• One constant name. pwv1::HEADER_BYTES is FILE_HEADER_BYTES.

• Internal items. Those there for tests and tools are #[doc(hidden)], and the crate's docs say they are outside the API.

• The browser build. Calls that wait for the GPU are not built for wasm32. The GPU module allows unused helpers there only.

• wgpu. pub use wgpu, so that callers take the version emberwave is built with.

• Docs and callers.

  • D70 in ARCHITECTURE.md, and CHANGELOG.md.
  • The browser section names record_rgb_to_texture.
  • Every caller in the CLI, the C API, the browser player and the tests, changed by hand or by a script that turns struct literals into a default changed member by member, checked for shadowed names.

Testing

• cargo test --release --workspace on the M3 Max. The partial share test now checks that out-of-range shares are refused and leave the share.
• Lints: cargo fmt --check; clippy with -D warnings for the workspace, for --no-default-features, for wasm32 (emberwave-web and emberwave-core), and for x86_64-pc-windows-msvc --workspace --all-targets.
• RUSTDOCFLAGS=-D warnings cargo doc for the core and the C API.

Benchmark impact

None.

Review

Our review agent compared every rewritten literal with the original, traced every blocking call on wasm32, and built the browser player for wasm32. It ran the tests in release and debug, the Rust 1.87 check, and clippy for Windows and wasm32. It found no defect of weight in the API change. Its findings are fixed in 357cf92:

• Medium. The tests had stopped taking EMBERWAVE_BACKEND once Default stopped reading it, though CLAUDE.md and CONTRIBUTING.md promise it for forcing a backend. They start from GpuOptions::from_env() again, so that one run uses one backend.
• Low:
  • A future matrix without a C constant would have reached C callers as BT.709 through a wildcard. It is now an internal error.
  • from_env's doc was stale, three doc links pointed at hidden items, and Concealer::bands showed a hidden type.
  • The wasm32 docs linked to calls that build leaves out; this is allowed on wasm32 only.
  • D59 and D60 are marked superseded, and draw.wgsl named the old call.
  • The CHANGELOG now says which structs other crates can no longer make.

main has since merged #153, which this branch includes.

Related issue

Closes #152 together with #153.