Skip to content

Commit a7290ba

Browse files
amartya4256HeikoKlare
authored andcommitted
Added documentation about SWT's Coordinate System
This Commit adds the documentation about SWT's new Coordinate system which aids to the monitor specific scaling on windows.
1 parent 88fffd8 commit a7290ba

2 files changed

Lines changed: 50 additions & 0 deletions

File tree

docs/hidpi-support-for-windows-dev-guide.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -366,6 +366,56 @@ Existing usages or extensions of SWT could (implicitly) rely on a static zoom fo
366366
As GDI/GDI+ works with integer pixels, but SWT uses a point coordinate system, fractional zooms (e.g., 125%, 150%) can lead to rounding issues and scaling can lead to slight inaccuracies.
367367
Especially on zooms like 125% and 175%, rendering and layout changes must be carefully tested.
368368

369+
### Coordinate System
370+
371+
SWT's HiDPI support requires coordinating between Windows' pixel-based coordinate system and SWT's point-based coordinate system.
372+
The coordinate mapping strategy differs between *static* and *dynamic* HiDPI support modes.
373+
374+
#### Windows vs SWT Coordinate Systems
375+
376+
**Windows Coordinate System:**
377+
- Uses absolute pixel values independent of zoom levels
378+
- Primary monitor always positioned at `(0, 0)`
379+
- Other monitors positioned relative to primary monitor
380+
381+
**Example: Two 1000×1000px monitors**
382+
- **Left monitor as primary:** Left `(0, 0, 1000, 1000)`, Right `(1000, 0, 1000, 1000)`
383+
- **Right monitor as primary:** Left `(-1000, 0, 1000, 1000)`, Right `(0, 0, 1000, 1000)`
384+
385+
**SWT Coordinate System:**
386+
- Uses point-based coordinates normalized to 100% scaling
387+
- Widget positions are relative to parent containers
388+
- Shell coordinates are absolute, mapping to Windows coordinate space
389+
390+
#### Coordinate Mapping by HiDPI Support Mode
391+
392+
**Static HiDPI Support (*System* DPI awareness):**
393+
- Uses `SingleZoomCoordinateSystemMapper`
394+
- Applies uniform scaling based on primary monitor DPI
395+
- All coordinates scaled consistently using single zoom factor
396+
397+
**Dynamic HiDPI Support (*PerMonitorV2* DPI awareness):**
398+
- Uses `MultiZoomCoordinateSystemMapper`
399+
- Handles per-monitor DPI differences
400+
- Shell positioning requires special handling to prevent coordinate ambiguity
401+
402+
#### Multi-Monitor Coordinate Mapping
403+
404+
The `MultiZoomCoordinateSystemMapper` addresses coordinate ambiguity in dynamic HiDPI support:
405+
406+
**Shell Position Handling:**
407+
- **Top-left position:** Stored in absolute pixels to preserve monitor boundaries
408+
- **Width and height:** Stored in points, adjusted for monitor's zoom factor
409+
- **MonitorAwareRectangle and MonitorAwarePoint:** Coordinate objects track their associated monitor context for accurate pixel-to-point conversion and vice-versa.
410+
411+
**Benefits:**
412+
- Prevents multiple pixel coordinates from mapping to identical point values
413+
- Ensures Shell positioning works correctly across monitors with different zoom levels
414+
- Maintains SWT's point-based abstraction for application developers
415+
416+
![MultiZoomCoordinateSystem](images/coordinate_system_with_coordinate_system_mapper.png)
417+
Fig: The representation of the pixel coordinates space and points coordinates space using coordinate mappers
418+
369419
### Process & Thread DPI Awareness
370420

371421
Windows differentiates between process and thread DPI awareness.
71 KB
Loading

0 commit comments

Comments
 (0)