Core · spatial

Portal Spatial — Spatial Computing Core

The spatial protocol that defines where windows appear in AR space. Manages zones (center, left/right peripheral, overlay), dimensions (Desktop, VR, AR, Tablet), and the assignment engine that maps windows to zones based on position and policy.

portal-spatialv0.2.0spatial

6.5K

Lines of Code

323

Tests

Files

Architecture

The crate is organized into 8 modules: zone (zone types and registry), dimension (dimension configurations and active state tracking), assignment (policy engine for zone assignment), ipc (binary protocol over Unix socket), homography (DLT solver and matrix operations), ffi (C ABI for C++ interop), auth (zone authorization), and replay (window state replay for crash recovery). The IPC protocol supports 6 message types: AssignZone, SwitchDimension, QueryStatus, UpdateHomography, NotifyError, and Response.

Overview

portal-spatial is the foundational library for Portal's spatial computing paradigm. It provides the zone management system that controls where application windows appear in the user's field of view through AR glasses. The library defines four spatial zones — Center (primary viewing area), LeftPeripheral, RightPeripheral, and Overlay — and four dimensions (Desktop, VR, AR, Tablet) that represent different spatial configurations of these zones. An assignment engine uses configurable policies to map windows to zones based on their position, app identity, and current dimension state. The library also includes a homography solver (DLT-based) for perspective transform computation, an IPC server protocol for cross-process communication via Unix socket at /run/portal/spatial.sock, and C FFI bindings for integration with the C++ Wayfire plugin shim.

Key Types

ZoneIdEnum with 4 variants: Center, LeftPeripheral, RightPeripheral, Overlay. Determines spatial placement.

ZoneRegistryRegistry of all available zones with their properties and spatial relationships.

DimensionSpatial configuration (Desktop, VR, AR, Tablet) that defines which zones are active and their layout.

ActiveDimensionThread-safe tracker for the currently active dimension. Supports atomic dimension switching.

AssignmentEngineApplies an AssignmentPolicy to determine which zone a view/window should be assigned to based on position.

DefaultAssignmentPolicyDefault policy: center zone for center positions, peripheral zones for off-center positions.

HomographySolverDLT (Direct Linear Transform) solver for computing homography matrices from point correspondences.

IpcServerUnix socket server at /run/portal/spatial.sock that accepts zone/dimension commands from portal-wm.

Modules

zone

Zone type definitions — ZoneId enum (Center/LeftPeripheral/RightPeripheral/Overlay), Zone struct, ZoneRegistry for lookups.

dimension

Dimension configurations — Desktop/VR/AR/Tablet layouts, DimensionRegistry for dimension lookup, ActiveDimension for thread-safe state tracking.

assignment

Zone assignment engine and policies — maps views to zones based on position, app_id, and configurable rules.

ipc

Binary IPC protocol over Unix socket — message types (AssignZone, SwitchDimension, QueryStatus, UpdateHomography), encoding/decoding, server and client.

homography

Homography matrix operations — DLT solver for perspective transforms, matrix decomposition, point transformation.

ffi

C FFI bindings for C++ Wayfire plugin integration — creates assignment engines, applies zone assignments from C++ code.

auth

Zone authorization — controls which views can be placed in which zones based on permission rules.

replay

Window state replay — ReplayWindow tracks recent assignments for crash recovery, ReplayVerdict determines replay decisions.

Data Flow

portal-wm detects new windows → classifies by app_id → assigns zone via ZonePolicy → sends AssignZone IPC message → portal-spatial plugin (in Wayfire) applies the assignment

Dependencies

Internal (1)

portal-common

External (9)

nalgebra 0.33serde 1serde_json 1.0postcard 1.0thiserror workspacetracing 0.1tracing-subscriber 0.3hmac workspacesha2 workspace

Depends on portal-common for shared utilities. External: nalgebra (linear algebra), serde/postcard (serialization for IPC), thiserror (error types), tracing (logging).