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.

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

New in version 1.2.

Return type:: 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 (primary) 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 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.

Deprecated:

Use pyglet.gl.Config.match().

Parameters:

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

widthint: Requested screen width.
heightint: 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.

Deprecated:

Use pyglet.gl.Config.match().

Parameters:

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

modeScreenMode: Screen mode to switch this screen to.

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(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: Display this canvas was created on.