SDL: Use the term "points" instead of "screen coordinates"

SDLPushPostBot · May 15, 2023, 6:22pm

From 4de7433a9e64ffaecbd43f5349804f88150269f4 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Mon, 15 May 2023 11:16:46 -0700
Subject: [PATCH] Use the term "points" instead of "screen coordinates"

It turns out that screen coordinates were confusing people, thinking that meant pixels, when instead they are virtual coordinates; device independent units defined as pixels scaled by the display scale. We'll use the term "points" for this going forward, to reduce confusion.
---
 docs/README-ios.md                        | 29 ++++++++++-------------
 docs/README-migration.md                  |  4 ++--
 include/SDL3/SDL_render.h                 | 21 ++++++++--------
 src/video/wayland/SDL_waylandvideo.c      |  2 +-
 src/video/windows/SDL_windowsmodes.c      |  2 +-
 src/video/windows/SDL_windowswindow.c     |  4 ++--
 src/video/winrt/SDL_winrtpointerinput.cpp |  6 ++---
 7 files changed, 31 insertions(+), 37 deletions(-)

diff --git a/docs/README-ios.md b/docs/README-ios.md
index 715d337ea09f..0dc1e5e7b271 100644
--- a/docs/README-ios.md
+++ b/docs/README-ios.md
@@ -33,29 +33,26 @@ TODO: Add information regarding App Store requirements such as icons, etc.
 Notes -- Retina / High-DPI and window sizes
 ==============================================================================
 
-Window and display mode sizes in SDL are in "screen coordinates" (or "points",
-in Apple's terminology) rather than in pixels. On iOS this means that a window
-created on an iPhone 6 will have a size in screen coordinates of 375 x 667,
-rather than a size in pixels of 750 x 1334. All iOS apps are expected to
-size their content based on screen coordinates / points rather than pixels,
+Window and display mode sizes in SDL are in points rather than in pixels.
+On iOS this means that a window created on an iPhone 6 will have a size in
+points of 375 x 667, rather than a size in pixels of 750 x 1334. All iOS apps
+are expected to size their content based on points rather than pixels,
 as this allows different iOS devices to have different pixel densities
 (Retina versus non-Retina screens, etc.) without apps caring too much.
 
-SDL_GetWindowSize() and mouse coordinates are in screen coordinates rather
-than pixels, but the window will have a much greater pixel density when the
-device supports it, and the SDL_GetWindowSizeInPixels() can be called to
-determine the size in pixels of the drawable screen framebuffer.
+SDL_GetWindowSize() and mouse coordinates are in points rather than pixels,
+but the window will have a much greater pixel density when the device supports
+it, and the SDL_GetWindowSizeInPixels() can be called to determine the size
+in pixels of the drawable screen framebuffer.
 
 The SDL 2D rendering API will automatically handle this for you, by default
-providing a rendering area in screen coordinates, and you can call
-SDL_SetRenderLogicalPresentation() to gain access to the higher density
-resolution.
+providing a rendering area in points, and you can call SDL_SetRenderLogicalPresentation()
+to gain access to the higher density resolution.
 
 Some OpenGL ES functions such as glViewport expect sizes in pixels rather than
-sizes in screen coordinates. When doing 2D rendering with OpenGL ES, an
-orthographic projection matrix using the size in screen coordinates
-(SDL_GetWindowSize()) can be used in order to display content at the same scale
-no matter whether a Retina device is used or not.
+sizes in points. When doing 2D rendering with OpenGL ES, an orthographic projection
+matrix using the size in points (SDL_GetWindowSize()) can be used in order to
+display content at the same scale no matter whether a Retina device is used or not.
 
 
 Notes -- Application events
diff --git a/docs/README-migration.md b/docs/README-migration.md
index e701068c7eda..2e0b3a27dfd1 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -668,8 +668,8 @@ here, now. Passing NULL is the same as passing -1 here in SDL2, to signify you w
 to decide for you.
 
 When a renderer is created, it will automatically set the logical size to the size of
-the window in screen coordinates. For high DPI displays, this will set up scaling from
-window coordinates to pixels. You can disable this scaling with:
+the window in points. For high DPI displays, this will set up scaling from points to
+pixels. You can disable this scaling with:
 ```c
     SDL_SetRenderLogicalPresentation(renderer, 0, 0, SDL_LOGICAL_PRESENTATION_DISABLED, SDL_SCALEMODE_NEAREST);

diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h
index 766a72767408…959a8c9f1535 100644
— a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -140,7 +140,7 @@ typedef enum
typedef enum
{
SDL_LOGICAL_PRESENTATION_DISABLED, /**< There is no logical size in effect */

SDL_LOGICAL_PRESENTATION_MATCH, /**< The rendered content matches the window size in screen coordinates */

SDL_LOGICAL_PRESENTATION_MATCH, /< The rendered content matches the window size in points */
SDL_LOGICAL_PRESENTATION_STRETCH, /< The rendered content is stretched to the output resolution */
SDL_LOGICAL_PRESENTATION_LETTERBOX, /< The rendered content is fit to the largest dimension and the other dimension is letterboxed with black bars */
SDL_LOGICAL_PRESENTATION_OVERSCAN, /< The rendered content is fit to the smallest dimension and the other dimension extends beyond the output bounds */
@@ -235,8 +235,8 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(int width, int height, U

need a specific renderer, specify NULL and SDL will attempt to chooes the
best option for you, based on what is available on the user’s system.

- By default the rendering size matches the window size in screen
- coordinates, but you can call SDL_SetRenderLogicalPresentation() to enable

- By default the rendering size matches the window size in points,
- but you can call SDL_SetRenderLogicalPresentation() to enable
- high DPI rendering or change the content size and scaling options.
- \param window the window where rendering is displayed
  @@ -317,14 +317,14 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer);
  extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_RendererInfo *info);

/**

- Get the output size in screen coordinates of a rendering context.

- Get the output size in points of a rendering context.

- This returns the true output size in screen coordinates, ignoring any

- This returns the true output size in points, ignoring any
- render targets or logical size and presentation.
- \param renderer the rendering context

- \param w a pointer filled in with the width in screen coordinates
- \param h a pointer filled in with the height in screen coordinates

- \param w a pointer filled in with the width in points
- \param h a pointer filled in with the height in points
- \returns 0 on success or a negative error code on failure; call
- ```
     SDL_GetError() for more information.
```

@@ -841,8 +841,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer)

then copied to the output during presentation.
When a renderer is created, the logical size is set to match the window

- size in screen coordinates. The actual output size may be higher pixel
- density, and can be queried with SDL_GetRenderOutputSize().

- size in points. The actual output size may be higher pixel density, and can be queried with SDL_GetRenderOutputSize().
- You can disable logical coordinates by setting the mode to
- SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full
  @@ -887,7 +886,7 @@ extern DECLSPEC int SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *rende
  extern DECLSPEC int SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode, SDL_ScaleMode *scale_mode);

/**

- Get a point in render coordinates when given a point in window coordinates.

- Get a point in render coordinates when given a point in window coordinates (points).
- \param renderer the rendering context
- \param window_x the x coordinate in window coordinates
  @@ -905,7 +904,7 @@ extern DECLSPEC int SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *rende
  extern DECLSPEC int SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y);

/**

- Get a point in window coordinates when given a point in render coordinates.

- Get a point in window coordinates (points) when given a point in render coordinates.
- \param renderer the rendering context
- \param x the x coordinate in render coordinates
  diff --git a/src/video/wayland/SDL_waylandvideo.c b/src/video/wayland/SDL_waylandvideo.c
  index edb74a0fa073…7f4a8c0e7bf9 100644
  — a/src/video/wayland/SDL_waylandvideo.c
  +++ b/src/video/wayland/SDL_waylandvideo.c
  @@ -599,7 +599,7 @@ static void display_handle_done(void *data,
  driverdata->screen_height /= (int)driverdata->scale_factor;
  }
  } else {

   /* Calculate the screen coordinates from the pixel values, if xdg-output isn't present.

   /* Calculate the points from the pixel values, if xdg-output isn't present.
    * Use the native mode pixel values since they are pre-transformed.
    */
   driverdata->screen_width = native_mode.pixel_w / (int)driverdata->scale_factor;

diff --git a/src/video/windows/SDL_windowsmodes.c b/src/video/windows/SDL_windowsmodes.c
index 38fe6d1853e6…1d3905a8552a 100644
— a/src/video/windows/SDL_windowsmodes.c
+++ b/src/video/windows/SDL_windowsmodes.c
@@ -597,7 +597,7 @@ void WIN_ScreenPointFromSDLFloat(float x, float y, LONG *xOut, LONG *yOut, int *
goto passthrough;
}

/* Can’t use MonitorFromPoint for this because we currently have SDL coordinates, not pixels */

/* Can’t use MonitorFromPoint for this because we currently have SDL points, not pixels */
displayID = SDL_GetDisplayForPoint(&point);
if (displayID == 0) {
goto passthrough;
diff --git a/src/video/windows/SDL_windowswindow.c b/src/video/windows/SDL_windowswindow.c
index a8a7f5c7f616…8c49255a213f 100644
— a/src/video/windows/SDL_windowswindow.c
+++ b/src/video/windows/SDL_windowswindow.c
@@ -139,7 +139,7 @@ static int WIN_AdjustWindowRectWithStyle(SDL_Window *window, DWORD style, BOOL m
UINT frame_dpi;
#endif

/* Client rect, in SDL screen coordinates */

/* Client rect, in points */
SDL_RelativeToGlobalForWindow(window,
(use_current ? window->x : window->windowed.x),
(use_current ? window->y : window->windowed.y),
@@ -147,7 +147,7 @@ static int WIN_AdjustWindowRectWithStyle(SDL_Window *window, DWORD style, BOOL m
*width = (use_current ? window->w : window->windowed.w);
*height = (use_current ? window->h : window->windowed.h);

/* Convert client rect from SDL coordinates to pixels (no-op if DPI scaling not enabled) */

/* Convert client rect from points to pixels (no-op if DPI scaling not enabled) */
#if !defined(XBOXONE) && !defined(XBOXSERIES)
WIN_ScreenPointFromSDL(x, y, &dpi);
#endif
diff --git a/src/video/winrt/SDL_winrtpointerinput.cpp b/src/video/winrt/SDL_winrtpointerinput.cpp
index e30952f9e71b…7f49d2ce88d4 100644
— a/src/video/winrt/SDL_winrtpointerinput.cpp
+++ b/src/video/winrt/SDL_winrtpointerinput.cpp
@@ -379,10 +379,8 @@ void WINRT_ProcessMouseMovedEvent(SDL_Window *window, Windows::Devices::Input::M
//
// There may be some room for a workaround whereby OnPointerMoved’s values
// are compared to the values from OnMouseMoved in order to detect

// when this bug is active. A suitable transformation could then be made to
// OnMouseMoved’s values. For now, however, the system-reported values are sent
// to SDL with minimal transformation: from native screen coordinates (in DIPs)
// to SDL window coordinates.

// when this bug is active. A suitable transformation could then be made to
// OnMouseMoved’s values.
//
const Windows::Foundation::Point mouseDeltaInDIPs((float)args->MouseDelta.X, (float)args->MouseDelta.Y);
const Windows::Foundation::Point mouseDeltaInSDLWindowCoords = WINRT_TransformCursorPosition(window, mouseDeltaInDIPs, TransformToSDLWindowSize);