cvkg-render-gpu

Purpose

GPU-accelerated renderer for the CVKG UI framework. Translates scene graphs, SVG content, and compositor output into GPU draw calls via wgpu, targeting Vulkan, Metal, DX12, OpenGL, and WebGL2 from a single codebase.

Boundaries

• Owns all GPU resource management: pipelines, buffers, textures, bind groups, and WGSL shader variants.
• Consumes scene data from cvkg-core, cvkg-compositor, and cvkg-svg-serialize; does not own layout or DOM logic.
• Exposes GpuRenderer as the primary entry point; callers provide a winit window/surface and a RendererConfig.
• Accessibility tree construction is delegated to the accessibility module via AccessKit; input routing is the caller's responsibility.
• The material module and its re-exports (CompiledMaterial, MaterialCompiler, MaterialError, MaterialGraph, MaterialOp) define the material graph that drives pipeline selection at draw time.
• The subsystems module groups self-contained concerns (config, geometry, text, SVG, particles) that can be tested and modified independently.
• WASM/WebGL2 is a first-class target; shader variants with binding_array are swapped for single-texture equivalents on wasm32.

Dependency graph

graph LR
    cvkg_render_gpu[cvkg-render-gpu]

    %% Workspace dependencies
    cvkg_render_gpu --> cvkg_core[cvkg-core]
    cvkg_render_gpu --> cvkg_compositor[cvkg-compositor]
    cvkg_render_gpu --> cvkg_svg_filters[cvkg-svg-filters]
    cvkg_render_gpu --> cvkg_svg_serialize[cvkg-svg-serialize]
    cvkg_render_gpu --> cvkg_runic_text[cvkg-runic-text]

    %% External dependencies
    cvkg_render_gpu --> wgpu[wgpu 29]
    cvkg_render_gpu --> winit[winit 0.30]
    cvkg_render_gpu --> accesskit[accesskit 0.24]
    cvkg_render_gpu --> accesskit_winit[accesskit_winit 0.33]
    cvkg_render_gpu --> accesskit_unix["accesskit_unix 0.21<br/>optional, linux only"]
    cvkg_render_gpu --> glam[glam 0.30]
    cvkg_render_gpu --> naga[naga 29]
    cvkg_render_gpu --> lyon[lyon 1.0]
    cvkg_render_gpu --> usvg[usvg 0.47]
    cvkg_render_gpu --> image[image 0.25]
    cvkg_render_gpu --> lru[lru 0.12]
    cvkg_render_gpu --> rayon[rayon 1.12]
    cvkg_render_gpu --> swash[swash 0.2]
    cvkg_render_gpu --> roxmltree[roxmltree 0.21]
    cvkg_render_gpu --> serde[serde 1.0]
    cvkg_render_gpu --> serde_json[serde_json 1.0]
    cvkg_render_gpu --> futures[futures 0.3]
    cvkg_render_gpu --> bytemuck[bytemuck 1.14]
    cvkg_render_gpu --> log[log 0.4]

    %% Reverse dependents
    cvkg_render_native[cvkg-render-native] --> cvkg_render_gpu
    cvkg_test[cvkg-test] --> cvkg_render_gpu
    cvkg_gallery[cvkg-gallery] --> cvkg_render_gpu
    cvkg[cvkg] --> cvkg_render_gpu
    berserker[berserker] --> cvkg_render_gpu
    adele_web[demos/adele-web] --> cvkg_render_gpu
    berserker_fire_web[demos/berserker-fire-web] --> cvkg_render_gpu

Public API overview

Re-exports (top-level)

Modules

Usage example

use cvkg_render_gpu::{
    GpuRenderer, RendererConfig,
    CompiledMaterial, MaterialCompiler,
    SkylinePacker,
};
use winit::event_loop::EventLoop;
use winit::window::Window;

fn main() {
    let event_loop = EventLoop::new().unwrap();
    let window = Window::new(&event_loop).unwrap();

    // Initialize the renderer (blocking; uses pollster internally)
    let config = RendererConfig::default();
    let renderer = GpuRenderer::new(&window, config).expect("renderer init");

    // The renderer now owns the wgpu device, queue, and surface.
    // Call renderer.render(&scene) each frame with updated scene data.

    // Material compilation (optional, for custom materials):
    let compiler = MaterialCompiler::new();
    // ... define a MaterialGraph, then:
    // let compiled: CompiledMaterial = compiler.compile(&graph).unwrap();

    // Atlas packing:
    let mut packer = SkylinePacker::new(2048, 2048);
    let pos = packer.pack(256, 128);
    assert!(pos.is_some());
}

Use cases

• Desktop and web UI rendering — drives the full CVKG compositor pipeline on GPU, from SVG scene graphs to final composited frames.
• SVG filter effects — hardware-accelerated SVG filters (blur, color matrix, displacement) via the filter module.
• Material-driven pipelines — custom WGSL materials compiled through the material graph system (MaterialCompiler → CompiledMaterial).
• Accessibility — produces an AccessKit tree from the rendered scene so screen readers and assistive tech can navigate the UI.
• Color-blind simulation — ColorBlindMode applies Daltonization or simulation matrices in a tonemap pass.
• Particle systems — GPU-driven particle simulation and rendering via the particles subsystem.
• Text rendering — shaped and rasterized text via cvkg-runic-text and swash, packed into atlases with SkylinePacker.
• Multi-platform deployment — native (Vulkan/Metal/DX12) and web (WebGL2) from the same crate, with automatic shader variant selection on wasm32.

Edge cases and limitations

• WASM texture arrays — binding_array<texture_2d<f32>> is not supported on WebGL2. Three shader files (common, material_opaque, bloom) have _wasm variants that use single textures instead. If you add new shaders that use binding arrays, you must also provide a WASM variant.
• Surface format negotiation — GpuRenderer requests a surface format from wgpu; if the adapter cannot provide a compatible format, initialization fails. Headless or offscreen rendering requires a surface-compatible target.
• Atlas overflow — SkylinePacker::pack returns None when a rectangle exceeds atlas dimensions. Callers must handle this (e.g. allocate a new atlas page).
• Thread safety on WASM — wgpu on wasm32 requires the fragile-send-sync-non-atomic-wasm feature. Types that are Send + Sync on native are intentionally !Send / !Sync on WASM. Do not share GpuRenderer across web workers.
• Rayon on WASM — parallel iteration via rayon on wasm32 requires wasm-bindgen-rayon and a SharedArrayBuffer-capable environment (COOP/COEP headers).
• naga in build scripts — naga is a build dependency used to validate/translate WGSL at compile time. Build failures in build.rs will surface as compile errors even if the Rust source is correct.
• AccessKit platform backends — on Linux/BSD, accesskit_unix is an optional dependency. Without it, the accessibility module cannot connect to AT-SPI; it will compile but tree updates are silently dropped.

Build flags / features / env vars

| Name | Type | Default | Effect | |---|---|---| | pillage | Feature | off | Enables the pillage feature flag (crate-internal capability gate). | | RUST_LOG | Env var | — | Controls log crate output. Set to cvkg_render_gpu=debug for renderer diagnostics, or wgpu=error for GPU validation warnings. | | WGPU_ADAPTER_NAME | Env var | — | Non-wasm32 only. Case-insensitive substring match against adapter/driver name. Forces selection of a specific GPU adapter (e.g. WGPU_ADAPTER_NAME=nvidia). | | WGPU_BACKEND | Env var | — | Passed through to wgpu; e.g. WGPU_BACKEND=vulkan forces a specific backend. | | naga (build-dep) | Build dependency | — | Used in build.rs to validate WGSL shader source at compile time. No runtime effect. |