Crate agg_gui_wgpu 

WgpuGfxCtx — a hardware-accelerated DrawCtx implementation via wgpu.

Platform coverage

Target	Backend
Windows	Vulkan, DX12
macOS / iOS	Metal
Linux / Android	Vulkan
WASM (wasm32-unknown-unknown)	WebGL2 (via wgpu webgl feature)

Scope

This crate is the renderer and nothing else: the DrawCtx implementation, its pipelines and shaders, offscreen framebuffers, screenshot capture, the custom_render hook for widgets that want their own GPU passes, and the Gpu surface bundle that platform shells build their swap-chain on. It contains no widgets, no event loop, and no demo content, so any app can depend on it directly.

Platform shells (winit event loop, browser canvas + rAF loop) live in demo-wgpu, which re-exports this crate for backwards compatibility.

Per-frame usage

ctx.reset(width, height);
ctx.begin_frame(surface_view);   // clear + stash the target view
app.paint(&mut ctx);             // 2-D commands accumulate
ctx.end_frame();                 // flush everything to the GPU
ctx.present(surface_texture);    // drop per-frame handles, then present

Always present through WgpuGfxCtx::present rather than SurfaceTexture::present() directly: the ctx may hold a clone of the back buffer (for screenshots), and on DX12 a clone surviving present makes the next swap-chain resize fail.

Deferred draw command model

Unlike the GL backend which submits draw calls immediately, WgpuGfxCtx accumulates DrawCommand enums during fill() / stroke() / etc., then flushes them all in WgpuGfxCtx::end_frame using a single wgpu::CommandEncoder. This avoids the render-pass borrow lifetime conflict: a RenderPass exclusively borrows its encoder, preventing both from living in the same struct simultaneously.

Coordinate system

All incoming coordinates are Y-up pixel space: origin at the bottom-left of the viewport, positive Y upward. The vertex shader converts to NDC with ndc = (pos / resolution) * 2 - 1. Scissor rects are stored in Y-up form and converted to wgpu’s Y-down framebuffer convention inside end_frame.

Re-exports

pub use gpu::clamp_surface_size;

pub use gpu::surface_acquire_action;

pub use gpu::CopySrc;

pub use gpu::FrameAcquire;

pub use gpu::Gpu;

pub use gpu::GpuConfig;

pub use gpu::GpuInitError;

pub use gpu::RetryWake;

pub use gpu::SurfaceAcquire;

pub use gpu::SurfaceError;

pub use custom_render::SharedCustomRenderer;

pub use custom_render::WgpuCustomRender;

pub use custom_render::WgpuCustomRenderCtx;

pub use ssaa::ssaa_linear_scale;

pub use ssaa::SsaaFramebuffer;

Modules

custom_render

Public hook for user widgets to inject their own wgpu render pass(es) into the agg-gui frame.

gpu

wgpu device + surface bundle and the surface-acquire recovery policy the platform shells share. wgpu device + surface bundle for one OS window, and the surface-acquire recovery policy that goes with it.

pipelines

All wgpu::RenderPipeline objects and associated wgpu::BindGroupLayout resources created once at startup.

ssaa

Re-usable off-screen SSAA framebuffer for widgets that need 3-D / GPU rendering with antialiasing.

Structs

LastEndFrameStats

Wall-clock breakdown of the most recent WgpuGfxCtx::end_frame call.

RectInPixels

A rectangle in framebuffer pixels: origin at the TOP-left of the surface, +Y downward — the same convention the readback buffers use (“first row is the top row”), and deliberately NOT agg-gui’s Y-up drawing space. Callers holding a Y-up widget rect must flip it: y = surface_height - (rect.top).

WgpuGfxCtx

A DrawCtx that renders via wgpu (Vulkan / DX12 / Metal / WebGL2).

WgpuPaintContext

GPU handle passed to widgets via DrawCtx::gl_paint on the wgpu backend.