gpui
pixfx-gpui paints live effects into a gpui window: colour with normal blending, light with additive blending, enlarged on the GPU with nearest-neighbour sampling so the pixel art stays crisp.
Requirements
Additive sprites and nearest sampling need a gpui fork. Check it out next to this repository at ../zed-gpui, branch pixfx/additive-sprites. Without it, crates/pixfx-gpui and examples/gpui-web do not build; everything else does, because both are separate cargo workspaces.
cargo test --manifest-path crates/pixfx-gpui/Cargo.toml
Use
Keep one FxScene per window. Play each effect once, tick the scene with real elapsed time, paint each effect during gpui's paint phase where its view stands, then end the frame:
use pixfx_core::{Layer, Options};
use pixfx_gpui::FxScene;
let campfire = pixfx_effects::effect("fire/campfire").ok_or("missing")?;
let mut fx = FxScene::default();
let fire = fx.play(campfire, Options::default())?;
// each frame
fx.tick(dt_seconds)?;
// inside a canvas paint callback
fx.paint(fire, Layer::Both, origin, 4, window)?;
fx.end_frame(window)?;
examples/gpui-web/main.rs is a complete app: a candle and a campfire on a ground, ticked from Instant::now() and repainted every animation frame.
API
FxScene is the gpui shell over a pixfx-scene Scene: the scene decides which frame each effect shows, which frames are shared and when one leaves the atlas; FxScene uploads, paints and drops images.
FxScene::default(), FxScene::with_threads(n)
default() paints each frame on the spot, on the window's thread. with_threads(n) (native only) paints on n threads: each effect is stepped, drawn and turned into images on one of them, and the window's thread only paints images. A frame shows from the window frame after it comes back; until then the effect shows the one it had, so an effect's first frame shows one window frame late. For windows with many effects at once: with 100 fires, the window's thread spends 1.4 ms a frame instead of 81 ms, and 5 threads paint a frame's layers in 30 ms (16 ms for 50 fires).
FxScene::play(effect, opts)
Play an effect on a canvas with glow_margin room on every side; returns its FxHandle.
FxScene::tick(dt)
Advance every effect by dt seconds (an error for NaN, infinite or negative dt). A picture changes only when its clock reaches a new frame (1/30 s for most effects). Finished effects leave.
stop(fx), remove(fx), done(fx)
Let it end (loops fade out, one-shots are cut short), drop it now, or ask whether it is gone.
paint(fx, layer, origin, scale, window)
Paint layer with the effect's origin at origin (logical pixels), each effect pixel scale×scale logical pixels (0 paints as 1). Colour is painted with SpriteBlend::Normal, then light with SpriteBlend::Additive, both with SpriteFilter::Nearest. Call it during the paint phase.
end_frame(window)
Run once after every effect is painted. It drops from the atlas the images replaced or released this frame and, past the byte budget (set_budget, 64 MiB by default), the frames painted least recently, never one painted this frame. bytes() is what the shared frames hold.
A frame is rasterised and uploaded only when no effect has painted it yet. Effects with the same options on the same frame paint the same images, wherever they stand, so twenty campfires cost one upload. Only the occupied rectangle of each layer is uploaded. An effect fading out after stop paints its own images, redrawn once per frame of its clock. Paint a scene into one window only.
Web demo
cd examples/gpui-web
trunk serve --release
Open http://127.0.0.1:8090/ and click the page once: gpui throttles a page that does not have focus, so effects run slowly until it is focused. Add ?backend=webgl or ?backend=webgpu to force a renderer. The console logs the frame rate every two seconds. The first build takes about 5 minutes; later builds take seconds.