Enum SurfaceTarget 

pub enum SurfaceTarget {
    Wayland {
        display: NonNull<c_void>,
        surface: NonNull<c_void>,
    },
    Xcb {
        connection: NonNull<c_void>,
        window: u32,
        visual_id: u32,
    },
    Win32 {
        hinstance: NonNull<c_void>,
        hwnd: NonNull<c_void>,
    },
    AppKit {
        layer: NonNull<c_void>,
    },
    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.

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 *.

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.

Win32

Windows: module instance + window handle.

Fields

hinstance: NonNull<c_void>

HINSTANCE of the module that registered the window class.

hwnd: NonNull<c_void>

HWND.

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 *.

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 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) -> Self

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

Formats the value using the given formatter.

impl Eq for SurfaceTarget

impl Hash for SurfaceTarget

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

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: &Self) -> bool

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for SurfaceTarget