Skip to content

CSL_SPEC.md

Latest commit

 

History

History
82 lines (63 loc) · 2.45 KB

CSL_SPEC.md

File metadata and controls

82 lines (63 loc) · 2.45 KB
Raw

CHISEL .csl Format Specification (Implemented v2.0/v2.1/v2.2/v2.3)

This document defines the exact .csl behavior currently implemented in this repository.

1) Global Header

V2.0/V2.1/V2.2 Header (8 bytes)

Offset Type Field Value
0x00 u8[3] Magic "CSL"
0x03 u8 Version 0x20, 0x21, or 0x22
0x04 u16 LE Width 1..=65535
0x06 u16 LE Height 1..=65535

V2.3 Header (14 bytes)

Offset Type Field Value
0x00 u8[3] Magic "CSL"
0x03 u8 Version 0x23
0x04 u16 LE Width 1..=65535
0x06 u16 LE Height 1..=65535
0x08 u8 Flags See below
0x09 u32 LE CRC32 IEEE CRC32 of payload

V2.3 Flags:

  • Bit 0 (0x01): Scanline traversal (1 = scanline, 0 = Morton)
  • Bit 1 (0x02): Grayscale mode (1 = grayscale)
  • Bit 2 (0x04): YCoCg transform (1 = YCoCg)

2) Decoder State

Initial state:

  • x = 0, y = 0
  • current_alpha = 255
  • color_cache = [[0,0,0,0]; 64]

Cache policy:

  • 64-slot RGBA hash cache: slot = (r*3 + g*5 + b*7 + a*11) % 64.
  • Cache updates on most pixel-drawing opcodes.

3) Opcode Map (Implemented Active Subset)

The currently active encode/decode paths use:

  • 0x40..=0x7F: cache draw (V2.1+)
  • 0x80..=0x9F: cache draw (V2.0)
  • 0xA0..=0xBF: short solid RGB run (len=1..32)
  • 0xC0..=0xCF: literal RGB run (len=1..16)
  • 0xD0..=0xDF: literal RGB run (V2.3)
  • 0xE4..=0xEB: literal RGBA run (len=1..8)
  • 0xED: residual pixel (Paeth-based)
  • 0xF0: extended solid RGB run
  • 0xF1: repeat last pixel run
  • 0xF2: transparent pixel run (V2.2+)
  • 0xF3: LZ back-reference
  • 0xF5: transparent rectangle skip (V2.2+)
  • 0xFF: alpha setter

Bitstream framing is prefix-based and bit-packed.

4) Strict Decoding Rules

Decoding fails on any of:

  • Invalid magic or unsupported version byte
  • Payload underflow
  • Invalid or reserved opcode
  • Violated preconditions
  • CRC32 checksum mismatch (V2.3 only)

5) Encoder Behavior (Current)

The encoder is lossless and uses a cost-aware greedy pipeline:

  1. RGBA literal runs for unstable alpha windows.
  2. Alpha synchronization (0xFF) for RGB-coded paths.
  3. LZ candidate with rolling hash (constrained to fixed-alpha spans).
  4. RGB literal runs with short lookahead chooser.
  5. Solid runs (0xA0..0xBF, 0xF0).
  6. Repeat runs (0xF1).
  7. Fallback RGB literal or residual path.