pyglet.display

Display and screen management.

Rendering is performed on the content area of a pyglet.window.Window, or an entire screen.

Windows must belong to a Display. On Microsoft Windows and macOS, there is only one display, which can be obtained with get_display(). Linux supports multiple displays, corresponding to discrete X11 display connections and screens. get_display() on Linux returns the default display and screen 0 (localhost:0.0); if a particular screen or display is required then Display can be instantiated directly.

Within a display one or more screens are attached. A Screen often corresponds to a physical attached monitor, however a monitor or projector set up to clone another screen will not be listed. Use Display.get_screens() to get a list of the attached screens; these can then be queried for their sizes and virtual positions on the desktop.

The size of a screen is determined by its current mode, which can be changed by the application; see the documentation for Screen.

New in version 1.2.

class Canvas

Abstract drawing area.

Canvases are used internally by pyglet to represent drawing areas – either within a window or full-screen.

New in version 1.2.

__init__(display: Display) → None

display: Display this canvas was created on.

class Display

A display device supporting one or more screens.

__init__(name: str = None, x_screen: int = None) → None

Create a display connection for the given name and screen.

On X11, name is of the form "hostname:display", where the default is usually ":1". On X11, x_screen gives the X screen number to use with this display. A pyglet display can only be used with one X screen; open multiple display connections to access multiple X screens.

Note that TwinView, Xinerama, xrandr and other extensions present multiple monitors on a single X screen; this is usually the preferred mechanism for working with multiple monitors under X11 and allows each screen to be accessed through a single pyglet`~pyglet.display.Display`

On platforms other than X11, name and x_screen are ignored; there is only a single display device on these systems.

get_default_screen() → Screen

Get the default (primary) screen as specified by the user’s operating system preferences.

Return type:: Screen

get_screens() → list[pyglet.display.base.Screen]

Get the available screens.

A typical multi-monitor workstation comprises one Display with multiple Screen s. This method returns a list of screens which can be enumerated to select one for full-screen display.

For the purposes of creating an OpenGL config, the default screen will suffice.

Return type:: list of Screen

get_windows() → list[pyglet.window.Window]

Get the windows currently attached to this display.

Return type:: list[Window]

name: str = None: Name of this display, if applicable.

x_screen: int = None: The X11 screen number of this display, if applicable.

class Screen

A virtual monitor that supports fullscreen windows.

Screens typically map onto a physical display such as a monitor, television or projector. Selecting a screen for a window has no effect unless the window is made fullscreen, in which case the window will fill only that particular virtual screen.

The width and height attributes of a screen give the current resolution of the screen. The x and y attributes give the global location of the top-left corner of the screen. This is useful for determining if screens are arranged above or next to one another.

Use get_screens() or get_default_screen() to obtain an instance of this class.

__init__( display: Display, x: int, y: int, width: int, height: int, ) → None

get_best_config( template: Config = None, ) → Config

Get the best available GL config.

Any required attributes can be specified in template. If no configuration matches the template, NoSuchConfigException will be raised. A configuration supported by the platform that best fulfils the needs described by the template.

Deprecated:: Use pyglet.gl.Config.match().
Parameters:: template (Config) – A configuration with desired attributes filled in.
Return type:: Config

get_closest_mode(width: int, height: int) → ScreenMode

Get the screen mode that best matches a given size.

If no supported mode exactly equals the requested size, a larger one is returned; or None if no mode is large enough. :rtype: ScreenMode

New in version 1.2.

abstract get_display_id() → str | int: Get a unique identifier for the screen. :rtype: str | int

get_dpi(): Get the DPI of the screen.

get_matching_configs( template: Config, ) → list[pyglet.gl.base.Config]

Get a list of configs that match a specification.

Any attributes specified in template will have values equal to or greater in each returned config. If no configs satisfy the template, an empty list is returned.

Deprecated:: Use pyglet.gl.Config.match().
Parameters:: template (Config) – A configuration with desired attributes filled in.
Return type:: list[Config]

get_mode() → ScreenMode: Get the current display mode for this screen. :rtype: ScreenMode

New in version 1.2.

get_modes() → list[pyglet.display.base.ScreenMode]: Get a list of screen modes supported by this screen. :rtype: list[ScreenMode]

New in version 1.2.

abstract get_monitor_name() → str | Literal['Unknown']

Get a friendly name for the screen if available.

Windows and Mac OSX report what the system will see the screen as.

On Linux, there is no API for retrieving the monitor name, other than manually decoding the EDID information. Instead, it will return the connection name.

If no name can be queried, a default name of Unknown will be returned. :rtype: str | Literal['Unknown']

get_scale() → float

Get the pixel scale ratio of the screen.

Return type:: float

restore_mode() → None

Restore the screen mode to the user’s default.

Return type:: None

set_mode(mode: ScreenMode) → None

Set the display mode for this screen.

The mode must be one previously returned by get_mode() or get_modes().

Return type:: None

display: Display this screen belongs to.

height: Height of the screen, in pixels.

width: Width of the screen, in pixels.

x: Left edge of the screen on the virtual desktop.

y: Top edge of the screen on the virtual desktop.

class ScreenMode

Screen resolution and display settings.

Applications should not construct ScreenMode instances themselves; see Screen.get_modes().

The depth and rate variables may be None if the operating system does not provide relevant data.

New in version 1.2.

__init__(screen: Screen) → None

depth: int = None: Pixel color depth, in bits per pixel.

height: int = None: Height of screen, in pixels.

rate: int = None: Screen refresh rate in Hz.

width: int = None: Width of screen, in pixels.

get_display() → Display

Get the default display device.

If there is already a Display connection, that display will be returned. Otherwise, a default Display is created and returned. If multiple display connections are active, an arbitrary one is returned. :rtype: Display

New in version 1.2.

class Display

A display device supporting one or more screens.

__init__(name: str = None, x_screen: int = None) → None

Create a display connection for the given name and screen.

On X11, name is of the form "hostname:display", where the default is usually ":1". On X11, x_screen gives the X screen number to use with this display. A pyglet display can only be used with one X screen; open multiple display connections to access multiple X screens.

Note that TwinView, Xinerama, xrandr and other extensions present multiple monitors on a single X screen; this is usually the preferred mechanism for working with multiple monitors under X11 and allows each screen to be accessed through a single pyglet`~pyglet.display.Display`

On platforms other than X11, name and x_screen are ignored; there is only a single display device on these systems.

get_default_screen() → Screen

Get the default (primary) screen as specified by the user’s operating system preferences.

Return type:: Screen

get_screens() → list[pyglet.display.base.Screen]

Get the available screens.

A typical multi-monitor workstation comprises one Display with multiple Screen s. This method returns a list of screens which can be enumerated to select one for full-screen display.

For the purposes of creating an OpenGL config, the default screen will suffice.

Return type:: list of Screen

get_windows() → list[pyglet.window.Window]

Get the windows currently attached to this display.

Return type:: list[Window]

name: str = None: Name of this display, if applicable.

x_screen: int = None: The X11 screen number of this display, if applicable.

class Screen

A virtual monitor that supports fullscreen windows.

Screens typically map onto a physical display such as a monitor, television or projector. Selecting a screen for a window has no effect unless the window is made fullscreen, in which case the window will fill only that particular virtual screen.

The width and height attributes of a screen give the current resolution of the screen. The x and y attributes give the global location of the top-left corner of the screen. This is useful for determining if screens are arranged above or next to one another.

Use get_screens() or get_default_screen() to obtain an instance of this class.

__init__( display: Display, x: int, y: int, width: int, height: int, ) → None

get_best_config( template: Config = None, ) → Config

Get the best available GL config.

Any required attributes can be specified in template. If no configuration matches the template, NoSuchConfigException will be raised. A configuration supported by the platform that best fulfils the needs described by the template.

Deprecated:: Use pyglet.gl.Config.match().
Parameters:: template (Config) – A configuration with desired attributes filled in.
Return type:: Config

get_closest_mode(width: int, height: int) → ScreenMode

Get the screen mode that best matches a given size.

If no supported mode exactly equals the requested size, a larger one is returned; or None if no mode is large enough. :rtype: ScreenMode

New in version 1.2.

abstract get_display_id() → str | int: Get a unique identifier for the screen. :rtype: str | int

get_dpi(): Get the DPI of the screen.

get_matching_configs( template: Config, ) → list[pyglet.gl.base.Config]

Get a list of configs that match a specification.

Any attributes specified in template will have values equal to or greater in each returned config. If no configs satisfy the template, an empty list is returned.

Deprecated:: Use pyglet.gl.Config.match().
Parameters:: template (Config) – A configuration with desired attributes filled in.
Return type:: list[Config]

get_mode() → ScreenMode: Get the current display mode for this screen. :rtype: ScreenMode

New in version 1.2.

get_modes() → list[pyglet.display.base.ScreenMode]: Get a list of screen modes supported by this screen. :rtype: list[ScreenMode]

New in version 1.2.

abstract get_monitor_name() → str | Literal['Unknown']

Get a friendly name for the screen if available.

Windows and Mac OSX report what the system will see the screen as.

On Linux, there is no API for retrieving the monitor name, other than manually decoding the EDID information. Instead, it will return the connection name.

If no name can be queried, a default name of Unknown will be returned. :rtype: str | Literal['Unknown']

get_scale() → float

Get the pixel scale ratio of the screen.

Return type:: float

restore_mode() → None

Restore the screen mode to the user’s default.

Return type:: None

set_mode(mode: ScreenMode) → None

Set the display mode for this screen.

The mode must be one previously returned by get_mode() or get_modes().

Return type:: None

display: Display this screen belongs to.

height: Height of the screen, in pixels.

width: Width of the screen, in pixels.

x: Left edge of the screen on the virtual desktop.

y: Top edge of the screen on the virtual desktop.

class Canvas

Abstract drawing area.

Canvases are used internally by pyglet to represent drawing areas – either within a window or full-screen.

New in version 1.2.

__init__(display: Display) → None

display: Display this canvas was created on.