---
title: "Coordinate spaces and display topology"
slug: architecture/coordinates
---


Saccade maps captured pixels, desktop interaction coordinates, and presentation
surfaces without exposing platform geometry types to the portable core. A transform is
direct and epoch tagged. The runtime does not compose a chain of floating-point matrices
in a target or input path.

## Coordinate representation

Portable coordinates use signed Q24.8 values stored in `int32_t`. One unit has 256
subunits, giving one-two-hundred-and-fifty-sixth-unit precision and a range of almost
8.4 million whole units in either direction. Negative desktop origins are ordinary.

The coordinate spaces are:

- `capture`: pixels in one acquired image or crop.
- `desktop`: the platform's unvirtualized interaction space.
- `surface`: backing pixels local to one presentation surface.
- `window`: coordinates local to one source window.

On macOS, one desktop unit is one screen point. ScreenCaptureKit describes content in
screen points and provides the scale to captured output pixels. AppKit converts screen
points to the backing pixels used by a `CAMetalLayer`. On Windows, the process is
per-monitor-v2 DPI aware and one desktop unit is one physical desktop pixel. This keeps
each platform in the same coordinates used by its native input API while preserving the
same target and action semantics.

## Direct transform

The 64-byte transform descriptor contains source and destination bounds, source and
destination space names, a transform epoch, and a 0, 90, 180, or 270 degree clockwise
rotation. Initialization validates every bound and precomputes three Q32.32 scales per
axis:

- A lower scale for conservative near rectangle edges.
- An upper scale for conservative far rectangle edges.
- A nearest scale for points.

Point mapping subtracts the source origin, applies the quarter turn, multiplies by the
nearest scale, shifts, and adds the destination origin. Source and destination endpoints
are handled exactly. A point outside the source bounds is rejected and never clamped.

Rectangle mapping first clips to the source bounds. It maps the half-open near edge down
and the far edge up, so a changed or actionable capture pixel cannot disappear through
quantization. A completely clipped rectangle reports `SACCADE_ERROR_NOT_FOUND`.
Constructing an inverse swaps the spaces and bounds and applies the inverse quarter turn.
Scaling can be many-to-one, so inverse point mapping has bounded quantization error.
Downscaling can merge adjacent subunits within that bound.

Initialization performs the only integer divisions. Mapping uses fixed arithmetic and
does not allocate, lock, retry a compare-and-swap, or read shared state.

## Display catalog

The portable catalog owns at most 16 display records. Each 80-byte record contains:

- The platform display identifier.
- Top-left desktop bounds and work bounds.
- Top, left, bottom, and right safe-area insets.
- Presentation backing width and height.
- Maximum refresh rate and quarter-turn rotation.
- Main, built-in, active, asleep, and mirrored flags.

Records are sorted by display identifier before publication. Reordering the input does
not change the epoch. Geometry, work-area, safe-area, scale, refresh, rotation, display
membership, or flag changes publish a new epoch. Invalid or over-capacity input leaves
the previous 1,296-byte snapshot unchanged. Publication and lookup allocate no memory.

Desktop-to-overlay transforms use the drawable's presented width and height and therefore
have zero additional quarter-turn rotation. AppKit has already oriented those dimensions.
Physical display rotation stays in the catalog for capture correlation. Applying it again
would rotate the overlay twice.

The macOS collector and its statistics are main-thread owned. It obtains the documented
Core Graphics display identifier from `NSScreen.deviceDescription`, uses
`CGDisplayBounds` for the top-left desktop frame, translates AppKit's bottom-left visible
frame into that space, and uses `convertRectToBacking` for drawable dimensions. It does
not use
`CGDisplayPixelsWide` as a proxy for a Retina drawable. Calls from another thread fail
before touching collector state.

Capture, accessibility, scene, overlay, and input work carry the catalog epoch. Results
from an older topology are stale even if their numeric coordinates still happen to fit.

Source: [View the pinned source](https://github.com/Cosmin-B/saccade/blob/d126ab2b05465839bf70702026081b2eaef62257/docs/architecture/coordinates.md) · [Edit this source](https://github.com/Cosmin-B/saccade/edit/main/docs/architecture/coordinates.md)