Decoding REXPaint Files in Odin

This is a practical guide to reading REXPaint v1.70 `.xp` files in Odin, using the format as an accessible introduction to binary parsing. An `.xp` file is gzip-compressed; after decompression, it contains little-endian integers describing the version and layer count, followed by each layer’s dimensions and its cells. Every cell occupies ten bytes: a 32-bit character index and six RGB color bytes. Cells are stored column by column, and character indices use CP437 by default. The guide also explains REXPaint’s transparency convention: hot pink (255, 0, 255) marks empty backgrounds, with remaining transparent cells on the bottom layer rendered black.

The implementation builds an Odin decoder in stages: gzip decompression, a cursor that tracks the current byte offset, and helpers for reading integers and colors before assembling layers and cells. It emphasizes useful failure reporting rather than a generic success flag, distinguishing truncated data, invalid dimensions, excessive layer sizes, and gzip errors. Bounds and size checks happen before reads or allocations, while deferred cleanup releases partially built layers and cells if parsing fails. A coordinate helper accounts for column-major storage, and the decoded file’s nested allocations must be freed by the caller with the allocator used to create them. The examples target Odin’s dev-2026-10 toolchain; later core compression changes may require adapting the gzip code.