Crate plutonium_engine

Expand description

A small retained/immediate 2D graphics engine built on wgpu.

plutonium_engine provides a window/app runner, sprite and atlas rendering, SVG and raster texture loading, MSDF/raster text rendering, simple retained UI objects, popups, layout helpers, animation helpers, and deterministic RNG utilities for examples and tests.

§Quick start

use plutonium_engine::{
    app::{run_app, WindowConfig},
    utils::Position,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = WindowConfig {
        title: "Plutonium".to_string(),
        width: 800,
        height: 600,
        ..Default::default()
    };

    let mut sprite = None;
    run_app(config, move |engine, _frame, _app| {
        if sprite.is_none() {
            match engine.create_texture_2d("examples/media/player.svg", Position::default(), 1.0) {
                Ok(texture) => sprite = Some(texture),
                Err(err) => {
                    log::warn!("failed to load sprite: {err}");
                    return;
                }
            }
        }

        engine.clear_render_queue();
        if let Some(texture) = &sprite {
            texture.render(engine);
        }
    })?;

    Ok(())
}

§Feature flags

widgets (default): retained widgets such as buttons and text inputs.
layout: anchor/percent layout helpers.
anim: tweening and animation helpers.
raster: PNG/JPEG/raster font helper APIs.
wasm: WebAssembly support helpers, including JavaScript entropy support.

§Coordinates and threading

Positions and sizes are logical pixels with the origin at the top-left corner; +x points right and +y points down. The engine converts logical pixels to device pixels internally using the current DPI scale factor.

Engine objects are single-thread affine. Most retained objects wrap Rc<RefCell<_>> internals and are intentionally !Send/!Sync; create and use them on the same UI/render thread that owns the PlutoniumEngine.

§Backend type stability

Low-level/manual integration APIs intentionally expose wgpu and winit types such as wgpu::Surface, wgpu::SurfaceError, and winit::dpi::PhysicalSize. These signatures are the backend interop layer: callers that create their own surfaces, drive their own event loops, or handle raw keyboard state use the exact backend types pinned by this crate. Upgrading wgpu or winit is therefore a public API change and is handled as part of this crate’s semver surface rather than hidden behind lossy wrapper types.

Re-exports§

pub use app::FrameContext;
pub use app::Key;
pub use app::Keys;
pub use app::PlutoniumApp;
pub use app::WindowConfig;
pub use error::EngineError;
pub use popup::PopupAction;
pub use popup::PopupActionStyle;
pub use popup::PopupConfig;
pub use popup::PopupDismissReason;
pub use popup::PopupEvent;
pub use popup::PopupSize;

Modules§

app: Documentation and public API for app.
camera: Documentation and public API for camera.
error: Documentation and public API for error.
input: Documentation and public API for input.
pluto_objects: Documentation and public API for pluto objects.
popup: Documentation and public API for popup.
renderer: Documentation and public API for renderer.
rng: Deterministic RNG service with per-stream generators. Uses SplitMix64 for seeding and xorshift64* for the stream PRNG. Also supports deriving streams from human-readable names via a fast FNV-1a 64-bit hash.
text: Documentation and public API for text.
texture_atlas: Documentation and public API for texture atlas.
texture_svg: Documentation and public API for texture svg.
traits: Documentation and public API for traits.
ui: Documentation and public API for ui.
utils: Documentation and public API for utils.

Structs§

DrawParams: DrawParams data.
FontLoadOptions: FontLoadOptions data.
HaloStyle: Configurable halo/highlight style for tutorials and guided interactions.
PlutoniumEngine: Core renderer and retained-object registry.
PrewarmConfig: PrewarmConfig data.
QueuedItem: QueuedItem data.
WarmStats: WarmStats data.

Enums§

GlyphSet: Options for glyph set.
HaloFalloff: Curve used to fade halo intensity as it radiates outward.
HaloMode: Halo rendering mode.
HaloPreset: Predefined halo styles for common tutorial/highlight scenarios.
PrewarmPolicy: Options for prewarm policy.
RasterHintingMode: Options for raster hinting mode.
TextureFit: Options for texture fit.