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 :class`~pyglet.canvas.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 :class`~pyglet.canvas.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()

Get the default display device.

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

New in version 1.2.

Return type::class`~pyglet.canvas.Display`

class Display(name=None, x_screen=None)

A display device supporting one or more screens.

New in version 1.2.

get_default_screen()

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

Return type:Screen

get_screens()

Get the available screens.

A typical multi-monitor workstation comprises one :class`~pyglet.canvas.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()

Get the windows currently attached to this display.

Return type:sequence of Window

name = None

Name of this display, if applicable.

Type:str

x_screen = None

The X11 screen number of this display, if applicable.

Type:int

class Screen(display, x, y, width, height)

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.

get_best_config(template=None)

Get the best available GL config.

Any required attributes can be specified in template. If no configuration matches the template, NoSuchConfigException will be raised.

Warning

Deprecated. Use pyglet.gl.Config.match().

Parameters:template (pyglet.gl.Config) – A configuration with desired attributes filled in. Return type:Config Returns:A configuration supported by the platform that best fulfils the needs described by the template.

get_closest_mode(width, height)

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.

Parameters:

• width (int) – Requested screen width.
• height (int) – Requested screen height.

Return type:

ScreenMode

New in version 1.2.

get_matching_configs(template)

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.

Warning

Deprecated. Use pyglet.gl.Config.match().

Parameters:template (pyglet.gl.Config) – A configuration with desired attributes filled in. Return type:list of Config Returns:A list of matching configs.

get_mode()

Get the current display mode for this screen.

Return type:ScreenMode

New in version 1.2.

get_modes()

Get a list of screen modes supported by this screen.

Return type:list of ScreenMode

New in version 1.2.

restore_mode()

Restore the screen mode to the user’s default.

set_mode(mode)

Set the display mode for this screen.

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

Parameters:mode (ScreenMode) – Screen mode to switch this screen to.

display = None

Display this screen belongs to.

height = None

Height of the screen, in pixels.

width = None

Width of the screen, in pixels.

x = None

Left edge of the screen on the virtual desktop.

y = None

Top edge of the screen on the virtual desktop.

class Canvas(display)

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.

display = None

Display this canvas was created on.