Struct Renderer

pub struct Renderer { /* private fields */ }

GPU renderer for a host-owned surface or externally managed render target.

single-pass compositing: a single wgpu::RenderPass is opened per frame, driven by a FrameRenderPlan. Per-layer stencil_ref counters are assigned by FrameRenderPlan::build_cpu, removing the previous StencilFrameState field.

Examples

use ailloli_ui_render_wgpu::Renderer;

assert!(std::mem::size_of::<Renderer>() > 0);

Implementations

impl Renderer

pub fn device(&self) -> &Device

Borrows the device for host resource creation and command recording.

Resources created here are compatible with this renderer’s pipelines and caches. The borrow does not transfer device ownership. This works for both surface-backed renderers and Self::new_with_render_context.

Examples

use ailloli_ui_render_wgpu::Renderer;
fn encoder(ui: &Renderer) -> wgpu::CommandEncoder {
    ui.device().create_command_encoder(&wgpu::CommandEncoderDescriptor {
        label: Some("host and UI frame"),
    })
}

pub fn queue(&self) -> &Queue

Borrows the shared queue for host uploads and submission.

Submit the encoder returned by the host on this queue after recording UI. UI atlas uploads use this same queue; recording alone does not flush them.

Examples

use ailloli_ui_render_wgpu::Renderer;
fn submit(ui: &Renderer, encoder: wgpu::CommandEncoder) {
    ui.queue().submit([encoder.finish()]);
}

pub fn record_layered_to_target_scaled( &mut self, encoder: &mut CommandEncoder, target: BorrowedRenderTarget<'_>, layers: &[LayerPass<'_>], scale: Scale, load_op: TargetLoadOp, ) -> Result<(), TargetRecordingError>

Records UI commands into an encoder and target owned by the host.

This method never acquires a frame, submits an encoder, or presents. It records complete UI render passes, not commands inside an already-open pass. End the host’s preceding render pass before calling it. The renderer retains its pipelines, glyph/icon atlases, and offscreen pool. Its stencil attachment is resized only when the borrowed target’s extent changes; this does not resize a managed window or reconfigure its native surface.

scale.dpr is finite and strictly positive: 1.0 maps one logical UI unit to one physical pixel, and 2.0 maps it to two. Target dimensions remain physical pixels at either scale. A format change requires a renderer whose pipelines were built for that format; resizing alone does not.

Submission order

Preparation can enqueue atlas writes on Self::queue. They are executed before command buffers in its next submission. Submit this UI recording on that queue before recording another frame with the same renderer, including calls to its managed render or capture methods. Recording several UI frames and submitting them together is unsupported: later atlas updates or pooled texture reuse could change resources referenced by earlier commands. A CPU wait for GPU completion is not needed between correctly ordered submissions.

Use TargetLoadOp::Load to overlay an initialized destination, or TargetLoadOp::Clear to replace it. The host may record additional passes after UI, but those passes can of course cover the UI pixels.

Errors

Returns TargetRecordingError::InvalidRenderTarget for zero/oversized extents, a pipeline-format mismatch, nonpositive/nonfinite DPR, an invalid supplied texture descriptor, or a missing COPY_SRC usage for effects. Returns TargetRecordingError::FrameTextureUnavailable when backdrop blur or a non-normal blend is requested without a backing texture. Ordinary UI and foreground-only effects may supply just a view.

These checks occur before recording, uploads, or changes to UI caches. The encoder remains usable after a returned error. The checks cannot verify that a view actually matches its declared texture, metadata, or device; follow the full BorrowedRenderTarget contract.

Panics

Invalid GPU handles or bindings use wgpu’s validation/error handling, which may panic. An invalid layer plan can also panic. Arbitrary GPU validation or panic failures are not rolled back and are not returned as typed errors.

Examples

use ailloli_ui_core::Scale;
use ailloli_ui_render_wgpu::{
    BorrowedRenderTarget, LayerPass, Renderer, TargetLoadOp, TargetRecordingError,
};
fn overlay(
    ui: &mut Renderer,
    target: BorrowedRenderTarget<'_>,
    layers: &[LayerPass<'_>],
) -> Result<(), TargetRecordingError> {
    // The host has already initialized the target on the shared queue.
    let mut encoder = ui.device().create_command_encoder(&Default::default());
    ui.record_layered_to_target_scaled(
        &mut encoder, target, layers, Scale::new(1.0), TargetLoadOp::Load,
    )?;
    ui.queue().submit([encoder.finish()]);
    // Present the host surface here if there is one.
    Ok(())
}

pub fn new_with_surface_target<T>( target: Arc<T>, size: PhysicalExtent, options: RendererOptions, pre_present: Option<Arc<dyn Fn() + Send + Sync>>, ) -> Result<Self, RendererError>

where T: HasWindowHandle + HasDisplayHandle + Send + Sync + 'static,

Creates a renderer from an owned raw-window-handle provider.

Presentation adapters are responsible for converting their native size to PhysicalExtent and for supplying an optional pre-present hook.

Errors

Returns an error when raw handles cannot create a surface, no compatible adapter/device can be opened, or all surface configurations fail.

Panics

May panic if wgpu rejects renderer shader or pipeline creation.

Examples

use std::sync::Arc;
use ailloli_ui_render_wgpu::{PhysicalExtent, Renderer, RendererError, RendererOptions};

fn create<T>(target: Arc<T>) -> Result<Renderer, RendererError>
where
    T: wgpu::rwh::HasWindowHandle
        + wgpu::rwh::HasDisplayHandle
        + Send
        + Sync
        + 'static,
{
    Renderer::new_with_surface_target(
        target,
        PhysicalExtent::new(1280, 720),
        RendererOptions::default(),
        None,
    )
}

pub fn new_with_render_context( context: WgpuRenderContext, options: RendererOptions, ) -> Self

Creates a renderer for an externally managed render target.

The renderer retains context but owns no native surface; swapchain-only entry points return RendererError::RenderTargetUnavailable.

Panics

May panic if wgpu rejects atlas or stencil resource creation.

Examples

use ailloli_ui_render_wgpu::{Renderer, RendererOptions, WgpuRenderContext};

fn create(context: WgpuRenderContext) -> Renderer {
    Renderer::new_with_render_context(context, RendererOptions::default())
}

pub fn new_with_render_context_and_bootstrap( context: WgpuRenderContext, options: RendererOptions, ) -> Self

Compatibility alias for Self::new_with_render_context.

options.bootstrap has no effect until a surface-backed renderer is bootstrapped; detached contexts already own their device and queue.

Examples

use ailloli_ui_render_wgpu::{Renderer, RendererOptions, WgpuRenderContext};

fn create(context: WgpuRenderContext) -> Renderer {
    Renderer::new_with_render_context_and_bootstrap(
        context,
        RendererOptions::default(),
    )
}

pub fn isolated_budget_config(&self) -> IsolatedBudgetConfig

Returns the active per-frame isolated-rendering budget.

Examples

use ailloli_ui_render_wgpu::{IsolatedBudgetConfig, Renderer};

fn budget(renderer: &Renderer) -> IsolatedBudgetConfig {
    renderer.isolated_budget_config()
}

pub fn set_isolated_budget_config(&mut self, config: IsolatedBudgetConfig)

Replaces the budget used when planning subsequent frames.

This does not mutate metrics from the previously completed frame.

Examples

use ailloli_ui_render_wgpu::{IsolatedBudgetConfig, Renderer};

fn reset_budget(renderer: &mut Renderer) {
    renderer.set_isolated_budget_config(IsolatedBudgetConfig::default());
}

pub fn text_measurer(&self) -> &FontMetrics

Returns the renderer’s reusable font metrics engine.

Examples

use ailloli_ui_render_wgpu::Renderer;
use ailloli_ui_text::FontMetrics;

fn metrics(renderer: &Renderer) -> &FontMetrics {
    renderer.text_measurer()
}

pub fn set_text_face_blobs(&mut self, blobs: Arc<HashMap<u64, Arc<[u8]>>>)

Replaces font bytes indexed by runtime face identifier.

The shared map is retained without copying. An absent face causes glyph preparation to record a missing-face event and skip that glyph.

Examples

use std::{collections::HashMap, sync::Arc};
use ailloli_ui_render_wgpu::Renderer;

fn clear_faces(renderer: &mut Renderer) {
    renderer.set_text_face_blobs(Arc::new(HashMap::new()));
}

pub fn resize(&mut self, new_size: PhysicalExtent)

Best-effort resize of the active backend and stencil target.

This method discards surface errors and recreates stencil storage even when native configuration was skipped or deferred. Prefer Self::try_resize when the host needs the precise outcome.

Examples

use ailloli_ui_render_wgpu::{PhysicalExtent, Renderer};

fn resize(renderer: &mut Renderer) {
    renderer.resize(PhysicalExtent::new(1920, 1080));
}

pub fn try_resize( &mut self, new_size: PhysicalExtent, ) -> Result<ResizeOutcome, RendererError>

Resizes the backend and recreates stencil storage after an applied change.

new_size is in physical pixels. Zero dimensions are skipped; an unchanged extent leaves all resources intact.

Errors

Surface-backed renderers propagate unavailability, recreation-required, and configuration failures. Detached contexts resize their virtual config without error.

Examples

use ailloli_ui_render_wgpu::{PhysicalExtent, Renderer, RendererError, ResizeOutcome};

fn resize(renderer: &mut Renderer) -> Result<ResizeOutcome, RendererError> {
    renderer.try_resize(PhysicalExtent::new(1920, 1080))
}

pub fn try_reconfigure_surface( &mut self, new_size: PhysicalExtent, ) -> Result<ResizeOutcome, RendererError>

Forces Surface::configure, including when the requested extent equals the current extent.

This is the recovery entry point for SurfaceError::Lost and SurfaceError::Outdated. A detached render context has no presentation surface and therefore returns RendererError::RenderTargetUnavailable.

Errors

Propagates surface unavailability, format-incompatibility, or native configuration failure. Zero-sized requests return ResizeOutcome::SkippedZero.

Examples

use ailloli_ui_render_wgpu::{PhysicalExtent, Renderer, RendererError, ResizeOutcome};

fn recover(renderer: &mut Renderer) -> Result<ResizeOutcome, RendererError> {
    renderer.try_reconfigure_surface(PhysicalExtent::new(1280, 720))
}

pub fn detach_surface(&mut self) -> bool

Drops the native surface while retaining the GPU context and all device-bound caches for a future presentation reattachment.

Returns true when an attachment was present. Detached render-context mode has no owned native surface and returns false.

Outstanding offscreen frame leases are released first. Device-bound pipelines, atlases, and caches remain valid for compatible reattachment.

Examples

use ailloli_ui_render_wgpu::{Renderer, SurfaceAttachmentState};

fn suspend(renderer: &mut Renderer) {
    let _had_attachment = renderer.detach_surface();
    assert_eq!(renderer.surface_attachment_state(), SurfaceAttachmentState::Detached);
}

pub fn reattach_surface_target<T>( &mut self, target: Arc<T>, size: PhysicalExtent, pre_present: Option<Arc<dyn Fn() + Send + Sync>>, ) -> Result<SurfaceReattachOutcome, RendererError>

where T: HasWindowHandle + HasDisplayHandle + Send + Sync + 'static,

Reattaches a host target through its raw window/display handle traits.

The current instance, adapter, device, queue, pipelines, atlases, and caches are reused when compatible. Otherwise the surface bootstrap is repeated and every device-bound renderer resource is rebuilt safely. size is in physical pixels.

Errors

Detached-context renderers cannot acquire surface ownership. Surface renderers propagate raw-handle, adapter, device, and configuration errors.

Panics

A required context rebuild may panic if wgpu rejects renderer pipeline creation.

Examples

use std::sync::Arc;
use ailloli_ui_render_wgpu::{
    PhysicalExtent, Renderer, RendererError, SurfaceReattachOutcome,
};

fn resume<T>(
    renderer: &mut Renderer,
    target: Arc<T>,
) -> Result<SurfaceReattachOutcome, RendererError>
where
    T: wgpu::rwh::HasWindowHandle
        + wgpu::rwh::HasDisplayHandle
        + Send
        + Sync
        + 'static,
{
    renderer.reattach_surface_target(target, PhysicalExtent::new(1280, 720), None)
}

pub fn surface_attachment_state(&self) -> SurfaceAttachmentState

Reports whether this renderer currently owns a native attachment.

Externally managed render contexts always report Detached because the renderer does not own their targets.

Examples

use ailloli_ui_render_wgpu::{Renderer, SurfaceAttachmentState};

fn state(renderer: &Renderer) -> SurfaceAttachmentState {
    renderer.surface_attachment_state()
}

pub fn try_surface_config(&self) -> Option<&SurfaceConfiguration>

Returns the active presentation configuration, or None while the native surface is detached.

Detached render contexts return their virtual configuration as Some; only a detached native surface returns None.

Examples

use ailloli_ui_render_wgpu::Renderer;

fn width(renderer: &Renderer) -> Option<u32> {
    renderer.try_surface_config().map(|config| config.width)
}

pub fn surface_config(&self) -> &SurfaceConfiguration

Returns the active presentation configuration.

Hosts retaining a renderer across suspension should use Self::try_surface_config while the surface may be detached.

Panics

Panics when a native surface-backed renderer is currently detached.

Examples

use ailloli_ui_render_wgpu::Renderer;

fn format(renderer: &Renderer) -> wgpu::TextureFormat {
    renderer.surface_config().format
}

pub fn surface_capabilities(&self) -> SurfaceCapabilities

Returns current native capabilities or a synthetic detached-context set.

A detached native surface returns an empty set. A detached render context reports its configured format, FIFO, chosen alpha mode, and usage.

Examples

use ailloli_ui_render_wgpu::Renderer;

fn format_count(renderer: &Renderer) -> usize {
    renderer.surface_capabilities().formats.len()
}

pub fn adapter_info(&self) -> AdapterInfo

Queries native adapter information or a stable detached-context sentinel.

The sentinel uses backend Empty, zero vendor/device identifiers, and the name ailloli_ui_render_wgpu detached.

Examples

use ailloli_ui_render_wgpu::Renderer;

fn adapter_name(renderer: &Renderer) -> String {
    renderer.adapter_info().name
}

pub fn surface_config_deferred_reason( &self, ) -> Option<SurfaceConfigDeferredReason>

Returns the current presentation deferral reason, if any.

Externally managed contexts return None; detached native surfaces report Detached.

Examples

use ailloli_ui_render_wgpu::{Renderer, SurfaceConfigDeferredReason};

fn reason(renderer: &Renderer) -> Option<SurfaceConfigDeferredReason> {
    renderer.surface_config_deferred_reason()
}

pub fn isolated_frame_metrics(&self) -> IsolatedFrameMetrics

Metrics from the most recent frame that ran isolated offscreen passes.

Frames reset the counters before planning. The returned snapshot is Copy and remains valid after subsequent rendering.

Examples

use ailloli_ui_render_wgpu::{IsolatedFrameMetrics, Renderer};

fn metrics(renderer: &Renderer) -> IsolatedFrameMetrics {
    renderer.isolated_frame_metrics()
}

pub fn render( &mut self, clear: Color, cmds: &[DrawCmd], ) -> Result<(), RendererError>

Renders one unclipped command slice to the managed surface at DPR 1.

Errors

Returns an error when this renderer has no managed surface, frame acquisition fails, or the acquired frame exposes no copyable texture. Transient capability deferral is treated as a skipped successful frame.

Examples

use ailloli_ui_core::Color;
use ailloli_ui_render_wgpu::{Renderer, RendererError};

fn frame(renderer: &mut Renderer) -> Result<(), RendererError> {
    renderer.render(Color::BLACK, &[])
}

pub fn render_layers( &mut self, clear: Color, layers: &[&[DrawCmd]], ) -> Result<(), RendererError>

Renders multiple unclipped command slices at DPR 1.

Layer order is painter’s order; empty slices remain valid layers.

Errors

Returns the same managed-surface errors as Self::render.

Examples

use ailloli_ui_core::Color;
use ailloli_ui_render_wgpu::{Renderer, RendererError};
use ailloli_ui_runtime::DrawCmd;

fn frame(renderer: &mut Renderer, commands: &[DrawCmd]) -> Result<(), RendererError> {
    renderer.render_layers(Color::BLACK, &[commands, &[]])
}

pub fn render_layers_scaled( &mut self, clear: Color, layers: &[&[DrawCmd]], scale: Scale, ) -> Result<(), RendererError>

Renders multiple unclipped slices with an explicit logical-to-physical scale.

Errors

Returns the same managed-surface errors as Self::render.

Examples

use ailloli_ui_core::{Color, Scale};
use ailloli_ui_render_wgpu::{Renderer, RendererError};

fn frame(renderer: &mut Renderer) -> Result<(), RendererError> {
    renderer.render_layers_scaled(Color::BLACK, &[&[]], Scale::new(2.0))
}

pub fn render_layered( &mut self, clear: Color, layers: &[LayerPass<'_>], ) -> Result<(), RendererError>

Renders layered draw commands to the swapchain (DPR = 1).

Errors

Returns the same managed-surface errors as Self::render_layered_scaled.

Examples

use ailloli_ui_core::Color;
use ailloli_ui_render_wgpu::{LayerPass, Renderer, RendererError};

fn frame(renderer: &mut Renderer) -> Result<(), RendererError> {
    renderer.render_layered(Color::BLACK, &[LayerPass::new(&[])])
}

pub fn render_layered_scaled( &mut self, clear: Color, layers: &[LayerPass<'_>], scale: Scale, ) -> Result<(), RendererError>

Renders layered draw commands with explicit logical-to-physical scale.

The method acquires, records, notifies, and presents one frame. When capabilities are transiently deferred it records a benchmark event and returns Ok(()) without acquiring a texture.

Errors

Returns an error for detached/non-surface backends, frame acquisition failures, or a frame without an accessible texture.

Examples

use ailloli_ui_core::{Color, Scale};
use ailloli_ui_render_wgpu::{LayerPass, Renderer, RendererError};

fn frame(renderer: &mut Renderer) -> Result<(), RendererError> {
    renderer.render_layered_scaled(
        Color::BLACK,
        &[LayerPass::new(&[])],
        Scale::new(1.5),
    )
}

pub fn render_layered_to_target_scaled<T: RenderTarget + ?Sized>( &mut self, clear: Color, layers: &[LayerPass<'_>], scale: Scale, target: &mut T, ) -> Result<(), RendererError>

Renders layered draw commands into an injected RenderTarget.

The target’s frame extent drives physical geometry; scale converts logical coordinates. The frame is presented after the target’s pre-present callback.

Errors

Propagates target acquisition failures and rejects frames that do not expose their backing texture.

Examples

use ailloli_ui_core::{Color, Scale};
use ailloli_ui_render_wgpu::{LayerPass, RenderTarget, Renderer, RendererError};

fn frame<T: RenderTarget + ?Sized>(
    renderer: &mut Renderer,
    target: &mut T,
) -> Result<(), RendererError> {
    renderer.render_layered_to_target_scaled(
        Color::BLACK,
        &[LayerPass::new(&[])],
        Scale::new(2.0),
        target,
    )
}

pub fn render_layered_to_target( &mut self, clear: Color, layers: &[LayerPass<'_>], target: &mut dyn RenderTarget, ) -> Result<(), RendererError>

Renders one layer stack at DPR = 1 into an injected target.

Errors

Returns the same target/frame errors as Self::render_layered_to_target_scaled.

Examples

use ailloli_ui_core::Color;
use ailloli_ui_render_wgpu::{LayerPass, RenderTarget, Renderer, RendererError};

fn frame(
    renderer: &mut Renderer,
    target: &mut dyn RenderTarget,
) -> Result<(), RendererError> {
    renderer.render_layered_to_target(Color::BLACK, &[LayerPass::new(&[])], target)
}

pub fn render_layered_capture_once( &mut self, clear: Color, layers: &[LayerPass<'_>], params: CaptureParams, ) -> Result<CapturedFrame, RendererError>

Renders and readbacks one frame without presenting (for tests / capture).

This convenience overload uses DPR 1. Despite the historical wording, the acquired surface texture is presented after the GPU copy is queued.

Errors

Propagates surface readiness/acquisition, unsupported format, buffer mapping, missing texture, and optional PNG encoding failures.

Examples

use ailloli_ui_core::Color;
use ailloli_ui_render_wgpu::{
    CaptureParams, CapturedFrame, LayerPass, Renderer, RendererError,
};

fn capture(renderer: &mut Renderer) -> Result<CapturedFrame, RendererError> {
    renderer.render_layered_capture_once(
        Color::BLACK,
        &[LayerPass::new(&[])],
        CaptureParams { encode_png: true },
    )
}

pub fn render_layered_capture_once_scaled( &mut self, clear: Color, layers: &[LayerPass<'_>], scale: Scale, params: CaptureParams, ) -> Result<CapturedFrame, RendererError>

Renders, synchronously reads back, and optionally PNG-encodes one frame.

The GPU device is polled with Maintain::Wait; this method blocks until the staging buffer mapping finishes. Output is tightly packed RGBA8 in top-to-bottom row order. BGRA surfaces are converted in place.

Errors

Returns a typed error for deferred capabilities, missing/unsupported frame textures, map/channel failures, or PNG encoding failure.

Examples

use ailloli_ui_core::{Color, Scale};
use ailloli_ui_render_wgpu::{
    CaptureParams, CapturedFrame, LayerPass, Renderer, RendererError,
};

fn capture(renderer: &mut Renderer) -> Result<CapturedFrame, RendererError> {
    renderer.render_layered_capture_once_scaled(
        Color::BLACK,
        &[LayerPass::new(&[])],
        Scale::new(2.0),
        CaptureParams::default(),
    )
}