Skip to content

Latest commit

 

History

History
87 lines (73 loc) · 5.01 KB

JPEG.md

File metadata and controls

87 lines (73 loc) · 5.01 KB

JPEG

src/jpeg.bend adapts pinned stb_image's JPEG decoder, which raylib uses when built with SUPPORT_FILEFORMAT_JPG (off in default raylib, on in the reference archive the codec gates use). Baseline, extended and progressive Huffman frames decode; arithmetic coding, lossless and 12-bit frames fail, as in stb.

Function raylib Contract
Surface.decode_image(".jpg", bytes) (and the other raster tokens) LoadImageFromMemory JPEG content (0xFF fill bytes then SOI) after the PNG/BMP/PNM/PSD/PIC/GIF signatures, before the TGA fallback.
Surface.decode_jpeg(bytes) / Surface.load_jpeg(path) — The JPEG decoder alone.
Surface.load_image(path) LoadImage .jpg/.jpeg names (either case) through the same dispatch.

Results are GRAYSCALE (1) for one-component frames and R8G8B8 (4) otherwise: YCbCr through stb's fixed-point conversion, RGB when the component ids are R, G, B or an Adobe marker says transform 0 without JFIF, CMYK (Adobe transform 0) and YCCK (transform 2) through stb's rounded products, and other four-component frames as YCbCr. Chroma is upsampled as stb does: fancy 2x horizontal, vertical and 2x2 filters and nearest-neighbor otherwise.

The decoder keeps stb's arithmetic and stream behavior exactly:

  • the integer IDCT with stb's truncated constants (for example -7567, where libjpeg uses -7568), 16-bit coefficient wrapping and arithmetic shifts;
  • stb's 32-bit entropy buffer: bytes past the end of the data read as 0, a marker inside the data stops filling and later bits are zero, codes that need more bits than remain are errors, and its 9-bit fast tables decide which short codes fail at a marker;
  • streams that never define a Huffman or quantization table decode with stb's zeroed tables (symbol 0 with no bits, factor 0);
  • restart intervals, a scan ending where no restart marker follows, junk after a scan, extra fill bytes, DNL markers and an unknown marker after the frame (which ends the image successfully) follow stb's marker loop.

Jonlib contracts where stb's result is not defined or not supported:

  • dimensions above 4096 are UnsupportedImageSize;
  • an image stb would take from uninitialized memory is InvalidImageStream: a component no scan completely wrote (baseline) or initialized with a first DC scan (progressive), or a progressive stream that ends before EOI, for which stb skips its final dequantization and transform;
  • other failures are InvalidImageHeader (headers and markers) or InvalidImageStream (entropy-coded data); raylib returns no image.

Export

Surface.to_jpeg and Surface.write_jpeg are ExportImage's JPEG branch: stbi_write_jpg at quality 90. .jpg and .jpeg (ASCII case folded by Surface.write_image) select it. GRAYSCALE, GRAY_ALPHA, R8G8B8 and R8G8B8A8 pass stored samples; gray-alpha keeps both bytes and the writer ignores alpha. Every other format goes through LoadImageColors and is written as four channels. The encoder is the scalar float AAN DCT from Jon Olick's public-domain jo_jpeg, copied into src/jpeg_write.bend with each add and multiply kept as its own F32 operation. Subsampling is 4:2:0 and the scaled quality is 20. Other qualities, progressive output and ExportImageToMemory for JPEG are not implemented.

How it is verified

tools/jpeg_probe.py (gate jpeg) builds raylib with SUPPORT_FILEFORMAT_JPG=ON and compares native LoadImageFromMemory(".jpg") with Jonlib's file loading by .jpg names (the Surface.decode_image dispatch) on every committed fixture in tests/fixtures/jpeg and on variants derived from them: format, dimensions and every stored byte, or failure on both sides. The fixtures cover 1x1 to 64x48 images; grayscale, 4:4:4, 4:2:0, 4:2:2, 4:4:0, 4:1:1, 3:1:1 and mixed sampling; baseline and progressive (including successive-approximation refinement) frames; restart intervals per block and per row; quality 1 (16-bit tables) and 100; optimized and arithmetic coding; RGB and CMYK. The variants add YCCK and Adobe-RGB markers, truncated baseline and progressive data, junk after EOI, a missing EOI, extra fill bytes, a flipped entropy byte, removed Huffman tables, a bad SOI, lossless and 12-bit frames and the two contracts above. Surface.load_jpeg and a .JPEG name are checked too, on CPU-1, CPU-2 and JavaScript.

The fixtures were produced once from synthetic pixels by libjpeg-turbo's cjpeg (and PIL for CMYK); tools/jpeg_fixtures.py records and regenerates them, and tests/fixtures/jpeg/manifest.json lists each command. Native raylib, not the encoder, is the reference.

tools/jpeg_export_probe.py (gate jpeg-export) compares Surface.to_jpeg and suffix-selected Surface.write_image with pinned ExportImage on small GRAYSCALE, GRAY_ALPHA, R8G8B8, R8G8B8A8 and one RGB565 image, including a size that is not a multiple of 16 and the .JPG / .JpEg suffixes. CPU-1, CPU-2 and JavaScript must match every byte. Performance is not measured.

Not covered: hosts other than the CI pair, larger images and performance, and decoding or export on the GPU lane.