Clay Module

GX includes a Clay module for immediate-mode UI layout. Clay is a high-performance declarative layout engine written in C (~4800 lines, MIT license). It computes element positions and sizes, then outputs an array of render commands that you draw with any renderer (raylib, OpenGL, Sokol, etc.).

Clay does not draw anything — it only computes layout. You iterate the render commands and draw rectangles, text, borders, and images yourself.

Prerequisites

The module ships with Clay bundled — no external dependencies needed. The C source is compiled automatically via @cfile.

Usage

import clay

Build with -I modules:

gx myapp.gx -I modules -o myapp.exe

Quick Example — Raylib UI Panel

import clay
import raylib.core
import raylib.input
import raylib.shapes
import raylib.text
import raylib.colors

fn main() {
    InitWindow(800, 600, "GX + Clay + Raylib")
    SetTargetFPS(60)

    var ctx = clay.gx_clay_init(800.0, 600.0)
    clay.gx_clay_use_default_measure()

    while (!WindowShouldClose()) {
        var dt = GetFrameTime()
        var mouse = GetMousePosition()
        clay.gx_clay_set_pointer(mouse.x, mouse.y, IsMouseButtonDown(0))
        clay.gx_clay_update_scroll(true, 0.0, GetMouseWheelMove() * 30.0, dt)

        // Declare layout
        clay.gx_clay_begin_layout()

        clay.gx_clay_open_id("root")
        clay.gx_clay_config_full(
            clay.COLUMN,
            clay.SIZING_GROW, 0.0, 0.0,
            clay.SIZING_GROW, 0.0, 0.0,
            16, 16, 16, 16, 12,
            clay.ALIGN_LEFT, clay.ALIGN_TOP,
            30.0, 30.0, 30.0, 255.0,
            0.0, 0.0, 0.0, 0.0
        )
            clay.gx_clay_text("Hello from Clay!", 255.0, 255.0, 255.0, 255.0, 0, 24)

            clay.gx_clay_open_id("button")
            clay.gx_clay_config_rect(80.0, 60.0, 200.0, 255.0, 6.0)
                clay.gx_clay_text("Click Me", 255.0, 255.0, 255.0, 255.0, 0, 18)
            clay.gx_clay_close()
        clay.gx_clay_close()

        // Get render commands
        var count: i32 = 0
        var cmds = clay.gx_clay_end_layout(dt, &count)

        // Draw with raylib
        BeginDrawing()
        ClearBackground(BLACK)

        for (i = 0 : count - 1) {
            var cmd = clay.gx_clay_get_command(cmds, i)
            var t = clay.gx_clay_cmd_type(cmd)

            if (t == clay.CMD_RECTANGLE) {
                DrawRectangle(
                    clay.gx_clay_cmd_x(cmd), clay.gx_clay_cmd_y(cmd),
                    clay.gx_clay_cmd_w(cmd), clay.gx_clay_cmd_h(cmd),
                    Color{(u8)clay.gx_clay_cmd_rect_r(cmd), (u8)clay.gx_clay_cmd_rect_g(cmd), (u8)clay.gx_clay_cmd_rect_b(cmd), (u8)clay.gx_clay_cmd_rect_a(cmd)}
                )
            }
            if (t == clay.CMD_TEXT) {
                DrawText(
                    clay.gx_clay_cmd_text_chars(cmd),
                    clay.gx_clay_cmd_x(cmd), clay.gx_clay_cmd_y(cmd),
                    clay.gx_clay_cmd_text_font_size(cmd),
                    Color{(u8)clay.gx_clay_cmd_text_r(cmd), (u8)clay.gx_clay_cmd_text_g(cmd), (u8)clay.gx_clay_cmd_text_b(cmd), (u8)clay.gx_clay_cmd_text_a(cmd)}
                )
            }
        }

        EndDrawing()
    }
    CloseWindow()
}

How It Works

Clay uses an open/configure/close pattern that replaces the C macro CLAY() { }:

// C (with macros):
// CLAY(CLAY_ID("panel"), { .backgroundColor = {60,60,60,255} }) { children }

// GX (explicit calls):
clay.gx_clay_open_id("panel")
clay.gx_clay_config_bg(60.0, 60.0, 60.0, 255.0)
    // ... children here ...
clay.gx_clay_close()

Each frame:

  1. gx_clay_begin_layout() — start declaring UI
  2. Open elements, configure them, add children, close them
  3. gx_clay_end_layout(dt, &count) — Clay computes positions/sizes
  4. Iterate render commands and draw with your renderer

Initialization

FunctionSignatureDescription
gx_clay_init(f32, f32) → *voidInitialize Clay with layout width/height
gx_clay_set_dimensions(f32, f32)Update dimensions on resize
gx_clay_set_pointer(f32, f32, bool)Set mouse position and button state
gx_clay_update_scroll(bool, f32, f32, f32)Update scroll containers
gx_clay_use_default_measure()Use built-in text measurement
gx_clay_set_measure_text(*void)Set custom text measure function
var ctx = clay.gx_clay_init(800.0, 600.0)
clay.gx_clay_use_default_measure()

On window resize:

clay.gx_clay_set_dimensions(new_width, new_height)

Layout Frame

FunctionSignatureDescription
gx_clay_begin_layout()Begin declaring UI elements
gx_clay_end_layout(f32, *i32) → *voidEnd layout, get render commands
gx_clay_get_command(*void, i32) → *voidGet command by index
clay.gx_clay_begin_layout()
// ... declare elements ...
var count: i32 = 0
var cmds = clay.gx_clay_end_layout(dt, &count)

for (i = 0 : count - 1) {
    var cmd = clay.gx_clay_get_command(cmds, i)
    // draw it
}

Element Building

Opening & Closing

FunctionSignatureDescription
gx_clay_open()Open element (auto ID)
gx_clay_open_id(cstr)Open element with string ID
gx_clay_open_idi(cstr, u32)Open with ID + index (for loops)
gx_clay_close()Close current element
// Simple container
clay.gx_clay_open_id("panel")
clay.gx_clay_config_bg(40.0, 40.0, 40.0, 255.0)
    // children
clay.gx_clay_close()

// Loop with indexed IDs
for (i = 0 : item_count - 1) {
    clay.gx_clay_open_idi("item", i)
    clay.gx_clay_config_rect(60.0, 60.0, 60.0, 255.0, 4.0)
        clay.gx_clay_text("Item", 255.0, 255.0, 255.0, 255.0, 0, 16)
    clay.gx_clay_close()
}

Text Elements

FunctionSignatureDescription
gx_clay_text(cstr, f32, f32, f32, f32, u16, u16)Text with color, font ID, size
gx_clay_text_ex(cstr, r, g, b, a, font, size, spacing, lineH, wrap, align)Full text config
// Simple text
clay.gx_clay_text("Score: 9500", 255.0, 255.0, 0.0, 255.0, 0, 20)

// Centered, wrapped text
clay.gx_clay_text_ex("Long description...",
    200.0, 200.0, 200.0, 255.0,
    0, 14,
    0, 0,
    clay.WRAP_WORDS, clay.TEXT_CENTER
)

Element Configuration

After opening an element, call one config function to set its properties.

Quick Configs

FunctionSignatureDescription
gx_clay_config_bg(r, g, b, a)Background color only
gx_clay_config_rect(r, g, b, a, radius)Color + rounded corners
gx_clay_config_row(gap, pad_x, pad_y)Horizontal layout
gx_clay_config_col(gap, pad_x, pad_y)Vertical layout
gx_clay_config_grow()Grow to fill both axes
// Colored box with rounded corners
clay.gx_clay_open_id("card")
clay.gx_clay_config_rect(50.0, 50.0, 50.0, 255.0, 8.0)
    // children
clay.gx_clay_close()

// Vertical list with 4px gap, 8px padding
clay.gx_clay_open_id("list")
clay.gx_clay_config_col(4, 8, 8)
    // children
clay.gx_clay_close()

Full Configuration

For complete control, use gx_clay_config_full:

extern fn gx_clay_config_full(
    direction: u8,       // ROW or COLUMN
    w_type: u8,          // SIZING_FIT/GROW/PERCENT/FIXED
    w_min: f32,          // width min (or percent value, or fixed size)
    w_max: f32,          // width max
    h_type: u8,          // SIZING_FIT/GROW/PERCENT/FIXED
    h_min: f32,          // height min
    h_max: f32,          // height max
    pad_left: u16,       // padding left
    pad_right: u16,      // padding right
    pad_top: u16,        // padding top
    pad_bottom: u16,     // padding bottom
    child_gap: u16,      // gap between children
    align_x: u8,         // ALIGN_LEFT/RIGHT/CENTER
    align_y: u8,         // ALIGN_TOP/BOTTOM/CENTER
    bg_r: f32,           // background color RGBA
    bg_g: f32,
    bg_b: f32,
    bg_a: f32,
    corner_tl: f32,      // corner radius (per corner)
    corner_tr: f32,
    corner_bl: f32,
    corner_br: f32
)

Example — centered column, 50% width, grow height:

clay.gx_clay_open_id("centered")
clay.gx_clay_config_full(
    clay.COLUMN,
    clay.SIZING_PERCENT, 0.5, 0.0,
    clay.SIZING_GROW, 0.0, 0.0,
    16, 16, 16, 16, 8,
    clay.ALIGN_CENTER, clay.ALIGN_TOP,
    45.0, 45.0, 50.0, 255.0,
    10.0, 10.0, 10.0, 10.0
)

Special Configs

FunctionSignatureDescription
gx_clay_config_border(r, g, b, a, left, right, top, bottom, between)Border
gx_clay_config_scroll(horizontal, vertical)Scrollable container
gx_clay_config_floating(off_x, off_y, z_index)Floating overlay
gx_clay_config_image(*void, w, h)Image element

Render Command Access

Each render command has a bounding box and type-specific data.

Command Properties

FunctionReturnsDescription
gx_clay_cmd_x/y/w/hf32Bounding box position and size
gx_clay_cmd_typeu8Command type constant
gx_clay_cmd_idu32Element ID

Command Types

ConstantValueDescription
CMD_RECTANGLE1Draw filled rectangle
CMD_BORDER2Draw border
CMD_TEXT3Draw text
CMD_IMAGE4Draw image
CMD_SCISSOR_START5Begin clipping region
CMD_SCISSOR_END6End clipping region
CMD_CUSTOM9Custom render command

Rectangle Data

FunctionReturnsDescription
gx_clay_cmd_rect_r/g/b/af32Background color (0-255)
gx_clay_cmd_rect_corner_tl/tr/bl/brf32Corner radius per corner

Text Data

FunctionReturnsDescription
gx_clay_cmd_text_charscstrText string
gx_clay_cmd_text_leni32String length
gx_clay_cmd_text_r/g/b/af32Text color
gx_clay_cmd_text_font_idu16Font ID
gx_clay_cmd_text_font_sizeu16Font size

Border Data

FunctionReturnsDescription
gx_clay_cmd_border_r/g/b/af32Border color
gx_clay_cmd_border_left/right/top/bottomu16Border width per side

Rendering with Raylib

for (i = 0 : count - 1) {
    var cmd = clay.gx_clay_get_command(cmds, i)
    var t = clay.gx_clay_cmd_type(cmd)
    var x = clay.gx_clay_cmd_x(cmd)
    var y = clay.gx_clay_cmd_y(cmd)
    var w = clay.gx_clay_cmd_w(cmd)
    var h = clay.gx_clay_cmd_h(cmd)

    if (t == clay.CMD_RECTANGLE) {
        DrawRectangle(x, y, w, h, Color{(u8)clay.gx_clay_cmd_rect_r(cmd), (u8)clay.gx_clay_cmd_rect_g(cmd), (u8)clay.gx_clay_cmd_rect_b(cmd), (u8)clay.gx_clay_cmd_rect_a(cmd)})
    }
    if (t == clay.CMD_TEXT) {
        DrawText(clay.gx_clay_cmd_text_chars(cmd), x, y,
                 clay.gx_clay_cmd_text_font_size(cmd),
                 Color{(u8)clay.gx_clay_cmd_text_r(cmd), (u8)clay.gx_clay_cmd_text_g(cmd), (u8)clay.gx_clay_cmd_text_b(cmd), (u8)clay.gx_clay_cmd_text_a(cmd)})
    }
    if (t == clay.CMD_SCISSOR_START) {
        BeginScissorMode(x, y, w, h)
    }
    if (t == clay.CMD_SCISSOR_END) {
        EndScissorMode()
    }
}

Interaction

FunctionSignatureDescription
gx_clay_hovered() → boolIs current element hovered?
gx_clay_pointer_over(cstr) → boolIs element with ID under pointer?
gx_clay_hash_id(cstr) → u32Hash a string to element ID
// Hover-reactive button
clay.gx_clay_open_id("btn")
var is_hov = clay.gx_clay_hovered()
if (is_hov) {
    clay.gx_clay_config_rect(100.0, 80.0, 220.0, 255.0, 6.0)
} else {
    clay.gx_clay_config_rect(80.0, 60.0, 200.0, 255.0, 6.0)
}
    clay.gx_clay_text("Hover Me", 255.0, 255.0, 255.0, 255.0, 0, 18)
clay.gx_clay_close()

Sizing Types

ConstantValueDescription
SIZING_FIT0Shrink-wrap to content size
SIZING_GROW1Expand to fill available space
SIZING_PERCENT2Percentage of parent (0.0 - 1.0)
SIZING_FIXED3Exact pixel size

For SIZING_FIT and SIZING_GROW, w_min/w_max set min/max constraints. For SIZING_PERCENT, w_min is the percentage (e.g. 0.5 = 50%). For SIZING_FIXED, w_min is the exact size in pixels.

Debug Mode

Clay includes a built-in debug overlay that visualizes the element tree:

clay.gx_clay_set_debug(true)

Constants Reference

Layout

ConstantValueDescription
ROW0Left-to-right layout
COLUMN1Top-to-bottom layout
ALIGN_LEFT / ALIGN_TOP0Align start
ALIGN_RIGHT / ALIGN_BOTTOM1Align end
ALIGN_CENTER2Align center

Text

ConstantValueDescription
WRAP_WORDS0Break on whitespace
WRAP_NEWLINES1Break on newlines only
WRAP_NONE2No wrapping
TEXT_LEFT0Left-align text
TEXT_CENTER1Center text
TEXT_RIGHT2Right-align text

Renderer Sub-modules

Instead of manually iterating render commands, use a renderer module for one-call rendering. Each renderer is a separate module to avoid pulling in unnecessary dependencies.

Feature Matrix

Featureclay_raylibclay_sokol
Filled rectanglesYesYes
Rounded rectanglesYesNo (drawn as sharp)
Text renderingYes (with fonts)No (skipped)
Borders (uniform)Yes (outline)Yes (4 rects)
Borders (per-side)Yes (4 rects)Yes (4 rects)
Images/texturesYesYes
Scissor/clippingYesYes
Text measurementYes (automatic)No

Raylib Renderer (clay_raylib)

Full-featured renderer with text, rounded corners, and automatic text measurement.

import clay
import clay_raylib
import raylib.core
import raylib.input
import raylib.text
import raylib.colors

fn main() {
    InitWindow(800, 600, "Clay + Raylib")
    SetTargetFPS(60)

    var ctx = clay.gx_clay_init(800.0, 600.0)

    // Set up fonts: index 0 = default font
    var font = GetFontDefault()
    clay_raylib.gx_clay_raylib_init(&font, 1)

    while (!WindowShouldClose()) {
        clay.gx_clay_set_pointer(GetMouseX(), GetMouseY(), IsMouseButtonDown(0))
        clay.gx_clay_begin_layout()

        // ... declare UI elements ...

        var count: i32 = 0
        var cmds = clay.gx_clay_end_layout(GetFrameTime(), &count)

        BeginDrawing()
        ClearBackground(BLACK)
        clay_raylib.gx_clay_render_raylib(cmds, count)  // one call!
        EndDrawing()
    }
    CloseWindow()
}

Font table: Pass a pointer to your Font array. The array index matches Clay’s font_id in text elements. gx_clay_raylib_init also installs the text measurement callback so Clay can compute accurate text layouts.

Multiple fonts:

var fonts: Font[3]
fonts[0] = LoadFontEx("regular.ttf", 16, 0, 0)
fonts[1] = LoadFontEx("bold.ttf", 16, 0, 0)
fonts[2] = LoadFontEx("mono.ttf", 14, 0, 0)
clay_raylib.gx_clay_raylib_init(&fonts, 3)

// Use font_id to select font:
clay.gx_clay_text("Normal text", 255.0, 255.0, 255.0, 255.0, 0, 16)  // font 0
clay.gx_clay_text("Bold text", 255.0, 255.0, 255.0, 255.0, 1, 16)    // font 1
FunctionSignatureDescription
gx_clay_raylib_init(*void, i32)Set font table + install text measurement
gx_clay_render_raylib(*void, i32)Render all commands (between Begin/EndDrawing)

Sokol GP Renderer (clay_sokol)

Basic renderer for Sokol GP. Handles rectangles, borders, images, and scissor. Text and rounded corners are not supported (Sokol GP lacks these natively).

import clay
import clay_sokol
import sokol.app
import sokol.gfx
import sokol.gp

// In your frame callback:
clay.gx_clay_begin_layout()
// ... declare UI ...
var count: i32 = 0
var cmds = clay.gx_clay_end_layout(dt, &count)

sgp_begin(width, height)
clay_sokol.gx_clay_render_sokol(cmds, count)  // one call!
sgp_flush()
sgp_end()
FunctionSignatureDescription
gx_clay_render_sokol(*void, i32)Render all commands (between sgp_begin/end)

Writing a Custom Renderer

If you need a different backend, iterate commands manually:

var count: i32 = 0
var cmds = clay.gx_clay_end_layout(dt, &count)

for (i = 0 : count - 1) {
    var cmd = clay.gx_clay_get_command(cmds, i)
    var t = clay.gx_clay_cmd_type(cmd)

    if (t == clay.CMD_RECTANGLE) {
        // draw rect at cmd_x/y/w/h with cmd_rect_r/g/b/a color
    }
    if (t == clay.CMD_TEXT) {
        // draw cmd_text_chars at cmd_x/y with cmd_text_font_size
    }
    // ... handle CMD_BORDER, CMD_IMAGE, CMD_SCISSOR_START/END
}

Platform Notes

  • TCC: Compiled with -DCLAY_DISABLE_SIMD (TCC lacks SSE intrinsics). Layout performance is still excellent for typical UI workloads.
  • Clang/GCC (-O2+): SIMD acceleration is available. Remove CLAY_DISABLE_SIMD from cflags for optimized builds if desired.
  • Clay uses zero malloc calls — all memory is pre-allocated in a single arena.

Module Layout

modules/
  clay/                          Core layout engine
    c/
      clay.h                     Clay header + implementation (~4800 lines)
      clay_impl.c                Single-TU compilation (#define CLAY_IMPLEMENTATION)
      gx_clay.h                  GX helper wrappers
    gx/
      clay.gx                    Module declarations, constants, extern functions

  clay_raylib/                   Raylib renderer (import clay_raylib)
    c/
      gx_clay_render_raylib.h   Render loop + text measurement + font table
    gx/
      clay_raylib.gx             Module declaration, 2 extern functions

  clay_sokol/                    Sokol GP renderer (import clay_sokol)
    c/
      gx_clay_render_sokol.h    Render loop (basic: rects, borders, images, scissor)
    gx/
      clay_sokol.gx              Module declaration, 1 extern function