From 66b52a1ea6f4c4d026389c7a19e44a528798a9bf Mon Sep 17 00:00:00 2001 From: Robert Pfeiffer Date: Wed, 3 Mar 2021 11:16:49 +0100 Subject: [PATCH 1/2] document get_desktop_sizes soft-deprecate pygame.display.list_modes in the docs, as many use cases of that function are better served by get_desktop_sizes. --- docs/reST/ref/display.rst | 35 +++++++++++++++++++++++++++++++++++ src_c/display.c | 4 ++-- src_c/doc/display_doc.h | 5 +++++ 3 files changed, 42 insertions(+), 2 deletions(-) diff --git a/docs/reST/ref/display.rst b/docs/reST/ref/display.rst index 6a03a7bd8f..121d9c9592 100644 --- a/docs/reST/ref/display.rst +++ b/docs/reST/ref/display.rst @@ -315,6 +315,26 @@ required). .. ## pygame.display.get_wm_info ## +.. function:: get_desktop_sizes + + | :sl:`Get sizes of active desktops` + | :sg:`get_desktop_sizes() -> list` + + This function returns the sizes of the currrently configured + virtual desktops as a list of (x, y) tuples of integers. + + The length of the list is not the same as the number of attached monitors, + as a desktop can be mirrored across multiple monitors. The desktop sizes + do not indicate the maximum monitor resolutions supported by the hardware, + but the desktop size configured in the operating system. + + In order to fit windows into the desktop as it is currently configured, and + to respect the resolution configured by the operating system in fullscreen + mode, this function *should* be used to replace many use cases of + ``pygame.display.list_modes()`` whenever applicable. + + .. versionchanged:: 2.0.0 + .. function:: list_modes | :sl:`Get list of available fullscreen modes` @@ -332,6 +352,21 @@ required). The display index ``0`` means the default display is used. + Since pygame 2.0, ``pygame.display.get_desktop_sizes()`` has taken over + some use cases from ``pygame.display.list_modes()``: + + To find a suitable size for non-fullscreen windows, it is preferable to + use ``pygame.display.get_desktop_sizes()`` to get the size of the *current* + desktop, and to then choose a smaller window size. This way, the window is + guaranteed to fit, even when the monitor is configured to a lower resolution + than the maximum supported by the hardware. + + To avoid changing the physical monitor resolution, it is also preferable to + use ``pygame.display.get_desktop_sizes()`` to determine the fullscreen + resolution. Developers are strongly advised to default to the current + physical monitor resolution unless the user explicitly requests a different + one (e.g. in an options menu or configuration file). + .. versionchanged:: 1.9.5 ``display`` argument added .. ## pygame.display.list_modes ## diff --git a/src_c/display.c b/src_c/display.c index 1e7d6c8a6e..eaa4b3e25b 100644 --- a/src_c/display.c +++ b/src_c/display.c @@ -3086,11 +3086,11 @@ static PyMethodDef _pg_display_methods[] = { {"_set_autoresize", (PyCFunction)pg_display_set_autoresize , METH_VARARGS, "provisional API, subject to change"}, {"_resize_event", (PyCFunction)pg_display_resize_event, METH_O, - "provisional API, subject to change"}, + "DEPRECATED, never officially supported, kept only for compatibility with release candidate"}, {"_get_renderer_info", (PyCFunction)pg_get_scaled_renderer_info, METH_NOARGS, "provisional API, subject to change"}, {"get_desktop_sizes", (PyCFunction)pg_get_desktop_screen_sizes, - METH_NOARGS, "provisional API, subject to change"}, + METH_NOARGS, DOC_PYGAMEDISPLAYGETDESKTOPSIZES}, {"is_fullscreen", (PyCFunction)pg_is_fullscreen, METH_NOARGS, "provisional API, subject to change"}, #endif diff --git a/src_c/doc/display_doc.h b/src_c/doc/display_doc.h index 6ef44da75c..266ace08c9 100644 --- a/src_c/doc/display_doc.h +++ b/src_c/doc/display_doc.h @@ -10,6 +10,7 @@ #define DOC_PYGAMEDISPLAYGETDRIVER "get_driver() -> name\nGet the name of the pygame display backend" #define DOC_PYGAMEDISPLAYINFO "Info() -> VideoInfo\nCreate a video display information object" #define DOC_PYGAMEDISPLAYGETWMINFO "get_wm_info() -> dict\nGet information about the current windowing system" +#define DOC_PYGAMEDISPLAYGETDESKTOPSIZES "get_desktop_sizes() -> list\nGet sizes of active desktops" #define DOC_PYGAMEDISPLAYLISTMODES "list_modes(depth=0, flags=pygame.FULLSCREEN, display=0) -> list\nGet list of available fullscreen modes" #define DOC_PYGAMEDISPLAYMODEOK "mode_ok(size, flags=0, depth=0, display=0) -> depth\nPick the best color depth for a display mode" #define DOC_PYGAMEDISPLAYGLGETATTRIBUTE "gl_get_attribute(flag) -> value\nGet the value for an OpenGL flag for the current display" @@ -77,6 +78,10 @@ pygame.display.get_wm_info get_wm_info() -> dict Get information about the current windowing system +pygame.display.get_desktop_sizes + get_desktop_sizes() -> list +Get sizes of active desktops + pygame.display.list_modes list_modes(depth=0, flags=pygame.FULLSCREEN, display=0) -> list Get list of available fullscreen modes From 7e2453a74cad53471735146e2580eeec35e6066c Mon Sep 17 00:00:00 2001 From: Robert Pfeiffer Date: Mon, 29 Mar 2021 10:40:21 +0200 Subject: [PATCH 2/2] discourage mode_ok and display index --- docs/reST/ref/display.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/reST/ref/display.rst b/docs/reST/ref/display.rst index 121d9c9592..ab6e6efdf4 100644 --- a/docs/reST/ref/display.rst +++ b/docs/reST/ref/display.rst @@ -23,10 +23,16 @@ special modules like hardware acceleration and OpenGL support. These are controlled by flags passed to ``pygame.display.set_mode()``. Pygame can only have a single display active at any time. Creating a new one -with ``pygame.display.set_mode()`` will close the previous display. If precise -control is needed over the pixel format or display resolutions, use the +with ``pygame.display.set_mode()`` will close the previous display. To detect +the number and size of attached screens, you can use +``pygame.display.get_desktop_sizes`` and then select appropriate window size +and display index to pass to ``pygame.display.set_mode()``. + +For backward compatibility ``pygame.display`` allows precise control over +the pixel format or display resolutions. This used to be necessary with old +grahics cards and CRT screens, but is usually not needed any more. Use the functions ``pygame.display.mode_ok()``, ``pygame.display.list_modes()``, and -``pygame.display.Info()`` to query information about the display. +``pygame.display.Info()`` to query detailed information about the display. Once the display Surface is created, the functions from this module affect the single existing display. The Surface becomes invalid if the module is @@ -197,7 +203,10 @@ required). screen_height=400 screen=pygame.display.set_mode([screen_width, screen_height]) - The display index ``0`` means the default display is used. + The display index ``0`` means the default display is used. If no display + index argument is provided, the default display can be overridden with an + environment variable. + .. versionchanged:: 1.9.5 ``display`` argument added @@ -333,7 +342,7 @@ required). mode, this function *should* be used to replace many use cases of ``pygame.display.list_modes()`` whenever applicable. - .. versionchanged:: 2.0.0 + .. versionadded:: 2.0.0 .. function:: list_modes