New display information management: `pygame.Display` et al.

[Matiiss]

With the advent of SDL3... I mean, it's been there for a while now

Note for SDL2, some of this functionality can be recreated with existing API and that should be done whenever possible
For example: #3530 (#3530 (comment))

A bunch of new API stuff relating to displays has been introduced, as of right now, the below should be an exhaustive list of all the related functions (the section names are meant to represent the Python interface) (the checkboxes are meant to help track what has been implemented):

Meta:

• https://wiki.libsdl.org/SDL3/SDL_DisplayID

Instance methods:

• https://wiki.libsdl.org/SDL3/SDL_GetDisplayName
• https://wiki.libsdl.org/SDL3/SDL_GetDisplayBounds
• https://wiki.libsdl.org/SDL3/SDL_GetDisplayUsableBounds
• https://wiki.libsdl.org/SDL3/SDL_GetDisplayContentScale
• https://wiki.libsdl.org/SDL3/SDL_GetCurrentDisplayMode
• https://wiki.libsdl.org/SDL3/SDL_GetCurrentDisplayOrientation
• https://wiki.libsdl.org/SDL3/SDL_GetDesktopDisplayMode
• https://wiki.libsdl.org/SDL3/SDL_GetFullscreenDisplayModes
• https://wiki.libsdl.org/SDL3/SDL_GetClosestFullscreenDisplayMode
• https://wiki.libsdl.org/SDL3/SDL_GetNaturalDisplayOrientation
• https://wiki.libsdl.org/SDL3/SDL_GetDisplayProperties

Class methods:

• https://wiki.libsdl.org/SDL3/SDL_GetDisplayForPoint
• https://wiki.libsdl.org/SDL3/SDL_GetDisplayForRect
• https://wiki.libsdl.org/SDL3/SDL_GetDisplayForWindow

Auxiliary methods (potentially class methods):

• https://wiki.libsdl.org/SDL3/SDL_GetDisplays
• https://wiki.libsdl.org/SDL3/SDL_GetPrimaryDisplay

This might live under pygame.display (e.g., pygame.display.Display, but, of course, aliased to pygame.Display)

Tentative Python signatures:

from __future__ import annotations

from enum import Enum
from fractions import Fraction
from typing import Self

from pygame import Rect, Window
from pygame.typing import Point


# https://wiki.libsdl.org/SDL3/SDL_DisplayOrientation
class DisplayOrientation(Enum): ...


# https://wiki.libsdl.org/SDL3/SDL_DisplayMode
class DisplayMode:
    @property
    def display_id(self) -> int: ...
    # AND/OR
    @property
    def display(self) -> Display: ...

    @property
    # OR `pixel_format`
    # this requires a PixelFormat enum which is out of scope for this issue
    def format(self) -> ...: ...

    @property
    # OR `width`
    def w(self) -> int: ...

    @property
    # OR `height`
    def h(self) -> int: ...

    @property
    def pixel_density(self) -> float: ...

    # @property
    # def refresh_rate(self) -> float: ...
    # @property
    # def refresh_rate_numerator(self) -> int: ...
    # @property
    # def refresh_rate_denominator(self) -> int: ...
    # OR (better yet)
    @property
    def refresh_rate(self) -> Fraction: ...


class Display:
    # https://wiki.libsdl.org/SDL3/SDL_DisplayID
    @property
    def id(self) -> int: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetDisplayName
    @property
    def name(self) -> str: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetDisplayBounds
    @property
    def bounds(self) -> Rect: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetDisplayUsableBounds
    @property
    def usable_bounds(self) -> Rect: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetDisplayContentScale
    @property
    def content_scale(self) -> float: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetCurrentDisplayMode
    @property
    def current_display_mode(self) -> DisplayMode: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetDesktopDisplayMode
    @property
    def desktop_display_mode(self) -> DisplayMode: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetFullscreenDisplayModes
    @property
    def fullscreen_display_modes(self) -> list[DisplayMode]: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetCurrentDisplayOrientation
    @property
    def current_display_orientation(self) -> DisplayOrientation: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetNaturalDisplayOrientation
    @property
    def natural_display_orientation(self) -> DisplayOrientation: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetDisplayProperties
    # this needs a whole Property type that seems wayyy out of scope of this issue
    # for more information read https://wiki.libsdl.org/SDL3/CategoryProperties
    @property
    def properties(self) -> ...: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetClosestFullscreenDisplayMode
    def get_closest_fullscreen_display_mode(
        self,
        width: int,
        height: int,
        refresh_rate: float = 0.0,
        include_hight_density_modes: bool = True,  # or default False?
    ) -> DisplayMode: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetDisplayForPoint
    @classmethod
    def from_point(cls, point: Point) -> Self: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetDisplayForRect
    @classmethod
    def from_rect(cls, rect: Rect) -> Self: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetDisplayForWindow
    @classmethod
    def from_window(cls, window: Window) -> Self: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetDisplays
    @classmethod
    def get_all(cls) -> list[Self]: ...

    # https://wiki.libsdl.org/SDL3/SDL_GetPrimaryDisplay
    @classmethod
    def get_primary(cls) -> Self: ...


# https://wiki.libsdl.org/SDL3/SDL_GetDisplays
def get_displays() -> list[Display]: ...


# https://wiki.libsdl.org/SDL3/SDL_GetPrimaryDisplay
def get_primary_display() -> Display: ...

[Starbuck5]

Thanks for taking a look at this. I think this is the future of pygame.display.

PixelFormat seems out of scope for this, but for it and other "enum" types check out what I'm proposing to do with AudioFormat in #3581. Instead of doing an enum, or an integer constant like existing things, it does it with "constant objects." That way, the constants can have functions and properties on them to get more information.

Another thing similar to this I dealt with in Audio is object singletons. Would you allow multiple Python objects sharing a display ID, or would you want one Python object per display ID. Seems like less of an issue here because everything looks immutable. But theoretically if you do pygame.display.get_primary_display() and pygame.Display.from_point with a point in that display, shouldn't they be the same object?

SDL_GetDisplayForWindow should probably be implemented on Window, no?

How would this interact with other systems? Are there events with display IDs? Windows should be openable at specific Displays.

Would this replace the need for other functions in display, like get_desktop_sizes, list_modes, and/or Info?

[Starbuck5]

CC @damusss

[damusss]

I like the object oriented approach to this, since it's very fitting considering how much information can be associated with each Display. I'll assume most of the instance methods are exposed as properties.

@Starbuck5 yes I think singletons make more sense. They can still expose the ID, but since it's an object representing a physical "single" "monitor" it makes more sense for the same physical display to be the same object. I think a python layer (similar to how you are implementing audio/mixer) would help a lot with this, and since display information does not create SDL structures that need to be freed it probably won't be an issue memory-wise.

I think the property Window.display would fit SDL_GetDisplayForWindow

It doesn't seem like a create property to set the display ID exists, the only way to create or move a window to a display is using the coordinates since they can go out of bounds relatively to the primary display to jump to different displays. The closest middle ground I found is SDL_WINDOWPOS_CENTERED_DISPLAY ( = SDL_WINDOWPOS_CENTERED_MASK|(displayID)), maybe we can find a way to abstract it for the user.

It seems like SDL2 only has a single SDL_DISPLAYEVENT event for state changes while SDL3 introduces many more detailed display events, each associated with a display ID (which should be actually the unique Display object when abstracted (singletons come in extra handy!)) and some extra information (https://wiki.libsdl.org/SDL3/SDL_EventType) which would create several different SDL3 only event constants/event types.

The milestone for this is 3.0.0, will all of this appear in that version or do you think what's possible to implement should be added to the current display module? (with some features being SDL3 only) It would definitely replace get_desktop_sizes, ... which would become duplicates until 3.0.0 (that version should also remove every/most window related function to pygame.display)

[Matiiss]

I don't currently see a need for singletons really, all Display objects would have a unique ID with them already, if you want to check if two Display objects are "the same", we can just make their __eq__ methods compare their IDs, that's it. The constructor for these objects (not recommended to be called directly by users (unless maybe they know the exact ID for sure, for example, they got it from an event)) would simply take in this ID and return a new Display object. That's it, pretty simple.
On a similar note, the __hash__ method should be based on the ID as well.

As for the Window object having a method to retrieve the Display, I don't think so. Maybe, but we should definitely have a Display.from_window. Surely you wouldn't suggest we have a Rect.get_display method, would you? 😄

The milestone was somewhat arbitrary, we probably do want this issue to be completed before 3.0, but that means it will be worked on in the current (2) major version as well. As I noted in my original post, this should be implemented in SDL2 whenever possible.

[Starbuck5]

Damus posted progress and questions on discord: https://discord.com/channels/772505616680878080/772940667231928360/1475618657106137308

still unsure about everything, should current_display_mode be called "current_mode" (or just mode?) ? is it okay for some attributes to raise a pygame.error on SDL2 if accessed? what's the final take on singletons? should fullscreen_display_modes and get_closest_fullscreen_display_mode be implemented?
and I'm also not sure what to do with the orientation (python enum, classic constant, constant object (which wouldn't have any methods or properties whatsoever))

Replying here to keep discussion organized.

• I like current_mode
• The attributes just shouldn't exist in SDL2. It would be okay if none of this existed in SDL2 honestly. Given that the plan is pgce2==sdl2, pgce3==sdl3. But I'm not against having an SDL2 version people can use sooner.
• R.E. singletons, maybe it's an optimization for events. Since otherwise it would need to be allocated every time. Since events are not lazy rn. It's not strictly necessary because what I said before they're not mutable
• fullscreen display mode stuff seems useful if SDL_SetWindowDisplayMode is implemented.
• I think orientation makes sense as an enum, maybe an int enum where the integers match the SDL constants

all Display objects would have a unique ID with them already

• BTW I don't see why this should be publicly exposed. In SDL it acts as a handle for the data, but for us we have Display objects as handles (from user perspective, obv we'd have one internally).

As for the Window object having a method to retrieve the Display, I don't think so. Maybe, but we should definitely have a Display.from_window. Surely you wouldn't suggest we have a Rect.get_display method, would you? 😄

• I thought about and changed my mind, but maybe slightly different reasoning. It's just that the Window doesn't actually own the Display. If you move the window around the display attribute changes, that seems strange.

Another note, what happens to the existing display object if you unplug a second monitor?

[damusss]

• I also prefer current_mode and desktop_mode since I don't like repeating the object name in the attributes.
• I agree that it's probably best if the stubs contain attributes conditionally, using the pygame.version.SDL version just like the python stubs do.
• The objects could start off by being optimized as singletons without it being a selling point and just an internal detail and keeping the __eq__ method.
• I hadn't thought about "hiding" the ID, but it makes sense since we're exposing something that doesn't look like it relies on it. Regarding it, should the __init__ in the stubs include it or lie about it? (since the ID is still necessary to create a Display object)
• Since the display owns the window, I'll agree with you both. I have already implemented Display.from_window and that's probably enough.

What I'll say about an unplugged monitor comes from documentation and intuition and it has side effects that are worse for SDL2.
In SDL3 each display has an unique ID, if a monitor is unplugged and plugged in again it will get a new ID. meaning that if a monitor for which a Display object exists is unplugged that ID will become invalid and the user will know about it when they try accessing any attributes that will make SDL_GetDisplayX functions error.
In SDL2 display ID is just the index in the internal "display array". If the monitor was the last one the error will be the same as SDL3, otherwise the python Display will start giving information of the next monitor in the list, since the internal _id (index) is the same but the array elements were rearranged (I only have 1 monitor and cannot test this, but I can do more research later).
I'm not sure if there's a clean solution to this. Display unplug events do exist but we don't have control over the existing display objects nor the existing references to them. The cleanest solution for SDL3 is probably to check whether the ID is valid before each operation, and, assuming the _id wasn't changed illegally, conclude it must have become invalid form the SDL side and output a nice error about it, but I'm open to any kind of suggestion since this solution sounds unhappy!

I also hope that creating the Display object in python won't raise issues when the event attributes will need to create them (likely from C).
Thank you @Starbuck5 for responding to my doubts.

[Starbuck5]

With regards to init, Display objects shouldn’t be initialized by the user ever. They should only come from internal functions. Therefore they don’t need an init— internally you can use dunder new to create the instances and then populate them custom.

With regards to unplugging, you could have the module own a list of references to all displays. In fact, you would need to do something like this to implement a singleton.

[damusss]

typedef enum SDL_DisplayEventID
{
    SDL_DISPLAYEVENT_NONE,          /**< Never used */
    SDL_DISPLAYEVENT_ORIENTATION,   /**< Display orientation has changed to data1 */
    SDL_DISPLAYEVENT_CONNECTED,     /**< Display has been added to the system */
    SDL_DISPLAYEVENT_DISCONNECTED,  /**< Display has been removed from the system */
    SDL_DISPLAYEVENT_MOVED          /**< Display has changed position */
} SDL_DisplayEventID;

Adding this to correct myself, SDL2 has some of the display events as well, meaning some of them can exist.

Regarding what you said, @Starbuck5 , the init is cleaner now, and I'm trying to work on the event side so I can try the unplugging solution. The only concern would be that even if I remove the unplugged display from the singleton dictionary, the user might still have a reference to it. Should the Display have a "valid" or "plugged" or similar property? or should we just let them check the events for unplugged monitors and handle their references themselves? (I think the second option is the best one, if someone worries whether the display can be disconnected they can likely handle the events. I would specify the rare possibility of a display becoming invalid and how to deal with it in the docs.)