oxiui-render-wgpu — wgpu GPU render backend for OxiUI

oxiui-render-wgpu is the GPU render backend for OxiUI, built on [wgpu]. It provides both the CPU-side preparation stack (texture atlas, draw-call batching, clip/scissor management, resource tracking) and a real headless GPU backend, [WgpuBackend], that initialises an offscreen device, compiles the solid / gradient / textured / instanced / blur / blur_compute / composite WGSL pipelines, rasterizes a [oxiui_core::paint::DrawList] (solid/gradient/textured fills, images, nine-slices, box shadows, backdrop blur, stencil-clipped and blended draws, tessellated fill/stroke paths), and reads pixels back to CPU memory.

wgpu is the Rust graphics boundary for this ecosystem: the crate itself is Rust and links no graphics C/C++ libraries at build time. At runtime, wgpu dispatches to the platform's GPU API — Vulkan, Metal, DX12, or WebGPU — which is provided by the operating system's installed drivers. [gpu::WgpuBackend::headless] acquires an adapter at runtime and gracefully returns [UiError::Unsupported] when no usable GPU is available, so headless CI on machines without a GPU can skip rather than fail. The crate contains a single unsafe block, in [surface::SurfaceContext::from_raw_handles], required to build a windowed swap-chain surface from raw window/display handles; every other module (including the entire headless gpu backend) is free of unsafe.

Installation

[dependencies]
oxiui-render-wgpu = "0.2.1"

Quick Start

CPU-side frame preparation

Batch a DrawList into pipeline-sorted draw batches without touching a GPU:

use oxiui_core::{geometry::Rect, paint::DrawList, Color};
use oxiui_render_wgpu::{WgpuPrep, RenderQuality, ClipRect};

let mut prep = WgpuPrep::new(512, RenderQuality::balanced());
prep.clip.push(ClipRect::new(0.0, 0.0, 100.0, 100.0));

let mut list = DrawList::new();
list.push_rect(Rect::new(10.0, 10.0, 20.0, 20.0), Color(255, 0, 0, 255));

let frame = prep.prepare(&list);
assert_eq!(frame.batches.len(), 1);
assert_eq!(frame.culled_count, 0);

Headless GPU rendering (runtime adapter required)

use oxiui_core::{paint::{DrawList, RenderBackend}, geometry::Rect, Color, UiError};
use oxiui_render_wgpu::WgpuBackend;

# fn main() -> Result<(), UiError> {
// Returns UiError::Unsupported if no GPU adapter is available — skip-friendly.
let mut backend = WgpuBackend::headless(256, 256)?;
backend.set_clear_color(Color(26, 27, 38, 255));

let mut list = DrawList::new();
list.push_rect(Rect::new(32.0, 32.0, 64.0, 64.0), Color(255, 0, 0, 255));
backend.execute(&list)?;

let rgba = backend.readback_rgba()?; // CPU pixel readback
assert_eq!(rgba.len(), 256 * 256 * 4);
# Ok(())
# }

API Overview

WgpuPrep (crate root)

The CPU-side preparation state for the wgpu pipeline.

gpu module — real headless GPU backend

atlas module

Dynamic shelf-based texture atlas with LRU eviction.

batch module

Draw-call batcher grouping commands by pipeline state.

clip module

resource module

Generation-checked GPU resource handles with reference counting.

quality module

error module

surface module — windowed swap-chain (real-time presentation)

Feature-gated bridge modules

Error Mapping

GpuErrorKind classifies hardware errors; map_gpu_error maps them onto [oxiui_core::UiError]:

WgpuBackend::headless returns UiError::Unsupported when no adapter is available and UiError::Backend when device creation fails.

Feature Flags

default is empty — the CPU preparation stack and the headless gpu/surface backends build with zero optional dependencies.

Pure-Rust Status

The crate links no graphics C/C++/Fortran libraries at build time. GPU drivers (Vulkan / Metal / DX12 / WebGPU) are supplied by the operating system at runtime through wgpu, the Rust graphics boundary for the OxiUI ecosystem.

Related Crates

• oxiui — the OxiUI facade crate.
• oxiui-core — RenderBackend, DrawList, DrawCommand, Color, UiError, geometry types.
• oxiui-render-soft — the Pure-Rust CPU software renderer (display-free reference path).
• oxiui-egui — egui/eframe adapter that consumes this crate's wgpu render path.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)