#pragma once /* * Single source of truth for the soul ABI. * * Consumers must define an X-macro like: * #define X(ret, name, args) ... * and then invoke: * ARKSOUL_EXPORTS(X) * * Note: this file intentionally does not include headers. Include whatever you * need (e.g. , soul_types.h, wlroots headers) before expanding. */ #define ARKSOUL_EXPORTS(X) \ /* \ * `arksoul_export_metaload` \ * \ * Called at most once per process *per `soul_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 soul entrypoint. \ */ \ X(void, arksoul_export_metaload, (int argc, char **argv)) \ /* \ * `arksoul_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, arksoul_export_load, (int argc, char **argv)) \ /* \ * `arksoul_export_rebirth` \ * \ * Called after a hot reload with the previous soul'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, arksoul_export_rebirth, \ (void *self, uint8_t *marshalled_state, uint32_t n)) \ /* \ * `arksoul_export_ensoul` \ * \ * Called on first boot when no previous state exists. Must construct and \ * return an initial opaque state. \ */ \ X(opqst_t, arksoul_export_ensoul, (void *self)) \ /* \ * `arksoul_export_preserve` \ * \ * Called before unloading the current soul 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 \ * `arksoul_export_rebirth`. \ */ \ X(uint8_t *, arksoul_export_preserve, (opqst_t st, uint32_t *szout)) \ /* \ * `arksoul_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 `arksoul_export_load`). \ */ \ X(void, arksoul_export_release, (opqst_t st)) \ /* \ * `arksoul_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, arksoul_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)) \ /* \ * `arksoul_export_handle_button` \ * \ * Called for pointer button events (mouse/trackpad clicks). Returns the \ * updated opaque state. \ */ \ X(opqst_t, arksoul_export_handle_button, \ (struct wlr_pointer_button_event * event, uint32_t modifiers, \ opqst_t state)) \ /* \ * `arksoul_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, arksoul_export_handle_motion, \ (void *event, uint32_t modifiers, uint32_t is_absolute, double lx, \ double ly, opqst_t state)) \ /* \ * `arksoul_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, arksoul_export_handle_surface, \ (void *surface, surface_event_t event, opqst_t state))