diff options
| author | user <user@clank> | 2026-08-14 22:06:57 +0200 |
|---|---|---|
| committer | user <user@clank> | 2026-08-14 22:06:57 +0200 |
| commit | 2ae507a8a331799875e07c327730a1a4ca0363f4 (patch) | |
| tree | 685b167c2a87f5e9f877cca31d31f43fd4e71734 /src | |
| parent | sl0ppty: expand ~ in a path that a config file wrote (diff) | |
| download | slosh-2ae507a8a331799875e07c327730a1a4ca0363f4.tar.gz slosh-2ae507a8a331799875e07c327730a1a4ca0363f4.tar.xz slosh-2ae507a8a331799875e07c327730a1a4ca0363f4.zip | |
sl0ppty: shaders can be loaded from shared libraries
Adding an effect meant editing shader.c and rebuilding, which is fine for us
and useless to anyone else. Now any `*.so` in the shader directory that
exports a plugin table is loaded at startup, and what it declares is named in
the config exactly like a built-in -- same syntax, same three parameters,
same pass. Default location is a `shaders` directory beside the config file,
so dropping the .so next to config.kdl is the whole installation.
The interesting part is what a plugin can see, which is one header.
shader_abi.h holds cell_t, color_t, shade_ctx_t, shader_t and nothing else:
no libghostty-vt, no pty, no layout, no session. A shader is therefore
unable to reach anything but the cell it was handed, not by rule but because
nothing else is declared where it can find it. cell_t and color_t moved
there from sl0ppty.h for the same reason -- that is the one place they are a
contract with code compiled outside this tree rather than an internal type.
Loading is deliberately narrow:
- refused unless the library reports our ABI version *and* matching struct
sizes. The version says which contract; the sizes catch someone editing
their copy of the header, which a version number alone calls fine and a
running session calls garbled colours;
- refused if it redefines an existing name, because a config naming `dim`
means the `dim` it was written against;
- all-or-nothing per file, and per file: a bad library is a line on stderr
and everything else still loads (D9 fail-open);
- nothing is ever unloaded. A shade_fn may be sitting in a live config or on
a pane, so dlclose() is a jump into an unmapped page. A reload picks up
newly *added* plugins; replacing one needs a new session.
This is the single exception to D9's "a plugin is a subprocess", and it is
argued in D15 rather than drifted into: a shader is called per cell, per
pass, per frame, which no subprocess can be in the path of, and the measured
alternative -- interpreting bytecode per cell -- is 56ns against 8ns for the
compiled function. On trust, `shell` and a layout's `command=` already let a
file in the config directory run anything as you, so a .so beside them is
not a new boundary. The docs say so plainly rather than implying a sandbox.
contrib/shader-plugin is a working skeleton: Makefile, two commented effects
(one positional, one animated), and the three rules a shader has to keep. It
is built and loaded by the test suite, so a broken example is a failing test
rather than someone else's afternoon.
Diffstat (limited to 'src')
| -rw-r--r-- | src/config.c | 30 | ||||
| -rw-r--r-- | src/config.h | 6 | ||||
| -rw-r--r-- | src/shader.c | 176 | ||||
| -rw-r--r-- | src/shader.h | 64 | ||||
| -rw-r--r-- | src/shader_abi.h | 138 | ||||
| -rw-r--r-- | src/sl0ppty.h | 30 |
6 files changed, 365 insertions, 79 deletions
diff --git a/src/config.c b/src/config.c index 6b10d36..2b80a18 100644 --- a/src/config.c +++ b/src/config.c @@ -322,6 +322,7 @@ void config_defaults(config_t *c) { void config_free(config_t *c) { free(c->binds); free(c->shell); + free(c->shader_dir); memset(c, 0, sizeof *c); } @@ -433,6 +434,35 @@ bool config_load(config_t *c, const char *path, char *err, size_t errcap) { c->shell = strdup(sh); } + /* Shader plugins, before any shader is named below: a `shaders` block may + * use what one of these adds, and a name is looked up as it is parsed. The + * default is a directory beside this file, so dropping a `.so` next to the + * config is the whole installation procedure. */ + const char *sdir = kdl_arg(kdl_child(root, "shader_dir"), 0, NULL); + if (sdir) { + free(c->shader_dir); + c->shader_dir = strdup(sdir); + } + { + char dir[1024]; + if (c->shader_dir) { + char buf[1024]; + snprintf(dir, sizeof dir, "%s", + path_expand(c->shader_dir, buf, sizeof buf)); + } else { + snprintf(dir, sizeof dir, "%s", path); + char *slash = strrchr(dir, '/'); + if (slash) slash[1] = 0; + else dir[0] = 0; + snprintf(dir + strlen(dir), sizeof dir - strlen(dir), "shaders"); + } + char lerr[256] = {0}; + shader_load_dir(dir, lerr, sizeof lerr); + /* A plugin that will not load is worth a line, and worth nothing more: + * the config it came with still works, minus that effect (D9). */ + if (lerr[0] && err && !err[0]) snprintf(err, errcap, "%s", lerr); + } + /* One node per pass, in the order written, because a chain is a sequence. * Shared by `shaders { }` and by every state, so a state's chain is exactly * as expressive as the global one and there is one parser to be wrong. */ diff --git a/src/config.h b/src/config.h index a854fe8..f8b799c 100644 --- a/src/config.h +++ b/src/config.h @@ -228,6 +228,12 @@ typedef struct { /* what a new pane runs; NULL means $SHELL */ char *shell; + + /* Where to look for shader plugins (`*.so`). NULL means the default: a + * `shaders` directory beside the config file. Read before the `shaders` and + * `states` blocks are parsed, because what they are allowed to name depends + * on what has been loaded. */ + char *shader_dir; } config_t; /* Defaults, then <config dir>/config.kdl on top. Never fails: on a bad file diff --git a/src/shader.c b/src/shader.c index 6a02dbc..1d36891 100644 --- a/src/shader.c +++ b/src/shader.c @@ -1,6 +1,12 @@ -/* The shader pass and the built-in shaders. See shader.h for the model. */ +/* The shader pass, the built-in shaders, and loading more of them from disk. + * See shader.h for the model and shader_abi.h for what a plugin sees. */ +#define _GNU_SOURCE #include "shader.h" +#include <dlfcn.h> +#include <glob.h> +#include <stdio.h> +#include <stdlib.h> #include <string.h> /* Integer maths throughout: this runs per cell per pass per frame, and a float @@ -125,10 +131,9 @@ static void sh_spotlight(const shader_t *sh, const shade_ctx_t *ctx, dim_by(c, (uint8_t)((int)sh->amount * k / 255)); } -static const struct { - const char *name; - shade_fn fn; -} REGISTRY[] = { +/* shader_def_t rather than a struct of its own, so a built-in and a loaded + * shader are the same kind of thing and lookup does not have two shapes. */ +static const shader_def_t REGISTRY[] = { {"dim", sh_dim}, {"grayscale", sh_grayscale}, {"tint", sh_tint}, @@ -140,6 +145,33 @@ static const struct { {"spotlight", sh_spotlight}, }; +#define NBUILTIN (sizeof REGISTRY / sizeof *REGISTRY) + +/* ---- loaded shaders ----------------------------------------------------- + * + * Kept beside the built-ins rather than merged into them: a built-in is a + * fixed table the compiler can put in .rodata, and this is a list that grows + * at runtime. Lookup asks the built-ins first, so a plugin cannot shadow + * `dim` and change what every existing config means. + * + * Both the name and the function belong to the loaded library, which is why + * nothing here is ever freed or unloaded: a shader_t copied into a config or + * onto a pane holds both pointers. */ +static struct { + shader_def_t *defs; + size_t n, cap; + char **paths; /* what has been loaded, so a reload does not load it twice */ + size_t npaths, pathcap; +} LOADED; + +static const shader_def_t *find_kind(const char *kind) { + for (size_t i = 0; i < NBUILTIN; i++) + if (strcmp(REGISTRY[i].name, kind) == 0) return ®ISTRY[i]; + for (size_t i = 0; i < LOADED.n; i++) + if (strcmp(LOADED.defs[i].name, kind) == 0) return &LOADED.defs[i]; + return NULL; +} + bool shader_make(shader_t *out, const char *kind, color_t color, uint8_t amount) { return shader_make_p(out, kind, color, amount, 0); @@ -148,16 +180,136 @@ bool shader_make(shader_t *out, const char *kind, color_t color, bool shader_make_p(shader_t *out, const char *kind, color_t color, uint8_t amount, uint16_t param) { if (!out || !kind) return false; - for (size_t i = 0; i < sizeof REGISTRY / sizeof *REGISTRY; i++) { - if (strcmp(REGISTRY[i].name, kind) != 0) continue; - *out = (shader_t){REGISTRY[i].name, REGISTRY[i].fn, color, amount, param}; - return true; - } - return false; + const shader_def_t *d = find_kind(kind); + if (!d) return false; + *out = (shader_t){d->name, d->fn, color, amount, param}; + return true; } const char *shader_kind(size_t i) { - return i < sizeof REGISTRY / sizeof *REGISTRY ? REGISTRY[i].name : NULL; + if (i < NBUILTIN) return REGISTRY[i].name; + i -= NBUILTIN; + return i < LOADED.n ? LOADED.defs[i].name : NULL; +} + +/* ---- loading ------------------------------------------------------------ */ + +static bool already_loaded(const char *path) { + for (size_t i = 0; i < LOADED.npaths; i++) + if (strcmp(LOADED.paths[i], path) == 0) return true; + return false; +} + +static void remember_path(const char *path) { + if (LOADED.npaths == LOADED.pathcap) { + LOADED.pathcap = LOADED.pathcap ? LOADED.pathcap * 2 : 8; + LOADED.paths = realloc(LOADED.paths, LOADED.pathcap * sizeof *LOADED.paths); + } + LOADED.paths[LOADED.npaths++] = strdup(path); +} + +/* One library. Everything that can be wrong with it is checked before a + * single one of its shaders is registered, so a plugin is all-or-nothing: + * half a bundle is harder to explain than none of it. */ +static size_t load_one(const char *path, char *err, size_t errcap) { + void *lib = dlopen(path, RTLD_NOW | RTLD_LOCAL); + if (!lib) { + if (err && !err[0]) + snprintf(err, errcap, "%s: %s", path, dlerror() ? dlerror() : "dlopen"); + return 0; + } + + /* An object pointer is not a function pointer in ISO C, and dlsym returns + * the former. POSIX requires the conversion to work; the cast through a + * union is how it is written without the compiler being right to warn. */ + union { + void *obj; + const shader_plugin_t *(*fn)(void); + } entry = {.obj = dlsym(lib, SL0PPTY_SHADER_PLUGIN_SYM)}; + + if (!entry.obj) { + if (err && !err[0]) + snprintf(err, errcap, "%s: no " SL0PPTY_SHADER_PLUGIN_SYM, path); + dlclose(lib); + return 0; + } + + const shader_plugin_t *t = entry.fn(); + if (!t || t->abi != SL0PPTY_SHADER_ABI) { + if (err && !err[0]) + snprintf(err, errcap, "%s: shader ABI %u, we speak %u", path, + t ? t->abi : 0, SL0PPTY_SHADER_ABI); + dlclose(lib); + return 0; + } + /* The version says which contract; the sizes say whether the plugin really + * has that contract's structs. They differ when someone edits their copy of + * shader_abi.h, which a version number alone reports as fine and a running + * session reports as garbled colours or a crash. */ + if (t->cell_size != sizeof(cell_t) || t->ctx_size != sizeof(shade_ctx_t) || + t->shader_size != sizeof(shader_t)) { + if (err && !err[0]) + snprintf(err, errcap, "%s: built against different structs", path); + dlclose(lib); + return 0; + } + if (t->count && !t->shaders) { + if (err && !err[0]) snprintf(err, errcap, "%s: empty shader table", path); + dlclose(lib); + return 0; + } + + for (size_t i = 0; i < t->count; i++) { + const shader_def_t *d = &t->shaders[i]; + if (!d->name || !*d->name || !d->fn) { + if (err && !err[0]) snprintf(err, errcap, "%s: nameless shader", path); + continue; + } + if (find_kind(d->name)) { + /* Refused rather than replacing: a config naming `dim` means the `dim` + * it was written against, and a plugin that could redefine it would + * change effects nobody asked it to touch. */ + if (err && !err[0]) + snprintf(err, errcap, "%s: shader %s already exists", path, d->name); + continue; + } + if (LOADED.n == LOADED.cap) { + LOADED.cap = LOADED.cap ? LOADED.cap * 2 : 8; + LOADED.defs = realloc(LOADED.defs, LOADED.cap * sizeof *LOADED.defs); + } + LOADED.defs[LOADED.n++] = *d; + } + + /* The library stays mapped for the life of the session, on purpose: see + * shader_load_dir()'s comment in the header. */ + return t->count; +} + +size_t shader_load_dir(const char *dir, char *err, size_t errcap) { + if (err && errcap) err[0] = 0; + if (!dir || !*dir) return 0; + + char pattern[1024]; + snprintf(pattern, sizeof pattern, "%s/*.so", dir); + + glob_t g = {0}; + int rc = glob(pattern, 0, NULL, &g); + if (rc != 0) { + globfree(&g); + return 0; /* no directory, or nothing in it: the normal case */ + } + + size_t added = 0; + for (size_t i = 0; i < g.gl_pathc; i++) { + if (already_loaded(g.gl_pathv[i])) continue; + /* Remembered whether or not it loads. A library that fails today fails + * every reload, and saying so once is a warning while saying so on every + * save is a broken editor. */ + remember_path(g.gl_pathv[i]); + added += load_one(g.gl_pathv[i], err, errcap); + } + globfree(&g); + return added; } /* ---- the pass ----------------------------------------------------------- */ diff --git a/src/shader.h b/src/shader.h index 74518fc..5e25b37 100644 --- a/src/shader.h +++ b/src/shader.h @@ -26,6 +26,7 @@ #include <stddef.h> #include <stdint.h> +#include "shader_abi.h" #include "sl0ppty.h" /* Per pane, and separately per config. Small and fixed: a stack this deep is @@ -36,54 +37,37 @@ * this frame. */ #define SHADE_CHAIN_MAX (SHADE_MAX * 2 + 2) -typedef struct { - uint16_t x, y; /* cell position within the content rect, 0-based */ - uint16_t cols, rows; /* content size, so an effect can be positional */ - int64_t now_ms; /* for anything animated */ - bool focused; +/* shade_ctx_t, shader_t and shade_fn are the ABI (shader_abi.h). */ - /* Where the cursor is, in the same rect-relative space as x/y. Only ever - * set for the pane that owns it, so an effect that follows the cursor does - * not chase another pane's. */ - bool has_cursor; - uint16_t cursor_x, cursor_y; - - /* What "terminal default" means while shading. A cell whose colour is unset - * is drawn in whatever the client's terminal calls default, and we never - * learn that RGB — but most terminal text is default-coloured, so a shader - * that skipped those cells would visibly do nothing. The pass materialises - * them to these before running the chain. Configured, because guessing is - * the one thing that would be worse. */ - color_t default_fg, default_bg; -} shade_ctx_t; - -typedef struct shader shader_t; -typedef void (*shade_fn)(const shader_t *sh, const shade_ctx_t *ctx, cell_t *c); - -struct shader { - const char *kind; /* registry name, NULL for an empty slot */ - shade_fn fn; - color_t color; /* the target colour, for shaders that have one */ - uint8_t amount; /* strength, 0..255; 0 is identity, 255 is fully applied */ - /* One number whose meaning is the shader's own, because a second parameter - * that is a column for one effect and a radius for another is not really - * two things: - * ruler the column to mark margin first column to dim - * zebra rows per band spotlight radius in columns - * gradient 0 down, 1 up, 2 right, 3 left - */ - uint16_t param; -}; - -/* Build a shader by registry name. False if the name is not a built-in. */ +/* Build a shader by registry name. False if the name is not known — a + * built-in, or one a loaded plugin added. */ bool shader_make(shader_t *out, const char *kind, color_t color, uint8_t amount); /* The same, for the shaders that take a number of their own. */ bool shader_make_p(shader_t *out, const char *kind, color_t color, uint8_t amount, uint16_t param); -/* Iterate the registry: the i'th name, or NULL past the end. */ +/* Iterate the registry: the i'th name, or NULL past the end. Built-ins first, + * then anything plugins added, in load order. */ const char *shader_kind(size_t i); +/* Load every `*.so` in `dir` that exports a shader plugin, adding what they + * declare to the registry. Returns how many shaders were added; a directory + * that does not exist is not an error (it is the normal case). Failures are + * per file: a library that cannot be opened, does not export the symbol, or + * was built against another ABI is reported in `err` and skipped, and the + * rest still load. + * + * Idempotent by path: a file already loaded is not loaded again, so calling + * this on a config reload picks up newly added plugins and disturbs nothing. + * Nothing is ever unloaded — a shader's function pointer may be sitting in a + * live config or on a pane, and dlclose() would turn it into a jump into an + * unmapped page. Replacing a plugin therefore needs a new session. + * + * A plugin is native code with the privileges of the session that loads it. + * This is deliberately a directory you own, not a config value pointing + * anywhere: the trust decision is "put a file here". */ +size_t shader_load_dir(const char *dir, char *err, size_t errcap); + /* Run `n` shaders in order over the w×h rect at (x0,y0). `base` supplies * everything in the context except the per-cell position and the size. */ void shade_apply(screen_t *s, const shader_t *shaders, size_t n, uint16_t x0, diff --git a/src/shader_abi.h b/src/shader_abi.h new file mode 100644 index 0000000..98decfd --- /dev/null +++ b/src/shader_abi.h @@ -0,0 +1,138 @@ +/* The shader ABI: everything a shader needs to see, and nothing else. + * + * This header exists so a shader can be compiled *outside* this tree — a + * plugin includes only this file, with no libghostty-vt, no pty, no layout. + * That is also the contract: a shader gets a cell and where it sits, and it + * cannot reach anything else, because nothing else is declared here. + * + * Everything in here is ABI. Changing the layout of these structs breaks + * every plugin built against the old one, so SL0PPTY_SHADER_ABI is bumped + * when they change, and a plugin that reports the wrong version (or the wrong + * sizes, which catches a plugin built against an edited copy of this file) is + * refused at load rather than trusted into a crash. + */ +#ifndef SL0PPTY_SHADER_ABI_H +#define SL0PPTY_SHADER_ABI_H + +#include <stdbool.h> +#include <stddef.h> +#include <stdint.h> + +#define SL0PPTY_SHADER_ABI 1 + +enum { + ATTR_BOLD = 1 << 0, + ATTR_DIM = 1 << 1, + ATTR_ITALIC = 1 << 2, + ATTR_UNDERLINE = 1 << 3, + ATTR_BLINK = 1 << 4, + ATTR_INVERSE = 1 << 5, + ATTR_INVISIBLE = 1 << 6, + ATTR_STRIKE = 1 << 7, +}; + +typedef struct { + bool set; /* false = terminal default */ + uint8_t r, g, b; +} color_t; + +/* A composited cell. `len` bytes of UTF-8; a grapheme cluster may be several + * codepoints, hence the buffer rather than a codepoint. width 0 means this is + * the tail half of a wide cell and must not be painted. + * + * A shader may write fg, bg and attrs. It may not write text, len or width: + * selection and copy read the terminal rather than the screen, so rewriting + * text here would desync them, and changing width would break the invariant + * the compositor relies on. */ +typedef struct { + char text[16]; + uint8_t len; + uint8_t width; + uint16_t attrs; + color_t fg, bg; +} cell_t; + +/* Where a cell sits, and what else the effect is allowed to know. */ +typedef struct { + uint16_t x, y; /* cell position within the content rect, 0-based */ + uint16_t cols, rows; /* content size, so an effect can be positional */ + int64_t now_ms; /* for anything animated */ + bool focused; + + /* Where the cursor is, in the same rect-relative space as x/y. Only ever + * set for the pane that owns it, so an effect that follows the cursor does + * not chase another pane's. */ + bool has_cursor; + uint16_t cursor_x, cursor_y; + + /* What "terminal default" means while shading. A cell whose colour is unset + * is drawn in whatever the client's terminal calls default, and we never + * learn that RGB — but most terminal text is default-coloured, so a shader + * that skipped those cells would visibly do nothing. The pass materialises + * them to these before running the chain. Configured, because guessing is + * the one thing that would be worse. */ + color_t default_fg, default_bg; +} shade_ctx_t; + +typedef struct shader shader_t; +typedef void (*shade_fn)(const shader_t *sh, const shade_ctx_t *ctx, cell_t *c); + +struct shader { + const char *kind; /* registry name, NULL for an empty slot */ + shade_fn fn; + color_t color; /* the target colour, for shaders that have one */ + uint8_t amount; /* strength, 0..255; 0 is identity, 255 is fully applied */ + /* One number whose meaning is the shader's own, because a second parameter + * that is a column for one effect and a radius for another is not really + * two things: + * ruler the column to mark margin first column to dim + * zebra rows per band spotlight radius in columns + * gradient 0 down, 1 up, 2 right, 3 left + */ + uint16_t param; +}; + +/* ---- plugins ------------------------------------------------------------ + * + * A shared library dropped in the shader directory, exporting one symbol: + * + * const shader_plugin_t *sl0ppty_shader_plugin(void); + * + * SL0PPTY_SHADER_PLUGIN() writes that for you. See + * contrib/shader-plugin/ for a complete one. + */ + +typedef struct { + const char *name; /* what to call it in the config */ + shade_fn fn; +} shader_def_t; + +typedef struct { + uint32_t abi; /* SL0PPTY_SHADER_ABI it was built against */ + uint32_t cell_size; /* the three sizes catch a plugin built against a */ + uint32_t ctx_size; /* copy of this header that has drifted, which a */ + uint32_t shader_size; /* version number alone would not */ + const char *name; /* the bundle's name, for the log line */ + size_t count; + const shader_def_t *shaders; +} shader_plugin_t; + +#define SL0PPTY_SHADER_PLUGIN_SYM "sl0ppty_shader_plugin" + +/* Define the entry point. `defs` is a static array of shader_def_t. */ +#define SL0PPTY_SHADER_PLUGIN(bundle_name, defs) \ + const shader_plugin_t *sl0ppty_shader_plugin(void); \ + const shader_plugin_t *sl0ppty_shader_plugin(void) { \ + static const shader_plugin_t table = { \ + .abi = SL0PPTY_SHADER_ABI, \ + .cell_size = sizeof(cell_t), \ + .ctx_size = sizeof(shade_ctx_t), \ + .shader_size = sizeof(shader_t), \ + .name = (bundle_name), \ + .count = sizeof(defs) / sizeof((defs)[0]), \ + .shaders = (defs), \ + }; \ + return &table; \ + } + +#endif /* SL0PPTY_SHADER_ABI_H */ diff --git a/src/sl0ppty.h b/src/sl0ppty.h index 96f8542..f7b7ee6 100644 --- a/src/sl0ppty.h +++ b/src/sl0ppty.h @@ -8,36 +8,12 @@ #include <sys/types.h> #include "input.h" +/* cell_t, color_t and the ATTR_* flags live in the shader ABI, because that is + * the one place they are a *contract* with code compiled outside this tree. */ +#include "shader_abi.h" /* ---- screen: our composited cell buffer + diff emitter ---------------- */ -enum { - ATTR_BOLD = 1 << 0, - ATTR_DIM = 1 << 1, - ATTR_ITALIC = 1 << 2, - ATTR_UNDERLINE = 1 << 3, - ATTR_BLINK = 1 << 4, - ATTR_INVERSE = 1 << 5, - ATTR_INVISIBLE = 1 << 6, - ATTR_STRIKE = 1 << 7, -}; - -typedef struct { - bool set; /* false = terminal default */ - uint8_t r, g, b; -} color_t; - -/* A composited cell. `len` bytes of UTF-8; a grapheme cluster may be several - * codepoints, hence the buffer rather than a codepoint. width 0 means this is - * the tail half of a wide cell and must not be painted. */ -typedef struct { - char text[16]; - uint8_t len; - uint8_t width; - uint16_t attrs; - color_t fg, bg; -} cell_t; - /* One geometry (DESIGN.md): every painted interactive element records its rect * here as it is painted, and a click is a lookup. Drawing and hit-testing * cannot disagree because there is only one of them. */ |
