Skip to content

ILIB Format

Jump to bottom
NtinosTheGamer2324 edited this page May 18, 2026 · 1 revision

ILIB Image Library Format Specification

Version 1.0

Overview

.ilib is a binary container format for bundling multiple raster images into a single file. It is designed for use in ModuOS as the standard image resource library format. Images are stored as zlib-compressed raw RGBA pixel streams, allowing fast random access to any image by ID without scanning the entire file.

Design Goals

  • Simple — minimal structure, easy to parse in C with no external dependencies beyond zlib.
  • Random access — any image can be decoded directly using its absolute file offset, no sequential scanning needed.
  • Compact — raw RGBA data is zlib-compressed before storage.
  • Format-agnostic input — source images (PNG, BMP, etc.) are fully normalized to raw RGBA before packing; the container has no concept of source format.

File Structure

An .ilib file consists of three sections laid out sequentially:

┌─────────────────────────┐
│     Container Header    │  6 bytes
├─────────────────────────┤
│      Resource Table     │  N × 18 bytes
│  (one entry per image)  │
├─────────────────────────┤
│      Data Payloads      │  variable length
│  (one blob per image)   │
└─────────────────────────┘

All multi-byte integers are little-endian.

Section 1 — Container Header

Offset 0x00, size 6 bytes.

Offset Size Type Field Description
0 4 char[4] Magic Always 49 4C 49 42 ("ILIB")
4 2 uint16 Image Count Total number of images in the file

A file with zero images is valid (Image Count = 0) and contains no resource table entries or payloads.

Section 2 — Resource Table

Immediately follows the header at offset 0x06.

One 18-byte entry per image, stored sequentially in ID order. The table is Image Count × 18 bytes in total.

Entry Layout

Offset Size Type Field Description
0 2 uint16 Image ID Unique identifier; auto-incremented from 0
2 2 uint16 Width Image width in pixels
4 2 uint16 Height Image height in pixels
6 4 uint32 Raw Size Uncompressed RGBA byte count (width × height × 4)
10 4 uint32 Compressed Size Byte length of the zlib payload in the file
14 4 uint32 File Offset Absolute byte offset of the payload from the start of the file

Notes

  • Image ID is assigned by list order at compile time (0, 1, 2, …). Reordering images in the compiler changes their IDs.
  • Raw Size must always equal Width × Height × 4. A parser should reject entries where this invariant does not hold.
  • File Offset points into the Data Payloads section and is absolute from byte 0 of the file, not relative to the section start.

Section 3 — Data Payloads

Immediately follows the resource table. Each payload is a zlib-compressed blob of raw RGBA pixel data.

Pixel Data Format

  • Color model: RGBA, 4 channels, 8 bits per channel (32 bits per pixel)
  • Channel order: R, G, B, A — one byte each, in that order
  • Row order: top-down (first byte is the top-left pixel)
  • No row padding, no BMP-style alignment, no file headers of any kind
  • Uncompressed size is always width × height × 4 bytes

Compression

  • Algorithm: zlib (RFC 1950), compression level 6 (default)
  • Each image is compressed independently
  • Payloads are packed sequentially with no gaps or alignment padding between them

Locating a Payload

To read image with ID n:

  1. Find the resource table entry where Image ID == n.
  2. Seek to File Offset bytes from the start of the file.
  3. Read exactly Compressed Size bytes.
  4. Decompress with zlib → yields Raw Size bytes of RGBA pixel data.

File Offset Calculation

For a file with N images, payload offsets are calculated as:

payload_section_start = 6 + (N × 18)

offset[0] = payload_section_start
offset[i] = offset[i-1] + compressed_size[i-1]

Example with 3 images:

Byte 0x000000  ┌──────────────────┐
               │  Header (6 B)    │
Byte 0x000006  ├──────────────────┤
               │  Entry 0 (18 B)  │
Byte 0x000018  ├──────────────────┤
               │  Entry 1 (18 B)  │
Byte 0x00002A  ├──────────────────┤
               │  Entry 2 (18 B)  │
Byte 0x00003C  ├──────────────────┤
               │  Payload 0       │  ← offset stored in Entry 0
               ├──────────────────┤
               │  Payload 1       │  ← offset stored in Entry 1
               ├──────────────────┤
               │  Payload 2       │  ← offset stored in Entry 2
               └──────────────────┘

Magic Bytes

Byte Hex ASCII
0 49 I
1 4C L
2 49 I
3 42 B

Limits

Property Limit
Max image count 65,535 (uint16 max)
Max image width 65,535 px (uint16 max)
Max image height 65,535 px (uint16 max)
Max payload offset 4,294,967,295 bytes (~4 GB) (uint32 max)
Color depth Always 32-bit RGBA (8 bits per channel)
Compression Always zlib

Validation Rules

A conforming parser must reject a file if any of the following are true:

  1. The file is shorter than 6 bytes.
  2. Bytes 0–3 are not 49 4C 49 42 ("ILIB").
  3. The file is shorter than 6 + (Image Count × 18) bytes.
  4. For any entry, Raw Size ≠ Width × Height × 4.
  5. For any entry, File Offset + Compressed Size exceeds the file size.

C Structure Reference

/* Container header (6 bytes at file offset 0) */
#define ILIB_MAGIC       "ILIB"
#define ILIB_HEADER_SIZE  6
#define ILIB_ENTRY_SIZE   18

/* Resource table entry — all fields little-endian */
typedef struct {
    uint16_t image_id;      /* 0:  Image ID (0-based, sequential)        */
    uint16_t width;         /* 2:  Width in pixels                        */
    uint16_t height;        /* 4:  Height in pixels                       */
    uint32_t raw_size;      /* 6:  Uncompressed size = width*height*4     */
    uint32_t cmp_size;      /* 10: Compressed payload size in bytes       */
    uint32_t file_offset;   /* 14: Absolute file offset of payload        */
} ilib_entry_t;             /* Total: 18 bytes                            */

Changelog

Version Date Notes
1.0 2026-05-17 Initial release

Clone this wiki locally