Repository navigation
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.
-
uvruns from(0, 0)at the top left to(1, 1)at the bottom right. -
frag_coordis the pixel position, also with the origin at the top left. Pixel centers are at.5. -
tron.resolutionis the window size in pixels, souv == frag_coord / tron.resolution.
| 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 |
| 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 |
tron reads the shader source to decide how often to draw:
- A shader that uses
tron.timeortron.frameredraws every frame. - A shader that uses
tron.cursor_change_timeortron.previous_cursorredraws 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.
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.
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);
}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);
}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);
}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));
}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
shadeso 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,loopandwhile; integer loop counters need expliciti32oru32types and conversions likef32(i). -
Integer and float mixing. WGSL never converts implicitly: write
2.0 * x, not2 * 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.
- 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.
Using tron
Looks
Features
Reference