Skip to content

Writing Shaders

Ö. Efe D. edited this page Sep 15, 2026 · 1 revision

Writing Shaders

A tron shader is a WGSL file that defines one function:

fn shade(uv: vec2<f32>, frag_coord: vec2<f32>) -> vec4<f32> {
    return terminal(uv);
}

tron calls shade for every pixel of the window and uses the color it returns. Save the file as ~/.config/tron/shaders/<name>.wgsl and add it to [shader] files. tron reloads it on every save. See Shaders for setup.

Coordinates

  • uv runs from (0, 0) at the top left to (1, 1) at the bottom right.
  • frag_coord is the pixel position, also with the origin at the top left. Pixel centers are at .5.
  • tron.resolution is the window size in pixels, so uv == frag_coord / tron.resolution.

Functions

Function Returns
terminal(uv) The rendered terminal at uv, premultiplied alpha. With several shaders, the output of the previous shader
previous(uv) The final image of the previous frame, after all shaders. Transparent on the first frame and after a resize. Use it for trails and afterglow

The tron uniform

Field Type Meaning
tron.resolution vec2<f32> Window size in pixels
tron.time f32 Seconds since tron started
tron.frame u32 Frames rendered since the shader chain was loaded
tron.cursor vec4<f32> Cursor rectangle in pixels: x, y, width, height. Zero size when hidden
tron.previous_cursor vec4<f32> The cursor rectangle before the last cursor change
tron.cursor_change_time f32 Value of tron.time when the cursor last changed
tron.cell_size vec2<f32> Size of one cell in pixels
tron.focused f32 1.0 while the window has focus, else 0.0
tron.background vec4<f32> Background color, premultiplied alpha

When shaders redraw

tron reads the shader source to decide how often to draw:

  • A shader that uses tron.time or tron.frame redraws every frame.
  • A shader that uses tron.cursor_change_time or tron.previous_cursor redraws for one second after each cursor change, then stops.
  • A shader that uses previous( keeps the previous frame, which costs one extra texture.
  • Other shaders redraw only when the terminal content changes.

animation = "always" or "never" under [shader] overrides this.

Alpha

Return premultiplied alpha: the color channels are already multiplied by alpha. Colors from terminal() are premultiplied, so changing their rgb and keeping their a is always correct.

Many shaders are written for opaque windows and return alpha 1. tron keeps the output alpha at most at the terminal's alpha, and raises it only as far as the brightest color channel needs. A translucent window (opacity < 1) therefore stays translucent while a shader runs, and bright effects still show on transparent parts.

Examples

Scanlines

fn shade(uv: vec2<f32>, frag_coord: vec2<f32>) -> vec4<f32> {
    let color = terminal(uv);
    let scanline = 0.9 + 0.1 * sin(frag_coord.y * 3.14159);
    return vec4<f32>(color.rgb * scanline, color.a);
}

CRT with barrel distortion

This is the built-in crt.wgsl:

fn shade(uv: vec2<f32>, frag_coord: vec2<f32>) -> vec4<f32> {
    let centered = uv * 2.0 - 1.0;
    let warped = centered * (1.0 + 0.04 * dot(centered.yx, centered.yx));
    let tuv = warped * 0.5 + 0.5;
    if any(tuv < vec2<f32>(0.0)) || any(tuv > vec2<f32>(1.0)) {
        return vec4<f32>(0.0, 0.0, 0.0, 1.0);
    }
    let color = terminal(tuv);
    let scanline = 0.85 + 0.15 * sin(frag_coord.y * 3.14159);
    let vignette = smoothstep(1.45, 0.35, length(centered));
    return vec4<f32>(color.rgb * scanline * vignette, color.a);
}

Animated background behind dark areas

fn shade(uv: vec2<f32>, frag_coord: vec2<f32>) -> vec4<f32> {
    let color = terminal(uv);
    // Brightness of the terminal pixel: text is bright, the background is dark.
    let luma = dot(color.rgb, vec3<f32>(0.299, 0.587, 0.114));
    let wave = 0.5 + 0.5 * sin(uv.x * 6.0 + tron.time);
    let glow = vec3<f32>(0.1, 0.0, 0.2) * wave;
    // Show the background only where the terminal is dark.
    let mask = 1.0 - smoothstep(0.05, 0.2, luma);
    return vec4<f32>(color.rgb + glow * mask, color.a);
}

Cursor trail

This is the built-in cursor-trail.wgsl. It reads the cursor uniforms, so it redraws only for a moment after the cursor moves:

const DURATION: f32 = 0.15;
const TINT: vec3<f32> = vec3<f32>(0.31, 0.84, 1.0);

// Distance from `p` to the segment `a`-`b`.
fn segment_distance(p: vec2<f32>, a: vec2<f32>, b: vec2<f32>) -> f32 {
    let ab = b - a;
    let t = clamp(dot(p - a, ab) / max(dot(ab, ab), 1e-4), 0.0, 1.0);
    return length(p - a - ab * t);
}

fn shade(uv: vec2<f32>, frag_coord: vec2<f32>) -> vec4<f32> {
    let color = terminal(uv);
    let progress = (tron.time - tron.cursor_change_time) / DURATION;
    if progress >= 1.0 || tron.cursor.z <= 0.0 || tron.previous_cursor.z <= 0.0 {
        return color;
    }
    let start = tron.previous_cursor.xy + tron.previous_cursor.zw * 0.5;
    let to = tron.cursor.xy + tron.cursor.zw * 0.5;
    // The tail catches up with the head as the trail fades.
    let ease = 1.0 - pow(1.0 - progress, 3.0);
    let tail = mix(start, to, ease);
    let radius = min(tron.cursor.z, tron.cursor.w) * 0.5;
    let distance = segment_distance(frag_coord, tail, to);
    let coverage = clamp(radius - distance + 0.5, 0.0, 1.0);
    let strength = coverage * (1.0 - progress) * 0.6 * tron.focused;
    return vec4<f32>(mix(color.rgb, TINT * max(color.a, strength), strength), max(color.a, strength));
}

Porting Ghostty and Shadertoy shaders

Ghostty and Shadertoy shaders are GLSL with a mainImage function. The built-in ports in examples/shaders show many complete conversions.

GLSL (Ghostty / Shadertoy) tron WGSL
void mainImage(out vec4 fragColor, in vec2 fragCoord) fn shade(uv: vec2<f32>, frag_coord: vec2<f32>) -> vec4<f32>
iResolution.xy tron.resolution
iTime tron.time
iFrame tron.frame
texture(iChannel0, uv) terminal(uv)
iCurrentCursor tron.cursor
iPreviousCursor tron.previous_cursor
iTimeCursorChange tron.cursor_change_time
vec2, vec3, vec4 vec2<f32>, vec3<f32>, vec4<f32>
mat2 mat2x2<f32>
float x = 1.0; var x: f32 = 1.0; or let x = 1.0;
fract, mix, smoothstep, clamp, length, dot the same names
mod(x, y) x - y * floor(x / y) (WGSL % truncates toward zero instead)
atan(y, x) atan2(y, x)
fragColor = ...; return ...;

Things to watch for:

  • Y axis. Shadertoy, and Ghostty on OpenGL, put the origin at the bottom left. tron puts it at the top left. Flip the coordinates at the start of shade so the original math runs unchanged:

    let frag = vec2<f32>(frag_coord.x, tron.resolution.y - frag_coord.y);
    let gl_uv = vec2<f32>(uv.x, 1.0 - uv.y);

    Then sample the terminal at the flipped-back position: terminal(vec2<f32>(p.x, 1.0 - p.y)). Ghostty's cursor uniforms use the same bottom-left space, so flip the cursor's y as well.

  • Global mutable state. GLSL globals become function parameters or var<private> in WGSL.

  • Loops. WGSL has for, loop and while; integer loop counters need explicit i32 or u32 types and conversions like f32(i).

  • Integer and float mixing. WGSL never converts implicitly: write 2.0 * x, not 2 * x, for floats.

  • Alpha. Return premultiplied alpha, and keep the terminal's alpha for text areas (see Alpha above).

  • Licenses. Shadertoy applies CC BY-NC-SA 3.0 when the author gives no license. Keep the original credit and license at the top of your port.

Debugging

  • Compile errors show the WGSL message and line. Line numbers count the prelude tron adds before your code.
  • Return a solid color, such as vec4<f32>(1.0, 0.0, 0.0, 1.0), to check that your shader runs.
  • Visualize a value as a color: return vec4<f32>(vec3<f32>(fract(tron.time)), 1.0);
  • The startup screen's Shaders tab previews your files next to the built-in ones.

Clone this wiki locally