Display and screen management.

Rendering is performed on a Canvas, which conceptually could be an off-screen buffer, the content area of a pyglet.window.Window, or an entire screen. Currently, canvases can only be created with windows (though windows can be set fullscreen).

Windows and canvases must belong to a Display. On Windows and Mac OS X 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.

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.

New in version 1.2.

__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.canvas.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:


get_screens() list[pyglet.canvas.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:


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.

display: Display,
x: int,
y: int,
width: int,
height: int,
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.




template (Config) – A configuration with desired attributes filled in.

Return type:


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.

template: Config,
) list[]

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.




template (Config) – A configuration with desired attributes filled in.

Return type:


get_mode() ScreenMode

Get the current display mode for this screen. :rtype: ScreenMode

New in version 1.2.

get_modes() list[pyglet.canvas.base.ScreenMode]

Get a list of screen modes supported by this screen. :rtype: list[ScreenMode]

New in version 1.2.

restore_mode() None

Restore the screen mode to the user’s default.

Return type:


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:



Display this screen belongs to.


Height of the screen, in pixels.


Width of the screen, in pixels.


Left edge of the screen on the virtual desktop.


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 this canvas was created on.