Skip to content
Portal Control Protocol

Surface

Overview

Section titled “Overview”

A Surface represents a top-level window or popup managed by the compositor. Each surface belongs to one application and carries its geometry, type, workspace assignment, output mapping, and compositor state flags.

Surfaces are populated by the compositor capability domain, not by application declarations. The compositor creates surface primitives when an application maps a new window and removes them when the window is destroyed. Clients query surfaces through the registry or the session context.

JSON Schema

Section titled “JSON Schema”
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Surface",
  "type": "object",
  "required": ["id", "app_id", "title", "surface_type", "geometry", "state"],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^surf:[a-z0-9-]+$",
      "description": "Unique surface identifier, stable while the surface exists."
    },
    "app_id": {
      "type": "string",
      "description": "Owning application identifier."
    },
    "title": {
      "type": "string",
      "description": "Window title from the shell protocol or application."
    },
    "surface_type": {
      "type": "string",
      "description": "Surface role (toplevel, popup, dialog, etc.)."
    },
    "geometry": {
      "type": "object",
      "required": ["x", "y", "w", "h"],
      "properties": {
        "x": { "type": "integer" },
        "y": { "type": "integer" },
        "w": { "type": "integer", "minimum": 1 },
        "h": { "type": "integer", "minimum": 1 }
      },
      "description": "Position and size in compositor logical coordinates."
    },
    "workspace": {
      "type": ["string", "null"],
      "description": "Workspace ID. Null when the surface is sticky (on all workspaces)."
    },
    "output": {
      "type": ["string", "null"],
      "description": "Output ID this surface is displayed on."
    },
    "state": {
      "type": "object",
      "properties": {
        "focused": { "type": "boolean" },
        "activated": { "type": "boolean" },
        "minimized": { "type": "boolean" },
        "fullscreen": { "type": "boolean" },
        "maximized": { "type": "boolean" },
        "occluded": { "type": "boolean" },
        "floating": { "type": "boolean" }
      },
      "description": "Compositor state flags, multiple can be true at once."
    },
    "atspi2_root": {
      "type": ["string", "null"],
      "description": "Root element ID of the accessibility tree for this surface."
    }
  }
}

Core Types

Section titled “Core Types”

SurfaceId

Section titled “SurfaceId”
pub struct SurfaceId(pub String);
// Format: "surf:{app_client}-{window_index}"

Stable for the lifetime of the surface. If a window is destroyed and recreated, it receives a new ID.

SurfaceType

Section titled “SurfaceType”
pub enum SurfaceType {
    Toplevel,    // regular application window
    Popup,       // popup overlay
    Tooltip,     // tooltip overlay
    Menu,        // menu window
    Dialog,      // modal or modeless dialog
    Subsurface,  // embedded subsurface
    LayerShell,  // panel, notification, or other layer-shell surface
    XdgShell,    // generic xdg-shell surface
}

Geometry

Section titled “Geometry”
pub struct Geometry {
    pub x: i32,
    pub y: i32,
    pub w: u32,  // minimum 1
    pub h: u32,  // minimum 1
}

Coordinates are in compositor logical space, relative to the output origin.

SurfaceState

Section titled “SurfaceState”
pub struct SurfaceState {
    pub focused: bool,
    pub activated: bool,
    pub minimized: bool,
    pub fullscreen: bool,
    pub tiled: Option<TileEdge>,
    pub maximized: bool,
    pub occluded: bool,
    pub floating: bool,
}

Multiple flags can be true simultaneously. A surface can be activated and maximized at the same time, for example.

TileEdge

Section titled “TileEdge”
pub enum TileEdge {
    Left, Right, Top, Bottom,
    TopLeft, TopRight, BottomLeft, BottomRight,
}

None when the surface is not tiled. Tile edges are used for half-screen and quarter-screen snap layouts.

WorkspaceId and OutputId

Section titled “WorkspaceId and OutputId”
pub struct WorkspaceId(pub String);  // e.g., "ws:1"
pub struct OutputId(pub String);     // e.g., "out:HDMI-A-1"

Field Reference

Section titled “Field Reference”

atspi2_root

Section titled “atspi2_root”

When set, this points to the root Element of the accessibility tree for this surface. All elements within the window are descendants of this root. When null, the application has no accessibility support and elements will use compositor-only fallback representations.

state flags

Section titled “state flags”
Flag Meaning
focused Holds keyboard focus
activated Active window of its application (may not have keyboard focus)
minimized Hidden to a taskbar or equivalent
fullscreen Covers the entire output
maximized Maximized within its output
occluded Fully hidden behind other surfaces
floating Not tiled and not maximized

Example

Section titled “Example”
{
  "id": "surf:12-w1",
  "app_id": "com.example.present",
  "title": "Quarterly Report",
  "surface_type": "toplevel",
  "geometry": { "x": 100, "y": 50, "w": 1200, "h": 800 },
  "workspace": "ws:1",
  "output": "out:INTERNAL-1",
  "state": {
    "focused": true,
    "activated": true,
    "minimized": false,
    "fullscreen": false,
    "maximized": false,
    "occluded": false,
    "floating": false
  },
  "atspi2_root": "atspi:::0.5:12/document/frame"
}

This is a focused, activated toplevel on workspace ws:1. The atspi2_root field contains an accessibility tree root, so the full element tree is available for inspection and interaction.

Last updated: