solidcraft-upstream/docs/render-hdr-input.md

Bounded Radiance input

solidcraft_render::lighting provides a caller-owned cooperative RGBE decoder. This is input preparation only: it enables no environment import command, document format, PBR material, lighting capability, GPU upload or image-render backend. The existing canvas decoder explicitly accepts PNG/JPEG only, so Cargo feature unification cannot send HDR through its synchronous whole-image loading path. It is the independent input foundation for #813 / #620, coordinated with the maintainer's renderer work described in #792.

HdrSource::new(Vec<u8>) checks a bounded header using the existing image metadata codec. Success does not mean the pixel stream is valid. Use validate(cancelled) for a synchronous full-stream check, or construct HdrDecodeTask and repeatedly call step(units, cancelled) for cooperative preparation. Only Complete(DecodedHdr) contains publishable pixels. Cancellation and errors release partial buffers; subsequent calls return Consumed, including after successful completion. The cancellation callback must itself be bounded. The consumer owns scheduling and must not perform synchronous validate on a latency-sensitive UI thread.

Input limits are 16 MiB of encoded Vec capacity, a 64 KiB header, 2048x1024 and 2,097,152 pixels. Only 2:1, square-pixel, standard -Y +X RGBE is accepted. EXR, XYZE and other orientations are unsupported. A call accepts 1–16,384 work units; each unit decodes one packet (at most 128 component writes) or converts one pixel. An overall work cap bounds malformed old-style runs. Corrected channels must be finite, nonnegative and at most 100,000,000. Limits are intentional preview policy, not a statement about all valid Radiance files.

The float pixel allocation is at most 24 MiB, with one RGBE scanline at most 8 KiB and a shared encoded source at most 16 MiB. Construction reserves float storage fallibly; initialization happens incrementally. This is a per-task estimate, not a process memory quota. The consumer must admit concurrent jobs, source ownership, decoded copies, colour conversion, GPU textures and IBL maps within its own total budget before starting.

RGBE conversion follows image 0.25.10's mantissa/exponent convention, with no tone mapping or clipping to [0,1]. Stored values are divided by header EXPOSURE and COLORCORR. Physical units are not guaranteed by arbitrary input files. HdrInfo::primaries preserves explicit PRIMARIES chromaticities; absence is unspecified. Output is linear RGB in the source colour space, not implicitly linear sRGB. Consumers must choose and validate a working-space transform; basic finite/range validation of chromaticities here does not prove an invertible or physically meaningful gamut. No gamut conversion is performed by this utility.

The scanline adapter is derived from the permissively licensed image codec; see ATTRIBUTION.md, NOTICE and THIRD-PARTY-LICENSES.txt. Test images are original inline byte fixtures. No commercial-product images or materials are included.