API reference

Every header version (OS/2 1.x and 2.x, and Windows 3 through 5), 1-, 2-, 4-, 8-, 16-, 24-, and 32-bit pixels, RLE4 and RLE8, bitfields with or without alpha, and top-down and bottom-up rows. A JPEG or PNG stream in place of the pixels is reported (error.EmbeddedJpeg, error.EmbeddedPng) with the reader at its first byte, for the caller to hand to a JPEG or PNG decoder. dib.zig decides the cases the format leaves open. The color table is the bytes between the info header and the pixels, as the pixel offset says, up to 256 entries.

Format: GIF87a and GIF89a (W3C, 1987 and 1990), with the NETSCAPE2.0 (or ANIMEXTS1.0) application extension's loop count. Global and local color tables, interlacing, and the graphic control extension's transparent index, delay, and disposal. ICC profiles (ICCRGBG1012) and XMP packets (XMP DataXMP) go to Options.blob_sink and Config.metadata, or, after the first frame, applyTrailer. Comments, plain text, and other application extensions are skipped.

Frames follow the APNG model: decodeFrame writes each frame into its region of the caller's canvas, which must hold the previous frame with its disposal applied. The first frame clears the canvas outside its region to transparent black and writes its transparent pixels as transparent black (Frame.blend is src); a later frame with a transparent index leaves the canvas under those pixels alone (src_over). Disposal is the caller's: Frame.disposal says what to do with the region before the next frame, and decodeFrameConfig reports the next frame before it is drawn, so a caller can save the region that restore-to-previous needs.

Where the specification leaves room, this decoder does what Wuffs does by default: the canvas grows to hold the first frame, later frames are clipped to it, a frame's LZW data must hold exactly its pixels (unless Options.ignore_too_much_data lets it hold more), an index past the color table (or with no color table) is opaque black, the last of several graphic control extensions wins, and a byte that starts no block ends the image as the trailer does. A file cut short is Truncated, even after its last frame, where the trailer should be.

Format: the PNG specification, third edition (W3C, 2025), which includes APNG. Every color type, bit depth, and Adam7 interlacing; tRNS becomes an alpha channel in the native format. gAMA, cHRM, sRGB, cICP, mDCV, cLLI, pHYs, iCCP, eXIf, and bKGD are reported in Config and never applied; iCCP and eXIf bytes go to the blob sink as they pass. cICP takes precedence over iCCP, sRGB, gAMA, and cHRM, as section 4.3 orders them.

Strict, as Wuffs is: the CRC-32 of every critical chunk (IHDR, PLTE, IDAT, IEND) is checked, and so is the image data's Adler-32, unless Options.ignore_checksums is set. Ancillary chunks' CRCs are not checked, as in Wuffs; libpng and libspng accept a bad one too. The image data must decompress to exactly the rows the image needs, with nothing after the zlib stream in its chunks; an interlaced frame one row tall is the exception, as in Wuffs: data after its last row is skipped. Chunks that shape the pixels (IHDR, PLTE, tRNS, IDAT, IEND, acTL, fcTL, fdAT) must follow the specification; a chunk that cannot change the pixels (a metadata chunk with a malformed body, a tRNS beside an alpha channel) is ignored, as the specification allows, and the first of a duplicate wins. An unknown critical chunk is Unsupported. An out-of-range palette index is opaque black, as the specification requires.

APNG: the frames are the animation's. A default image outside the animation (no fcTL before IDAT) is skipped, as APNG decoders are to do. decodeFrame writes each frame into its region of the caller's canvas: blend-over frames are composited onto what the canvas holds, and the first frame clears the canvas outside its region to transparent black. Disposal is the caller's: Frame.disposal says what to do with the region before the next call. A still image's IEND is read by the second decodeFrame, which returns null.

Format: ITU T.81 (JPEG), with T.871 (JFIF) and Adobe's APP14 for the color transform. Sequential and progressive DCT images with 8- or 12-bit samples, Huffman- or arithmetic-coded; lossless images (process 14, Huffman-coded) of 2 to 16 bits; every sampling factor libjpeg-turbo accepts, restart intervals, grayscale, gray with alpha (two components, unconverted, as libjpeg reads them), YCbCr, RGB, CMYK, and YCCK; and decoding DCT images at 1/2, 1/4, or 1/8 size (Options.scale). The hierarchical processes and lossless arithmetic coding, which libjpeg-turbo does not decode either, are Unsupported.

The pixels are libjpeg-turbo's with its default settings, bit for bit: its accurate integer IDCT, its "fancy" upsampling, and its YCbCr to RGB. CMYK and YCCK images decode to RGB by libjpeg-turbo's naive conversion, or to their stored inks with Options.cmyk = .raw. Samples of other precisions than 8 bits are scaled to the native format, rounded: 16-bit past 8 bits, 8-bit below.

Strict, as libjpeg-turbo is when it treats warnings as errors: a truncated file, a marker segment of the wrong length, an undefined Huffman code, entropy-coded data that ends before its scan or restart interval does, a wrong restart marker, or an inconsistent progression is an error. Bytes that are not a marker between segments are skipped, as the reference skips them. decodeFrame reads through EOI.

Metadata is reported in Config and never applied: JFIF density, the EXIF orientation, and the ICC profile (reassembled from its APP2 segments), EXIF, and XMP blobs, which go to the blob sink as they pass. Metadata.gain_map flags an HDR gain map (Ultra HDR, Adobe's, or ISO 21496-1): an MPF APP2 segment, which locates the second image, and either the gain map namespace in the XMP or ISO 21496-1's APP2 segment. The gain map image after EOI is never read.

Format: the Truevision TGA File Format Specification, version 2.0. Every image type the specification defines: color-mapped (1, 9) with 8- or 16-bit indices and 15-, 16-, 24-, or 32-bit entries, true-color (2, 10) at 15, 16, 24, and 32 bits, gray (3, 11) at 8 bits and 16 (gray and alpha), run-length encoded or not, in any of the four origins, and type 0, which has no image (no frames). Where the specification leaves a choice:

• 32-bit pixels and color-map entries always carry alpha, whatever the descriptor's attribute-bit count says, as every reader we compare with does; 16-bit pixels use their top bit as alpha only when the descriptor names one attribute bit; 15- and 16-bit color-map entries are opaque, as the specification says of their 16th bit. Five-bit channels widen by bit replication.
• A color map's first entry index offsets the indices: pixel value i is entry i - first. An index outside the map is opaque black, as in Wuffs.
• Run-length packets may run from one scan line into the next (the specification says they should not, and older writers do), but not past the last pixel (RunPastEnd).
• The descriptor's interleaving bits (7-6), the screen origin, and the color-map fields of an image without a color map are ignored; a color map in a true-color or gray file is skipped.

The TGA 2.0 footer and extension area follow the pixels, so they cannot shape Config: the decodeFrame call after the image reads the rest of the input and trailer reports what it found. Reading forward only, the decoder finds an extension area that starts right after the image data or ends right before the footer, the two places writers put it.

Formats: the Netpbm specifications (netpbm.sourceforge.net/doc: pbm, pgm, ppm, pam, and pfm). The native pixel format is 8-bit for a maxval up to 255 and 16-bit above it, gray, gray and alpha, RGB, or RGBA as the file stores; PBM is gray8, and PFM is rgba_f32. A sample v with maxval m is the fraction v / m of full scale, so it becomes v * 255 / m (or v * 65535 / m) rounded to nearest; maxval 255 and 65535 keep the samples as they are.

How strict the decoder is, where the specifications leave room:

• Header numbers are ASCII decimal, separated by at least one whitespace character (space, tab, CR, LF, VT, FF). A comment runs from # to the next CR or LF, which stays and counts as whitespace, so 255#c\n ends a header. Exactly one whitespace character ends a PBM, PGM, PPM, or PFM header. A zero width, height, depth, or maxval, a maxval over 65535, or anything else out of place is BadHeader; a width or height over 2^32 - 1 is ImageTooLarge.
• PAM: P7 and a newline, then lines of one keyword and its value; blank lines and lines starting with # (after blanks) are ignored, and blanks (whitespace but LF, so a CR too) may end a line. WIDTH, HEIGHT, DEPTH, MAXVAL, and ENDHDR must each appear once, and an unknown keyword or an extra token on a line is BadHeader. The tuple types BLACKANDWHITE and GRAYSCALE (read the same way, as gray scaled by maxval), RGB, and their _ALPHA forms are read from the first one to four planes, and further planes are skipped, as the PAM specification recommends; a depth too small for the type is BadHeader. Without a tuple type, depth 1 to 4 reads as gray, gray and alpha, RGB, and RGBA; any other tuple type, or no tuple type with a larger depth, is Unsupported.
• PFM: PF (color) or Pf (gray), the width, the height, and the scale, a nonzero decimal number whose sign gives the byte order (negative is little endian); the scale's magnitude names units and is not applied. Rows are stored bottom to top and written top to bottom.
• A sample above maxval is SampleOutOfRange.
• Plain rasters (P1, P2, P3) are read leniently, as their specifications ask: any whitespace between samples, and comments, as libnetpbm accepts them. A sample must end with whitespace, a comment, or the end of the input, and anything after the last sample must start with whitespace or a comment; otherwise it is BadRaster. The decoder reads nothing past the last sample.
• Frames: a raw PBM, PGM, PPM, or PAM file is a sequence of images, each a frame. Whitespace between images and after the last is skipped (as libnetpbm skips it between plain images); then the input must end or hold another image with the same magic number, size, and native format (FrameMismatch otherwise). Config.frame_count is null for these, since only the end of the input tells. Plain files and PFM hold one image, and the decoder stops after it.

Format: the Wireless Bitmap of the WAP Wireless Application Environment specification (WAP-237, section 6 and appendix A), type 0, the only type it defines: a multi-byte integer type field (0), a fixed header octet (0: no extension headers), the width and height as multi-byte integers, then the rows, one bit per pixel, most significant bit first, each row padded to an octet. A set bit is white, a clear one black. A multi-byte integer is big-endian groups of 7 bits, each octet but the last with its top bit set. The decoder reads nothing after the last row.

Format: RFC 9649, the WebP container and the lossless bitstream, and RFC 6386 for the lossy one. It decodes simple files and extended (VP8X) images, lossless or lossy, with a lossy image's ALPH chunk, still or animated. ICCP, EXIF, and XMP chunks before the image (or the first frame) are reported in Config.metadata, and every one goes to the blob sink as it passes; EXIF's orientation is read.

As libwebp reads them: a still image's bitstream must match the VP8X canvas, chunks before the image may come in any order (only the image chunk ends them), and chunks after it are skipped, but the RIFF payload must be all there, so a still image's decodeFrame reads to its end. An animation's chunks follow libwebp's demuxer, and its frames are composited as libwebp's animation decoder composites them, given a caller that disposes of each frame's region to transparent black.

• The source is converted with image.convert to RGB8 (RGBA8 with alpha), then to BT.601 limited-range YUV 4:2:0, a macroblock row at a time: each chroma sample from the average of its 2x2 pixels.
• EncodeOptions.quality picks the quantizer. With segments (every effort but fast), macroblocks are clustered by their luma activity into four segments, each with its own quantizer and loop filter level: busier ones, where artifacts hide, quantize more coarsely.
• Each macroblock's luma is predicted as one 16x16 block or as sixteen 4x4 blocks, and its chroma as two 8x8 blocks, choosing the modes that cost least in squared error plus lambda times the bits, the bits estimated from the token probabilities. Above fast, trellis quantization (vp8_encode_trellis.zig) chooses the levels the same way.
• Coefficients are kept compactly in work memory as they are chosen, with the counts of every token. After the last macroblock the token probabilities are chosen from the counts, the token partition is coded into the spare room of the coefficients' memory (or sized, when it does not fit), the first is sized by a pass of the boolean coder that writes nothing, and the file is written in one pass.
• Alpha goes in ALPH, compressed by the lossless encoder (src/webp/encode.zig) when that is smaller than raw.

Format: TIFF 6.0 with BigTIFF. Classic and BigTIFF files in either byte order; strips and tiles; uncompressed, PackBits, LZW, Deflate, CCITT modified Huffman, Group 3, and Group 4, and JPEG data (through image.jpeg, TIFF Technical Note 2); predictors 2 and 3; 1 to 32-bit integer and 16, 24, 32, and 64-bit float samples, chunky or planar; gray, palette, RGB, CMYK (as cmyk8 or cmyk16), and YCbCr with subsampling. Every IFD in the main chain is a page and a frame. samples.zig says how samples become the native format.

The input is read forward, as every decoder here reads it. TIFF's offsets point anywhere, and the usual writer puts the IFD after the pixels, so data behind the reader needs Options.seeker (error.DataBehind without one). With a seeker, decodeConfig walks the whole IFD chain to report the page count, a canvas as large as the largest page, the work memory the largest page needs, and a native format that holds every page; a chain that loops ends where it repeats, as in libtiff. Without one, the config is the first page's, frame_count is null when there is a second page, and a later page that does not fit it is error.PageMismatch.

Each frame is a page, written to the top-left corner of the canvas; the rest of the canvas becomes black, transparent if the native format has alpha. Work memory is the page's strip or tile offsets and byte counts, the decompressor's state, and one row of the strip or tile (one strip or tile of every plane for planar data, which interleaves them), so for chunky data it does not grow with the image's height. JPEG gray, RGB, and YCbCr decode straight to the caller's rows; other JPEG pages take a strip or tile of samples. A JPEG stream that is progressive or not interleaved, which keeps every coefficient, is error.Unsupported.

The box is read twice, once to size the work memory and once into it, and the Exif, xml , and codestream boxes may come before or after it, so the reader must be able to move back: Options.seeker is required (error.NeedsSeeker).

var r = JpegReconstructor.init(reader, .{ .seeker = .file(&file_reader) });
const work = try gpa.alloc(u8, try r.workLen());
try r.run(writer, work);