pygame documentation | || Home || Help Contents || || pygame || cdrom || constants || cursor || display || draw || || event || font || image || joystick || key || mixer || || mixer_music || mouse || movie || sndarray || surfarray || time || || transform || || CD || Channel || Clock || Font || Joystick || Movie || || Overlay || Rect || Sound || Surface || || color || cursors || sprite ||

## pygame.display

Contains routines to work with the display. Mainly used for setting the display mode and updating the display surface.
Pygame offers a fairly simple interface to the display buffer. The buffer is represented as an offscreen surface to which you can write directly. If you want the screen to show what you have written, the pygame.display.update() function will guarantee the the desired portion of the screen is updated. You can call pygame.display.flip() to update the entire screen, and also flip a hardware surface created with DOUBLEBUF.
There are a number of ways to start the video display. The easiest way is to pick a common screen resolution and depth and just initialize the video, checking for exceptions. You will probably get what you want, but pygame may be emulating your requested mode and converting the display on update (this is not the fastest method). When calling pygame.display.set_mode() with the bit depth omitted or set to zero, pygame will determine the best video mode available and set to that. You can also query for more information on video modes with pygame.display.mode_ok(), pygame.display.list_modes(), and pygame.display.Info().
When using a display depth other than what you graphic resources may be saved at, it is best to call the Surface.convert() routine to convert them to the same format as the display, this will result in the fastest blitting.
Pygame currently supports any but depth >= 8 bits per pixl. 8bpp formats are considered to be 8-bit palettized modes, while 12, 15, 16, 24, and 32 bits per pixel are considered 'packed pixel' modes, meaning each pixel contains the RGB color componsents packed into the bits of the pixel.
After you have initialized your video mode, you can take the surface that was returned and write to it like any other Surface object. Be sure to call update() or flip() to keep what is on the screen synchronized with what is on the surface. Be sure not to call display routines that modify the display surface while it is locked.

Info | - get display capabilities and settings
flip | - update the display
get_active | - get state of display mode
get_caption | - get the current title of the window
get_driver | - get the current sdl video driver
get_init | - get status of display module initialization
get_surface | - get current display surface
get_wm_info | - get settings from the system window manager
gl_get_attribute | - get special OPENGL attributes
gl_set_attribute | - set special OPENGL attributes
iconify | - minimize the display window
init | - initialize the display module
list_modes | - query all resolutions for requested mode
mode_ok | - query a specific display mode
quit | - uninitialize the display module
set_caption | - changes the title of the window
set_gamma | - change the brightness of the display
set_gamma_ramp | - advanced control over the display gamma ramps
set_icon | - changes the window manager icon for the window
set_mode | - set the display mode
set_palette | - set the palette
toggle_fullscreen | - switch the display fullscreen mode
update | - update an area of the display

Info
`pygame.display.Info() -> VidInfo`

Gets a vidinfo object that contains information about the capabilities and current state of the video driver. This can be called before the display mode is set, to determine the current video mode of a display. You can print the VidInfo object to see all its members and values.

flip
`pygame.display.flip() -> None`

This will update the contents of the entire display. If your display mode is using the flags HWSURFACE and DOUBLEBUF, this will wait for a vertical retrace and swap the surfaces. If you are using a different type of display mode, it will simply update the entire contents of the surface.
When using an OPENGL display mode this will perform a gl buffer swap.

get_active
`pygame.display.get_active() -> bool`

Returns true if the current display is active on the screen. This done with the call to pygame.display.set_mode(). It is potentially subject to the activity of a running window manager.
Calling set_mode() will change all existing display surface to reference the new display mode. The old display surface will be lost after this call.

get_caption
`pygame.display.get_caption() -> title, icontitle`

Returns the current title and icontitle for the display window.

get_driver
`pygame.display.get_driver() -> name`

Once the display is initialized, this will return the name of the currently running video driver. There is no way to get a list of all the supported video drivers.

get_init
`pygame.display.get_init() -> bool`

Returns true if SDL's video system is currently intialized.

get_surface
`pygame.display.get_surface() -> Surface`

Returns a Surface object representing the current display. Will return None if called before the display mode is set.

get_wm_info
`pygame.display.get_wm_info() -> dictionary`

Creates a dictionary filled with name and value pairs. Most platforms will have a 'window' value, set to the system's window id number or handle. Different platforms will get different key values, which are entirely dependent on SDL. On rare platforms this is unimplmented in the SDL system, and you will get an empty dictionary.

gl_get_attribute
`pygame.display.gl_get_attribute(flag) -> value`

After calling pygame.display.set_mode() with the OPENGL flag you will likely want to check the value of any special opengl attributes you requested. You will not always get what you requested.
See pygame.display.gl_set_attribute() for a list of flags.
The OPENGL flags are; GL_ALPHA_SIZE, GL_DEPTH_SIZE, GL_STENCIL_SIZE, GL_ACCUM_RED_SIZE, GL_ACCUM_GREEN_SIZE, GL_ACCUM_BLUE_SIZE, GL_ACCUM_ALPHA_SIZE, GL_RED_SIZE, GL_GREEN_SIZE, GL_BLUE_SIZE, GL_DEPTH_SIZE

gl_set_attribute
`pygame.display.gl_set_attribute(flag, value) -> None`

When calling pygame.display.set_mode() with the OPENGL flag, pygame automatically handles setting the opengl attributes like color and doublebuffering. OPENGL offers several other attributes you may want control over. Pass one of these attributes as the flag, and its appropriate value.
This must be called before pygame.display.set_mode()
The OPENGL flags are; GL_ALPHA_SIZE, GL_DEPTH_SIZE, GL_STENCIL_SIZE, GL_ACCUM_RED_SIZE, GL_ACCUM_GREEN_SIZE, GL_ACCUM_BLUE_SIZE, GL_ACCUM_ALPHA_SIZE GL_MULTISAMPLEBUFFERS, GL_MULTISAMPLESAMPLES, GL_STEREO

iconify
`pygame.display.iconify() -> bool`

Tells the window manager (if available) to minimize the application. The call will return true if successful. You will receive an APPACTIVE event on the event queue when the window has been minimized.

init
`pygame.display.init() -> None`

Manually initialize SDL's video subsystem. Will raise an exception if it cannot be initialized. It is safe to call this function if the video has is currently initialized.

list_modes
`pygame.display.list_modes([depth, [flags]]) -> [[x,y],...] | -1`

This function returns a list of possible dimensions for a specified color depth. The return value will be an empty list if no display modes are available with the given arguments. A return value of -1 means that any requested resolution should work (this is likely the case for windowed modes). Mode sizes are sorted from biggest to smallest.
If depth is not passed or 0, SDL will choose the current/best color depth for the display. You will usually want to pass FULLSCREEN when using the flags, if flags is omitted, FULLSCREEN is the default.

mode_ok
`pygame.display.mode_ok(size, [flags, [depth]]) -> int`

This uses the same arguments as the call to pygame.display.set_mode(). It is used to determine if a requested display mode is available. It will return 0 if the requested mode is not possible. Otherwise it will return the best and closest matching bit depth for the mode requested.
The size is a 2-number-sequence containing the width and height of the desired display mode. Flags represents a set of different options for the display mode. If omitted or given as 0, it will default to a simple software window. You can mix several flags together with the bitwise-or (|) operator. Possible flags are HWSURFACE (or the value 1), HWPALETTE, DOUBLEBUF, and/or FULLSCREEN. There are other flags available but these are the most usual. A full list of flags can be found in the SDL documentation. The optional depth arguement is the requested bits per pixel. It will usually be left omitted, in which case the display will use the best/fastest pixel depth available.

quit
`pygame.display.quit() -> None`

Manually uninitialize SDL's video subsystem. It is safe to call this if the video is currently not initialized.

set_caption
`pygame.display.set_caption(title, [icontitle]) -> None`

If the display has a window title, this routine will change the name on the window. Some environments support a shorter icon title to be used when the display is minimized. If icontitle is omittied it will be the same as caption title.

set_gamma
`pygame.display.set_gamma(r, [g, b]) -> bool`

Sets the display gamma to the given amounts. If green and blue are ommitted, the red value will be used for all three colors. The color arguments are floating point values with 1.0 being the normal value. If you are using a display mode with a hardware palette, this will simply update the palette you are using. Not all hardware supports gamma. The return value will be true on success.

set_gamma_ramp
`pygame.display.set_gamma_ramp(r, g, b) -> bool`

Pass three sequences with 256 elements. Each element must be a '16bit' unsigned integer value. This is from 0 to 65536. If you are using a display mode with a hardware palette, this will simply update the palette you are using. Not all hardware supports gamma. The return value will be true on success.

set_icon
`pygame.display.set_icon(Surface) -> None`

Sets the runtime icon that your system uses to decorate the program window. It is also used when the application is iconified and in the window frame.
You likely want this to be a smaller image, a size that your system window manager will be able to deal with. It will also use the Surface colorkey if available.
Some window managers on X11 don't allow you to change the icon after the window has been shown the first time.

set_mode
`pygame.display.set_mode(size, [flags, [depth]]) -> Surface`

Sets the current display mode. If calling this after the mode has already been set, this will change the display mode to the desired type. Sometimes an exact match for the requested video mode is not available. In this case SDL will try to find the closest match and work with that instead.
The size is a 2-number-sequence containing the width and height of the desired display mode. Flags represents a set of different options for the new display mode. If omitted or given as 0, it will default to a simple software window. You can mix several flags together with the bitwise-or (|) operator. Possible flags are HWSURFACE (or the value 1), HWPALETTE, DOUBLEBUF, and/or FULLSCREEN. There are other flags available but these are the most usual. A full list of flags can be found in the pygame documentation.
The optional depth arguement is the requested bits per pixel. It will usually be left omitted, in which case the display will use the best/fastest pixel depth available.
You can create an OpenGL surface (for use with PyOpenGL) by passing the OPENGL flag. You will likely want to use the DOUBLEBUF flag when using OPENGL. In which case, the flip() function will perform the GL buffer swaps. When you are using an OPENGL video mode, you will not be able to perform most of the pygame drawing functions (fill, set_at, etc) on the display surface.

set_palette
`pygame.display.set_palette([[r, g, b], ...]) -> None`

Displays with a HWPALETTE have two palettes. The display Surface palette and the visible 'onscreen' palette.
This will change the video display's visible colormap. It does not effect the display Surface's base palette, only how it is displayed. Setting the palette for the display Surface will override this visible palette. Also passing no args will reset the display palette back to the Surface's palette.
You can pass an incomplete list of RGB values, and this will only change the first colors in the palette.

toggle_fullscreen
`pygame.display.toggle_fullscreen() -> bool`

Tells the window manager (if available) to switch between windowed and fullscreen mode. If available and successfull, will return true. Note, there is currently limited platform support for this call.

update
`pygame.display.update([rectstyle]) -> None`

This call will update a section (or sections) of the display screen. You must update an area of your display when you change its contents. If passed with no arguments, this will update the entire display surface. If you have many rects that need updating, it is best to combine them into a sequence and pass them all at once. This call will accept a sequence of rectstyle arguments. Any None's in the list will be ignored.
This call cannot be used on OPENGL displays, and will generate an exception.