REAPER JSFX Graphics & UI

Patterns for custom graphical interfaces in JSFX including drawing primitives, widgets, visualizations, and mouse interaction.

Requires: reaper-jsfx-core for language fundamentals.

Rules

Rule	Description
gfx-basics	@gfx section, coordinate system, colors, drawing primitives
gfx-widgets	Knobs, sliders, buttons, toggles, dropdowns
gfx-visualization	Waveform display, spectrum analyzer, level meters
gfx-interaction	Mouse handling, keyboard input, drag behavior

Official Documentation

• JSFX Graphics Functions
• Geraint's UI Library

Key Principles

1. @gfx Runs in Separate Thread

@gfx 400 300  // Request 400x300 initial size

// Runs ~30 times per second
// gfx_w, gfx_h contain actual dimensions
// Do NOT modify audio state here (race conditions)

2. Coordinate System

// Origin (0,0) is top-left
// X increases rightward
// Y increases downward

gfx_x = 0;      // Left edge
gfx_y = 0;      // Top edge
gfx_x = gfx_w;  // Right edge
gfx_y = gfx_h;  // Bottom edge

3. Color Before Drawing

// Set color first (0-1 range)
gfx_r = 1; gfx_g = 0; gfx_b = 0; gfx_a = 1;  // Red, full opacity

// Then draw
gfx_circle(100, 100, 50, 1);  // Filled red circle

4. Handle Retina/HiDPI (Critical for macOS)

Platform difference: On macOS retina, gfx_w/gfx_h are physical pixels (2x logical).

@init
base_w = 500; base_h = 380;

@gfx 500 380  // Preferred size (resizable)

// Request retina - REAPER updates to actual value (1.0 or 2.0)
!gfx_ext_retina ? gfx_ext_retina = 1;
retina = gfx_ext_retina > 0 ? gfx_ext_retina : 1;

// Calculate logical window size and scale
logical_w = gfx_w / retina;
logical_h = gfx_h / retina;
scale = min(logical_w / base_w, logical_h / base_h);

// Centering offset and combined draw scale
offset_x = (logical_w - base_w * scale) * 0.5 * retina;
offset_y = (logical_h - base_h * scale) * 0.5 * retina;
draw_scale = scale * retina;

// Mouse in base coordinates
mx = (mouse_x - offset_x) / draw_scale;
my = (mouse_y - offset_y) / draw_scale;

// Helper: scale size
function s(v) ( v * draw_scale; );
// Helper: scale X with offset
function sx(v) ( v * draw_scale + offset_x; );
// Helper: scale Y with offset
function sy(v) ( v * draw_scale + offset_y; );

See gfx-basics for complete scaling system.

Quick Reference

Use Case	Rule
Drawing shapes/text	gfx-basics
Knobs and buttons	gfx-widgets
Meters and displays	gfx-visualization
Mouse interaction	gfx-interaction

Minimal UI Example

@gfx 200 100

// Background
gfx_r = gfx_g = gfx_b = 0.1; gfx_a = 1;
gfx_x = gfx_y = 0;
gfx_rectto(gfx_w, gfx_h);

// Level meter
gfx_r = 0; gfx_g = 0.8; gfx_b = 0.2;
meter_h = gfx_h * current_level;
gfx_x = 10;
gfx_y = gfx_h - meter_h;
gfx_rectto(50, gfx_h);

// Label
gfx_r = gfx_g = gfx_b = 1;
gfx_x = 60; gfx_y = 10;
gfx_drawstr("Level");