pyglet.canvas

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.

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.

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:: Screen

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:: 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, )

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.

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

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:: Screen

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:: 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, )

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.

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