Goggles

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 9 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Goggles

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/goggles-dev/Goggles)

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

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.

- [Shader Compatibility Report](docs/shader_compatibility.md) - Full compilation status for all RetroArch presets

## Build

This project uses [Pixi](https://pixi.sh) for dependency management and build tasks.

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

```bash
git submodule update --init --recursive
```

```bash
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:

```bash
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`.

```bash
# 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

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

This downloads from [libretro/slang-shaders](https://github.com/libretro/slang-shaders). All shaders except tracked crt-lottes-fast files are gitignored.

## Documentation

See [docs/architecture.md](docs/architecture.md) for project architecture and design.

Topic-specific docs:
- [Threading](docs/threading.md) - Concurrency model and job system
- [DMA-BUF Sharing](docs/dmabuf_sharing.md) - Cross-process GPU buffer sharing
- [Filter Chain](docs/filter_chain_workflow.md) - RetroArch shader pipeline
- [RetroArch](docs/retroarch.md) - Core shader preset workflow
- [Shader Compatibility Report](docs/shader_compatibility.md) - Full compilation status for all RetroArch presets
- [Project Policies](docs/project_policies.md) - Development rules and conventions
- [Roadmap](ROADMAP.md) - Development pending work

## License

This project is licensed under the MIT License. See [LICENSE](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](THIRD_PART_NOTICES.md).

Goggles

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README