diff options
Diffstat (limited to 'src/kinds')
| -rw-r--r-- | src/kinds/pardes_addon.h | 117 |
1 files changed, 81 insertions, 36 deletions
diff --git a/src/kinds/pardes_addon.h b/src/kinds/pardes_addon.h index c3fbc097..c6aa448b 100644 --- a/src/kinds/pardes_addon.h +++ b/src/kinds/pardes_addon.h @@ -13,18 +13,26 @@ * 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. + * 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. + * + * addons/fake/fake.c implements every function; it is the template, and + * addons/snake/snake.c a game in it. */ #ifndef PARDES_ADDON_H #define PARDES_ADDON_H #include <stddef.h> #include <stdint.h> +#include <string.h> /* memcpy, for pa_copy and PA_POD */ /* Major in the high half: an addon of another major is refused. */ -#define PA_ABI_MAJOR 1u +#define PA_ABI_MAJOR 2u #define PA_ABI_MINOR 0u #define PA_ABI ((PA_ABI_MAJOR << 16) | PA_ABI_MINOR) +#define PA_OK 0 /* ---- the picture ---- */ @@ -52,42 +60,48 @@ typedef struct pa_cell { } pa_cell; /* The pane's body, which `paint` writes: `rows` rows of `cols` cells, - * `stride` cells apart, every one zero (unpainted) when the call begins. */ + * `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. */ - 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; + /* The pane has the keyboard in some view: for the picture ("paused"). */ + uint8_t focused, pad[3]; } 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. */ + * 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. 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, stride; + 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`, - * lowest first) and the start of the pane's tag (empty: the pane's path). */ + * at least 64, lowest first) and the start of the pane's tag, which the + * core follows with one space, its own words for a picture shown + * (`petscii:on palette:commodore ascii:off`, when this frame placed one), + * and the pane's path; empty, the kind's name. paint is called once a + * frame, body and prefix together, never over no cells. */ typedef struct pa_paint { pa_placement *placements; uint32_t cap, n; @@ -165,17 +179,22 @@ typedef struct pa_out { #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). */ +/* 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 { - 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]; + 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 flags: the pane has the keyboard in some view. */ +#define PA_FOCUSED 0x1u typedef struct pa_head { uint32_t size, abi; @@ -190,7 +209,7 @@ typedef struct pa_head { typedef struct pa_ops { pa_head head; - /* Once, at load: nonzero refuses the addon. */ + /* 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 @@ -198,12 +217,17 @@ typedef struct pa_ops { 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); + /* Time has come to now_ns (monotonic, any origin; --addon-test's starts + * at 1 s): step, and return the absolute time of the next step, 0 for + * none. Called when that time comes and once after open, a taken key or + * mouse, ctl, job_done, load, and a change of PA_FOCUSED in `flags`: a + * kind that returned 0 is woken by the next thing that happens to it. + * Absent, the pane repaints when the core repaints. */ + uint64_t (*tick)(void *st, uint64_t now_ns, uint32_t flags); /* 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. */ + /* Every key but Esc, which leaves; nonzero if taken. A key not taken goes + * to the editor's own navigation. 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); @@ -214,18 +238,23 @@ typedef struct pa_ops { * 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. */ + /* 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. */ + /* 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 (its length; at most `n`), and back. With - * none, a Restore reopens the pane from its path and its `where`. */ + /* The pane's record for a dump: at most `n` bytes, n at least 1 MiB; 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) returned, 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); } pa_ops; @@ -235,11 +264,11 @@ typedef struct pa_ops { _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) == 72, "pa_placement"); +_Static_assert(sizeof(pa_placement) == 80, "pa_placement"); _Static_assert(sizeof(pa_paint) == 120, "pa_paint"); _Static_assert(sizeof(pa_key) == 8 && sizeof(pa_mouse) == 10, "pa_key"); _Static_assert(sizeof(pa_api) == 64 && sizeof(pa_out) == 16, "pa_api"); -_Static_assert(sizeof(pa_word) == 40 && sizeof(pa_head) == 56, "pa_head"); +_Static_assert(sizeof(pa_word) == 32 && sizeof(pa_head) == 56, "pa_head"); _Static_assert(sizeof(pa_ops) == 192, "pa_ops"); #endif @@ -251,7 +280,7 @@ static inline pa_cell *pa_at(const pa_window *w, unsigned row, unsigned col) { /* `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) { +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); @@ -262,7 +291,7 @@ static inline unsigned pa_put(const pa_window *w, unsigned row, unsigned col, co c->len = (uint8_t)len; c->fg = fg; c->bg = bg; - c->attrs = 0; + c->attrs = attrs; c->flags = PA_PAINTED; n++; } @@ -272,6 +301,22 @@ static inline unsigned pa_put(const pa_window *w, unsigned row, unsigned col, co 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, "", words, 1), .paint = paint }; */ #define PA_ADDON(nm, ver, ex, ws, nws) \ |
