pdf-odin-llm/docs/render-layer-contract.md

## Frozen types for the rendering layer

These are shared across many files, so they are fixed here rather than invented
by whoever writes the first one. Add fields if you need them; do not rename or
restructure without saying so.

### Rasteriser (`raster.odin`)

Rasterising is separated from compositing by a span callback, so the same code
fills a bitmap, builds a clip mask, and feeds a display list.

```odin
// Coverage for one horizontal run on scanline y, starting at pixel x0.
// Values are 0..255. The slice is only valid for the duration of the call.
Span_Proc :: #type proc(user: rawptr, y: int, x0: int, coverage: []u8)

Raster_Clip :: struct { x0, y0, x1, y1: int }   // device pixels, half-open

raster_fill :: proc(fp:       ^Flat_Path,
                    even_odd: bool,
                    clip:     Raster_Clip,
                    span:     Span_Proc,
                    user:     rawptr,
                    allocator := context.allocator) -> Error
```

Requirements: exact analytic coverage horizontally; at least 15 sub-scanlines
vertically (or an equivalent cell/area accumulator). Both fill rules. Never
allocate per scanline. Bounded by `clip` — a path 10^9 units tall must cost the
same as one that fills the clip. Degenerate input (no points, one point, all
points collinear, NaN already filtered by `path.odin`) must produce no spans
rather than misbehaving.

### Stroking (`stroke.odin`)

```odin
// Converts a stroke into a fill. Output is a Flat_Path in DEVICE space,
// already flattened, to be filled with the nonzero rule.
stroke_flatten :: proc(out:   ^Flat_Path,
                       path:  ^Path,
                       state: ^Stroke_State,
                       ctm:   Matrix,
                       flatness := FLATNESS) -> Error
```

A zero or sub-pixel line width must still draw a hairline exactly one pixel
wide — that is what `0 w` means (ISO 32000-2, 8.4.3.2) and thin table rules are
everywhere. Dashes are applied along the flattened path in user space, then
transformed. Caps apply to the ends of each dash. A degenerate subpath (a single
point) draws a dot under round or square caps and nothing under butt caps.

### Colour (`colorspace.odin`)

```odin
Colorspace_Kind :: enum {
    Device_Gray, Device_RGB, Device_CMYK,
    Cal_Gray, Cal_RGB, Lab, ICC_Based,
    Indexed, Separation, Device_N, Pattern,
}

Colorspace :: struct {
    kind: Colorspace_Kind,
    n:    int,              // components a colour value in this space has
    name: string,

    base:   ^Colorspace,    // Indexed
    lookup: []byte,
    hival:  int,

    alt:            ^Colorspace,   // Separation / DeviceN / ICCBased
    tint:           ^Function,
    colorant_names: []string,
    is_none:        bool,          // /None paints nothing at all
    is_all:         bool,

    white_point: [3]f64,           // CalGray / CalRGB / Lab
    black_point: [3]f64,
    gamma:       [3]f64,
    mtx:         [9]f64,
    range:       [4]f64,

    under: ^Colorspace,            // Pattern's underlying space
}

colorspace_load :: proc(doc: ^Document, obj: Object, res: ^Dict) -> (^Colorspace, Error)
colorspace_to_rgb :: proc(cs: ^Colorspace, c: Color) -> [3]f64
colorspace_default_color  :: proc(cs: ^Colorspace) -> Color
colorspace_default_decode :: proc(cs: ^Colorspace, bpc: int, allocator := context.allocator) -> []f64
colorspace_device_gray :: proc(doc: ^Document) -> ^Colorspace   // cached singletons
colorspace_device_rgb  :: proc(doc: ^Document) -> ^Colorspace
colorspace_device_cmyk :: proc(doc: ^Document) -> ^Colorspace
```

ICCBased is rendered through its `/Alternate`, or through the device space
implied by `/N` when there is none. That is not colour management and is not
pretending to be; it is what every non-colour-managed viewer does. Loaded spaces
are cached on the Document keyed by the object they came from, because a page
that names the same space in 400 XObjects must not build it 400 times.

### Functions (`function.odin`)

```odin
// `kind` is an enum whose values ARE the format's type numbers, so a switch on
// it is exhaustive and `FunctionType 1` cannot be smuggled through as an int.
Function_Kind :: enum u8 { Sampled = 0, Exponential = 2, Stitching = 3, PostScript = 4 }

Function :: struct {
    kind:   Function_Kind,
    domain: []f64,
    range:  []f64,      // required for 0 and 4
    n_in, n_out: int,
    ...
}
function_load :: proc(doc: ^Document, obj: Object) -> (^Function, Error)
function_eval :: proc(fn: ^Function, in_: []f64, out: []f64)
```

Type 4 is a real PostScript calculator: implement the whole operator set with a
bounded operand stack and a bounded execution step count. Inputs are clamped to
`/Domain` and outputs to `/Range` before returning — the format requires it and
a shading with an out-of-range tint otherwise paints garbage.

### Images (`image.odin`)

```odin
Image :: struct {
    width, height: int,
    bpc:           int,
    cs:            ^Colorspace,
    is_mask:       bool,      // /ImageMask: a 1-bit stencil, painted in fill colour
    interpolate:   bool,
    decode:        []f64,
    smask:         ^Image,    // /SMask, alpha
    mask:          ^Image,    // /Mask as a stencil
    color_key:     []int,     // /Mask as a colour-key range
    // Decoded on demand, cached: straight-alpha RGBA8 unless is_mask.
    rgba:          Bitmap,
    decoded:       bool,
}

image_load    :: proc(doc: ^Document, stm: ^Stream, res: ^Dict) -> (^Image, Error)
image_decode  :: proc(doc: ^Document, img: ^Image) -> (^Bitmap, Error)  // cached on img
image_load_inline :: proc(doc: ^Document, d: ^Dict, data: []byte, res: ^Dict) -> (^Image, Error)
```

Decoded images are cached on the Document keyed by their stream, and the cache
has a byte budget — a 300-page catalogue must not hold every photograph at once.

### Fonts (`font.odin` and friends)

Each font-program reader is self-contained and knows nothing about PDF:

```odin
// font_cff.odin
cff_parse        :: proc(data: []byte, allocator := context.allocator) -> (^Cff_Font, Error)
cff_glyph_count  :: proc(f: ^Cff_Font) -> int
cff_glyph_path   :: proc(f: ^Cff_Font, gid: u16, out: ^Path) -> Error   // glyph space
cff_glyph_advance:: proc(f: ^Cff_Font, gid: u16) -> f64
cff_gid_for_name :: proc(f: ^Cff_Font, name: string) -> (u16, bool)
cff_gid_for_cid  :: proc(f: ^Cff_Font, cid: u16) -> (u16, bool)
cff_font_matrix  :: proc(f: ^Cff_Font) -> Matrix

// font_truetype.odin -- same shape, plus cmap lookup
tt_parse, tt_glyph_count, tt_glyph_path, tt_glyph_advance,
tt_gid_for_unicode, tt_gid_for_mac_code, tt_gid_for_name, tt_units_per_em

// font_type1.odin
t1_parse, t1_glyph_count, t1_glyph_path, t1_glyph_advance, t1_gid_for_name,
t1_builtin_encoding
```

`font.odin` ties them to the PDF font dictionary:

```odin
Font_Code :: struct {
    code:     u32,   // raw character code from the string
    cid:      u32,
    gid:      u32,
    width:    f64,   // glyph space (1/1000 text space for everything but Type3)
    unicode:  rune,  // -1 if unknown
    nbytes:   int,   // bytes of the string this code consumed
    is_space: bool,  // single-byte code 32 -- word spacing applies
}

font_load       :: proc(doc: ^Document, d: ^Dict) -> (^Font, Error)   // cached on doc
font_decode     :: proc(f: ^Font, s: []byte, out: ^[dynamic]Font_Code)
font_glyph_path :: proc(f: ^Font, gid: u32, out: ^Path) -> Error
font_matrix     :: proc(f: ^Font) -> Matrix
```

A font that fails to load must still produce a Font with widths, so text lays
out and extracts correctly even when nothing can be drawn. Missing glyphs draw
nothing; they never abort a page.

### Public API (`page.odin`)

```odin
Render_Options :: struct {
    ctm:            Matrix,     // applied on top of the page flip and /Rotate
    background:     [4]u8,      // default opaque white
    alpha:          bool,       // default false: an opaque RGB(A) page
    no_annotations: bool,
    allocator:      mem.Allocator,
}

render_page  :: proc(page: ^Page, opts := Render_Options{}) -> (Bitmap, Error)
run_page     :: proc(page: ^Page, dev: ^Device, ctm: Matrix) -> Error
extract_text :: proc(page: ^Page, allocator := context.allocator) -> (string, Error)
```