/* 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), and is back from every * call within 2 ms: what takes longer goes on a job (a Debug pardes says * a call over 16 ms, and `--addon-test` fails on it). 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 * * Conventions: init, ctl and load return PA_OK (0), or nonzero to refuse; * key, mouse and address return nonzero when the event or text was theirs. * The pa_api pointer handed to init is kept by the addon; it is about the * pane of the current call. A kind's state is one thing, stepped by `tick` * however many views show it; what a view sees of it is laid out by `view` * and drawn by `paint`, which writes nothing a step reads. Minors after 3.0 * add fields at the ends of records: a core reads an addon's new ones by * its head's minor, an addon pardes's by api->size. * * addons/fake/fake.c implements every function; it is the template. In * Zig, src/kinds/addon.zig makes the pa_ops from a struct, and * addons/snake/snake.zig is a game in it. */ #ifndef PARDES_ADDON_H #define PARDES_ADDON_H #include #include #include /* memcpy, for pa_copy and PA_POD */ /* Major in the high half: an addon of another major is refused. */ #define PA_ABI_MAJOR 3u #define PA_ABI_MINOR 0u #define PA_ABI ((PA_ABI_MAJOR << 16) | PA_ABI_MINOR) #define PA_OK 0 #define PA_RASTER_MAX (32u << 20) /* a placement's w*h*4 above this is dropped, said once */ #define PA_RECORD_MAX (1u << 20) /* the most a dump's record holds */ /* ---- 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), drawn only * with PA_PAINTED in its flags (pa_put sets it); a zero cell is the pane's * background. */ #define PA_PAINTED 0x01u 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 in one view, which `paint` writes: `rows` rows of * `cols` cells, `stride` cells apart, every one zero (unpainted) when the * call begins. How a frontend shows the placements (glyph art, its * palette) is the core's words' (Petscii, Palette, Ascii), never the * addon's. */ 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 in some view: for the picture ("paused"). * `view`: the id of the view painted (pa_view's), whose layout paint * draws; `glyphs`: it shows pictures as glyph art. */ uint8_t focused, view, glyphs, pad; } 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, packed rows of w*4 bytes), over the `dst` cells, at `at` pixels in * them, or fitted there (no larger than it is) when at.w is 0; one of * more than PA_RASTER_MAX bytes is dropped. The raster is the addon's and must stay as it is until the pane's next paint or * close. `key` names the pixels in this pane: one key, one picture, so a * frontend keeps what it uploaded under it. `from` is 0, or the key of a * picture a frontend may still hold of which rows dirty_y .. dirty_y + * dirty_h of this one alone differ (a frontend that holds it may patch * those rows; any other uploads the whole). */ typedef struct pa_placement { const uint8_t *rgba; uint32_t w, h; pa_rect src; pa_cells dst; pa_rect at; uint64_t key; uint64_t from; uint32_t dirty_y, dirty_h; } pa_placement; /* What `paint` hands back beside the cells: placements (room for `cap`, * at least 64, lowest first); `at` and `span`, where the window is in the * pane's whole (the share above it and the share it shows, 0 to 1), the * rail's thumb, 0 and 0 for none; and `pointer`, the pointer a frontend * shows over the pane (PA_POINTER_*), which a terminal ignores. paint is * called once a frame in each view, never over no cells. */ #define PA_POINTER_DEFAULT 0u #define PA_POINTER_LINK 1u typedef struct pa_paint { pa_placement *placements; uint32_t cap, n; float at, span; uint32_t pointer, pad; } 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 /* `view`: the id of the view it came from (pa_view's), whose layout it is * about (a key's count of lines, a click's cell). */ typedef struct pa_key { uint32_t cp; uint8_t ctrl, alt, shift, view; } 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_WHEEL_LEFT 5 #define PA_WHEEL_RIGHT 6 #define PA_PRESS 0 #define PA_RELEASE 1 #define PA_MOTION 2 #define PA_DRAG 3 /* A pointer event in the cells of view `view`'s window; a motion at col * and row 0xffff when the pointer leaves the window. `amount`: a wheel's * turn in notches, a touchpad's fraction of one (a terminal's are whole). */ typedef struct pa_mouse { uint8_t button, action, ctrl, shift, alt, view; uint16_t col, row; float amount; } pa_mouse; /* ---- what pardes does for an addon ---- */ /* A view of the pane (`view`, `id` 1 and up): its window, a cell's * pixels; the theme's text, paper, selection and link colours (PA_RGB); * the raster a picture is wanted at: `dpi`, at most `max_px` a side, and * never smaller than the pixels it covers when `fill` is set; and * `glyphs`, 1 when the frontend shows placements as glyph art (a terminal * without graphics). */ typedef struct pa_view { uint16_t cols, rows, cell_w, cell_h; uint32_t fg, bg, sel, link; uint16_t dpi, max_px; uint8_t fill, glyphs, id, pad; } pa_view; /* 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); /* The pane's seed: the same pane, the same number, on every machine (a * game's board), and what `pardes --addon-test`'s `seed N` sets. A pane * restored from a dump is a new one: a kind keeps its seed in its record * to reseed alike. */ uint64_t (*seed)(void); /* Memory of pardes's that outlives a call, as realloc's (n 0 frees it), * on any thread at any time: what a pane's arena cannot hold, a cache, a * library's own heap. */ void *(*heap)(void *ptr, size_t n); /* Run `text` as a middle click would. */ void (*exec)(const char *text, uint32_t n); /* The text the pane has selected now, which a yank, a chord's Snarf and * a keyboard Look take; n 0, none. */ void (*select)(const char *text, uint32_t n); /* A job's answer not yet come is dropped (a job running runs on). */ void (*cancel)(uint32_t token); /* `place text` rows, a line each, onto the pane's +Search list: from * `search`, or later (a job_done). */ void (*found)(const char *rows, uint32_t n); /* The core's PA_ABI. */ uint32_t abi, pad; } pa_api; /* What a job allocates from, on its worker (pa_api is not there): as often * as it needs, all of it freed after its job_done. The last it allocates * is the answer, which the job writes and returns the length of. */ 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. An `opens` word opens a pane of the kind * wherever it runs (`open` with its argument as the path, or none); any * other goes to `ctl` of the pane of its kind it is written to, refused * elsewhere. The core checks `arg` before the call; ctl is required when a * word has opens 0. */ typedef struct pa_word { 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[6]; const char *doc; } pa_word; #define PA_WORD(nm, ld, a, op, dc) { .name = (nm), .leader = (ld), .arg = (a), .opens = (op), .doc = (dc) } /* tick's in and out. `now`, monotonic, any origin (--addon-test's starts * at 1 s); `flags`: PA_FOCUSED, the pane has the keyboard in some view, * PA_FRAMED, a frame of it was drawn since the last tick. `next`: the * absolute time of the next step, 0 for none. `prefix`: the start of the * pane's tag after this step, which the core follows with one space, its * art words for a kind of PA_PICTURES, and the pane's path; empty, the * kind's name. */ #define PA_FOCUSED 0x1u #define PA_FRAMED 0x2u typedef struct pa_tick { uint64_t now; uint32_t flags, pad; uint64_t next; char prefix[96]; uint32_t prefix_len, pad2; } pa_tick; /* head.flags: its panes show pictures, and the core says how in their tag * (`petscii:on palette:commodore ascii:off`, Petscii, Palette, Ascii). */ #define PA_PICTURES 0x1u typedef struct pa_head { uint32_t size, abi; /* The pane's kind word in /index, NUL-padded. */ char name[16]; uint32_t version, flags; /* The extensions it opens, space-separated (".png .jpg"), or "". */ const char *exts; const pa_word *words; uint32_t nwords, pad; } pa_head; typedef struct pa_ops { pa_head head; /* Once, at load: PA_OK, or nonzero to refuse 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 t->now: step the state, once however many views show * it, and set t->next and t->prefix (pa_tick). Called when that time * comes and once after open, a taken key or mouse, ctl, job_done, load, * view, and a change of PA_FOCUSED: a kind that set no next is woken by * the next thing that happens to it. Absent: the prefix is the name. */ void (*tick)(void *st, pa_tick *t); /* Required. Pure over the state and win->view's layout: the same paints * the same, and changes nothing. */ void (*paint)(void *st, const pa_window *win, pa_paint *out); /* Every key, Esc first; nonzero if taken. A key not taken goes to the * editor's own navigation (Esc: it leaves). 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 (a miss * may `say` why, an error). A place looked at in a list the kind made * (`text`) comes as ` `. And where the pane is now, as such * a text (jumps, Recent, a Restore): `L` or `L:F`, its first number a * line's and F how far into it, then, after a space, the window's height * in lines if it has one: two places within it are one visit of the * jumps. */ 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`): PA_OK, else * refused with `reply`. Required when a word has opens 0. */ 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: `name value` * lines. */ 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, the kind's own small state (its file is * the pane's path, read again at a Restore): its length, at most n * (PA_RECORD_MAX); 0 is no record (load is not called and the pane * reopens from its path, its `where` and its words' last values), and so * is having no dump. */ uint32_t (*dump)(void *st, uint8_t *buf, uint32_t n); /* On the state open(path, bytes, len) made from the file as it is, with * the writer's head.version: PA_OK, or nonzero to refuse (the pane waits * as a placeholder, its record kept). */ int (*load)(void *st, const uint8_t *buf, uint32_t n, uint32_t version); /* The pane's own search for the core's `/`, which returns at once: its * rows go to api->found, now or from a job_done. Absent: `/` finds * nothing here. */ void (*search)(void *st, const char *pat, uint32_t n); /* A view shows the pane (its facts, or new ones), or stops (cols 0): lay * out for v->id, ask for its rasters. Absent: paint lays out from the * window. */ void (*view)(void *st, const pa_view *v); } pa_ops; /* The records' sizes on a 64-bit target: an addon built against another * copy of this header that disagrees does not compile. */ #if UINTPTR_MAX == 0xffffffffffffffffu _Static_assert(sizeof(pa_cell) == 20, "pa_cell"); _Static_assert(sizeof(pa_window) == 24, "pa_window"); _Static_assert(sizeof(pa_rect) == 16 && sizeof(pa_cells) == 8, "pa_rect"); _Static_assert(sizeof(pa_placement) == 80, "pa_placement"); _Static_assert(sizeof(pa_paint) == 32 && sizeof(pa_view) == 32 && sizeof(pa_tick) == 128, "pa_paint"); _Static_assert(sizeof(pa_key) == 8 && sizeof(pa_mouse) == 16, "pa_key"); _Static_assert(sizeof(pa_api) == 112 && sizeof(pa_out) == 16, "pa_api"); _Static_assert(sizeof(pa_word) == 32 && sizeof(pa_head) == 56, "pa_head"); _Static_assert(sizeof(pa_ops) == 208, "pa_ops"); #endif /* ---- 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, uint16_t attrs) { 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 = attrs; c->flags = PA_PAINTED; n++; } text += len; if (!c) break; } return n; } /* `n` bytes of src[off..len] into buf: the body of a kind whose text is small. */ static inline uint32_t pa_copy(const void *src, uint64_t len, uint64_t off, void *buf, uint32_t n) { if (off >= len) return 0; if (n > len - off) n = (uint32_t)(len - off); memcpy(buf, (const uint8_t *)src + off, n); return n; } /* dump and load as a byte copy of a plain struct `type`, refused across * versions: PA_POD(snake, VERSION) then .dump = snake_dump, .load = snake_load */ #define PA_POD(type, ver) \ static uint32_t type##_dump(void *st, uint8_t *buf, uint32_t n) { \ return n < sizeof(type) ? 0 : (memcpy(buf, st, sizeof(type)), (uint32_t)sizeof(type)); } \ static int type##_load(void *st, const uint8_t *buf, uint32_t n, uint32_t version) { \ return version != (ver) || n != sizeof(type) ? 1 : (memcpy(st, buf, sizeof(type)), PA_OK); } /* An addon's head, its size and ABI filled: * const pa_ops pardes_addon = { .head = PA_ADDON("game", 1, 0, "", words, 1), .paint = paint }; */ #define PA_ADDON(nm, ver, fl, ex, ws, nws) \ { .size = sizeof(pa_head), .abi = PA_ABI, .name = nm, .version = (ver), .flags = (fl), .exts = (ex), .words = (ws), .nwords = (nws) } #endif