# sdl2.ext.displays - Querying the Connected Displays

This module provides the `get_displays` function, which returns a list of `DisplayInfo` objects containing information about the names, supported resolutions, current resolutions, locations, and DPIs of all the connected displays.

class sdl2.ext.displays.DisplayInfo(index)

  The name and video mode information for a given connected display.

  Video modes are represented with `SDL_VideoMode` structures, which contain the width (`mode.w`), height (`mode.h`), refresh rate (`mode.refresh_rate`), and SDL pixel format (`mode.format`) for a given video mode.

  Note that refresh rates in SDL are returned as integers, meaning that the refresh rate for a display may be reported incorrectly on some platforms (e.g. `59` for an OS-reported refresh rate of 59.94 Hz).

  Parameters:

    index (int) – The index of the display to query. Must be less than the total number of connected displays.

  index

    The index of the display.

    Type:

      int

  name

    The name of the display.

    Type:

      str

  modes

    A list of all video modes supported by the display.

    Type:

      list of `SDL_VideoMode`

  property dpi

    The current diagonal DPI for the display.

    Note that this value is the DPI reported by the display itself, which is not always available or guaranteed to be accurate.

    Type:

      float

  property current_mode

    The current mode for the display.

    Type:

      `SDL_DisplayMode`

  property desktop_mode

    The desktop mode for the display.

    If the fullscreen resolution has been changed by SDL, this returns the original desktop mode for the display.

    Type:

      `SDL_DisplayMode`

  property bounds

    The bounding rectangle of the display relative to the full desktop.

    The x and y values for the rectangle represent the pixel coordinates of the top-left corner of the display relative to the full desktop. For example, for a multi-monitor desktop with 2 1920x1200 displays side by side, x and y would be (0, 0) for the left display and (1920, 0) for the right display. The w and h values indicate the current resolution of the display.

    Type:

      `SDL_Rect`

  closest_mode(w, h, hz=None)

    Determines the closest supported mode to a given resolution.

    For example, if this method is called with (1280, 800) on a display that supports up to 1280x720, the 1280x720 display mode will be returned.

    Parameters:

      - w (int) – The target display mode width (in pixels).

      - h (int) – The target display mode height (in pixels).

      - hz (int, optional) – The target display mode refresh rate (in Hz). If `None`, refresh rate will be ignored.

    Returns:

      The closest mode to the requested size/Hz supported by the display.

    Return type:

      `SDL_DisplayMode`

  has_mode(w, h, hz=None)

    Checks whether a given mode is supported by the display.

    Note that this function treats a reported refresh rate of 59 Hz as equivalent to 60 Hz (and 99 Hz to 100 Hz, etc.) to better support OSes that report 60 Hz as 59.94 Hz and get rounded down.

    Parameters:

      - w (int) – The width of the mode to check (in pixels).

      - h (int) – The height of the mode to check (in pixels).

      - hz (int, optional) – The refresh rate of the mode to check (in Hz). If `None`, refresh rate will be ignored.

    Returns:

      True if the mode is supported, otherwise False.

    Return type:

      bool

sdl2.ext.displays.get_displays()

  Returns a list all currently connected displays.

  Returns:

    The display info objects for each connected display.

  Return type:

    list of `DisplayInfo`