Struct WgpuSurfaceBundle

pub struct WgpuSurfaceBundle { /* private fields */ }

Reusable GPU context plus an optional host-owned surface attachment.

The target passed to Self::new_with_surface_target or Self::reattach_surface_target is stored by wgpu’s surface so its raw handles remain valid for the entire attachment lifetime.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::WgpuSurfaceBundle;

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

Implementations

impl WgpuSurfaceBundle

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

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

Creates a renderer bundle from any owned raw-window-handle provider.

The physical size is clamped to at least one pixel per dimension in the resulting surface configuration. Adapter candidates are tried in stable device/backend/name order.

Errors

Returns an error when no compatible adapter/device can be opened, the raw handles cannot create a surface, or every candidate rejects surface configuration.

Panics

Pipeline creation may panic if the selected device rejects the renderer shaders or layouts. Native surface-configuration panics are caught and cause the next adapter candidate to be tried.

Examples

use std::sync::Arc;
use ailloli_ui_render_wgpu::{
    pipeline_cache::{SurfaceBootstrapConfig, WgpuSurfaceBundle},
    PhysicalExtent, RendererError,
};

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

pub fn context(&self) -> &SurfaceGpuContext

Returns the reusable device-bound context.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::{SurfaceGpuContext, WgpuSurfaceBundle};

fn context(bundle: &WgpuSurfaceBundle) -> &SurfaceGpuContext {
    bundle.context()
}

pub fn attachment(&self) -> Option<&SurfaceAttachment>

Borrows the native attachment, or returns None while detached.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::{SurfaceAttachment, WgpuSurfaceBundle};

fn attachment(bundle: &WgpuSurfaceBundle) -> Option<&SurfaceAttachment> {
    bundle.attachment()
}

pub fn attachment_state(&self) -> SurfaceAttachmentState

Reports whether a native surface is attached.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::{
    SurfaceAttachmentState, WgpuSurfaceBundle,
};

fn attached(bundle: &WgpuSurfaceBundle) -> bool {
    bundle.attachment_state() == SurfaceAttachmentState::Attached
}

pub fn device(&self) -> &Device

Returns the logical device, including while the surface is detached.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::WgpuSurfaceBundle;

fn device(bundle: &WgpuSurfaceBundle) -> &wgpu::Device {
    bundle.device()
}

pub fn queue(&self) -> &Queue

Returns the submission queue, including while the surface is detached.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::WgpuSurfaceBundle;

fn queue(bundle: &WgpuSurfaceBundle) -> &wgpu::Queue {
    bundle.queue()
}

pub fn pipelines(&self) -> &PipelineCache

Returns the format-specific pipeline cache retained across detachments.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::{PipelineCache, WgpuSurfaceBundle};

fn pipelines(bundle: &WgpuSurfaceBundle) -> &PipelineCache {
    bundle.pipelines()
}

pub fn format(&self) -> TextureFormat

Returns the color format expected by all cached pipelines.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::WgpuSurfaceBundle;

fn format(bundle: &WgpuSurfaceBundle) -> wgpu::TextureFormat {
    bundle.format()
}

pub fn extent(&self) -> PhysicalExtent

Returns the configured physical-pixel extent or the last attached extent.

The remembered value remains available while detached and may contain a zero dimension only if the caller originally supplied one before any successful surface configuration.

Examples

use ailloli_ui_render_wgpu::{pipeline_cache::WgpuSurfaceBundle, PhysicalExtent};

fn extent(bundle: &WgpuSurfaceBundle) -> PhysicalExtent {
    bundle.extent()
}

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

Returns the active surface configuration, or None while detached.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::WgpuSurfaceBundle;

fn configured_width(bundle: &WgpuSurfaceBundle) -> Option<u32> {
    bundle.config().map(|config| config.width)
}

pub fn detach_surface(&mut self) -> bool

Drops only native presentation resources while retaining the GPU context.

Returns true when an attachment was dropped and false when the bundle was already detached. The last configured physical extent is retained.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::{
    SurfaceAttachmentState, WgpuSurfaceBundle,
};

fn detach(bundle: &mut WgpuSurfaceBundle) {
    let _had_surface = bundle.detach_surface();
    assert_eq!(bundle.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,

Attaches a new raw-window-handle target.

The existing context is tried first. If its adapter or pipeline format cannot present to the new surface, a complete context bootstrap is used as a correctness fallback and the outcome tells the renderer to rebuild every device-bound cache.

The existing attachment, if any, is dropped before the new target is tried. size is in physical pixels.

Errors

Returns an error when the raw handles cannot create a surface or neither reuse nor full GPU bootstrap can produce a configured attachment.

Panics

Rebuild may panic if wgpu rejects renderer pipeline creation.

Examples

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

fn reattach<T>(
    bundle: &mut WgpuSurfaceBundle,
    target: Arc<T>,
) -> Result<SurfaceReattachOutcome, RendererError>
where
    T: wgpu::rwh::HasWindowHandle
        + wgpu::rwh::HasDisplayHandle
        + Send
        + Sync
        + 'static,
{
    bundle.reattach_surface_target(target, PhysicalExtent::new(800, 600), None)
}

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

Best-effort resize that discards the detailed outcome or error.

Prefer Self::try_resize when the host must react to deferred surface capabilities or request surface recreation. new_size is in physical pixels; a zero dimension is skipped.

Examples

use ailloli_ui_render_wgpu::{pipeline_cache::WgpuSurfaceBundle, PhysicalExtent};

fn resize(bundle: &mut WgpuSurfaceBundle) {
    bundle.resize(PhysicalExtent::new(1024, 768));
}

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

Reconfigures an attached surface only when its physical extent changed.

Errors

Returns RendererError::RenderTargetUnavailable while detached, RendererError::SurfaceRecreationRequired if the retained pipeline format is no longer supported, or a configuration error if wgpu rejects the update. Zero-sized requests return ResizeOutcome::SkippedZero before attachment state is inspected.

Examples

use ailloli_ui_render_wgpu::{
    pipeline_cache::{ResizeOutcome, WgpuSurfaceBundle},
    PhysicalExtent, RendererError,
};

fn resize(bundle: &mut WgpuSurfaceBundle) -> Result<ResizeOutcome, RendererError> {
    bundle.try_resize(PhysicalExtent::new(1024, 768))
}

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

Reconfigures the presentation surface even when its physical extent is unchanged.

Errors

Returns the same attachment, format, and wgpu configuration errors as Self::try_resize. A zero dimension is still skipped.

Examples

use ailloli_ui_render_wgpu::{
    pipeline_cache::{ResizeOutcome, WgpuSurfaceBundle},
    PhysicalExtent, RendererError,
};

fn recover(bundle: &mut WgpuSurfaceBundle) -> Result<ResizeOutcome, RendererError> {
    bundle.try_reconfigure(PhysicalExtent::new(1024, 768))
}

pub fn reconfigure(&mut self) -> Result<ResizeOutcome, RendererError>

Forces recovery configuration using the current remembered extent.

Errors

Returns the same errors as Self::try_reconfigure.

Examples

use ailloli_ui_render_wgpu::{
    pipeline_cache::{ResizeOutcome, WgpuSurfaceBundle},
    RendererError,
};

fn recover(bundle: &mut WgpuSurfaceBundle) -> Result<ResizeOutcome, RendererError> {
    bundle.reconfigure()
}

pub fn surface_capabilities(&self) -> SurfaceCapabilities

Queries current capabilities or returns an empty set while detached.

The empty detached value is a sentinel; use Self::attachment_state when that distinction matters.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::WgpuSurfaceBundle;

fn format_count(bundle: &WgpuSurfaceBundle) -> usize {
    bundle.surface_capabilities().formats.len()
}

pub fn adapter_info(&self) -> AdapterInfo

Queries information about the retained adapter.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::WgpuSurfaceBundle;

fn backend(bundle: &WgpuSurfaceBundle) -> wgpu::Backend {
    bundle.adapter_info().backend
}

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

Returns the current reason configuration must wait, if any.

Detachment is reported explicitly. An attached surface returns SurfaceConfigDeferredReason::NoFormats or SurfaceConfigDeferredReason::NoPresentModes for transient empty capabilities, otherwise None.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::{
    SurfaceConfigDeferredReason, WgpuSurfaceBundle,
};

fn deferred(bundle: &WgpuSurfaceBundle) -> Option<SurfaceConfigDeferredReason> {
    bundle.surface_config_deferred_reason()
}

pub fn pre_present_notify(&self)

Invokes the host callback associated with the active attachment.

This is a no-op while detached or when no callback was supplied.

Examples

use ailloli_ui_render_wgpu::pipeline_cache::WgpuSurfaceBundle;

fn notify(bundle: &WgpuSurfaceBundle) {
    bundle.pre_present_notify();
}

Trait Implementations

impl RenderTarget for WgpuSurfaceBundle

fn size(&self) -> PhysicalExtent

Returns the current physical-pixel extent.

fn format(&self) -> TextureFormat

Returns the texture format of subsequently acquired frames.

fn acquire_frame(&mut self) -> Result<RenderFrame, RendererError>

Acquires one renderable frame or a typed renderer error.

fn pre_present_notify(&self)

Gives the host a chance to notify its window system before presentation.

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

Requests a new physical-pixel extent.