diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-06 00:02:06 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-06 01:21:34 -0300 |
| commit | 423440f25b4b23b56162008bba35218d438767fe (patch) | |
| tree | a7b06a88c7a55308e7e906ff49fa264a1fd147cf /src/kinds | |
| parent | 94ca47f225632fefc8f688c0c0822d25d6a5db1e (diff) | |
| download | pardes-423440f25b4b23b56162008bba35218d438767fe.tar.gz pardes-423440f25b4b23b56162008bba35218d438767fe.zip | |
kinds #2, a pane of a kind is one slot and image is a kind compiled in: src/kinds/pardes_addon.h is the kinds' C ABI (the cell, the window a kind paints, placements and the tag prefix it hands back, keys, the mouse, pa_api of six functions over the pane's arena, words, the head and pa_ops of paint and sixteen optional functions), translated once by the build into the core's records, never mirrored; src/Kind.zig is the core's side: the kinds this process has (a registry with the checks a load makes: the head's size and abi major, a paint, a name, words, leaders and extensions none else has), a pane's Slot (the kind's state and arena, its path, the art bytes Petscii, Palette and Ascii set, its tick deadline and jobs) and the addon arm at the sites: Look and the initial file by extension, draw (cells into the grid, placements keyed by serial and the kind's key), the tag prefix from a paint over no cells, nextWake and the step (ticks, jobs' answers landing on the loop), close, Recent, paneDir, /index's kind word; a dump writes a slot by hand (kind name and version, path, where, art, the kind's own record) and loads it through the kind's open and load, or as a placeholder that keeps the record when the kind is not here; image.zig's pane is now a static pa_ops (open refuses what it cannot read, the decode a job whose answer lands at a step instead of a thread polled by draw, one placement fitted by the frontend, its record the file's bytes), Pane.image is Pane.addon, and the three art words act on the slot; no golden changes (images.snap and tagbottomimage.snap pass, the tag prefix and the placement key are the same bytes); tests: the image dump test, the Petscii/Palette/Ascii ctl tests, the image tag-prefix test and fs_namespace's decode test rewritten on the slot (the decode now lands at the step after the open), plus a registry test; gates: core-test 960/960 on both, unit-test 1487/1488 tui and 1531/1532 gui, behaviour-test 244/244, pane-test 171/172, snap all ok, process-test 0 of 37 failed on both
Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'src/kinds')
| -rw-r--r-- | src/kinds/pardes_addon.h | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/src/kinds/pardes_addon.h b/src/kinds/pardes_addon.h new file mode 100644 index 00000000..8a95d6d7 --- /dev/null +++ b/src/kinds/pardes_addon.h @@ -0,0 +1,261 @@ +/* pardes_addon.h: an addon, a shared library that brings pardes one + * kind of pane (a picture, a game, a plot). + * + * An addon exports one symbol, `pardes_addon`, a `pa_ops` whose `head` + * names its kind. pardes calls it on its own thread, one call at a time; + * it keeps no pointer pardes hands it past the call (but its `pa_api`), + * starts no threads (it has jobs), and reads no file, clock or + * environment (it is handed bytes and the time). Every function but + * `paint` is optional: leave it NULL and pardes does the default the + * comment beside it says. + * + * cc -shared -fPIC -o game.so game.c + * echo 'Addon load ./game.so' > $PARDES_MOUNT/ctl + * pardes --addon-test ./game.so game.script a test, as a script + * + * addons/fake/fake.c implements every function; it is the template. + */ +#ifndef PARDES_ADDON_H +#define PARDES_ADDON_H + +#include <stddef.h> +#include <stdint.h> + +/* Major in the high half: an addon of another major is refused. */ +#define PA_ABI_MAJOR 1u +#define PA_ABI_MINOR 0u +#define PA_ABI ((PA_ABI_MAJOR << 16) | PA_ABI_MINOR) + +/* ---- the picture ---- */ + +/* A cell's colour: the theme's own, one of its 256, or RGB. */ +#define PA_DEFAULT 0x01000000u +#define PA_INDEX(n) (0x02000000u | (uint8_t)(n)) +#define PA_RGB(r, g, b) (((uint32_t)(uint8_t)(r) << 16) | ((uint32_t)(uint8_t)(g) << 8) | (uint32_t)(uint8_t)(b)) + +#define PA_BOLD 0x01u +#define PA_DIM 0x02u +#define PA_ITALIC 0x04u +#define PA_REVERSE 0x10u +#define PA_UNDERLINE 0x100u + +/* A cell: one character, `len` bytes of UTF-8 (at most 7). */ +#define PA_UNPAINTED 0x01u /* flags: the pane's background, nothing drawn */ +typedef struct pa_cell { + uint8_t text[8]; + uint32_t fg, bg; + uint16_t attrs; + uint8_t len; + uint8_t flags; +} pa_cell; + +/* The pane's body, which `paint` writes: `rows` rows of `cols` cells, + * `stride` cells apart, every one PA_UNPAINTED when the call begins. */ +typedef struct pa_window { + pa_cell *cells; + uint32_t stride; + uint16_t rows, cols; + /* A cell's size in pixels, as the frontend draws it. */ + uint16_t cell_w, cell_h; + /* The pane has the keyboard. */ + uint8_t focused; + /* How the frontend shows this pane's placements, which the core words + * Petscii, Palette and Ascii set: as glyph art (Petscii on, or a frontend + * with no pixels), in the commodore (0) or the terminal's (1) palette, + * with letters among the glyphs. An addon may say so in its prefix. */ + uint8_t glyphs, palette, ascii; +} pa_window; + +typedef struct pa_rect { uint32_t x, y, w, h; } pa_rect; /* pixels */ +typedef struct pa_cells { uint16_t x, y, w, h; } pa_cells; /* cells of the window */ + +/* A picture over the cells: the `src` part of an RGBA raster (straight + * alpha, `stride` bytes a row), over the `dst` cells; at `at` pixels in + * them, or fitted there (no larger than it is) when `at.w` is 0. The + * raster is the addon's and must stay as it is until the pane's next paint + * or close. `key` is the pixels' identity in the pane: one key, one + * picture, so a frontend keeps what it uploaded under it. */ +typedef struct pa_placement { + const uint8_t *rgba; + uint32_t w, h, stride; + pa_rect src; + pa_cells dst; + pa_rect at; + uint64_t key; +} pa_placement; + +/* What `paint` hands back beside the cells: placements (room for `cap`, + * lowest first) and the start of the pane's tag (empty: the pane's path). */ +typedef struct pa_paint { + pa_placement *placements; + uint32_t cap, n; + char prefix[96]; + uint32_t prefix_len; +} pa_paint; + +/* ---- input ---- */ + +/* A key: a codepoint, or one of these. */ +#define PA_KEY_ENTER 0x0Du +#define PA_KEY_TAB 0x09u +#define PA_KEY_BACKSPACE 0x7Fu +#define PA_KEY_UP 0xF0001u +#define PA_KEY_DOWN 0xF0002u +#define PA_KEY_LEFT 0xF0003u +#define PA_KEY_RIGHT 0xF0004u +#define PA_KEY_HOME 0xF0005u +#define PA_KEY_END 0xF0006u +#define PA_KEY_PAGE_UP 0xF0007u +#define PA_KEY_PAGE_DOWN 0xF0008u +#define PA_KEY_DELETE 0xF0009u +typedef struct pa_key { + uint32_t cp; + uint8_t ctrl, alt, shift, pad; +} pa_key; + +#define PA_LEFT 0 +#define PA_MIDDLE 1 +#define PA_RIGHT 2 +#define PA_WHEEL_UP 3 +#define PA_WHEEL_DOWN 4 +#define PA_PRESS 0 +#define PA_RELEASE 1 +#define PA_MOTION 2 +#define PA_DRAG 3 +/* A pointer event in the window's cells. */ +typedef struct pa_mouse { + uint8_t button, action, ctrl, shift, alt, pad; + uint16_t col, row; +} pa_mouse; + +/* ---- what pardes does for an addon ---- */ + +/* Valid during any call pardes makes for a pane, and about that pane. */ +typedef struct pa_api { + uint32_t size; + /* Zeroed memory from the pane's arena, which pardes frees at its close; + * NULL when the arena is full. */ + void *(*alloc)(size_t n); + void (*free)(void *ptr, size_t n); + /* `job_run` over a copy of `in` on a worker; its answer comes to + * `job_done` with the token returned here (0: refused). */ + uint32_t (*job)(const void *in, uint32_t n); + /* Look at `text` as a click would: a URL, `file:12`, a word. */ + void (*look)(const char *text, uint32_t n); + /* A message on the pane, or an error (`err` 1: also refuses an `open`). */ + void (*say)(const char *text, uint32_t n, int err); + /* A new text pane named `name` holding `bytes`; its serial, 0 if none. */ + uint32_t (*text)(const char *name, uint32_t name_len, const char *bytes, uint32_t n); +} pa_api; + +/* A job's answer buffer: `alloc` it once, write it, return its length. */ +typedef struct pa_out { + void *(*alloc)(struct pa_out *out, size_t n); + void *ctx; +} pa_out; + +/* ---- the addon ---- */ + +#define PA_ARG_NONE 0 +#define PA_ARG_OPTIONAL 1 +#define PA_ARG_REQUIRED 2 + +/* A word the addon brings. Written to a pane of its kind, it goes to `ctl`; + * one that `opens` it, run anywhere else, opens a pane of the kind + * (`open` with its argument as the path, or none). */ +typedef struct pa_word { + uint32_t size; + const char *name; + /* The keys after the leader (Space) that run it, "ng" for SPC n g, or NULL. */ + const char *leader; + uint8_t arg, opens, pad[2]; + const char *doc; +} pa_word; + +typedef struct pa_head { + uint32_t size, abi; + /* The pane's kind word in /index, NUL-padded. */ + char name[16]; + uint32_t version; + /* The extensions it opens, space-separated (".png .jpg"), or "". */ + const char *exts; + const pa_word *words; + uint32_t nwords; +} pa_head; + +typedef struct pa_ops { + pa_head head; + /* Once, at load: nonzero refuses the addon. */ + int (*init)(const pa_api *api); + /* A new pane (path and bytes NULL for one a word opened): its state, + * which every call below is handed. NULL with nothing said is a pane + * with no state; `say` an error to refuse it. */ + void *(*open)(const char *path, const uint8_t *bytes, uint64_t len); + /* The pane closes; its arena is freed after. */ + void (*close)(void *st); + /* Time has come to `now_ns`: step, and say when next (0: never). Absent, + * the pane repaints when the core repaints. */ + uint64_t (*tick)(void *st, uint64_t now_ns); + /* Required. Pure: the same state paints the same, and changes nothing. */ + void (*paint)(void *st, const pa_window *win, pa_paint *out); + /* Every key but Esc, which leaves; nonzero if taken. Absent: no keys. */ + int (*key)(void *st, const pa_key *k); + /* Nonzero if taken. Absent: a click focuses the pane. */ + int (*mouse)(void *st, const pa_mouse *m); + /* The pane's body as text (9P `body`). Absent: empty. */ + uint64_t (*body_len)(void *st); + uint32_t (*body)(void *st, uint64_t off, char *buf, uint32_t n); + /* Go to `text` (`:12`, `12:0.33`); nonzero if it is a place here. And + * where the pane is now, as such a text (jumps, Recent, a Restore). */ + int (*address)(void *st, const char *text, uint32_t n); + uint32_t (*where)(void *st, char *buf, uint32_t n); + /* One of the addon's words, as written (`Fit width`): 0 taken, else + * refused with `reply`. Required with words. */ + int (*ctl)(void *st, const char *line, uint32_t n, char *reply, uint32_t cap); + /* What the pane's ctl file reads after the core's fields. */ + uint32_t (*ctl_read)(void *st, char *buf, uint32_t n); + /* On a worker thread, pure over `in`: the answer's length. */ + uint32_t (*job_run)(const uint8_t *in, uint32_t n, pa_out *out); + /* Back on pardes's thread; `out` is gone after the call. */ + void (*job_done)(void *st, uint32_t token, const uint8_t *out, uint32_t n); + /* The pane's record for a dump (its length; at most `n`), and back. With + * none, a Restore reopens the pane from its path and its `where`. */ + uint32_t (*dump)(void *st, uint8_t *buf, uint32_t n); + int (*load)(void *st, const uint8_t *buf, uint32_t n, uint32_t version); +} pa_ops; + +/* ---- helpers ---- */ + +static inline pa_cell *pa_at(const pa_window *w, unsigned row, unsigned col) { + return row < w->rows && col < w->cols ? &w->cells[row * w->stride + col] : 0; +} + +/* `text` (UTF-8) from (row, col) on, a character a cell, cut at the edge; + * the cells written. */ +static inline unsigned pa_put(const pa_window *w, unsigned row, unsigned col, const char *text, uint32_t fg, uint32_t bg) { + unsigned n = 0; + while (*text) { + pa_cell *c = pa_at(w, row, col + n); + unsigned len = 1; + while (len < 7 && (text[len] & 0xC0) == 0x80) len++; + if (c) { + for (unsigned i = 0; i < 8; i++) c->text[i] = i < len ? (uint8_t)text[i] : 0; + c->len = (uint8_t)len; + c->fg = fg; + c->bg = bg; + c->attrs = 0; + c->flags = 0; + n++; + } + text += len; + if (!c) break; + } + return n; +} + +/* An addon's head, its size and ABI filled: + * const pa_ops pardes_addon = { .head = PA_ADDON("game", 1, "", words, 1), .paint = paint }; */ +#define PA_ADDON(nm, ver, ex, ws, nws) \ + { .size = sizeof(pa_head), .abi = PA_ABI, .name = nm, .version = (ver), .exts = (ex), .words = (ws), .nwords = (nws) } + +#endif |
