Jonlib reproduces raylib's LoadImageRaw header rule and ExportImage(".raw")
bytes. Surface.write_image also selects RAW for a .raw suffix; loading needs
the caller's width, height and format.
| API | Result |
|---|---|
Surface.load_raw(path, width, height, format, header_size) |
IO(Result<&1, &1, Surface.IOError, Surface>) |
Surface.write_raw(image, path) |
IO(Result<&1, &1, Surface.IOError, Unit>) |
Surface.load_raw supports ordinary, non-changing files in formats 1..13.
R32 words are little-endian finite values in [0,1]; both zero signs and
positive subnormals are preserved exactly (see R32.md). R32G32B32
payloads are three little-endian words per pixel (width*height*12 bytes);
every non-NaN sample is preserved exactly, including signed zero, subnormals
and infinities. Dimensions are 1..4096. The U32 header size plus the required
image bytes must fit a nonnegative signed C int, and the file size must not
exceed 2,147,483,647 bytes. Invalid request parameters are rejected before
opening.
The pinned native header rule:
- If the file is shorter than the required image bytes, fail.
- Use a positive header offset only if
header_size + required_bytes <= file_size. - Otherwise read the image from byte zero, even if a nonzero header was requested.
Only the selected payload is read, using bounded Base.File.read_at; ignored
headers and tails are never materialized as a whole-file list, and they may
contain arbitrary bytes. Opened handles are closed before the result image is
constructed, including on size and read failures. A short read is rejected
rather than filled with synthetic pixels.
Surface.IOError results:
DataError{InvalidRequest}: unsupported dimensions/format or unsafe header arithmetic.DataError{OutOfDomain}: a complete selected payload contains a sample outside the format's domain (R32: negative nonzero, above one, infinity or NaN; R32G32B32: NaN); reported after closure. This is Jonlib's checked-storage adaptation, not a native rejection.DataError{TruncatedImageData}: too few file/payload bytes.DataError{UnsupportedImageSize}: a reported file size exceeds the signed-int bound.FileError{code, message}: the original Base open/size/read error.
Surface.write_raw consumes its owner and writes exactly the native-order
image bytes, without a header or storage padding, then closes the file after
the write result. R32 and R32G32B32 words are written unchanged; NaN
R32G32B32 samples are rejected with SourceError{owner, OutOfDomain} before the
file is opened, and open/write failures are FileError{code, message}. The raw float domain and the
JavaScript NaN-representation gap are described in FLOAT-RGB.md.
All gates compare exact output against pinned native raylib on the CPU-1, CPU-2 and JavaScript lanes (see VERIFICATION.md). File IO is verified on CPU and JavaScript only; no GPU filesystem claim is made.
- Formats 1..7 (
tools/raw_file_probe.py, gateraw-file): nativeLoadImageRawfollowed byExportImageis compared withload_raw+write_rawmetadata and bytes for all seven formats: exact-fit and non-fitting headers, the largest permitted header, ignored tails and missing/empty/short inputs; a native export failure is also checked. Typed controls cover parameters, a sparse 2 GiB file (never sent to native) and read failures, and 100 success/truncation/read-error cycles run underRLIMIT_NOFILE=64. - R32 (
tools/r32_raw_file_probe.py, gater32-raw-file): native usesLoadImageRawandSaveFileDataonly, avoiding incidental float-to-byte casts. Cases cover exact-fit headers, ignored invalid headers/tails, non-fitting offsets, the largest safe header, all R32 threshold words, a 33,024-pixel signed-zero/subnormal file, truncation and out-of-domain payloads (including a large file whose final word is invalid, checking tail-recursive validation). Every successful load is written and reloaded. A candidate-only 64 MiB sparse file selects one word at a 32 MiB header offset under a 256 MiB runtime-RSS ceiling, guarding against whole-file materialization. 100 success/sample/truncation/read/size cycles run under the 64-descriptor limit. - RGB float (
tools/float_rgb_raw_file_probe.py, gatefloat-rgb-raw-file): load/header cases compare every output file with native loaded storage (SaveFileData), and some normalized cases also with nativeExportImage(".raw"). Controls cover request, file, truncation, size and NaN domains, and a directory write checks the file-error variant. 100 load/domain/truncation/read/size/write cycles run under the descriptor limit.
python3 tools/run_gates.py --bend-source "$BEND_SOURCE" --raylib-source "$RAYLIB_SOURCE" --only raw-fileConcurrent modification, special-file semantics, native callbacks, wider parameter/format domains (compressed and half-float layouts, NaN payload preservation) and full platform/resource coverage.