Crate retro_image 

Decoder for image formats of retro computers.

Give decode a file name and the bytes of a file and it returns the picture as 8-bit RGB, plus an alpha plane if the picture has transparency. The file name chooses which of the supported formats to try (see formats); many formats are also recognized by their content, so a file with the wrong extension still decodes.

// A 1x1 PAM picture, held in memory: the library never touches files.
let file = b"P7\nWIDTH 1\nHEIGHT 1\nDEPTH 3\nMAXVAL 255\nTUPLTYPE RGB\nENDHDR\n\xff\x80\x00";

let decoded = retro_image::decode("dot.pam", file)?;
let image = decoded.image();
assert_eq!((image.width(), image.height()), (1, 1));
assert_eq!(image.rgb(), [0xff, 0x80, 0x00]); // 3 bytes per pixel, row by row
assert!(!image.has_alpha());
assert_eq!(decoded.format().platform(), "Unix");

Guarantees

• Decoding never panics on malformed input. Truncated, corrupt and hostile files make a decoder return a DecodeError; a panic would be a bug. Every decoder is tested against truncated and mutated real files and fuzzed for this.
• Memory is bounded. A picture may take at most max_image_bytes (64 MiB, 4 bytes per pixel) of memory unless the program calls set_max_image_bytes. Dimensions come from untrusted headers, so the limit is checked before anything is allocated for them; a bigger picture fails with DecodeError::TooLarge. A decoder holds some temporary buffers while it works, so the peak memory of a decode is a small multiple of the limit, not of the file size.
• Types are thread-safe. Image, Format and DecodeError are Send and Sync.
• Errors can grow. DecodeError is #[non_exhaustive], so new reasons are not breaking changes.

The crate is no_std (it needs alloc) and has no dependencies. This file holds no external format knowledge: it is the public API. Each decoder module cites the documents its layouts come from; the platform surveys are in docs/research/.

Structs

Attempt

One format that decode tried and that failed.

Decoded

A decoded picture and the format that decoded it, as decode returns them.

Format

One supported file format.

FormatId

An identifier for a Format that stays the same between releases, so a program can store it, for example to remember which format a user picked.

Image

A decoded picture: 8-bit color, row-major, top row first, and an alpha plane when some pixel is not opaque.

NoCompanions

No companion files: every lookup finds nothing.

Enums

DecodeError

Why a file could not be decoded.

Traits

Companions

Files that accompany the main one, such as a palette file next to a picture (PIC.COL next to PIC.MIC).

Functions

candidates

The formats decode tries for filename, in order: those matching its extension, then the other formats with a signature. filename is only looked at for its extension.

decode

Decodes data on its own: the picture, and the format that accepted it. See decode_with for how the format is chosen.

decode_with

Decodes data, choosing the format from filename and the content.

formats

Every supported format.

max_image_bytes

The most memory one decoded picture may take, in bytes: 64 MiB until set_max_image_bytes changes it.

set_max_image_bytes

Sets the most memory one decoded picture may take, in bytes. See max_image_bytes for how pictures are counted.