Module surface 

The surface host element: the inverse of crate::portal. Where a portal draws an offscreen Bevy camera into the React UI, a surface renders a React UI subtree out into an offscreen Image the app can drape over any 3D mesh/material (a diegetic monitor, a control panel, a curved hologram — with the app’s own shader on top).

Ownership split

The consuming app owns the surface registry (Surfaces): it creates a named surface at a fixed pixel resolution and gets back a Handle<Image> to use as a material texture. React references the same name with <surface name={…}>…</surface>; the bevy-react reconciler spawns that subtree as a detached UI root carrying RSurface, and bind_surfaces spawns a dedicated 2D UI camera that draws the subtree into the registered image (via UiTargetCamera). An unregistered name renders nowhere until the app registers it.

Render model

Each surface is RenderMode::Live (the UI camera renders every frame — the default, correct for animated/interactive UI) or RenderMode::Snapshot (renders once on register/invalidate, then freezes — cheap for static panels). drive_surfaces toggles Camera::is_active.

Interaction

A surface is clickable in-world: tag the mesh that displays the texture with SurfacePointer (the mesh needs UVs). drive_surface_pointer ray-casts the main camera through the cursor, reads the hit UV, and drives a single virtual PointerId::Custom pointer parked on the surface’s image render target. Bevy’s UI picking backend then hit-tests the offscreen subtree and fires the usual Pointer<…> events on the React nodes — which bevy-react’s core turns back into onClick/onPointer* calls. The virtual pointer’s id is published in SurfaceVirtualPointer so the core crate can scope its event collection to it.

Structs

RSurface

Marks a reconciler node as a <surface name=…> detached UI root. The bevy-react reconciler inserts it (and keeps the node out of the on-screen layout); bind_surfaces points its UiTargetCamera at the surface’s offscreen UI camera.

SurfaceCamera

Marks the offscreen 2D UI camera bind_surfaces spawns for a named surface, so drive_surfaces can control its activity for RenderMode::Snapshot.

SurfacePointer

App-facing marker: put this on the 3D entity (mesh) that displays a surface’s texture, naming the surface it shows. drive_surface_pointer ray-casts these meshes so clicking them drives the surface’s React UI. The mesh must have UVs.

SurfaceSpec

Parameters for Surfaces::create.

SurfaceVirtualPointer

Holds the id of the single virtual pointer driving in-world surface clicks, plus the small bit of frame-to-frame state the driver needs. Published so the core crate can recognize (and scope to) surface-originated picking events.

Surfaces

The registry of named UI surfaces. Insert it (the plugin does) and have app systems create surfaces, then use the returned handle as a material texture.

Enums

RenderMode

How often a surface’s UI camera renders into its texture.

UvChannel

Which of a mesh’s UV sets a surface texture is mapped to. Re-exported from bevy_mesh so apps pass the same value to the material’s *_channel fields and to SurfacePointer. An enum to define which UV attribute to use for a texture.

Functions

bind_surfaces

Spawn a UI camera for each registered surface, then bind every <surface> root to its camera (and hide roots whose name isn’t registered, so they never spill onto the main screen). Runs after the reconciler op drain so a freshly-mounted surface binds the same frame.

drive_surface_pointer

Ray-cast the main camera through the cursor at the SurfacePointer meshes and drive the virtual pointer to the hit UV (mapped into the surface’s texture pixels), so Bevy’s UI picking backend hit-tests the offscreen subtree. Emits PointerInput move/press/release events for the SurfaceVirtualPointer.

drive_surfaces

Toggle each surface camera’s activity: always on for RenderMode::Live; on for one frame after a dirty RenderMode::Snapshot, then off. Mirrors the portal crate’s drive_render_targets. Also despawns the camera of a surface that has been removed, so a torn-down surface (e.g. on a scene switch) leaves no orphan camera rendering into a freed texture.

init_surface_pointer

Spawn the virtual surface pointer at startup and publish its id.