mirrors/SDL
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

Browse Source
This commit is contained in:
SDL Wiki Bot 2023-05-17 19:59:14 +00:00
parent 26e780bc9e
commit 5836e057de
3 changed files with 54 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/README-highdpi.md
View File

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

7
include/SDL3/SDL_render.h
View File

@ -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().

50
include/SDL3/SDL_video.h
View File

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