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

@@ -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

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);
 ```

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

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;

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;

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

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);