Enum SurfaceTarget 

pub enum SurfaceTarget {
    Wayland {
        display: NonNull<c_void>,
        surface: NonNull<c_void>,
        transparent: bool,
        main_device: Option<u64>,
    },
    Xcb {
        connection: NonNull<c_void>,
        window: u32,
        visual_id: u32,
        transparent: bool,
        main_device: Option<u64>,
    },
    Win32 {
        hinstance: NonNull<c_void>,
        hwnd: NonNull<c_void>,
        transparent: bool,
    },
    AppKit {
        layer: NonNull<c_void>,
        transparent: bool,
    },
    Web {
        canvas_id: u32,
    },
    Offscreen,
}

A window’s native presentation handles, in the form a HAL backend needs to create a surface.

Produced by crcbl-shell, destructured only by HAL backends. Engine code, samples and the editor pass it through opaquely; a #[cfg] on a platform in a consumer crate is a regression.

Exhaustiveness

This enum is intentionally not #[non_exhaustive]. Adding a platform should break every backend’s match loudly at compile time — the whole engine is one workspace, and a silently-ignored new platform is exactly the failure this type exists to prevent.

Variants and their producers

Variant	Shell backend	Vulkan entry point
Wayland	Wayland (P0)	vkCreateWaylandSurfaceKHR
Xcb	X11 (P0)	vkCreateXcbSurfaceKHR
Web	canvas (P5)	— (WebGPU GPUCanvasContext)
Win32	Win32 (P14)	vkCreateWin32SurfaceKHR
AppKit	AppKit (P14)	vkCreateMetalSurfaceEXT
Offscreen	HeadlessShell	— (image ring, no WSI)

Xlib is absent on purpose: topic 15 links libxcb, not libX11, so no shell backend can produce an Xlib target and a variant nobody constructs is a variant every backend still has to handle.

Transparency travels here

Every variant that names a desktop window carries transparent: the shell sets it from the window’s WindowDesc::transparent (crcbl-shell, named rather than linked, see the module docs), and transparent reads it whatever the platform. The window is what knows it was made transparent, so the renderer learns it from the window’s own handles rather than from a second statement that could disagree. A presenter that sees it asks for premultiplied alpha, and one whose surface cannot composite that way refuses rather than drawing the window opaque.

Web and Offscreen carry no flag. The web shell refuses a transparent window, since what shows through a canvas is the page’s business, so a canvas target is never one; an offscreen ring has no compositor to blend with, and its readback holds whatever alpha the frame wrote either way.

Variants

Wayland

Wayland: wl_display* + wl_surface*, as returned by libwayland-client (topic 15’s WSI-ABI exception — the driver calls libwayland functions on these).

Fields

display: NonNull<c_void>

struct wl_display *.

surface: NonNull<c_void>

struct wl_surface *.

transparent: bool

The window was created transparent. The compositor blends the surface by its buffer’s alpha, so a presenter asks for premultiplied alpha; the surface itself is made the same way.

main_device: Option<u64>

The dev_t of the DRM device the compositor composites on, as zwp_linux_dmabuf_feedback_v1.main_device names it: the GPU a buffer reaches without a copy between devices, which a backend matches to one of its adapters for Instance::display_adapter (crcbl-hal, named rather than linked, see the module docs). None when the compositor offers no zwp_linux_dmabuf_v1 at version 4 or had not answered when the target was read.

Xcb

X11 through XCB: xcb_connection_t* plus the window’s XID.

Fields

connection: NonNull<c_void>

xcb_connection_t *.

window: u32

xcb_window_t — an XID, not a pointer.

visual_id: u32

xcb_visualid_t of the window, needed by some backends to pick a compatible format.

transparent: bool

The window was created transparent. The X11 shell makes every window on the root visual, which has no alpha, and refuses a transparent one, so it always sets this false; the field is here so that a backend reads transparency the same way on every window system.

main_device: Option<u64>

The dev_t of the DRM device the X server renders on, from DRI3 Open — the counterpart of Wayland’s main_device, and matched to an adapter the same way. None without DRI3 (Xvfb has none).

Win32

Windows: module instance + window handle, and whether the window was made for per-pixel transparency.

Fields

hinstance: NonNull<c_void>

HINSTANCE of the module that registered the window class.

hwnd: NonNull<c_void>

HWND.

transparent: bool

The window was created transparent (WS_EX_NOREDIRECTIONBITMAP): it has no redirection surface, so nothing presented to the HWND itself is shown, and a backend must present through DirectComposition with premultiplied alpha.

Windows is the one window system where this changes how a backend makes the surface, not only which alpha its swapchain asks for. A backend that cannot present this way refuses the surface by name rather than drawing into a window that shows nothing.

AppKit

macOS/iOS: a CAMetalLayer*.

The shell creates and owns the layer (attaching it to its NSView), so backends never have to touch AppKit — Metal takes the layer directly and VK_EXT_metal_surface takes it through MoltenVK.

Fields

layer: NonNull<c_void>

CAMetalLayer *.

transparent: bool

The window was created transparent: the shell made the window and this layer non-opaque. A presenter keeps the layer non-opaque and asks for premultiplied alpha, which is how Core Animation blends a layer’s contents.

Web

Web: an integer key into the shell’s JS-side canvas registry.

Topic 15 specifies a hand-rolled JS shim rather than wasm-bindgen, so the canvas is identified by a number the shim assigns — no string allocation crosses the wasm boundary, and this variant stays Copy.

Fields

canvas_id: u32

Registry key handed out by the shell’s JS shim.

Offscreen

No window at all: render into a backend-managed image ring and read back.

HeadlessShell (topic 15) and crcbl screenshot (topic 11) need a target to hand the HAL even though there is nothing to present to. Backends implement this as a swapchain-shaped rotation of offscreen images, which is what makes the P1 golden-image e2e run through the same acquire/present code path as a real window instead of a second, less-tested one.

It deliberately carries no size

It used to carry width and height, and that was a defect. Every other variant names handles, which a resize does not touch — which is exactly why crcbl-shell only requires a target to be re-queried after a mode change. A size made this one variant change value on every resize, so a surface created from an earlier target silently described the wrong extent, and the seam had one rule for five variants and another for the sixth.

The extent comes from where it comes from for every other target: the shell’s WindowState::size, passed to the backend in the swapchain descriptor. crcbl-hal’s swapchain module states that precedence as a backend obligation. (No intra-doc link: this crate must not depend on crcbl-shell — see the module docs.)

Implementations

impl SurfaceTarget

pub const fn platform_name(&self) -> &'static str

A short, stable name for the platform this target names.

For logs and error messages — "wayland", "xcb", "win32", "appkit", "web", "offscreen".

pub const fn transparent(&self) -> bool

Whether the window behind this target was created transparent, so the desktop should show through where the frame’s alpha is below one.

Always false for Web and Offscreen; see the type’s docs for why they carry no flag.

pub const fn is_windowed(&self) -> bool

Whether this target presents to a real window server.

false only for SurfaceTarget::Offscreen. Backends use it to skip WSI extension checks and present-queue selection.

Trait Implementations

impl Clone for SurfaceTarget

fn clone(&self) -> SurfaceTarget

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for SurfaceTarget

impl Debug for SurfaceTarget

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Eq for SurfaceTarget

impl Hash for SurfaceTarget

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for SurfaceTarget

fn eq(&self, other: &SurfaceTarget) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for SurfaceTarget