1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
|
/* 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 <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 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 `<name> <place>`. 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
|