diff options
| author | Josh Rahm <joshuarahm@gmail.com> | 2026-01-14 00:09:26 -0700 |
|---|---|---|
| committer | Josh Rahm <joshuarahm@gmail.com> | 2026-01-14 00:11:37 -0700 |
| commit | f216280bc0fdc4a6f00187dba1d1ddc22b54097d (patch) | |
| tree | 64637e9df49011b3ec81738b4347ab7a97e88980 /ark/include/world_exports.h | |
| parent | cc6302ee2073d1ea40608abb77ca6019feca4a2a (diff) | |
| download | montis-main.tar.gz montis-main.tar.bz2 montis-main.zip | |
It makes a bit more sense.
Diffstat (limited to 'ark/include/world_exports.h')
| -rw-r--r-- | ark/include/world_exports.h | 117 |
1 files changed, 117 insertions, 0 deletions
diff --git a/ark/include/world_exports.h b/ark/include/world_exports.h new file mode 100644 index 0000000..c0ee74e --- /dev/null +++ b/ark/include/world_exports.h @@ -0,0 +1,117 @@ +#pragma once + +/* + * Single source of truth for the world ABI. + * + * Consumers must define an X-macro like: + * #define X(ret, name, args) ... + * and then invoke: + * ARKWORLD_EXPORTS(X) + * + * Note: this file intentionally does not include headers. Include whatever you + * need (e.g. <stdint.h>, world_types.h, wlroots headers) before expanding. + */ + +#define ARKWORLD_EXPORTS(X) \ + /* \ + * `arkworld_export_metaload` \ + * \ + * Called at most once per process *per `world_name`*. This is the place \ + * for truly global initialization that should survive hot reloads (e.g. \ + * one-time language runtime init, registering global hooks, etc.). \ + * \ + * Notes: \ + * - May be a no-op. \ + * - Must be safe to call before any other world entrypoint. \ + */ \ + X(void, arkworld_export_metaload, (int argc, char **argv)) \ + /* \ + * `arkworld_export_load` \ + * \ + * Called every time the shared object is loaded (cold start and each hot \ + * reload). Use this for per-load initialization that must be re-done after \ + * `dlopen`. \ + */ \ + X(void, arkworld_export_load, (int argc, char **argv)) \ + /* \ + * `arkworld_export_rebirth` \ + * \ + * Called after a hot reload with the previous world's preserved state. \ + * Must return the new live opaque state (`opqst_t`) to be used for future \ + * handler calls. \ + * \ + * Contract: \ + * - Must not fail hard on state incompatibility; fall back to a default. \ + * - `self` is an opaque pointer owned by the runtime; treat it as \ + * read-only. \ + */ \ + X(opqst_t, arkworld_export_rebirth, \ + (void *self, uint8_t *marshalled_state, uint32_t n)) \ + /* \ + * `arkworld_export_enworld` \ + * \ + * Called on first boot when no previous state exists. Must construct and \ + * return an initial opaque state. \ + */ \ + X(opqst_t, arkworld_export_enworld, (void *self)) \ + /* \ + * `arkworld_export_preserve` \ + * \ + * Called before unloading the current world during hot reload. Must \ + * serialize the provided opaque state into a newly allocated byte buffer. \ + * \ + * Ownership: \ + * - Return a heap-allocated buffer (e.g. `malloc`). \ + * - The runtime takes ownership and will `free()` it after \ + * `arkworld_export_rebirth`. \ + */ \ + X(uint8_t *, arkworld_export_preserve, (opqst_t st, uint32_t * szout)) \ + /* \ + * `arkworld_export_release` \ + * \ + * Called immediately before the shared object is unloaded. Use this to \ + * release resources owned by the opaque state (and any per-load resources \ + * created in `arkworld_export_load`). \ + */ \ + X(void, arkworld_export_release, (opqst_t st)) \ + /* \ + * `arkworld_export_handle_keybinding` \ + * \ + * Called for keyboard events. Returns the updated opaque state. Set \ + * `*out_handled` to non-zero if the event is consumed. \ + */ \ + X(opqst_t, arkworld_export_handle_keybinding, \ + (struct wlr_keyboard * keyboard, struct wlr_keyboard_key_event * event, \ + uint32_t modifiers, uint32_t keysym, uint32_t codepoint, \ + int *out_handled, opqst_t state)) \ + /* \ + * `arkworld_export_handle_button` \ + * \ + * Called for pointer button events (mouse/trackpad clicks). Returns the \ + * updated opaque state. \ + */ \ + X(opqst_t, arkworld_export_handle_button, \ + (struct wlr_pointer_button_event * event, uint32_t modifiers, \ + opqst_t state)) \ + /* \ + * `arkworld_export_handle_motion` \ + * \ + * Called for pointer motion. Returns the updated opaque state. \ + * \ + * Parameters: \ + * - `event` is an opaque pointer to the underlying wlroots event struct \ + * (type depends on `is_absolute`). \ + * - `lx`/`ly` are layout coordinates in compositor space. \ + */ \ + X(opqst_t, arkworld_export_handle_motion, \ + (void *event, uint32_t modifiers, uint32_t is_absolute, double lx, \ + double ly, opqst_t state)) \ + /* \ + * `arkworld_export_handle_surface` \ + * \ + * Called when a surface is mapped/unmapped/destroyed. `surface` is an \ + * opaque pointer to the runtime surface representation. Returns the updated \ + * opaque state. \ + */ \ + X(opqst_t, arkworld_export_handle_surface, \ + (void *surface, surface_event_t event, opqst_t state)) |