diff --git a/docs/README-highdpi.md b/docs/README-highdpi.md index a63cbbcb67..c6fe908e85 100644 --- a/docs/README-highdpi.md +++ b/docs/README-highdpi.md @@ -1,18 +1,18 @@ - -SDL 3.0 has new support for high DPI displays - -Displays now have a content display scale. - -The display scale is the expected scale for content based on the DPI settings of the display. For example, a 4K display might have a 2.0 (200%) display scale, which means that the user expects UI elements to be twice as big on this display, to aid in readability. - -The window size is now distinct from the window pixel size. - -The window also has a display scale, which is the content display scale relative to the window pixel size. - -For example, a 3840x2160 window displayed at 200% on Windows, and a 1920x1080 window on a 2x display on macOS will both have a pixel size of 3840x2160 and a display scale of 2.0. - -You can query the window size using SDL_GetWindowSize(), and when this changes you get an SDL_EVENT_WINDOW_RESIZED event. - -You can query the window pixel size using SDL_GetWindowSizeInPixels(), and when this changes you get an SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event. You are guaranteed to get a SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event when a window is created and resized, and you can use this event to create and resize your graphics context for the window. - -You can query the window display scale using SDL_GetWindowDisplayScale(), and when this changes you get an SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED event. + +SDL 3.0 has new support for high DPI displays + +Displays now have a content display scale. + +The display scale is the expected scale for content based on the DPI settings of the display. For example, a 4K display might have a 2.0 (200%) display scale, which means that the user expects UI elements to be twice as big on this display, to aid in readability. + +The window size is now distinct from the window pixel size. + +The window also has a display scale, which is the content display scale relative to the window pixel size. + +For example, a 3840x2160 window displayed at 200% on Windows, and a 1920x1080 window on a 2x display on macOS will both have a pixel size of 3840x2160 and a display scale of 2.0. + +You can query the window size using SDL_GetWindowSize(), and when this changes you get an SDL_EVENT_WINDOW_RESIZED event. + +You can query the window pixel size using SDL_GetWindowSizeInPixels(), and when this changes you get an SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event. You are guaranteed to get a SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event when a window is created and resized, and you can use this event to create and resize your graphics context for the window. + +You can query the window display scale using SDL_GetWindowDisplayScale(), and when this changes you get an SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED event. diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h index 7ea1a31244..b6909aafcf 100644 --- a/include/SDL3/SDL_render.h +++ b/include/SDL3/SDL_render.h @@ -235,7 +235,8 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(int width, int height, U * best option for you, based on what is available on the user's system. * * By default the rendering size matches the window size in pixels, but you - * can call SDL_SetRenderLogicalPresentation() to change the content size and scaling options. + * can call SDL_SetRenderLogicalPresentation() to change the content size and + * scaling options. * * \param window the window where rendering is displayed * \param name the name of the rendering driver to initialize, or NULL to @@ -821,8 +822,8 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer) * then copied to the output during presentation. * * You can disable logical coordinates by setting the mode to - * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full - * pixel resolution of the output window. + * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel + * resolution of the output window. * * You can convert coordinates in an event into rendering coordinates using * SDL_ConvertEventToRenderCoordinates(). diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index fe41eb2716..cf81ebb6e3 100644 --- a/include/SDL3/SDL_video.h +++ b/include/SDL3/SDL_video.h @@ -410,10 +410,14 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(SDL_Dis /** * Get the content scale of a display. * - * The content scale is the expected scale for content based on the DPI settings of the display. For example, a 4K display might have a 2.0 (200%) display scale, which means that the user expects UI elements to be twice as big on this display, to aid in readability. + * The content scale is the expected scale for content based on the DPI + * settings of the display. For example, a 4K display might have a 2.0 (200%) + * display scale, which means that the user expects UI elements to be twice as + * big on this display, to aid in readability. * * \param displayID the instance ID of the display to query - * \returns The content scale of the display, or 0.0f on error; call SDL_GetError() for more details. + * \returns The content scale of the display, or 0.0f on error; call + * SDL_GetError() for more details. * * \since This function is available since SDL 3.0.0. * @@ -556,12 +560,20 @@ extern DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *window /** * Get the content display scale relative to a window's pixel size. * - * This is a combination of the window pixel density and the display content scale, and is the expected scale for displaying content in this window. For example, if a 3840x2160 window had a display scale of 2.0, the user expects the content to take twice as many pixels and be the same physical size as if it were being displayed in a 1920x1080 window with a display scale of 1.0. + * This is a combination of the window pixel density and the display content + * scale, and is the expected scale for displaying content in this window. For + * example, if a 3840x2160 window had a display scale of 2.0, the user expects + * the content to take twice as many pixels and be the same physical size as + * if it were being displayed in a 1920x1080 window with a display scale of + * 1.0. * - * Conceptually this value corresponds to the scale display setting, and is updated when that setting is changed, or the window moves to a display with a different scale setting. + * Conceptually this value corresponds to the scale display setting, and is + * updated when that setting is changed, or the window moves to a display with + * a different scale setting. * * \param window the window to query - * \returns the display scale, or 0.0f on failure; call SDL_GetError() for more information. + * \returns the display scale, or 0.0f on failure; call SDL_GetError() for + * more information. * * \since This function is available since SDL 3.0.0. */ @@ -648,11 +660,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window); * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist * property to YES, otherwise you will not receive a High-DPI OpenGL canvas. * - * The window pixel size may differ from its window coordinate size if the window is on a high pixel density display. - * Use SDL_GetWindowSize() to query the client area's size in window - * coordinates, and SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() - * to query the drawable size in pixels. Note that the drawable size can vary - * after the window is created and should be queried again if you get an + * The window pixel size may differ from its window coordinate size if the + * window is on a high pixel density display. Use SDL_GetWindowSize() to query + * the client area's size in window coordinates, and + * SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() to query the + * drawable size in pixels. Note that the drawable size can vary after the + * window is created and should be queried again if you get an * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event. * * If the window is set fullscreen, the width and height parameters `w` and @@ -712,11 +725,12 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindow(const char *title, int w, i * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist * property to YES, otherwise you will not receive a High-DPI OpenGL canvas. * - * The window pixel size may differ from its window coordinate size if the window is on a high pixel density display. - * Use SDL_GetWindowSize() to query the client area's size in window - * coordinates, and SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() - * to query the drawable size in pixels. Note that the drawable size can vary - * after the window is created and should be queried again if you get an + * The window pixel size may differ from its window coordinate size if the + * window is on a high pixel density display. Use SDL_GetWindowSize() to query + * the client area's size in window coordinates, and + * SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() to query the + * drawable size in pixels. Note that the drawable size can vary after the + * window is created and should be queried again if you get an * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event. * * If the window is set fullscreen, the width and height parameters `w` and @@ -1020,9 +1034,9 @@ extern DECLSPEC int SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); * NULL can safely be passed as the `w` or `h` parameter if the width or * height value is not desired. * - * The window pixel size may differ from its window coordinate size if the window is on a high pixel density display. - * Use SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() to get the - * real client area size in pixels. + * The window pixel size may differ from its window coordinate size if the + * window is on a high pixel density display. Use SDL_GetWindowSizeInPixels() + * or SDL_GetRenderOutputSize() to get the real client area size in pixels. * * \param window the window to query the width and height from * \param w a pointer filled in with the width of the window, may be NULL