Coordinate spaces¶
Tick UI works in two coordinate systems. Layout space is the reference resolution your code targets. Screen space is the pixel size of the actual render target. This page explains the split, when each one applies, and how to convert between them.
Why two coordinate systems exist¶
Games run on a wide range of resolutions. Tick UI lets your code target a single reference resolution, typically 1920×1080, and scales that resolution to the actual screen each frame. The split keeps every layout call independent of the current screen size, so UI code stays readable and portable between projects.
Layout space¶
Layout space is where your DoUI code lives. The origin sits at the
top-left of the reference rect. The X axis grows to the right; the Y
axis grows downward. Units are layout pixels, sized relative to the
active reference resolution.
When you write using (ui.Auto().Top(64)), the 64 is in layout
pixels, not screen pixels. Tick UI converts to screen pixels
when it pushes the rect.
Screen space¶
Screen space is where rendering and input happen. The origin sits at the top-left of the render target. Units are physical render-target pixels.
For URP projects with render scale not equal to 1.0, the render target is smaller or larger than the OS window. The drawer tracks the actual target size and converts pixel positions to clip space against it. For the integration mechanics, refer to Render pipelines.
The reference-resolution map¶
Configuration.AspectRatioLayouts maps an aspect ratio to a
reference (width, height). BeginFrame takes the frame size you
pass it (typically Screen.width and Screen.height), computes the
aspect ratio, and picks the closest entry in the map.
The default BaseGameUI configuration covers common ratios:
| Aspect ratio | Reference resolution |
|---|---|
| 16:9 | 1920×1080 |
| 16:10 | 1920×1200 |
| 4:3 | 1600×1200 |
| 21:9 | 2560×1080 |
| 32:9 | 3840×1080 |
Override CreateConfiguration in your BaseGameUI subclass to add
or replace entries. For the field reference, refer to
Configuration.
The conversion API¶
ui.LayoutToScreen(rect) converts a layout-space rect to screen
space. ui.ScreenToLayout(point) converts the other direction.
BeginFrame recomputes the cached scale factors that back these
conversions, so each call is a couple of multiplies.
Most user code does not call these directly. The layout helpers
(Top, Center, Pad, the schemas) call LayoutToScreen for you
when they push onto the rect stack.
Inputs arrive in screen pixels¶
Mouse and touch positions arrive from the active IInput provider in
screen-space pixels with the Y axis matching Unity's convention
(origin at the bottom-left). BeginFrame flips Y to match the
top-left origin used elsewhere, so panels and widgets work in a
consistent system.
For the input provider details, refer to Architecture. For the focus-resolution use of the flipped position, refer to Input and focus.
What the rect stack stores¶
A LayoutRect pushed via PushRect, Pad, Top, or any other
helper holds its Rect in layout-space-converted-to-screen pixels.
That is, the conversion happens at push time, and the rest of the
frame works in the converted form. Peek() returns that
post-conversion (screen-space) rect.
For the per-frame stack-balance contract, refer to Stacks.
Additional resources¶
- Frame lifecycle: when the scale cache
refreshes (
BeginFrame). - Stacks: the rect stack stores screen-space rects.
- Layout: the API surface that uses conversion under the hood.
- Configuration: the field reference for the aspect-ratio map.
- Handle resize: adding an aspect ratio at runtime.