From 17dbcf83fbecbfadd60da10ee66a22c9e1a5baf4 Mon Sep 17 00:00:00 2001
From: Andrey Kolkov <a.kolkov@gmail.com>
Date: Wed, 29 Jul 2026 18:21:20 +0300
Subject: [PATCH] docs: document logical DIP coordinate space contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All mouse/pointer/scroll coordinates are in logical DIP (device-independent
pixels), consistent with WindowProvider.Size(). Explicitly document that
callers should NOT divide by ScaleFactor — DPI scaling is applied internally
by the framework on all platforms.

Motivated by gogpu#398: user double-scaled coordinates because the godoc
did not clearly state the coordinate space contract.
---
 events.go  |  7 +++++++
 pointer.go | 12 ++++++++----
 scroll.go  |  8 ++++----
 3 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/events.go b/events.go
index b703669..8a176cc 100644
--- a/events.go
+++ b/events.go
@@ -44,14 +44,21 @@ type EventSource interface {
 	OnTextInput(func(text string))
 
 	// Mouse events
+	//
+	// All mouse/pointer coordinates (x, y) are in logical DIP (device-independent
+	// pixels), consistent with WindowProvider.Size(). Do NOT divide by ScaleFactor —
+	// the framework applies DPI scaling internally on all platforms.
 
 	// OnMouseMove registers a callback for mouse movement.
+	// x, y are in logical DIP relative to the window content area.
 	OnMouseMove(func(x, y float64))
 
 	// OnMousePress registers a callback for mouse button press.
+	// x, y are in logical DIP relative to the window content area.
 	OnMousePress(func(button MouseButton, x, y float64))
 
 	// OnMouseRelease registers a callback for mouse button release.
+	// x, y are in logical DIP relative to the window content area.
 	OnMouseRelease(func(button MouseButton, x, y float64))
 
 	// OnScroll registers a callback for scroll wheel events.
diff --git a/pointer.go b/pointer.go
index c59e0de..4848754 100644
--- a/pointer.go
+++ b/pointer.go
@@ -42,12 +42,16 @@ type PointerEvent struct {
 	// The ID remains constant from PointerDown through PointerUp/PointerCancel.
 	PointerID int
 
-	// X is the horizontal position relative to the window content area.
-	// Uses logical pixels (CSS pixels equivalent).
+	// X is the horizontal position relative to the window content area, in
+	// logical DIP (device-independent pixels). Consistent with App.Size() on
+	// all platforms. Do NOT divide by ScaleFactor — DPI scaling is applied
+	// internally by the framework.
 	X float64
 
-	// Y is the vertical position relative to the window content area.
-	// Uses logical pixels (CSS pixels equivalent).
+	// Y is the vertical position relative to the window content area, in
+	// logical DIP (device-independent pixels). Consistent with App.Size() on
+	// all platforms. Do NOT divide by ScaleFactor — DPI scaling is applied
+	// internally by the framework.
 	Y float64
 
 	// Pressure indicates the normalized pressure of the pointer input.
diff --git a/scroll.go b/scroll.go
index a20403c..3b1d96d 100644
--- a/scroll.go
+++ b/scroll.go
@@ -68,12 +68,12 @@ func (p ScrollPhase) String() string {
 //	    }
 //	})
 type ScrollEvent struct {
-	// X is the pointer horizontal position at the time of scrolling.
-	// Uses logical pixels relative to the window content area.
+	// X is the pointer horizontal position at the time of scrolling, in
+	// logical DIP (device-independent pixels). Consistent with App.Size().
 	X float64
 
-	// Y is the pointer vertical position at the time of scrolling.
-	// Uses logical pixels relative to the window content area.
+	// Y is the pointer vertical position at the time of scrolling, in
+	// logical DIP (device-independent pixels). Consistent with App.Size().
 	Y float64
 
 	// DeltaX is the horizontal scroll amount.