selune
e99b3bd4e8
A cancellable, bounded Radiance HDR decoder for render lighting input; reference images still accept PNG and JPEG only.
48 lines
3.0 KiB
Markdown
48 lines
3.0 KiB
Markdown
# 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.
|