Beta

garchomp

X11 Compositor

A GPU-accelerated X11 compositor built with wgpu and Rust. garchomp replaces picom with tighter gar integration, Lua-scripted animations, per-window rules, and experimental HDR support. Enjoy smooth blur, shadows, rounded corners, and workspace transitions with modern GPU rendering.

View on GitHub Install

garchomp compositor - blur and shadow effects

garchomp compositor - workspace transition

Features

GPU-accelerated rendering with wgpu (Vulkan/GL)
Dual Kawase blur for fast, high-quality backgrounds
Soft drop shadows with configurable radius and offset
Rounded window corners with per-window overrides
Lua-scripted animation system (open, close, workspace)
Per-window rules based on WM_CLASS, title, or instance
Configurable VSync modes (off, on, adaptive)
Experimental HDR support with ACES tonemapping
Multi-monitor support via RandR
Focus-based opacity (dim unfocused windows)
Fullscreen bypass for unredirected rendering
Workspace transition animations synced with gar
File-watch hot-reload (auto or via garchompctl reload)
Window type detection with smart effect exclusion
IPC control via garchompctl

Quick Start Guide

Get up and running with garchomp in just a few steps. This guide covers installation, basic configuration, and essential commands.

1. Installation

Install garchomp using the unified installer or build from source:

terminal

$ curl -fsSL https://gar.musicsian.com/install.sh | bash -s -- --component=garchomp # Install via script

$ cd ~/.local/src/gardesk/garchomp && cargo build --release # Or build from source

2. Running with gar

When using gar, garchomp starts automatically via gar.exec_once() in your config. For standalone use:

terminal

$ garchomp # Start compositor (uses DISPLAY env)

$ garchomp -v # Verbose logging

$ garchomp -vv # Debug logging

3. Essential Commands

Use garchompctl to control the compositor at runtime:

terminal

$ garchompctl ping # Health check

$ garchompctl status # Show status (JSON)

$ garchompctl reload # Reload configuration

$ garchompctl set blur false # Disable blur

$ garchompctl list # List managed windows

4. Configuration File

Configure garchomp in ~/.config/gar/init.lua using the garchomp namespace. Changes apply after garchompctl reload.

terminal

$ mkdir -p ~/.config/gar # Create config directory

$ $EDITOR ~/.config/gar/init.lua # Edit configuration

5. Quick Config

Add these lines to your init.lua to enable basic effects:

~/.config/gar/init.lua

-- garchomp compositor
garchomp.set("blur_enabled", true)
garchomp.set("blur_strength", 5)
garchomp.set("shadow_enabled", true)
garchomp.set("corner_radius", 12)
garchomp.set("fade_enabled", true)

-- Start with gar session
gar.exec_once("garchomp")

Configuration Reference

garchomp uses Lua for configuration, integrated with gar's shared config at ~/.config/gar/init.lua.

Minimal Configuration

~/.config/gar/init.lua

-- Minimal garchomp configuration
garchomp.set("blur_enabled", true)
garchomp.set("blur_strength", 5)
garchomp.set("shadow_enabled", true)
garchomp.set("shadow_radius", 12)
garchomp.set("corner_radius", 12)
garchomp.set("fade_enabled", true)
garchomp.set("fade_duration", 0.15)

Full Configuration Example

~/.config/gar/init.lua

-- ═══════════════════════════════════════════
-- garchomp compositor configuration
-- ═══════════════════════════════════════════

-- ═══════════════════════════════════════════
-- Blur Effect
-- ═══════════════════════════════════════════

garchomp.set("blur_enabled", true)
garchomp.set("blur_strength", 5)          -- 1-20, higher = more blur

-- ═══════════════════════════════════════════
-- Shadows
-- ═══════════════════════════════════════════

garchomp.set("shadow_enabled", true)
garchomp.set("shadow_radius", 12)         -- Blur radius
garchomp.set("shadow_offset_x", 0)        -- Horizontal offset
garchomp.set("shadow_offset_y", 5)        -- Vertical offset
garchomp.set("shadow_opacity", 0.5)       -- 0.0-1.0

-- ═══════════════════════════════════════════
-- Rounded Corners
-- ═══════════════════════════════════════════

garchomp.set("corner_radius", 12)

-- ═══════════════════════════════════════════
-- Fading / Opacity
-- ═══════════════════════════════════════════

garchomp.set("fade_enabled", true)
garchomp.set("fade_duration", 0.15)       -- Seconds

-- ═══════════════════════════════════════════
-- Performance
-- ═══════════════════════════════════════════

garchomp.set("vsync", "adaptive")         -- off, on, adaptive

-- ═══════════════════════════════════════════
-- HDR (Experimental)
-- ═══════════════════════════════════════════

garchomp.set("hdr_enabled", false)
garchomp.set("hdr_peak_luminance", 1000)  -- Peak nits
garchomp.set("hdr_paper_white", 203)      -- SDR white level
garchomp.set("tonemap_operator", "aces")  -- aces, reinhard, hable

-- ═══════════════════════════════════════════
-- Animations
-- ═══════════════════════════════════════════

garchomp.animate("window_open", {
    duration = 0.2,
    curve = "ease-out",
    animate = function(t, window)
        window:set_scale(0.95 + 0.05 * t, 0.95 + 0.05 * t)
        window:set_opacity(t)
    end
})

garchomp.animate("window_close", {
    duration = 0.15,
    curve = "ease-in",
    animate = function(t, window)
        local inv = 1 - t
        window:set_scale(0.9 + inv * 0.1, 0.9 + inv * 0.1)
        window:set_opacity(inv)
    end
})

garchomp.animate("workspace_switch", {
    duration = 0.25,
    curve = "ease-in-out",
})

-- ═══════════════════════════════════════════
-- Per-Window Rules
-- ═══════════════════════════════════════════

-- Disable corners for Firefox
garchomp.rule({ class = "Firefox" }, {
    blur_behind = true,
    corner_radius = 0,
    opacity = 1.0
})

-- Blur behind terminals
garchomp.rule({ class = "Alacritty" }, {
    blur_behind = true,
    opacity = 0.95
})

garchomp.rule({ class = "kitty" }, {
    blur_behind = true,
    opacity = 0.95
})

-- No effects for video players
garchomp.rule({ class = "mpv" }, {
    shadow_enabled = false,
    corner_radius = 0,
    animations_enabled = false
})

-- Dialogs
garchomp.rule({ title = "Open File" }, {
    shadow_enabled = true,
    corner_radius = 8
})

All Configuration Options

Option	Type	Default	Description
blur_enabled	bool	false	Enable blur effect
blur_strength	int	5	Blur intensity (1-20)
blur_iterations	int	4	Multi-pass blur iterations
shadow_enabled	bool	true	Enable drop shadows
shadow_radius	int	12	Shadow blur radius
shadow_offset_x	int	0	Horizontal shadow offset
shadow_offset_y	int	5	Vertical shadow offset
shadow_opacity	float	0.6	Shadow opacity (0-1)
shadow_color_r/g/b	float	0.0	Shadow color channels (0-1)
corner_radius	float	12.0	Window corner radius
opacity_focused	float	1.0	Focused window opacity multiplier
opacity_unfocused	float	1.0	Unfocused window opacity multiplier
fade_enabled	bool	false	Enable fade animations
fade_in_duration	float	0.1	Fade-in duration (seconds)
fade_out_duration	float	0.1	Fade-out duration (seconds)
vsync	string	"adaptive"	VSync mode (off/on/adaptive)
hdr_enabled	bool	false	Enable HDR rendering
hdr_peak_luminance	int	1000	Display peak luminance (nits)
hdr_paper_white	int	203	SDR white level (nits)
tonemap_operator	string	"aces"	HDR tonemapper

Overview

garchomp is a GPU-accelerated X11 compositor built with Rust and wgpu. It intercepts window rendering via the X11 Composite extension and applies visual effects before presenting to the screen.

Architecture

wgpu - Cross-platform GPU API (Vulkan, Metal, DX12, GL)
EGL - Context creation and pixmap texture import
X11 Composite - Window redirection and overlay window
x11rb - Pure Rust X11 protocol implementation
mlua - Lua 5.4 configuration scripting

Rendering Pipeline

X11 Server
    |
Composite Extension (redirect all windows)
    |
Window Pixmaps (NameWindowPixmap)
    |
EGL Texture Import
    |
wgpu Multi-Pass Pipeline:
    Pass 1: Blur backgrounds (dual kawase)
    Pass 2: Shadow rendering
    Pass 3: Window content (rounded corners)
    Pass 4: Animation transforms
    Pass 5: Final composition + tonemapping
    |
Present to Overlay Window

Blur

garchomp uses a dual Kawase blur algorithm for fast, high-quality background blur. This multi-pass technique is more efficient than Gaussian blur at large radii.

Configuration

garchomp.set("blur_enabled", true)
garchomp.set("blur_strength", 5)  -- 1-20

Per-Window Blur

-- Blur behind terminals
garchomp.rule({ class = "Alacritty" }, {
    blur_behind = true
})

Blur Algorithms

Dual Kawase (default) - Efficient multi-pass, best for large radii
Box - Simple and fast, can look blocky at high strength
Gaussian - Highest quality, slower than Kawase

Note: Blur only affects windows with transparency. Fully opaque windows won't show blur.

Shadows

Drop shadows add depth to windows. Shadows are rendered as a blurred rectangle behind each window.

Configuration

garchomp.set("shadow_enabled", true)
garchomp.set("shadow_radius", 12)      -- Blur amount
garchomp.set("shadow_offset_x", 0)     -- Horizontal offset
garchomp.set("shadow_offset_y", 5)     -- Vertical offset
garchomp.set("shadow_opacity", 0.6)    -- 0.0-1.0
garchomp.set("shadow_color_r", 0.0)   -- Red (0.0-1.0)
garchomp.set("shadow_color_g", 0.0)   -- Green
garchomp.set("shadow_color_b", 0.0)   -- Blue

Shadows use a signed distance field (SDF) shader with smooth fade-out edges. They respect rounded corners automatically.

Disable for Video Players

garchomp.rule({ class = "mpv" }, {
    shadow_enabled = false
})

Rounded Corners

Apply rounded corners to windows using a shader-based mask.

Configuration

garchomp.set("corner_radius", 12)  -- Pixels

Per-Window Override

-- No rounded corners for Firefox
garchomp.rule({ class = "Firefox" }, {
    corner_radius = 0
})

Opacity

Control window transparency with fade animations for open/close.

Configuration

garchomp.set("fade_enabled", true)
garchomp.set("fade_duration", 0.15)  -- Seconds

Focus-Based Opacity

Dim unfocused windows to highlight the active one:

garchomp.set("opacity_focused", 1.0)    -- Active window
garchomp.set("opacity_unfocused", 0.85)  -- Inactive windows

Per-Window Opacity

garchomp.rule({ class = "Alacritty" }, {
    opacity = 0.95
})

Opacity stacks: the final value is rule_opacity × focus_multiplier. Windows can also have _NET_WM_WINDOW_OPACITY set by other tools, which multiplies further.

Custom Lua Animations

Define custom animations using the garchomp.animate() function.

garchomp.animate("window_open", {
    duration = 0.2,          -- Seconds
    curve = "ease-out",      -- Easing function
    animate = function(t, window)
        -- t goes from 0 to 1 over duration
        window:set_scale(0.95 + 0.05 * t, 0.95 + 0.05 * t)
        window:set_opacity(t)
        window:set_offset(0, (1 - t) * 20)
    end
})

Window Methods

window:set_scale(sx, sy) / get_scale() - Scale transform
window:set_offset(x, y) / get_offset() - Translate
window:set_opacity(alpha) / get_opacity() - Transparency (0-1)
window:set_brightness(mult) - Brightness multiplier
window:set_saturation(sat) - Saturation (0-1)
window:set_blur_radius(r) - Blur amount
window:set_corner_radius(r) - Corner radius
window:id() - Get window X11 ID

Per-window rules can also define open_animation and close_animation to override the global trigger for specific windows.

Window Rules

Apply per-window settings using garchomp.rule().

Match Criteria

class - WM_CLASS (e.g., "Firefox")
title - Window title (substring match)
instance - WM_CLASS instance name
type - Window type (e.g., "normal", "dialog", "dock")
fullscreen - Fullscreen state (true/false)

Rule Properties

garchomp.rule({ class = "Firefox" }, {
    blur_behind = true,       -- Enable blur
    corner_radius = 0,        -- Override corners
    opacity = 1.0,            -- Opacity
    shadow_enabled = true,    -- Enable shadows
    animations_enabled = true -- Enable animations
})

Workspace Transitions

When integrated with gar, garchomp receives workspace change events and animates the transition.

garchomp.animate("workspace_switch", {
    duration = 0.25,
    curve = "ease-in-out",
})

The transition direction (left, right, up, down) is received from gar and used to determine the animation direction.

HDR Support

Experimental: garchomp can render in HDR using 10-bit visuals and tonemapping.

Requirements

10-bit display support (check xdpyinfo | grep depth)
GPU driver with HDR support
X11 DeepColor visual (depth 30)

Configuration

garchomp.set("hdr_enabled", true)
garchomp.set("hdr_peak_luminance", 1000)  -- Display peak
garchomp.set("hdr_paper_white", 203)      -- SDR white
garchomp.set("tonemap_operator", "aces")  -- aces, reinhard, hable

VSync Modes

Control frame synchronization to prevent tearing or reduce latency.

off - No sync, may tear but lowest latency
on - Wait for vblank (Fifo), no tearing
adaptive - Mailbox mode, low latency with minimal tearing

garchomp.set("vsync", "adaptive")

IPC / API Reference

Control garchomp at runtime via Unix socket IPC or the garchompctl CLI.

garchompctl Commands

terminal

$ garchompctl ping # Health check

$ garchompctl status # Compositor status (JSON)

$ garchompctl reload # Reload configuration

$ garchompctl set blur true # Enable blur

$ garchompctl set blur false # Disable blur

$ garchompctl set shadows true # Enable shadows

$ garchompctl set blur_strength 10 # Set blur strength

$ garchompctl list # List managed windows

$ garchompctl info 12345678 # Window details

Socket Location

$XDG_RUNTIME_DIR/garchomp.sock

Protocol

JSON messages over Unix socket, newline-delimited.

Request Types

{ "type": "ping" }
{ "type": "reload" }
{ "type": "status" }
{ "type": "set_effect", "effect": "blur", "enabled": true }
{ "type": "set_blur_strength", "strength": 8 }
{ "type": "list_windows" }
{ "type": "get_window_info", "window": 12345678 }
{ "type": "version", "version": 1 }

Response Types

{ "type": "pong" }
{ "type": "ok" }
{ "type": "error", "message": "Unknown effect" }
{ "type": "version", "version": 1, "name": "garchomp" }
{ "type": "status",
  "version": 1,
  "window_count": 5,
  "current_workspace": 1,
  "effects_enabled": {
    "blur": true,
    "shadows": true,
    "animations": true,
    "blur_strength": 5
  },
  "connected_to_gar": true,
  "monitors": [
    { "name": "DP-1", "x": 0, "y": 0, "width": 2560, "height": 1440, "primary": true }
  ]
}
{ "type": "window_info",
  "id": 12345678,
  "x": 100,
  "y": 100,
  "width": 800,
  "height": 600,
  "mapped": true,
  "override_redirect": false,
  "workspace": 1,
  "focused": true,
  "fullscreen": false,
  "class": "Firefox",
  "title": "Mozilla Firefox"
}
{ "type": "window_list", "windows": [...] }

gar Events

Events received from gar window manager:

{ "type": "workspace_changed", "from": 1, "to": 2, "direction": "right" }
{ "type": "focus_changed", "old": 12345678, "new": 87654321 }
{ "type": "window_fullscreen", "window": 12345678, "fullscreen": true }
{ "type": "window_moved", "window": 12345678, "x": 200, "y": 200 }
{ "type": "window_resized", "window": 12345678, "width": 1024, "height": 768 }
{ "type": "window_workspace", "window": 12345678, "workspace": 2 }
{ "type": "sync", "windows": [...], "current_workspace": 1 }

Troubleshooting

Common issues and solutions for garchomp.

Compositor Not Starting

Check DISPLAY environment variable is set
Verify X11 server is running: xdpyinfo
Check Composite extension: xdpyinfo | grep Composite
Run with verbose logging: garchomp -vv

No Effects Visible

Verify config syntax: lua -c ~/.config/gar/init.lua
Check effect states: garchompctl status
Ensure effects are enabled in config
Reload config: garchompctl reload

Performance Issues

Reduce blur_strength (lower = faster)
Try vsync = "on" instead of "adaptive"
Disable HDR if not needed
Check GPU driver is properly installed

Flickering / Tearing

Switch VSync mode: try "on" or "adaptive"
Check GPU driver (prefer Vulkan backend)
Verify no other compositor is running

Window Not Blurred

Window must have transparency (opacity < 1.0)
Check window rule overrides
Blur only affects background behind transparent areas

HDR Not Working

Requires 10-bit display support
Check: xdpyinfo | grep "depth.*30"
GPU driver must support HDR output
HDR is experimental - may not work on all systems

Log Locations

Journal: journalctl --user -u garchomp
Console: run garchomp -vv manually
Set RUST_LOG=garchomp=debug for more detail

Debugging Tips

terminal

$ RUST_LOG=garchomp=debug garchomp # Debug logging

$ Xephyr -br -ac -screen 1920x1080 :1 & # Start nested X

$ DISPLAY=:1 garchomp -vv # Test in Xephyr

$ garchompctl status | jq # Pretty-print status

garchomp

Features

Quick Start Guide

1. Installation

2. Running with gar

3. Essential Commands

4. Configuration File

5. Quick Config

Configuration Reference

Minimal Configuration

Full Configuration Example

All Configuration Options

Overview

Architecture

Rendering Pipeline

Effects

Blur

Configuration

Per-Window Blur

Blur Algorithms

Shadows

Configuration

Disable for Video Players

Rounded Corners

Configuration

Per-Window Override

Opacity

Configuration

Focus-Based Opacity

Per-Window Opacity

Animations

Built-in Animations

Custom Lua Animations

Window Methods

Easing Curves

Window Rules

Match Criteria

Rule Properties

Workspace Transitions

HDR Support

Requirements

Configuration

VSync Modes

Multi-Monitor

gar Integration

Events from gar

IPC / API Reference

garchompctl Commands

Socket Location

Protocol

Request Types

Response Types

gar Events

Troubleshooting

Compositor Not Starting

No Effects Visible

Performance Issues

Flickering / Tearing

Window Not Blurred

HDR Not Working

Log Locations

Debugging Tips