From 4de7433a9e64ffaecbd43f5349804f88150269f4 Mon Sep 17 00:00:00 2001 From: Sam Lantinga 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 715d337ea0..0dc1e5e7b2 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 e701068c7e..2e0b3a27df 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 766a727674..959a8c9f15 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 edb74a0fa0..7f4a8c0e7b 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 38fe6d1853..1d3905a855 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 a8a7f5c7f6..8c49255a21 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 e30952f9e7..7f49d2ce88 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);