⚡ Beta v0.1.0

garchomp

GPU-accelerated X11 compositor with blur, shadows, and animations

garchomp is the compositor component of the gardesk ecosystem. Built with wgpu for GPU-accelerated rendering, it provides modern desktop effects including blur behind transparent windows, soft shadows, rounded corners, and smooth animations. Integrates with gar window manager for workspace transitions and focus effects. Configuration uses the same Lua format as gar, supporting hot-reload and per-window rules.

View on GitHub Download RPM

🎯 RPM Available

Features

✓
GPU Rendering
Hardware-accelerated compositing via wgpu (Vulkan/Metal/DX12)
✓
Blur Effects
Real-time Gaussian blur behind transparent windows
✓
Window Shadows
Soft drop shadows with configurable radius, offset, and color
✓
Rounded Corners
Configurable corner radius for all windows
✓
Lua Animations
Scriptable animations with custom easing and transforms
✓
Window Rules
Per-window effects based on class, title, or type
✓
HDR Support
High dynamic range rendering with tonemapping
✓
gar Integration
Workspace transitions, focus effects, and shared config

Installation

RPM (Fedora/RHEL)

terminal

$sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo

$sudo dnf install garchomp garchompctl

From Source

terminal

$git clone https://github.com/espadon/gardesk

$cd gardesk/garchomp

$cargo build --release

$sudo cp target/release/garchomp /usr/local/bin/

$sudo cp target/release/garchompctl /usr/local/bin/

Dependencies

wgpu - GPU abstraction (Vulkan, Metal, DX12 backends)
x11rb - X11 protocol bindings
mlua - Lua configuration runtime

Quick Start

Start garchomp as part of your X11 session:

terminal

$garchomp

INFO garchomp compositor starting INFO Initializing GPU renderer for 1920x1080 surface INFO GPU renderer initialized INFO Compositor initialized, tracking 5 windows

With gar Window Manager

When using gar, garchomp starts automatically via systemd:

# ~/.config/systemd/user/garchomp.service
[Unit]
Description=garchomp X11 compositor
PartOf=gar-session.target
After=gar.service

[Service]
ExecStart=/usr/bin/garchomp
Restart=on-failure

[Install]
WantedBy=gar-session.target

CLI Options

terminal

$garchomp --help

garchomp - X11 compositor for gar desktop environment Usage: garchomp [OPTIONS] Options: -d, --display <DISPLAY> X11 display to connect to -c, --config <PATH> Config file path [default: ~/.config/gar/init.lua] -v, --verbose Increase logging verbosity --no-hdr Disable HDR support -h, --help Print help -V, --version Print version

Verbosity Levels

terminal

$garchomp # INFO level logging

$garchomp -v # DEBUG level logging

$garchomp -vv # TRACE level logging

Configuration Locations

garchomp looks for configuration in this order:

~/.config/garchomp/init.lua - Dedicated garchomp config
~/.config/gar/init.lua - Shared with gar (garchomp = ... table)

Control with garchompctl

terminal

$garchompctl status

( "version": 1, "window_count": 5, "current_workspace": 1, "effects_enabled": ( "blur": true, "shadows": true, "animations": true, "blur_strength": 5 ), "connected_to_gar": true )

$garchompctl reload

Reloaded configuration

$garchompctl set-effect blur false

$garchompctl set-blur-strength 10

File Locations

Config: ~/.config/garchomp/init.lua or ~/.config/gar/init.lua
Socket: $XDG_RUNTIME_DIR/garchomp.sock
Logs: journalctl --user -u garchomp.service

Configuration Reference

garchomp uses Lua configuration, compatible with gar's init.lua. You can either use a dedicated ~/.config/garchomp/init.lua or add a garchomp section to ~/.config/gar/init.lua. Configuration supports hot-reload via file watching.

Blur Options

Option	Type	Default	Description
`blur_enabled`	-	false	Enable blur behind transparent windows
`blur_strength`	-	5	Blur intensity (0-20)
`blur_iterations`	-	4	Number of blur passes

Shadow Options

Option	Type	Default	Description
`shadow_enabled`	-	true	Enable window shadows
`shadow_radius`	-	12.0	Shadow blur radius in pixels
`shadow_offset_x`	-	0.0	Horizontal shadow offset
`shadow_offset_y`	-	5.0	Vertical shadow offset
`shadow_opacity`	-	0.5	Shadow opacity (0.0-1.0)
`shadow_color_r`	-	0.0	Shadow color red component (0.0-1.0)
`shadow_color_g`	-	0.0	Shadow color green component (0.0-1.0)
`shadow_color_b`	-	0.0	Shadow color blue component (0.0-1.0)

Corner Options

Option	Type	Default	Description
`corner_radius`	-	12.0	Default corner radius for windows

Opacity Options

Option	Type	Default	Description
`opacity`	-	1.0	Base opacity multiplier for all windows
`opacity_focused`	-	1.0	Opacity for focused windows
`opacity_unfocused`	-	1.0	Opacity for unfocused windows (dimming)

Fade Animation Options

Option	Type	Default	Description
`fade_enabled`	-	false	Enable fade animations
`fade_in_duration`	-	0.1	Window fade-in duration in seconds
`fade_out_duration`	-	0.1	Window fade-out duration in seconds

HDR Options

Option	Type	Default	Description
`hdr_enabled`	-	false	Enable HDR rendering
`hdr_peak_luminance`	-	1000.0	Peak luminance in nits
`hdr_paper_white`	-	203.0	SDR white level in nits
`hdr_tonemap`	-	"aces"	Tonemapping operator (aces, reinhard, hable, none)

VSync Options

Option	Type	Default	Description
`vsync`	-	"adaptive"	VSync mode (adaptive, on, off)

Minimal Configuration

-- ~/.config/garchomp/init.lua

-- Enable blur with moderate strength
garchomp.blur_enabled = true
garchomp.blur_strength = 8

-- Enable shadows
garchomp.shadow_enabled = true
garchomp.shadow_radius = 12.0

-- Rounded corners
garchomp.corner_radius = 10.0

Shared Configuration with gar

-- ~/.config/gar/init.lua

-- gar window manager configuration
gar.keybinds = (
  ( mods = ( "Mod4" ), key = "Return", action = "spawn", args = "alacritty" ),
  -- ... other gar keybinds
)

-- garchomp compositor configuration
garchomp = (
  blur_enabled = true,
  blur_strength = 8,
  shadow_enabled = true,
  shadow_radius = 12.0,
  corner_radius = 10.0,
  fade_enabled = true,
  fade_in_duration = 0.15,
  fade_out_duration = 0.1,
)

Complete Configuration Example

-- ~/.config/garchomp/init.lua

-- Blur behind transparent windows
garchomp.blur_enabled = true
garchomp.blur_strength = 10
garchomp.blur_iterations = 4

-- Window shadows
garchomp.shadow_enabled = true
garchomp.shadow_radius = 15.0
garchomp.shadow_offset_x = 0.0
garchomp.shadow_offset_y = 8.0
garchomp.shadow_opacity = 0.6
garchomp.shadow_color_r = 0.0
garchomp.shadow_color_g = 0.0
garchomp.shadow_color_b = 0.0

-- Rounded corners
garchomp.corner_radius = 12.0

-- Window opacity
garchomp.opacity = 1.0
garchomp.opacity_focused = 1.0
garchomp.opacity_unfocused = 0.9  -- Slightly dim unfocused windows

-- Fade animations
garchomp.fade_enabled = true
garchomp.fade_in_duration = 0.15
garchomp.fade_out_duration = 0.1

-- VSync mode (adaptive, on, off)
garchomp.vsync = "adaptive"

-- HDR rendering (optional)
garchomp.hdr_enabled = false
garchomp.hdr_peak_luminance = 1000.0
garchomp.hdr_paper_white = 203.0
garchomp.hdr_tonemap = "aces"

-- Custom animation for window open
garchomp.animate("window_open", (
  duration = 0.2,
  curve = "ease-out",
  animate = function(t, window)
    -- Scale from 0.9 to 1.0 with fade-in
    window:set_scale(0.9 + t * 0.1)
    window:set_opacity(t)
  end
))

-- Custom animation for window close
garchomp.animate("window_close", (
  duration = 0.15,
  curve = "ease-in",
  animate = function(t, window)
    -- Scale down and fade out
    window:set_scale(1.0 - t * 0.1)
    window:set_opacity(1.0 - t)
  end
))

-- Window rules
garchomp.rule(
  ( class = "Alacritty" ),
  ( blur_behind = true, opacity = 0.95, corner_radius = 8.0 )
)

garchomp.rule(
  ( window_type = "dock" ),
  ( shadow = false, corner_radius = 0.0 )
)

garchomp.rule(
  ( fullscreen = true ),
  ( shadow = false, corner_radius = 0.0, blur_behind = false )
)

Hot Reload

garchomp watches the config file for changes and reloads automatically:

terminal

$# Edit config file in another terminal

$vim ~/.config/garchomp/init.lua

$# garchomp logs:

INFO Config file changed, reloading... INFO Reloaded config: blur=true, shadows=true, corners=12.0px, fade=true

Or manually trigger reload via garchompctl:

terminal

$garchompctl reload

Overview

garchomp is an X11 compositor built for the gardesk desktop environment. Unlike picom or other compositors, garchomp uses GPU-accelerated rendering via wgpu (Vulkan/Metal/DX12) for high performance and modern effects. It integrates tightly with gar window manager for workspace transitions and focus effects.

The compositor handles window composition, blur effects, shadows, rounded corners, and animations. Configuration uses Lua, which can be shared with gar's init.lua or kept in a dedicated file.

Architecture

GPU Rendering

garchomp uses wgpu for GPU-accelerated rendering:

Automatic backend selection (Vulkan, Metal, DX12, OpenGL fallback)
Window textures created from X11 pixmaps via GLX/EGL
Shader-based blur, shadows, and corner rounding
VSync support (adaptive, on, off modes)

Window Tracking

garchomp tracks all mapped windows and their properties:

// Per-window state
struct TrackedWindow (
    id: Window,           // X11 window ID
    pixmap: Pixmap,       // Window contents for texturing
    damage: Damage,       // X11 Damage for change tracking
    x, y, width, height,  // Geometry
    opacity: f32,         // _NET_WM_WINDOW_OPACITY
    window_type: WindowType,  // normal, dock, dialog, etc.
    fullscreen: bool,     // _NET_WM_STATE_FULLSCREEN
    wm_class: String,     // For rule matching
    animations: WindowAnimations,  // Active animations
    rule_overrides: WindowRuleOverrides,  // Per-window effect overrides
)

Damage Tracking

X11 Damage extension tracks which windows have changed:

Only re-upload textures for damaged windows
Damage regions subtracted after processing
Minimizes GPU texture uploads per frame

Overlay Window

garchomp renders to an X11 overlay window that sits above all other windows:

Composite extension provides the overlay window
All client windows are redirected to off-screen pixmaps
Compositor reads pixmaps and renders to overlay

gar Integration

Workspace Sync

garchomp connects to gar via i3-IPC for workspace events:

Receives workspace change notifications with direction
Animates workspace transitions (slide left/right/up/down)
Tracks which windows belong to which workspace
Auto-reconnects if gar restarts

Focus Events

Focus changes trigger opacity animations:

// When focus changes from window A to window B:
// 1. Window A: animate opacity from 1.0 to opacity_unfocused
// 2. Window B: animate opacity from opacity_unfocused to 1.0

// Default: instant change (no animation)
garchomp.opacity_unfocused = 1.0

// With subtle dimming:
garchomp.opacity_unfocused = 0.9
garchomp.fade_enabled = true

Fullscreen Handling

Fullscreen windows are unredirected for direct rendering:

Bypasses compositor for maximum performance (games, video)
No shadows or rounded corners on fullscreen windows
Automatically re-redirects when leaving fullscreen

Animation System

Animation Triggers

Option	Type	Default	Description
`window_open`	-	-	Window is created and mapped
`window_close`	-	-	Window is unmapped/destroyed
`window_minimize`	-	-	Window is minimized
`window_unminimize`	-	-	Window is restored from minimized
`focus_in`	-	-	Window gains focus
`focus_out`	-	-	Window loses focus
`workspace_switch`	-	-	Switching between workspaces

Easing Curves

Available easing functions for smooth animations:

linear - Constant speed
ease-in - Slow start, fast end
ease-out - Fast start, slow end
ease-in-out - Slow start and end
ease-in-quad - Quadratic ease in
ease-out-quad - Quadratic ease out
ease-in-cubic - Cubic ease in
ease-out-cubic - Cubic ease out

Lua Callbacks

Animation callbacks receive progress (0.0-1.0) and a window proxy:

garchomp.animate("window_open", (
  duration = 0.2,
  curve = "ease-out",
  animate = function(t, window)
    -- t: animation progress (0.0 to 1.0, eased)
    -- window: proxy for setting transforms

    -- Scale from 80% to 100%
    window:set_scale(0.8 + t * 0.2)

    -- Fade in
    window:set_opacity(t)

    -- Offset from center (slide up)
    window:set_offset(0, (1.0 - t) * -50)

    -- Adjust corner radius during animation
    window:set_corner_radius(20 - t * 8)
  end
))

Window Rules

Window Matching

Option	Type	Default	Description
`class`	-	-	Match WM_CLASS (e.g., "Firefox", "Alacritty")
`instance`	-	-	Match WM_CLASS instance name
`title`	-	-	Match window title (substring match)
`window_type`	-	-	Match _NET_WM_WINDOW_TYPE (normal, dock, dialog, etc.)
`fullscreen`	-	-	Match fullscreen state (true/false)

Rule Overrides

Option	Type	Default	Description
`blur_behind`	-	-	Enable/disable blur behind this window
`shadow`	-	-	Enable/disable shadow for this window
`opacity`	-	-	Fixed opacity for this window (0.0-1.0)
`corner_radius`	-	-	Corner radius override for this window
`open_animation`	-	-	Custom animation for window open
`close_animation`	-	-	Custom animation for window close

Rule Examples

-- Blur and transparency for terminal
garchomp.rule(
  ( class = "Alacritty" ),
  ( blur_behind = true, opacity = 0.92 )
)

-- No shadow for dock/bar
garchomp.rule(
  ( window_type = "dock" ),
  ( shadow = false, corner_radius = 0.0 )
)

-- Disable effects for fullscreen
garchomp.rule(
  ( fullscreen = true ),
  ( shadow = false, blur_behind = false, corner_radius = 0.0 )
)

-- Custom opacity for specific app
garchomp.rule(
  ( class = "firefox", title = "Picture-in-Picture" ),
  ( opacity = 1.0, shadow = true )
)

-- Different animation for dialogs
garchomp.rule(
  ( window_type = "dialog" ),
  (
    open_animation = (
      duration = 0.15,
      curve = "ease-out",
      animate = function(t, w)
        w:set_scale(0.95 + t * 0.05)
        w:set_opacity(t)
      end
    )
  )
)

Visual Effects

Blur

Gaussian blur behind transparent windows. Uses multi-pass shader for smooth results.

-- Enable blur
garchomp.blur_enabled = true

-- Blur strength (0-20)
-- Higher values = more blur, more GPU usage
garchomp.blur_strength = 8

-- Blur iterations (passes)
-- More iterations = smoother blur, more GPU usage
garchomp.blur_iterations = 4

Blur only affects windows with transparency. Use window rules to enable blur for specific apps:

-- Enable blur for terminals
garchomp.rule(
  ( class = "Alacritty" ),
  ( blur_behind = true )
)

garchomp.rule(
  ( class = "kitty" ),
  ( blur_behind = true )
)

Shadows

Soft drop shadows rendered below windows:

garchomp.shadow_enabled = true
garchomp.shadow_radius = 15.0    -- Blur radius
garchomp.shadow_offset_x = 0.0   -- Horizontal offset
garchomp.shadow_offset_y = 8.0   -- Vertical offset (down)
garchomp.shadow_opacity = 0.6    -- Shadow darkness

-- Shadow color (default black)
garchomp.shadow_color_r = 0.0
garchomp.shadow_color_g = 0.0
garchomp.shadow_color_b = 0.0

Rounded Corners

Apply rounded corners to all windows:

-- Global corner radius
garchomp.corner_radius = 12.0

-- Per-window override
garchomp.rule(
  ( window_type = "dock" ),
  ( corner_radius = 0.0 )  -- No corners for bar
)

Window Opacity

Control window transparency based on focus:

-- Base opacity for all windows
garchomp.opacity = 1.0

-- Focused window opacity
garchomp.opacity_focused = 1.0

-- Unfocused window opacity (subtle dimming)
garchomp.opacity_unfocused = 0.9

Fade Animations

Smooth fade-in/out when windows appear or disappear:

garchomp.fade_enabled = true
garchomp.fade_in_duration = 0.15   -- Seconds
garchomp.fade_out_duration = 0.1   -- Seconds

HDR Rendering

High Dynamic Range rendering with tonemapping (requires HDR-capable display):

garchomp.hdr_enabled = true
garchomp.hdr_peak_luminance = 1000.0  -- Display peak brightness
garchomp.hdr_paper_white = 203.0      -- SDR white level

-- Tonemapping operators:
-- "aces"     - Academy Color Encoding System (cinematic)
-- "reinhard" - Reinhard global operator
-- "hable"    - Uncharted 2 filmic curve
-- "none"     - No tonemapping
garchomp.hdr_tonemap = "aces"

VSync Modes

-- "adaptive" - VSync when possible, tear if behind (recommended)
-- "on"       - Always wait for vsync (no tearing, may lag)
-- "off"      - No vsync (lowest latency, may tear)
garchomp.vsync = "adaptive"

Performance Tips

Blur is expensive - Start with blur_strength 5-8, increase if GPU can handle it
Limit blur windows - Use rules to enable blur only for terminals and specific apps
Fullscreen bypass - Fullscreen windows are automatically unredirected
VSync adaptive - Best balance of smoothness and responsiveness
Disable effects - Use garchompctl to toggle effects for testing

garchompctl CLI

garchompctl communicates with garchomp via a Unix socket for runtime control.

Commands

Option	Type	Default	Description
`reload`	-	-	Reload configuration from disk
`set_effect`	-	-	Enable/disable an effect (blur, shadows, animations, hdr)
`set_blur_strength`	-	-	Set blur strength (0-20)
`get_window_info`	-	-	Get information about a specific window
`list_windows`	-	-	List all managed windows
`ping`	-	-	Health check (returns pong)
`status`	-	-	Get compositor status and statistics
`version`	-	-	Protocol version negotiation

Usage Examples

terminal

$garchompctl status

( "version": 1, "window_count": 8, "current_workspace": 2, "effects_enabled": ( "blur": true, "shadows": true, "animations": true, "blur_strength": 8 ), "connected_to_gar": true, "monitors": [ ("name": "DP-1", "width": 2560, "height": 1440, "primary": true) ] )

$garchompctl reload

("type": "ok")

$garchompctl set-effect blur false

("type": "ok")

$garchompctl set-effect shadows true

("type": "ok")

$garchompctl set-blur-strength 12

("type": "ok")

$garchompctl list-windows

( "type": "window_list", "windows": [ ("id": 12345, "class": "Alacritty", "title": "~", "focused": true), ("id": 12346, "class": "firefox", "title": "GitHub", "focused": false) ] )

IPC Protocol

JSON over Unix socket at $XDG_RUNTIME_DIR/garchomp.sock.

Request Format

// Reload configuration
("type": "reload")

// Toggle effect
("type": "set_effect", "effect": "blur", "enabled": false)

// Set blur strength
("type": "set_blur_strength", "strength": 10)

// Get window info
("type": "get_window_info", "window": 12345)

// List windows
("type": "list_windows")

// Health check
("type": "ping")

// Status
("type": "status")

Response Format

// Success
("type": "ok")

// Error
("type": "error", "message": "Unknown effect: foo")

// Pong (health check)
("type": "pong")

// Status
(
  "type": "status",
  "version": 1,
  "window_count": 8,
  "current_workspace": 2,
  "effects_enabled": (
    "blur": true,
    "shadows": true,
    "animations": true,
    "blur_strength": 8
  ),
  "connected_to_gar": true
)

gar Events

garchomp receives events from gar window manager via i3-IPC:

Option	Type	Default	Description
`workspace_changed`	-	-	Workspace switched (from, to, direction)
`focus_changed`	-	-	Focus changed (old window, new window)
`window_fullscreen`	-	-	Window entered/exited fullscreen
`window_moved`	-	-	Window position changed
`window_resized`	-	-	Window size changed
`window_workspace`	-	-	Window moved to different workspace
`sync`	-	-	Full state sync (windows list, current workspace)

Event Format

// Workspace changed
(
  "type": "workspace_changed",
  "from": 1,
  "to": 2,
  "direction": "right"
)

// Focus changed
(
  "type": "focus_changed",
  "old": 12345,
  "new": 12346
)

// Window fullscreen
(
  "type": "window_fullscreen",
  "window": 12345,
  "fullscreen": true
)

Troubleshooting

GPU Initialization Failed

Check for Vulkan/GPU driver issues:

terminal

$vulkaninfo | head -20

$# If Vulkan not available, try OpenGL fallback:

$WGPU_BACKEND=gl garchomp

Black Screen or No Windows

Verify X11 composite extension:

terminal

$xdpyinfo | grep Composite

$# Should show: Composite

$# Check for other compositors:

$pgrep -a picom

$pgrep -a compton

$# Kill conflicting compositor first

Config Not Loading

Check config file paths and syntax:

terminal

$garchomp -v

INFO Loading dedicated config from ~/.config/garchomp/init.lua # or INFO Loading garchomp section from ~/.config/gar/init.lua

$# Test Lua syntax:

$luac -p ~/.config/garchomp/init.lua

Blur Not Working

Blur only works on windows with transparency:

terminal

$# Check if blur is enabled:

$garchompctl status | grep blur

$# Ensure window has transparency:

$# For Alacritty: set opacity < 1.0 in alacritty.yml

$# For kitty: set background_opacity in kitty.conf

Not Connected to gar

Check gar socket and connection:

terminal

$garchompctl status | grep connected_to_gar

"connected_to_gar": false

$# Check if gar is running:

$pgrep -a gar

$# Check socket exists:

$ls $XDG_RUNTIME_DIR/gar-i3.sock

High CPU/GPU Usage

Reduce effect intensity:

terminal

$# Disable blur (most expensive effect):

$garchompctl set-effect blur false

$# Reduce blur strength:

$garchompctl set-blur-strength 3

$# Disable all animations:

$garchompctl set-effect animations false

Wallpaper Not Showing

garchomp reads the root pixmap set by garbg:

terminal

$# Check if root pixmap is set:

$xprop -root | grep _XROOTPMAP_ID

$# If not set, start garbg:

$garbg set ~/Pictures/wallpaper.jpg

$# garchomp logs on pixmap update:

$journalctl --user -u garchomp | grep "Root pixmap"

Debug Logging

terminal

$garchomp -v # DEBUG level

$garchomp -vv # TRACE level

$# Or via environment:

$RUST_LOG=debug garchomp

$RUST_LOG=garchomp::render=trace garchomp

Known Limitations

X11 only - Wayland is not supported
Single GPU - No multi-GPU support
HDR requires compatible display and driver support
Blur is computationally expensive on integrated GPUs
Some applications request compositor bypass (_NET_WM_BYPASS_COMPOSITOR) which is ignored

Getting Help

GitHub Issues: github.com/espadon/gardesk/issues
Debug logging: garchomp -vv
Check status: garchompctl status