UMG/Slate Coordinate Spaces

1. The Mental Model

Four spaces, nested from the OS desktop down to a single widget. The picture below shows all of them at once — one point P inside a widget, with its coordinates in every space. Windowed PIE on a 4K monitor, viewport scale 2.0; all numbers are self-consistent.

Windowed PIE on a 4K monitor: window at desktop (640, 300), viewport panel offset (160, 220) inside it, viewport scale 2.0. In fullscreen the window and chrome offsets collapse to zero — which is exactly why coordinate bugs hide on dev machines.

2. Conversion Cheat Sheet

Find your starting point in the first column. All functions are callable from both C++ and Blueprint unless noted.

3. Recipes

R1 — Is the mouse over this widget?

The cursor position from GetMousePositionOnPlatform() is desktop-space — exactly the space a widget's cached geometry lives in, so you can test it directly with IsUnderLocation. Render transforms are respected: a rotated widget tests against its rotated bounds. If the widget receives pointer events anyway, IsHovered() is simpler.

const FGeometry& Geom = MyWidget->GetCachedGeometry();
const FVector2D MouseDesktop = UWidgetLayoutLibrary::GetMousePositionOnPlatform();

if (USlateBlueprintLibrary::IsUnderLocation(Geom, MouseDesktop))
{
    // cursor is over the widget (render transforms respected)
}

// Simplest alternative when the widget is hit-testable anyway:
if (MyWidget->IsHovered()) { /* ... */ }

R2 — Where inside the widget did the click land?

Pointer events hand you both pieces: the widget's geometry and the event position. Despite the name, GetScreenSpacePosition() is desktop-space (Slate "absolute"), so it pairs directly with AbsoluteToLocal. No viewport, no DPI, no window offset — the geometry's transform handles all of it, including render transforms.

FReply UMyWidget::NativeOnMouseButtonDown(const FGeometry& InGeometry, const FPointerEvent& InMouseEvent)
{
    // "ScreenSpacePosition" is desktop-space — same space as InGeometry's absolute side
    const FVector2D LocalClick = InGeometry.AbsoluteToLocal(InMouseEvent.GetScreenSpacePosition());

    // Normalised 0..1 position inside the widget (handy for sliders, colour pickers):
    const FVector2D UV = LocalClick / InGeometry.GetLocalSize();

    return FReply::Handled();
}

R3 — Make a widget follow the mouse

GetMousePositionOnViewport() returns a scaled viewport position, so tell SetPositionInViewport not to divide again: pass bRemoveDPIScale = false. The pixel-space route via PlayerController works too — then you keep the default.

// Scaled route — flag must be false:
FVector2D ViewportPos = UWidgetLayoutLibrary::GetMousePositionOnViewport(this);
CursorWidget->SetPositionInViewport(ViewportPos, /*bRemoveDPIScale=*/ false);

// Pixel route — default flag (true) divides for you:
float PixelX, PixelY;
if (GetOwningPlayer()->GetMousePosition(PixelX, PixelY))
{
    CursorWidget->SetPositionInViewport(FVector2D(PixelX, PixelY));
}

R4 — Pin a widget to a world location (nameplates, pings, markers)

ProjectWorldLocationToWidgetPosition projects to game-screen pixels internally, then divides by the DPI scale — its output is already scaled viewport space, even though the output pin is labelled Screen Position (the implementation runs its result through ScreenToViewport). So again: bRemoveDPIScale = false. The return value is false when the point is behind the camera — hide the widget instead of placing it. Use the …WithDistance variant if you also want the depth for distance-based scaling.

FVector2D WidgetPos;
const bool bOnScreen = UWidgetLayoutLibrary::ProjectWorldLocationToWidgetPosition(
    PC, TargetActor->GetActorLocation(), WidgetPos, /*bPlayerViewportRelative=*/ false);

if (bOnScreen)
{
    // Output is already DPI-scaled viewport space — don't let it be divided again:
    Nameplate->SetPositionInViewport(WidgetPos, /*bRemoveDPIScale=*/ false);
}
Nameplate->SetVisibility(bOnScreen ? ESlateVisibility::HitTestInvisible : ESlateVisibility::Hidden);

R5 — Place widget B at widget A's position

LocalToViewport takes a point in widget A's local space and returns both flavours of viewport position. Use Viewport Position (+ flag false) for placement. If both widgets live in the same hierarchy you can skip the viewport entirely and hop through desktop space.

const FGeometry& AnchorGeom = AnchorWidget->GetCachedGeometry();

FVector2D PixelPos, ViewportPos;
USlateBlueprintLibrary::LocalToViewport(
    this, AnchorGeom, FVector2D::ZeroVector /* anchor's top-left */, PixelPos, ViewportPos);

Follower->SetPositionInViewport(ViewportPos, /*bRemoveDPIScale=*/ false);

// Widget → widget directly, no viewport round-trip:
FVector2D InTargetSpace = TargetGeom.AbsoluteToLocal(AnchorGeom.LocalToAbsolute(SomeLocalPoint));

R6 — From a widget point into the world (trace from UI)

Going the other way — say, line-tracing from a custom crosshair widget — DeprojectScreenPositionToWorld expects game-screen pixels, so this is the one place you use the Pixel Position output instead:

FVector2D PixelPos, ViewportPos;
USlateBlueprintLibrary::LocalToViewport(this, CrosshairGeom, CrosshairLocalPoint, PixelPos, ViewportPos);

FVector WorldOrigin, WorldDirection;
if (PC->DeprojectScreenPositionToWorld(PixelPos.X, PixelPos.Y, WorldOrigin, WorldDirection))
{
    // trace along WorldDirection from WorldOrigin...
}

R7 — Game-screen pixels → widget local

When you have a coordinate in game-screen pixels — PlayerController::GetMousePosition, ProjectWorldLocationToScreen, hit results from a scene capture — ScreenToWidgetLocal maps it into a widget's local space. Leave bIncludeWindowPosition at its default (false) — see the gotchas for why setting it to true breaks this.

float MouseX, MouseY;
if (PC->GetMousePosition(MouseX, MouseY))   // game-screen pixels
{
    FVector2D LocalCoord;
    USlateBlueprintLibrary::ScreenToWidgetLocal(
        this, MyWidget->GetCachedGeometry(), FVector2D(MouseX, MouseY), LocalCoord);
    // LocalCoord is now in MyWidget's local space
}

4. The Spaces in Detail

4.1 Desktop space — Slate's "Absolute"

Slate builds every widget's geometry by accumulating transforms from the root down, and the root is placed at the window's desktop position: when a widget is painted, the engine appends the window-to-desktop transform and caches the result (SWidget::Paint → PersistentState.DesktopGeometry, which is what GetCachedGeometry() / GetTickSpaceGeometry() return). So an "absolute" coordinate is measured from the OS virtual-desktop origin (the primary monitor's top-left on Windows), in OS pixels — the engine's own parameter name for it is AbsoluteDesktopCoordinate.

The comment in Geometry.h hedges — "Absolute coordinates could be either desktop or window space depending on what space the root of the widget hierarchy is in" — because during the paint traversal the root is the window. But everything you touch from game or widget code (cached geometry, pointer events, the mouse functions) is desktop-rooted. That's why Geometry.AbsoluteToLocal(MouseEvent.GetScreenSpacePosition()) just works, in every window mode, on every monitor, in PIE and standalone alike.

4.2 Game-screen space (viewport pixels)

The space gameplay code calls "screen": origin at the top-left of the game viewport, units are render-resolution pixels (FViewport size). In PIE the origin is the viewport panel inside the editor window — the chrome offset is already excluded, which is why game-screen code behaves identically in PIE and standalone.

• APlayerController::GetMousePosition — mouse in game-screen pixels
• ProjectWorldLocationToScreen / DeprojectScreenPositionToWorld
• Every ScreenPosition input of USlateBlueprintLibrary (ScreenToWidgetLocal, ScreenToWidgetAbsolute, ScreenToViewport)
• Every PixelPosition output (LocalToViewport, AbsoluteToViewport)

4.3 Viewport space (scaled)

Same origin as game-screen space, divided by the viewport scale (GetViewportScale() — see §6). This is the coordinate system UMG lays widgets out in: a full-screen Canvas Panel spans GetViewportSize() / GetViewportScale() of these units regardless of render resolution. Conversion functions that output a Viewport Position mean this space.

4.4 Widget local space

The coordinate system internal to one widget: origin at its own top-left, X right, Y down, in Slate units. (Size.X, Size.Y) (GetLocalSize()) is the bottom-right corner. Points outside 0..Size — including negative values — are valid; they describe positions beyond the widget's edges, which you'll see when converting a point that isn't over the widget, or doing drag-offset math.

Slate units are resolution-independent layout units, the same idea as CSS pixels or Android dp: pixels = slate_units × scale, where the scale accumulates in FGeometry::Scale. At 1× scale they equal pixels; on a 4K display with a 2× UI scale, 100 Slate units cover 200 pixels.

4.5 Render transforms and paint space

A render transform (SetRenderTransform, SetRenderTransformAngle, SetRenderScale) rotates/scales/shears the widget visually without re-flowing layout. FGeometry tracks two accumulated transforms, and which one a function uses decides whether render transforms are "seen":

So a button rotated 45° is still clickable exactly where you see it, and AbsoluteToLocal on a click gives correct local coordinates inside the rotated frame. What does not change is layout: siblings don't move out of the way, and the layout bounding box stays axis-aligned at the pre-transform position.

5. FGeometry Reference

FGeometry encodes a widget's position, size, and the two accumulated transforms. Get it from GetCachedGeometry() (or the geometry parameter of a paint/input callback) and pass it to conversion functions.

6. DPI Scale: Who Multiplies What

UWidgetLayoutLibrary::GetViewportScale() is the UMG DPI scale: the project's DPI curve (Project Settings → User Interface) evaluated at the current viewport resolution, times the user's application scale. Notably it does not include the OS's native DPI scale — the game layer manager absorbs that before UMG sees any coordinates, so UMG code can treat the platform scale as 1.0.

float Scale = UWidgetLayoutLibrary::GetViewportScale(this);     // UMG DPI scale
FVector2D PixelSize = UWidgetLayoutLibrary::GetViewportSize(this); // game-screen PIXELS

// The relationships:
//   viewport_scaled = game_screen_pixels / Scale
//   layout size of a fullscreen Canvas Panel = PixelSize / Scale

With a 1× scale, pixel and scaled positions are identical — which is exactly why DPI bugs ship: everything looks right on a 1080p dev machine and falls apart on a 4K display or a console UI scale. Test with a non-1 DPI curve value before shipping. The full flag logic for SetPositionInViewport is in the mental model callout; the same rule applies to SetDesiredSizeInViewport (always scaled units, no flag).

7. Multiple Viewports & AddToPlayerScreen

Widgets can be added to the full game viewport or to a per-player screen area. In split-screen these are different regions of the window; even in single-player they have different geometry origins. Pair the add-function with the matching geometry-function:

8. Common Gotchas