Wisp at a glance

wisp is the in-repo 2D renderer that powers Screen Studio's preview, recording HUD, and export pipeline. It's a Pixi-shaped public API on top of wgpu: scene tree, sprite batcher, filter chain, mask system, text.

How it fits

flowchart LR
    Capture[Capture<br/>ScreenCaptureKit / windows-capture / pipewire] --> Stage[wisp::Stage]
    Editor[Editor scene graph] --> Stage
    Stage --> |Renderer::render_stage| Surface[winit surface]
    Stage --> |Renderer::render_stage| RT[RenderTexture]
    RT --> Encode[GStreamer appsrc → encoder → mp4mux]

Wisp owns the visual composition; everything around it (capture, encode, UI) talks to it via the same scene tree. The editor preview and the export pipeline render the same Stage — preview to a window surface, export to a RenderTexture.

Where to read more

The deep dive lives in its own book — every chunk chapter, filter pass, mask permutation, and text variant is documented there:

→ Wisp book — Pixi-shaped API tour, ~50 chunk chapters, text architecture, mask system, headless export, full quickstart.

If you're contributing to the recorder (Tauri shell, capture pipeline, editor surfaces, ui-storybook components), the rest of this project book is the right place. If you're using wisp as a library in some other wgpu app, the wisp book is the standalone reference.

Why a separate book

The wisp crate is publishable to crates.io independent of the recorder. External consumers want a focused reference — the recorder's Tauri integration, capture pipeline, Leptos UI, and storybook discipline are all noise to them. Splitting the books keeps each one short for its actual audience.

This is one of **two** sibling mdBooks deployed to the same GitHub
Pages site:

- **Project book** — `/Screen/` (recorder + capture + encoder + Tauri shell).
- **Wisp book** — `/Screen/wisp/` (renderer-only reference; publishable to crates.io independently).

Cross-references in either book go through the
`mdbook-preprocessor-cross` preprocessor so URLs adapt per book:

- `\{\{wisp-link path/to/chunk\}\}` — emits a relative URL inside
  the wisp book, an absolute `/Screen/wisp/path/to/chunk.html` URL
  from the project book.
- `\{\{shared path/to/fragment.md\}\}` — inlines a markdown
  fragment from `_docs/shared/` (this snippet you're reading is
  one).

Plain markdown links from the wisp book back to the project use
absolute URLs (`/Screen/...`) since the inverse direction is
single-target.

**`wisp` does not depend on `media`, `decode`, `playback`, `capture`,
or any application crate.** The dependency arrows go one way:

- `media` / `decode` / `playback` produce data (BGRA frames, audio
  histograms, geometry) and hand it to `wisp` via standalone types
  it already owns (`VideoTexture`, `Sprite`, `Graphics`).
- `wisp` provides the scene graph; everything else composes against it.

Any change that makes wisp pull from a higher-level crate breaks the
ability to publish wisp to crates.io as a standalone renderer. See
`_docs/wisp-book/src/intro.md` for the publishable-crate contract.