mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-10-17 07:16:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Sam Lantinga
2023-05-15 11:16:46 -07:00
parent 78251f973d
commit 4de7433a9e
7 changed files with 31 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/README-ios.md
View File

@@ -33,29 +33,26 @@ TODO: Add information regarding App Store requirements such as icons, etc.
Notes -- Retina / High-DPI and window sizes Notes -- Retina / High-DPI and window sizes
============================================================================== ==============================================================================
Window and display mode sizes in SDL are in "screen coordinates" (or "points", Window and display mode sizes in SDL are in points rather than in pixels.
in Apple's terminology) rather than in pixels. On iOS this means that a window On iOS this means that a window created on an iPhone 6 will have a size in
created on an iPhone 6 will have a size in screen coordinates of 375 x 667, points of 375 x 667, rather than a size in pixels of 750 x 1334. All iOS apps
rather than a size in pixels of 750 x 1334. All iOS apps are expected to are expected to size their content based on points rather than pixels,
size their content based on screen coordinates / points rather than pixels,
as this allows different iOS devices to have different pixel densities as this allows different iOS devices to have different pixel densities
(Retina versus non-Retina screens, etc.) without apps caring too much. (Retina versus non-Retina screens, etc.) without apps caring too much.
SDL_GetWindowSize() and mouse coordinates are in screen coordinates rather SDL_GetWindowSize() and mouse coordinates are in points rather than pixels,
than pixels, but the window will have a much greater pixel density when the but the window will have a much greater pixel density when the device supports
device supports it, and the SDL_GetWindowSizeInPixels() can be called to it, and the SDL_GetWindowSizeInPixels() can be called to determine the size
determine the size in pixels of the drawable screen framebuffer. in pixels of the drawable screen framebuffer.
The SDL 2D rendering API will automatically handle this for you, by default The SDL 2D rendering API will automatically handle this for you, by default
providing a rendering area in screen coordinates, and you can call providing a rendering area in points, and you can call SDL_SetRenderLogicalPresentation()
SDL_SetRenderLogicalPresentation() to gain access to the higher density to gain access to the higher density resolution.
resolution.
Some OpenGL ES functions such as glViewport expect sizes in pixels rather than 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 sizes in points. When doing 2D rendering with OpenGL ES, an orthographic projection
orthographic projection matrix using the size in screen coordinates matrix using the size in points (SDL_GetWindowSize()) can be used in order to
(SDL_GetWindowSize()) can be used in order to display content at the same scale display content at the same scale no matter whether a Retina device is used or not.
no matter whether a Retina device is used or not.
Notes -- Application events Notes -- Application events

4
docs/README-migration.md
View File

@@ -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. to decide for you.
When a renderer is created, it will automatically set the logical size to the size of 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 the window in points. For high DPI displays, this will set up scaling from points to
window coordinates to pixels. You can disable this scaling with: pixels. You can disable this scaling with:
```c ```c
SDL_SetRenderLogicalPresentation(renderer, 0, 0, SDL_LOGICAL_PRESENTATION_DISABLED, SDL_SCALEMODE_NEAREST); SDL_SetRenderLogicalPresentation(renderer, 0, 0, SDL_LOGICAL_PRESENTATION_DISABLED, SDL_SCALEMODE_NEAREST);
``` ```

21
include/SDL3/SDL_render.h
View File

@@ -140,7 +140,7 @@ typedef enum
typedef enum typedef enum
{ {
SDL_LOGICAL_PRESENTATION_DISABLED, /**< There is no logical size in effect */ 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_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_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 */ 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 * 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. * 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 * By default the rendering size matches the window size in points,
* coordinates, but you can call SDL_SetRenderLogicalPresentation() to enable * but you can call SDL_SetRenderLogicalPresentation() to enable
* high DPI rendering or change the content size and scaling options. * high DPI rendering or change the content size and scaling options.
* *
* \param window the window where rendering is displayed * \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); 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. * render targets or logical size and presentation.
* *
* \param renderer the rendering context * \param renderer the rendering context
* \param w a pointer filled in with the width in screen coordinates * \param w a pointer filled in with the width in points
* \param h a pointer filled in with the height in screen coordinates * \param h a pointer filled in with the height in points
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * 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. * then copied to the output during presentation.
* *
* When a renderer is created, the logical size is set to match the window * 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 * size in points. The actual output size may be higher pixel density, and can be queried with SDL_GetRenderOutputSize().
* density, and can be queried with SDL_GetRenderOutputSize().
* *
* You can disable logical coordinates by setting the mode to * You can disable logical coordinates by setting the mode to
* SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full * 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); 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 renderer the rendering context
* \param window_x the x coordinate in window coordinates * \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); 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 renderer the rendering context
* \param x the x coordinate in render coordinates * \param x the x coordinate in render coordinates

2
src/video/wayland/SDL_waylandvideo.c
View File

@@ -599,7 +599,7 @@ static void display_handle_done(void *data,
driverdata->screen_height /= (int)driverdata->scale_factor; driverdata->screen_height /= (int)driverdata->scale_factor;
} }
} else { } 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. * Use the native mode pixel values since they are pre-transformed.
*/ */
driverdata->screen_width = native_mode.pixel_w / (int)driverdata->scale_factor; driverdata->screen_width = native_mode.pixel_w / (int)driverdata->scale_factor;

2
src/video/windows/SDL_windowsmodes.c
View File

@@ -597,7 +597,7 @@ void WIN_ScreenPointFromSDLFloat(float x, float y, LONG *xOut, LONG *yOut, int *
goto passthrough; 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); displayID = SDL_GetDisplayForPoint(&point);
if (displayID == 0) { if (displayID == 0) {
goto passthrough; goto passthrough;

4
src/video/windows/SDL_windowswindow.c
View File

@@ -139,7 +139,7 @@ static int WIN_AdjustWindowRectWithStyle(SDL_Window *window, DWORD style, BOOL m
UINT frame_dpi; UINT frame_dpi;
#endif #endif
/* Client rect, in SDL screen coordinates */ /* Client rect, in points */
SDL_RelativeToGlobalForWindow(window, SDL_RelativeToGlobalForWindow(window,
(use_current ? window->x : window->windowed.x), (use_current ? window->x : window->windowed.x),
(use_current ? window->y : window->windowed.y), (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); *width = (use_current ? window->w : window->windowed.w);
*height = (use_current ? window->h : window->windowed.h); *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__) #if !defined(__XBOXONE__) && !defined(__XBOXSERIES__)
WIN_ScreenPointFromSDL(x, y, &dpi); WIN_ScreenPointFromSDL(x, y, &dpi);
#endif #endif

6
src/video/winrt/SDL_winrtpointerinput.cpp
View File

@@ -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 // There may be some room for a workaround whereby OnPointerMoved's values
// are compared to the values from OnMouseMoved in order to detect // are compared to the values from OnMouseMoved in order to detect
// when this bug is active. A suitable transformation could then be made to // 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 // OnMouseMoved's values.
// to SDL with minimal transformation: from native screen coordinates (in DIPs)
// to SDL window coordinates.
// //
const Windows::Foundation::Point mouseDeltaInDIPs((float)args->MouseDelta.X, (float)args->MouseDelta.Y); const Windows::Foundation::Point mouseDeltaInDIPs((float)args->MouseDelta.X, (float)args->MouseDelta.Y);
const Windows::Foundation::Point mouseDeltaInSDLWindowCoords = WINRT_TransformCursorPosition(window, mouseDeltaInDIPs, TransformToSDLWindowSize); const Windows::Foundation::Point mouseDeltaInSDLWindowCoords = WINRT_TransformCursorPosition(window, mouseDeltaInDIPs, TransformToSDLWindowSize);