Goggles

A hooking-based frame streaming tool with support for RetroArch shader processing.

zfast-crt

crt-royale

Goggles captures Vulkan application frames and shares them across processes using Linux DMA-BUF with DRM format modifiers and cross-process GPU synchronization.

┌───────────────────────────────────────┐
│         Target Application            │
│  ┌─────────────┐                      │
│  │  Swapchain  │                      │
│  └──────┬──────┘                      │
│         │ vkQueuePresentKHR           │
│         ▼                             │
│  ┌─────────────────────────────────┐  │
│  │  Capture Layer                  │  │
│  │  Export DMA-BUF                 │  │
│  └──────────────┬──────────────────┘  │
└─────────────────┼─────────────────────┘
                  │
                  │ Unix Socket + Semaphore Sync
                  ▼
┌─────────────────┼─────────────────────┐
│  Goggles Viewer │                     │
│  ┌──────────────┴──────────────────┐  │
│  │  CaptureReceiver                │  │
│  └──────────────┬──────────────────┘  │
│                 ▼                     │
│  ┌─────────────────────────────────┐  │
│  │  VulkanBackend                  │  │
│  │  Import DMA-BUF ──► FilterChain │  │
│  └─────────────────────────────────┘  │
└───────────────────────────────────────┘

The filter chain transforms captured DMA-BUF images through a series of shader passes before presenting to the display. It supports RetroArch .slangp preset files which define multi-pass post-processing effects (CRT simulation, scanlines, etc.).

                        Shader Preset (.slangp)
                                 │
  ┌──────────────────────────────┼─────────────────────────────┐
  │                              ▼                             │
  │  ┌────────┐     ┌────────┐     ┌────────┐     ┌────────┐   │
  │  │Original│───▶│ Pass 0 │───▶│ Pass 1 │───▶│ Pass N │   │
  │  └────────┘ ┌─▶└────────┘ ┌─▶└────────┘ ┌─▶└────────┘   │
  │       │     │       │      │       │      │       │        │
  │       └─────┴───────┴──────┴───────┴──────┘       ▼        │
  │                                                  Output    │
  └────────────────────────────────────────────────────────────┘
                                                       │
                                                       ▼
                                             ┌───────────────────┐
                                             │ Goggles Swapchain │
                                             └───────────────────┘

Shader Preset Compatibility Database

Status Key

• Verified: Manually inspected; visual output is perfect.
• Partial: Compiles and runs; full feature set or parameters pending review.
• Untested: Compiles successfully; requires human eyes for visual artifacts.

Name	Build	Status	Platform	Notes
crt/crt-royale.slangp	Pass	Partial	Mesa: RDNA3	Full verification pending after the shader parameter controlling support.
crt/zfast-crt.slangp	Pass	Verified	Mesa: RDNA3, Proprietary: Ada

More reports pending validation...

Build

This project uses Pixi for dependency management and build tasks.

pixi run help # view all available tasks and their descriptions
pixi run <task-name> [args]... # run a task

Build output:

build/<preset>/
├── bin/goggles
├── lib/x86_64/libgoggles_vklayer.so
└── share/vulkan/implicit_layer.d/

Usage

Use pixi run start [preset] <app> [app_args...] to launch the viewer and target together. The preset argument is optional and defaults to debug.

# Quick smoke test (build + manifests as needed)
pixi run start vkcube --wsi xcb           # preset=debug
pixi run start release vkcube --wsi xcb   # preset=release

# Standard flow
pixi run build                   # 1. Build the project
./build/debug/bin/goggles        # 2. Run goggles app (receiver)
GOGGLES_CAPTURE=1 vkcube         # 3. Run target app with capture enabled

For Steam games, set launch options:

GOGGLES_CAPTURE=1 %command%

RetroArch Shaders

pixi run shader-fetch            # Download/refresh full RetroArch shaders into shaders/retroarch

This downloads from libretro/slang-shaders. All shaders except zfast-crt are gitignored.

Documentation

See docs/architecture.md for project architecture and design.

Topic-specific docs:

• Threading - Concurrency model and job system
• DMA-BUF Sharing - Cross-process GPU buffer sharing
• Filter Chain - RetroArch shader pipeline
• RetroArch - Shader preset compatibility
• Shader Compatibility Report - Full compilation status for all RetroArch presets
• Project Policies - Development rules and conventions
• Roadmap - Development pending work