imaging API

pub struct Pixel { const r: integer limit(0, 255), const g: integer limit(0, 255), const b: integer limit(0, 255), const a: integer limit(0, 255) = 255 }

Data per pixel of a PNG image. Fields r, g, b hold red, green and blue intensity and a holds opacity, each 0–255. The channels are const, so a pixel is REPLACED (img.data[i] = Pixel{…}), never edited in place, and limit(0, 255) is a range rather than a clamp — a value outside it stores 0.

**a defaults to 255, and the default is load-bearing.** An omitted field takes its type's zero, and zero alpha is INVISIBLE — so without the declared default every Pixel{r, g, b} ever written would silently become fully transparent (loft#914's omitted-field-zero in its purest form). With it, code that predates alpha keeps meaning what it meant: opaque.

pub fn value(self: Pixel) -> integer

Returns the pixel colour as a packed 24-bit integer (0xRRGGBB). Use for fast colour comparison or storage. Alpha is NOT in it — this is the pre-alpha contract and stays 24-bit, so a comparison written against it keeps answering what it answered. For opacity read p.a, or rgba() for the packed 32-bit form.

pub fn rgba(self: Pixel) -> integer

Returns the pixel as a packed 32-bit integer (0xAARRGGBB) — the byte order graphics::Canvas uses, so a decoded image can be handed to a canvas without a per-channel loop at the call site.

pub fn opaque(self: Pixel, cutoff: integer = 128) -> boolean

Is this texel opaque enough to count as covered?

A collision proxy, a trim box and a colour key all want the same question, and they want it with a THRESHOLD rather than a == 255: antialiased art has a fringe of partly-transparent texels that belong to the silhouette. Default 128 — half opacity — which is the midpoint of that fringe.

pub struct Image { name: text, width: integer, height: integer, data: vector<Pixel> }

Database structure with image data. The actual data is in height rows of width length: data is one FLAT vector in row-major order, so the pixel at (x, y) is data[y * width + x], and len(data) == width * height always holds on an image png() handed back.

pub fn save_png(self: const Image, path: text) -> boolean

Write this image to a PNG file. Returns true on success.

pub fn png(self: File) -> Image?

Decodes a PNG file and returns an Image. Returns null when there is nothing to decode — the path does not exist, names a directory, or holds bytes this decoder cannot read. So the answer is either a complete image (len(data) == width * height) or null; there is no half-filled Image to guard against. Any PNG colour type loads: greyscale and palette files are expanded to RGBA, and **alpha is carried** — a file with no alpha channel arrives fully opaque (a == 255), never transparent. Use to load sprite sheets or textures.