Shaders
Afterglow shaders are Phosphor shader packs. A pack is a directory with metadata.json and GLSL stages. Each stage uses the terminal shader contract. Each fragment stage defines vec4 pTerminal(vec2 uv). See the shader API for vertex and mesh stages, and for pointer maps. Configuration refers to a pack by its directory name, which normally equals its id. The shader API describes the contract.
Pack locations
Afterglow reads packs from these directories. A pack in a later row replaces a pack with the same ID in an earlier row.
| Directory | Contents |
|---|---|
data/shaders/ in the source tree | Bundled packs, in a development build only. |
afterglow/shaders/ in each XDG data directory, such as /usr/share/afterglow/shaders/ | Installed packs. |
~/.config/afterglow/shaders/ | Your own packs. Afterglow creates this directory. With afterglow --config DIR/config.json, this is DIR/shaders/. |
A binary that runs from the build tree puts the checkout’s data/shaders/ after the XDG data directories in this table. Thus a pack in the checkout replaces an installed pack with the same ID, and you test the pack that you edit. Your own packs in ~/.config/afterglow/shaders/ still replace the packs of the checkout.
Put each pack in its own subdirectory, such as ~/.config/afterglow/shaders/my-pack/metadata.json. Put include files that several packs share in a shared/ subdirectory of the same directory. Afterglow looks for an include file in this order:
- The pack’s own directory, for
#include "name.glsl"only. - The contract headers built into Afterglow, such as
terminal_lib.glsl. - For a pack in a script package, the
shared/subdirectory of the package’sshaders/directory. - The
shared/subdirectory of each directory in the table, in reverse table order, starting with your own directory.
Afterglow uses the first file that it finds. Script packages carry their own shaders/ directory. See packages.
Shader chains
The Shaders configuration group contains five chains and four event packs: the pane overview, the tab transition, the pane effects and the overlay transition.
| Chain | Input |
|---|---|
background | Each pane’s background, including images below text. |
text | Each pane’s text, decorations and images above text. |
cursor | Each pane’s cursor layer. |
pane | The completed pane. |
window | The completed window. |
overview | The completed window, while the pane overview shows. One pack ID, not a list. |
tabTransition | The completed window, while a tab switch runs. One pack ID, not a list. |
paneEffects | The completed window, while a pane opens or closes. One pack ID, not a list. |
overlayTransition | The overlay over its pane, after the pane chain, while the overlay fades in or out. The pack also reads the pane under the overlay. One pack ID, not a list. |
The first three chains run before pane composition. Layer inputs use premultiplied alpha. Empty areas are transparent. Shader output must also use premultiplied alpha. Afterglow draws the window docked areas, the tab bar and other controls after all shader chains. A pane area is part of its pane. The shader chains and the event packs draw over it. Without layer shaders, Afterglow does not allocate separate layers.
Shaders.params sets parameter values for each pack reference:
{"Shaders": {"window": ["bloom"], "params": {"bloom": {"strength": 0.5}}}}Afterglow compiles a pack one time. A change of Shaders.params does not compile it again. The change rebuilds the chains, so it resets buffer history and expires instance IDs.
The pane overview (pane_overview, Ctrl+Shift+D) shows the panes of every tab. The default overview pack is Phosphor Overview. Each tab becomes a small picture of its panes, each pane in its real place. The highlighted pane lifts a little, and its rim carries the Phosphor spectrum. Set Shaders.overview to another pack ID, or to an empty string to turn the overview off. When the overview closes, the chosen pane stays highlighted until the close ends. A pane in another tab shows its tab as the overview closes. Script packages can ship packs of their own, such as an overview with the script that drives it. See packages. The shader API describes how to write an overview pack.
Switching tabs runs Shaders.tabTransition. The default pack is Phosphor Tabs. The new tab slides in over the tab being left, and a line of the spectrum runs down the edge between them. Its style parameter chooses the slide (0) or a fade with no motion (1). The tab being left keeps running until the new tab arrives. It shows without its layer, pane and window shaders. With window shaders, the first frame of a switch can differ from the frame before it. Animation.tabCurve and Animation.tabDuration set the motion. Set Shaders.tabTransition to an empty string to switch tabs at once.
Splitting and closing panes run Shaders.paneEffects. The default pack is Phosphor Panes. A new pane fades in where it opens. A closed pane fades out. The rim of the pane is bright at once, in the spectrum, and then fades. Animation.paneEffectDuration sets the time. Animation.splits=false turns off the open and close animations and the line of a pane that is away. Script pulses still show. Set Shaders.paneEffects to an empty string to turn off all pane effects. A pane whose shell moves to another host, user or container gets a thin line at its edge, such as after afterglow ssh. The line is bright at the change and then settles. It stays while the pane is away. The line is cyan for a remote host, rose for an elevated user and purple for a container. With the followTheme parameter, these are the bright cyan, bright red and bright magenta of the theme. When the pane returns, the line fades out in its color. Between two contexts, the line changes color. Animation.contextDuration sets the time of the change. The mark parameter sets the strength of the line. A value of 0 removes it.
An overlay is a program that a script or afterglow ctl overlay runs over a pane. It runs Shaders.overlayTransition when it opens and closes. The default pack is Overlay Fade, which blends the pane and the overlay. Both have the pane’s layer and pane shaders while they blend, and the window shaders run over the result. Animation.overlayCurve and Animation.overlayDuration set the time. Set Shaders.overlayTransition to an empty string to switch at once.
Bundled packs
Afterglow installs two groups of packs. The Phosphor packs use the colors and the motion of the Phosphor design language. They are the defaults. A position moves on a spring, a color changes with a fade, and an edge that changes is bright at once and then fades.
| Pack | Chain | Default | Look |
|---|---|---|---|
phosphor-overview | overview | Yes | Each tab as a small picture of its panes, with the spectrum on the rim of the highlighted pane. |
phosphor-tabs | tabTransition | Yes | The new tab slides in over the tab being left. The spectrum runs down the edge between them. |
phosphor-panes | paneEffects | Yes | Panes fade in and out with a rim in the spectrum. A pane that is away keeps a line in the color of its context. |
phosphor-depths | window | No | Slow clouds of the spectrum below the text, dust, and an ember at the cursor. |
The packs with the spectrum have the parameters stop0 to stop3 for its four colors. Set their followTheme parameter to true to take the colors from the terminal palette.
The neutral packs have no color of their own. They take their colors from the theme. The three plain packs have the motion of the Phosphor packs with no gradient and no glow.
| Pack | Chain | Default | Look |
|---|---|---|---|
plain-overview | overview | No | Each tab as a small picture of its panes. The rim of the highlighted pane has the cursor color of the theme. |
plain-tabs | tabTransition | No | The new tab slides in over the tab being left, or the two fade. |
plain-panes | paneEffects | No | Panes fade in and out. A pane that is away keeps a line in a palette color of the theme. |
overlay-fade | overlayTransition | Yes | An overlay and its pane blend. |
bloom | pane or window | No | Bright text and colors glow into the space round them. |
cursor-trail | pane | No | A streak that fades follows the cursor when it jumps. |
To use the neutral group in place of the Phosphor packs:
{"Shaders": {"overview": "plain-overview", "tabTransition": "plain-tabs", "paneEffects": "plain-panes"}}The five layer chains are empty by default, so Afterglow draws the terminal with no shader until you name a pack.
The example packs in the source repository show other looks and the rest of the shader API. These include a CRT screen, a tilted screen, a carousel overview and a cube tab switch. Copy one into ~/.config/afterglow/shaders/ to use it. The Phosphor scene combines a 3D core, text afterimages and command reactions. Glasshouse provides another complete desktop scene.
Previous text and color
Include terminal_history.glsl to read uPreviousText, the previous frame’s processed text layer. Sample it with the canvas’s uv, as with terminalTexel. It starts transparent. Layout, theme and shader changes reset it. The include enables layer rendering, a history texture and animation frames. Other shaders require no text-history allocation or copy.
Set "highDynamicRange": true in the pack metadata for values above 1 between passes. One requesting shader changes the window’s intermediate targets and text history from RGBA8 to RGBA16F. This doubles intermediate texture memory. It does not change display output or convert color spaces. The chain must tone-map its radiance before final output. The Phosphor scene does this in its phosphor-lens pass, before text composition.
Packs support eight buffers, four image parameters, auxiliary depth output and a vertex stage. Mesh passes add imported or shader-generated triangles, instancing and hardware depth testing. Mesh Reactor demonstrates this path. See the shader API for pass order, coordinates, reset conditions and memory limits. Depth Trails demonstrates these interfaces.
System audio
- Install
cava. - Add
#include <terminal_audio.glsl>to the shader.
PhosphorAudio uses CAVA to analyze system playback through PipeWire or PulseAudio. One analyzer serves all windows. It runs only when an exposed window has an audio shader and is not minimized. Afterglow does not record audio to disk or change output selection or volume. Silence or missing CAVA does not stop normal scene animation.
The Audio configuration group reloads while Afterglow runs:
| Key | Values and behavior |
|---|---|
enabled | Default: true. Set false to stop capture. |
inputMethod | auto, pipewire or pulse. |
inputSource | Default: auto, the backend’s default playback source. |
Explicit source names depend on the backend. For PulseAudio, use the output’s monitor source. Use afterglow -o Audio.enabled=false to disable capture for one launch.
| Input | Meaning |
|---|---|
getBass(), getMids(), getTreble(), getOverall() | Smoothed RMS energy from 0 to 1. Also available as uAudioLevels.xyzw. |
audioBar(int index) | One of 64 mono logarithmic bands from 50 Hz to 10 kHz. Invalid indices return zero. |
audioBarSmooth(float position) | Interpolated spectrum at a position from 0 to 1. Pane coordinates have no effect. |
iAudioSpectrumSize | 64 for valid frames. Otherwise zero. |
uAudioSpectrum | A 64×1 R32F texture at binding 10. Use the helpers or texelFetch. |
Bass uses bins 0–19. Mids use bins 20–47. Treble uses bins 48–63. Automatic gain adjusts these visual levels. They are not calibrated sound-pressure measurements. Stopped, disabled, failed or stale capture produces zero values. Shaders without the audio include also receive zero. Audio inputs are independent of the eight Luau uSignal channels. Static audio shaders redraw when the spectrum changes. They do not need a continuous timer.
Scrollback
uScrollback provides retained terminal history counts:
| Component | Meaning |
|---|---|
.x | This pane’s retained history rows of the main screen. A window pass uses the focused pane. |
.y | The retained history rows of the main screen of all panes in the current tab, added together. |
.z | The .y count, smoothed with a 1.25-second time constant. |
.w | Reserved. Always zero. |
Background tabs, other windows, visible screen rows and discarded rows do not contribute. Tab changes, pane closure, buffer trimming and history clearing change the total. While a full-screen program uses the alternate screen, the counts keep the history of the main screen. Reflow can change the count because the unit is rows. Afterglow reads cached counts without scanning history text. Static shaders redraw until the smoothed value settles. They then redraw only for changes.
Script controls
The Luau API returns effects for host execution. Use afterglow.await when you need a result.
Signals
uSignal[0..7] holds a value for each pane and channel, and the seconds since it was set. Read them with signalValue(channel) and signalAge(channel). A channel that was never set has an age of 1,000,000 seconds. Set a channel with afterglow.signal, afterglow ctl signal or the control socket.
afterglow.signals(pane, values, scope) changes 1–8 distinct channels in one effect. Channels must be integers from 0 to 7. Values must fit in a finite float. Scope is pane, tab or window. The default is tab. The host resolves the scope from the anchor pane when it applies the effect.
return afterglow.signals(ev.pane, { { channel = 2, value = 0 }, { channel = 4, value = 0 }, { channel = 0, value = 1 },}, "tab")The host validates all values and targets before any change. Up to 128 panes receive the batch in one GUI-thread turn, with one timestamp. A scope with more than 128 panes rejects the complete batch with an error. Rendering sees the complete update. The batch uses one effect from the rate budget. A requested result lists the changed pane IDs in data.panes. The Phosphor scene uses snapshots and tab batches, including when loaded after pane creation. Background-tab commands do not increase the visible scene’s activity.
Parameters
afterglow.shaders(pane) returns active window effect instances in data.shaders. Each entry contains instance, shader, layer, parameters and effective values for the pane. Parameter metadata contains IDs, types, defaults, ranges, units and a supported flag. Repeated pack instances have different instance IDs.
local active = afterglow.await(afterglow.shaders(ev.pane))for _, instance in active and active.shaders or {} do if instance.shader == "bloom" then return afterglow.shader_parameters(ev.pane, instance.instance, { strength = 0.8 }, "tab") endendshader_parameters(pane, instance, values, scope?) replaces the calling script’s overrides for the selected targets. The default scope is pane. Other scopes are tab and window. The host resolves targets when it applies the effect. New panes do not inherit the update. Window-layer effects require window scope. Their value belongs to the window and does not depend on pane focus. Other layers permit up to 128 target panes. A scope with more than 128 panes rejects the complete update with an error. Each update is atomic and uses one effect. Results include data.panes.
Numbers must be finite. Integer parameters require integers. Boolean parameters require booleans. Colors require valid Qt color strings, such as #ff0077. Their names are the SVG names of Qt, not the X11 names of Colors: green is #008000 here. An eight-digit color puts alpha first: #AARRGGBB, not #RRGGBBAA. Unknown names, unsupported types or slots, and values outside the range reject the complete update. Phosphor validates metadata and ranges. Script values are not clamped. Configuration loading uses Phosphor validation and defaults. Images use the image path and size rules. The host validates and decodes images before it applies any part of the update.
An empty values table releases the script’s overrides on the selected targets. The latest successful write wins for each parameter across scripts. Reset or unload exposes another script’s value, then the configured value or default. An update replaces the owner’s previous table. Omitted parameters are released. Shader or configuration rebuilds clear overrides and expire instance IDs. Query again after a stale-ID error. Moving a pane between windows removes its source-window overrides. Closing a pane releases its overrides. Updates change temporary uniforms and image bindings. They do not edit configuration or recompile programs.
Transitions
An optional fifth argument controls animation:
return afterglow.shader_parameters(ev.pane, instance.instance, { strength = 0.8 }, "tab", { duration_ms = 650, curve = "ease-in-out" })Duration is 0–60000 ms. Zero applies the change immediately. Curves are linear, ease-in-out and the critically damped spring. The default curve is ease-in-out. Phosphor curve specs also work, such as 0.2,0,0,1 for a cubic Bézier or spring:20,1 for a spring with angular frequency 20 and damping ratio 1. Curves that overshoot are rejected, such as elastic and bounce curves and springs with damping below 1. Duration is also the maximum spring lifetime. A new target starts from the visible value with a new duration. Float parameters stay between their endpoints. Colors interpolate in linear-light sRGB and return encoded color uniforms. Integers, booleans and images change at completion. Omitted parameters and empty-table resets release overrides immediately. Unload, rebuild, pane closure and transfer cancel owned transitions. Results confirm acceptance, not animation completion. Afterglow keeps at most 4,096 overrides, one for each script, instance and pane. An update past this limit fails with an error. Hidden windows catch up when they render again.
shader-parameters.luau adds Bloom boost and reset commands. Install it in ~/.config/afterglow/scripts/ and enable Bloom in a shader chain. It targets the current tab, or the window for a window effect. It reports when Bloom is absent.
Presets
scene-controls provides effect selection, presets, quality, intensity, save and reset controls.
| Helper | Result |
|---|---|
shader_presets(pane, instance) | Available presets in data.presets. |
shader_preset(pane, instance, preset, scope?, transition?) | Apply a preset. data.values holds the values that it applied. |
save_shader_preset(pane, instance, name) | Save a preset. Return data.id and data.name. |
@defaults applies pack defaults. An empty shader_parameters table releases only the calling script’s changes. Saved presets use Phosphor’s schema and registry in ~/.config/afterglow/shader-presets/surface/. With afterglow --config DIR/config.json, they are in DIR/shader-presets/surface/. This directory is separate from PlasmaZones. Pack presets are read-only. Saves create new named entries that survive restarts. Applied values are temporary. Apply the preset again after a restart.
Scene state
scene_state(pane) returns data.scene:
| Field | Meaning |
|---|---|
tab_id | Current tab in the anchor pane’s window. |
history_rows | Combined retained history in that tab. |
history_normalized | rows / (rows + 5000). |
sample_ms | Monotonic sample time. |
audio_available | Whether valid audio data is available. |
bass, mids, treble, overall | Audio levels from 0 to 1. |
Samples remain cached for 100 ms. Tab changes invalidate the cache. History uses the current tab even when the anchor pane is in a background tab. Queries observe the shared analyzer without starting capture. Unavailable or stale capture returns false availability and zero levels. Scripts can sample with bounded timers. The host handles continuous FFT input and interpolation. contextual-scene makes one decision each second and changes exposure with a smooth transition.
Mirrored from docs/SHADERS.md in the Afterglow repository.