summaryrefslogtreecommitdiff
path: root/src/kinds/pardes_addon.h
blob: 6241c6c06da9500a69c7ccd95f0d712aa973d41f (plain) (blame)
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
/* 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
 *
 * 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 2u
#define PA_ABI_MINOR 0u
#define PA_ABI ((PA_ABI_MAJOR << 16) | PA_ABI_MINOR)
#define PA_OK 0

/* ---- 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, 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];
} 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. 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) 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;
  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);
  /* 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. */
  uint64_t (*seed)(void);
} 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 flags: the pane has the keyboard in some view. */
#define PA_FOCUSED 0x1u

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: 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 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. 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);
  /* 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`): 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: 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;

/* 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) == 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) == 32 && sizeof(pa_head) == 56, "pa_head");
_Static_assert(sizeof(pa_ops) == 192, "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, "", 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