Goggles

A real-time shader post-processing tool that runs target apps inside a nested compositor and applies shader effects.

zfast-crt

crt-royale

Goggles runs target apps inside a nested Wayland compositor, applies a shader filter chain, and forwards input.

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/crt-lottes-fast.slangp	Pass	Verified	Mesa: RDNA3, Proprietary: Ada

• Shader Compatibility Report - Full compilation status for all RetroArch presets

Build

This project uses Pixi for dependency management and build tasks.

After cloning, initialize the extracted filter-chain/ dependency before configuring or building:

git submodule update --init --recursive

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

For local co-development against a sibling goggles-filter-chain checkout, keep the committed submodule untouched and point CMake at the alternate source tree instead:

cmake --preset debug -DGOGGLES_FILTER_CHAIN_SOURCE_DIR=/abs/path/to/goggles-filter-chain

Build output:

build/<preset>/
├── bin/goggles

Dependency Artifacts

Prebuilt dependency assets consumed by Goggles package recipes are published in:

• https://github.com/goggles-dev/goggles-artifacts
• https://github.com/goggles-dev/goggles-artifacts/releases

Usage

Use pixi run start [-p preset] [goggles_args...] -- <app> [app_args...] to launch the viewer and target together. The -- separator is required so app arguments (like --config) don't get parsed as Goggles options. The preset defaults to debug.

# Quick smoke tests (build as needed)
pixi run start -- vkcube --wsi xcb                            # preset=debug
pixi run start -p release -- vkcube --wsi xcb                 # preset=release
pixi run start -p profile --app-width 480 --app-height 240 -- vkcube --wsi xcb

In default mode, Goggles exits when the target app exits. If the viewer window is closed early, Goggles terminates the launched target process.

For Steam games, prefer a wrapper that launches the game through Goggles: goggles -- %command%.

RetroArch Shaders

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

This downloads from libretro/slang-shaders. All shaders except tracked crt-lottes-fast files 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 - Core shader preset workflow
• Shader Compatibility Report - Full compilation status for all RetroArch presets
• Project Policies - Development rules and conventions
• Roadmap - Development pending work

License

This project is licensed under the MIT License. See LICENSE.

Some bundled third-party files use their own licenses (for example, assets/fonts/OFL.txt and curated shader files under shaders/retroarch/). See THIRD_PART_NOTICES.md.