diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-06 15:58:05 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-06 17:53:43 -0300 |
| commit | 31c77aa3f259e99a9723e188b77b651e5cd31621 (patch) | |
| tree | 062567bcf58d4b66e26ea2ec8b048a0128793980 /src/kinds/pardes_addon.h | |
| parent | 0706014591cf4af3ee2ed08890675956fb771cc8 (diff) | |
| download | pardes-31c77aa3f259e99a9723e188b77b651e5cd31621.tar.gz pardes-31c77aa3f259e99a9723e188b77b651e5cd31621.zip | |
kinds #34, ABI 3 (§17.8) and the Zig module's final surface (§17.6): tick takes a pa_tick and gives the next step and the tag's prefix, which leaves pa_paint; a kind's view(st, pa_view) is told each view by id, pa_window says which view paint is for and whether it shows glyph art, a key and a click the view they came from (in pa_key's and pa_mouse's padding, what §17 left out), pa_api loses view and gains cancel and found (search returns nothing), the head's flags say PA_PICTURES, PA_RASTER_MAX and PA_RECORD_MAX bound a picture and a record (no ask-again), 2.x is refused; addon.zig wraps every pa_ops function and pa_api call (heap as an Allocator, typed Mouse, Key and View, Color.rgb, an optional prefix(s, writer) after every tick, body_max) and refuses at compile time a word for a pane without ctl and a name over 15 bytes
Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'src/kinds/pardes_addon.h')
| -rw-r--r-- | src/kinds/pardes_addon.h | 185 |
1 files changed, 104 insertions, 81 deletions
diff --git a/src/kinds/pardes_addon.h b/src/kinds/pardes_addon.h index a2b57155..c3bfb354 100644 --- a/src/kinds/pardes_addon.h +++ b/src/kinds/pardes_addon.h @@ -5,7 +5,9 @@ * 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 + * 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. * @@ -16,9 +18,11 @@ * 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. ABI 2.1 adds fields at the ends of pa_api, - * pa_paint and pa_ops: a core reads an addon's new ones by its head's - * minor, an addon pardes's by api->size. + * 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 @@ -32,10 +36,12 @@ #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 2u -#define PA_ABI_MINOR 2u +#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 ---- */ @@ -62,18 +68,21 @@ typedef struct pa_cell { uint8_t flags; } 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. - * How a frontend shows the placements (glyph art, its palette) is the - * core's words' (Petscii, Palette, Ascii), never the addon's. */ +/* 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"). */ - uint8_t focused, pad[3]; + /* 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 */ @@ -81,8 +90,8 @@ typedef struct pa_cells { uint16_t x, y, w, h; } pa_cells; /* cells of the wi /* 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. The raster - * is the addon's and must stay as it is until the pane's next paint or + * 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 + @@ -100,27 +109,18 @@ typedef struct pa_placement { } pa_placement; /* What `paint` hands back beside the cells: placements (room for `cap`, - * 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. 2.1: `at` and - * `span`, where the window is in the pane's whole (the share above it and - * the share it shows, 0 to 1), are the rail's thumb; 0 and 0, none. A kind - * writes them only to a core whose api->size says 2.1. 2.2: `pointer`, the - * pointer a frontend shows over the pane (PA_POINTER_*), which a terminal - * ignores. In paint, not in mouse's answer: what is under a resting pointer - * is known after the motion (a PDF's link, found on a tick), and the field - * takes the record's tail padding, so its size stays. */ + * 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; - char prefix[96]; - uint32_t prefix_len; float at, span; - uint32_t pointer; + uint32_t pointer, pad; } pa_paint; /* ---- input ---- */ @@ -138,9 +138,11 @@ typedef struct pa_paint { #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, pad; + uint8_t ctrl, alt, shift, view; } pa_key; #define PA_LEFT 0 @@ -154,29 +156,28 @@ typedef struct pa_key { #define PA_RELEASE 1 #define PA_MOTION 2 #define PA_DRAG 3 -/* A pointer event in the window's cells; a motion at col and row 0xffff - * when the pointer leaves the window. 2.2: `amount`, a wheel's turn in - * notches, a touchpad's fraction of one (a terminal's are whole; 0 from an - * older core: one; an older kind is told each turn as a notch). */ +/* 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, pad; + uint8_t button, action, ctrl, shift, alt, view; uint16_t col, row; float amount; } pa_mouse; /* ---- what pardes does for an addon ---- */ -/* The pane as its next paint will see it (2.1, api->view): its window, a - * cell's pixels; the theme's text, paper, selection and link colours - * (PA_RGB); and 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. */ +/* 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; - /* 2.2: `glyphs`, 1 when the frontend shows placements as glyph art (a - * terminal without graphics; 0 from an older core). */ - uint8_t fill, glyphs, pad[2]; + uint8_t fill, glyphs, id, pad; } pa_view; /* Valid during any call pardes makes for a pane, and about that pane. */ @@ -200,19 +201,21 @@ typedef struct pa_api { * restored from a dump is a new one: a kind keeps its seed in its record * to reseed alike. */ uint64_t (*seed)(void); - /* 2.1 (api->size >= 96): 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. */ + /* 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); - /* The pane's window and the theme now (pa_view). */ - void (*view)(pa_view *out); /* 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); - /* 2.2 (api->size >= 104): the core's PA_ABI, so a kind reads the 2.2 - * fields it is given (pa_mouse.amount) only from a core that sets them. */ + /* 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; @@ -244,20 +247,36 @@ typedef struct pa_word { } 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; 2.2: a frame of it - * was drawn since the last tick. */ +/* 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; + uint32_t version, flags; /* The extensions it opens, space-separated (".png .jpg"), or "". */ const char *exts; const pa_word *words; - uint32_t nwords; + uint32_t nwords, pad; } pa_head; typedef struct pa_ops { @@ -270,19 +289,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 (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` (2.1: - * or of its pa_view): 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. */ + /* 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 but Esc, which leaves; nonzero if taken. A key not taken goes - * to the editor's own navigation. Absent: no keys. 2.1: Esc too, first; - * not taken, it leaves. */ + /* 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); @@ -308,18 +325,24 @@ typedef struct pa_ops { 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, written in `n` bytes (n at - * least 1 MiB), or a length past n, unwritten, to be called again with that - * many; 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. */ + /* 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) returned, with the writer's - * head.version: PA_OK, or nonzero to refuse (the pane waits as a - * placeholder, its record kept). */ + /* 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); - /* 2.1: the pane's own search for the core's `/`: rows `place text`, a - * line each, into `buf`; their length. Absent: `/` finds nothing here. */ - uint32_t (*search)(void *st, const char *pat, uint32_t n, char *buf, uint32_t cap); + /* 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 @@ -329,11 +352,11 @@ _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) == 128 && sizeof(pa_view) == 32, "pa_paint"); +_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) == 104 && sizeof(pa_out) == 16, "pa_api"); +_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) == 200, "pa_ops"); +_Static_assert(sizeof(pa_ops) == 208, "pa_ops"); #endif /* ---- helpers ---- */ @@ -382,8 +405,8 @@ static inline uint32_t pa_copy(const void *src, uint64_t len, uint64_t off, void 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) \ - { .size = sizeof(pa_head), .abi = PA_ABI, .name = nm, .version = (ver), .exts = (ex), .words = (ws), .nwords = (nws) } + * 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 |
