2
<title>pygame.display</title>
3
<body bgcolor=#aaeebb text=#000000 link=#331111 vlink=#331111>
6
<table cellspacing=3 width=100%><tr><td bgcolor=#00000>
7
<table width=100%><tr><td bgcolor=c2fc20 align=center>
8
<a href=http://www.pygame.org>
9
<img src=../pygame_tiny.gif border=0 width=200 height=60></a><br>
10
<b>pygame documentation</b>
11
</td><td bgcolor=6aee28 align=center valign=top width=100%>
14
<a href=http://www.pygame.org>Home</a> ||
15
<a href=../index.html>Help Contents</a> ||
18
|| <a href=pygame.html>pygame</a> ||
19
<a href=pygame_cdrom.html>cdrom</a> ||
20
<a href=pygame_constants.html>constants</a> ||
21
<a href=pygame_display.html>display</a> ||
22
<a href=pygame_draw.html>draw</a> ||
23
<a href=pygame_event.html>event</a> ||<br>
24
|| <a href=pygame_font.html>font</a> ||
25
<a href=pygame_image.html>image</a> ||
26
<a href=pygame_joystick.html>joystick</a> ||
27
<a href=pygame_key.html>key</a> ||
28
<a href=pygame_mixer.html>mixer</a> ||
29
<a href=pygame_mixer_music.html>mixer_music</a> ||<br>
30
|| <a href=pygame_mouse.html>mouse</a> ||
31
<a href=pygame_movie.html>movie</a> ||
32
<a href=pygame_surfarray.html>surfarray</a> ||
33
<a href=pygame_time.html>time</a> ||
34
<a href=pygame_transform.html>transform</a> ||<br>
35
<br>|| <a href=CD.html>CD</a> ||
36
<a href=Channel.html>Channel</a> ||
37
<a href=Clock.html>Clock</a> ||
38
<a href=Font.html>Font</a> ||
39
<a href=Joystick.html>Joystick</a> ||
40
<a href=Movie.html>Movie</a> ||<br>
41
|| <a href=Rect.html>Rect</a> ||
42
<a href=Sound.html>Sound</a> ||
43
<a href=Surface.html>Surface</a> ||<br>
44
<br>|| <a href=pygame_cursors.html>cursors</a> ||
45
<a href=pygame_sprite.html>sprite</a> ||
46
<a href=pygame_version.html>version</a> ||<br>
49
</td></tr></table></td></tr></table>
51
<h2 align=center>pygame.display</h2>
52
Contains routines to work with the display. Mainly used for
53
setting the display mode and updating the display surface.
55
Pygame offers a fairly simple interface to the display buffer.
56
The buffer is represented as an offscreen surface to which you
57
can write directly. If you want the screen to show what you have
58
written, the <a href=#update>pygame.display.update()</a> function will guarantee the
59
the desired portion of the screen is updated. You can call
60
<a href=#flip>pygame.display.flip()</a> to update the entire screen, and also flip
61
a hardware surface created with DOUBLEBUF.
63
There are a number of ways to start the video display. The
64
easiest way is to pick a common screen resolution and depth and
65
just initialize the video, checking for exceptions. You will
66
probably get what you want, but pygame may be emulating your
67
requested mode and converting the display on update (this is not
68
the fastest method). When calling <a href=#set_mode>pygame.display.set_mode()</a> with
69
the bit depth omitted or set to zero, pygame will determine the
70
best video mode available and set to that. You can also query for
71
more information on video modes with <a href=#mode_ok>pygame.display.mode_ok()</a>,
72
<a href=#list_modes>pygame.display.list_modes()</a>, and
73
<a href=#Info>pygame.display.Info()</a>.
75
When using a display depth other than what you graphic resources
76
may be saved at, it is best to call the <a href=Surface.html#convert>Surface.convert()</a> routine
77
to convert them to the same format as the display, this will
78
result in the fastest blitting.
80
Pygame currently supports any but depth >= 8 bits per pixl. 8bpp
81
formats are considered to be 8-bit palettized modes, while 12,
82
15, 16, 24, and 32 bits per pixel are considered 'packed pixel'
83
modes, meaning each pixel contains the RGB color componsents
84
packed into the bits of the pixel.
86
After you have initialized your video mode, you can take the
87
surface that was returned and write to it like any other Surface
88
object. Be sure to call <a href=#update>update()</a> or <a href=#flip>flip()</a> to keep what is on the
89
screen synchronized with what is on the surface. Be sure not to call
90
display routines that modify the display surface while it is locked.
95
<tr><td><a href=#Info>Info</a></td><td> -
96
get display capabilities and settings</td></tr>
99
<tr><td><a href=#flip>flip</a></td><td> -
100
update the display</td></tr>
103
<tr><td><a href=#get_active>get_active</a></td><td> -
104
get state of display mode</td></tr>
107
<tr><td><a href=#get_caption>get_caption</a></td><td> -
108
get the current title of the window</td></tr>
111
<tr><td><a href=#get_driver>get_driver</a></td><td> -
112
get the current sdl video driver</td></tr>
115
<tr><td><a href=#get_init>get_init</a></td><td> -
116
get status of display module initialization</td></tr>
119
<tr><td><a href=#get_surface>get_surface</a></td><td> -
120
get current display surface</td></tr>
123
<tr><td><a href=#iconify>iconify</a></td><td> -
124
minimize the display window</td></tr>
127
<tr><td><a href=#init>init</a></td><td> -
128
initialize the display module</td></tr>
131
<tr><td><a href=#list_modes>list_modes</a></td><td> -
132
query all resolutions for requested mode</td></tr>
135
<tr><td><a href=#mode_ok>mode_ok</a></td><td> -
136
query a specific display mode</td></tr>
139
<tr><td><a href=#quit>quit</a></td><td> -
140
uninitialize the display module</td></tr>
143
<tr><td><a href=#set_caption>set_caption</a></td><td> -
144
changes the title of the window</td></tr>
147
<tr><td><a href=#set_gamma>set_gamma</a></td><td> -
148
change the brightness of the display</td></tr>
151
<tr><td><a href=#set_icon>set_icon</a></td><td> -
152
changes the window manager icon for the window</td></tr>
155
<tr><td><a href=#set_mode>set_mode</a></td><td> -
156
set the display mode</td></tr>
159
<tr><td><a href=#set_palette>set_palette</a></td><td> -
160
set the palette</td></tr>
163
<tr><td><a href=#toggle_fullscreen>toggle_fullscreen</a></td><td> -
164
switch the display fullscreen mode</td></tr>
167
<tr><td><a href=#update>update</a></td><td> -
168
update an area of the display</td></tr>
175
<a name=Info><font size=+2><b>Info
176
</b></font><br><font size=+1><tt>
177
pygame.display.Info() -> VidInfo
179
Gets a vidinfo object that contains information about the
180
capabilities and current state of the video driver. This can be
181
called before the display mode is set, to determine the current
182
video mode of a display.
183
You can print the VidInfo object to see all its members and values.
186
<a name=flip><font size=+2><b>flip
187
</b></font><br><font size=+1><tt>
188
pygame.display.flip() -> None
190
This will update the contents of the entire display. If your
191
display mode is using the flags HWSURFACE and DOUBLEBUF, this
192
will wait for a vertical retrace and swap the surfaces. If you
193
are using a different type of display mode, it will simply update
194
the entire contents of the surface.
196
When using an OPENGL display mode this will perform a gl buffer swap.
199
<a name=get_active><font size=+2><b>get_active
200
</b></font><br><font size=+1><tt>
201
pygame.display.get_active() -> bool
203
Returns true if the current display is active on the screen. This
204
done with the call to <a href=#set_mode>pygame.display.set_mode()</a>. It is
205
potentially subject to the activity of a running window manager.
207
Calling <a href=#set_mode>set_mode()</a> will change all existing display surface
208
to reference the new display mode. The old display surface will
209
be lost after this call.
212
<a name=get_caption><font size=+2><b>get_caption
213
</b></font><br><font size=+1><tt>
214
pygame.display.get_caption() -> title, icontitle
216
Returns the current title and icontitle for the display window.
219
<a name=get_driver><font size=+2><b>get_driver
220
</b></font><br><font size=+1><tt>
221
pygame.display.get_driver() -> name
223
Once the display is initialized, this will return the name of the
224
currently running video driver. There is no way to get a list of
225
all the supported video drivers.
228
<a name=get_init><font size=+2><b>get_init
229
</b></font><br><font size=+1><tt>
230
pygame.display.get_init() -> bool
232
Returns true if SDL's video system is currently intialized.
235
<a name=get_surface><font size=+2><b>get_surface
236
</b></font><br><font size=+1><tt>
237
pygame.display.get_surface() -> Surface
239
Returns a Surface object representing the current display. Will
240
return None if called before the display mode is set.
243
<a name=iconify><font size=+2><b>iconify
244
</b></font><br><font size=+1><tt>
245
pygame.display.iconify() -> bool
247
Tells the window manager (if available) to minimize the
248
application. The call will return true if successful. You will
249
receive an APPACTIVE event on the event queue when the window has
253
<a name=init><font size=+2><b>init
254
</b></font><br><font size=+1><tt>
255
pygame.display.init() -> None
257
Manually initialize SDL's video subsystem. Will raise an
258
exception if it cannot be initialized. It is safe to call this
259
function if the video has is currently initialized.
262
<a name=list_modes><font size=+2><b>list_modes
263
</b></font><br><font size=+1><tt>
264
pygame.display.list_modes([depth, [flags]]) -> [[x,y],...] | -1
266
This function returns a list of possible dimensions for a
267
specified color depth. The return value will be an empty list of
268
no display modes are available with the given arguments. A return
269
value of -1 means that any requested resolution should work (this
270
is likely the case for windowed modes). Mode sizes are sorted
271
from biggest to smallest.
273
If depth is not passed or 0, SDL will choose the current/best
274
color depth for the display. You will usually want to pass
275
FULLSCREEN when using the flags, if flags is omitted, FULLSCREEN
279
<a name=mode_ok><font size=+2><b>mode_ok
280
</b></font><br><font size=+1><tt>
281
pygame.display.mode_ok(size, [flags, [depth]]) -> int
283
This uses the same arguments as the call to
284
<a href=#set_mode>pygame.display.set_mode()</a>. It is used to determine if a requested
285
display mode is available. It will return 0 if the requested mode
286
is not possible. Otherwise it will return the best and closest
287
matching bit depth for the mode requested.
289
The size is a 2-number-sequence containing the width and height
290
of the desired display mode. Flags represents a set of different
291
options for the display mode. If omitted or given as 0, it will
292
default to a simple software window. You can mix several flags
293
together with the bitwise-or (|) operator. Possible flags are
294
HWSURFACE (or the value 1), HWPALETTE, DOUBLEBUF, and/or
295
FULLSCREEN. There are other flags available but these are the
296
most usual. A full list of flags can be found in the SDL
297
documentation. The optional depth arguement is the requested bits
298
per pixel. It will usually be left omitted, in which case the
299
display will use the best/fastest pixel depth available.
302
<a name=quit><font size=+2><b>quit
303
</b></font><br><font size=+1><tt>
304
pygame.display.quit() -> None
306
Manually uninitialize SDL's video subsystem. It is safe to call
307
this if the video is currently not initialized.
310
<a name=set_caption><font size=+2><b>set_caption
311
</b></font><br><font size=+1><tt>
312
pygame.display.set_caption(title, [icontitle]) -> None
314
If the display has a window title, this routine will change the
315
name on the window. Some environments support a shorter icon
316
title to be used when the display is minimized. If icontitle is
317
omittied it will be the same as caption title.
320
<a name=set_gamma><font size=+2><b>set_gamma
321
</b></font><br><font size=+1><tt>
322
pygame.display.set_gamma(r, [g, b]) -> bool
324
Sets the display gamma to the given amounts. If green and blue
325
are ommitted, the red value will be used for all three colors.
326
The color arguments are floating point values with 1.0 being the
327
normal value. If you are using a display mode with a hardware
328
palette, this will simply update the palette you are using. Not
329
all hardware supports gamma. The return value will be true on
333
<a name=set_icon><font size=+2><b>set_icon
334
</b></font><br><font size=+1><tt>
335
pygame.display.set_icon(Surface) -> None
337
Sets the runtime icon that your system uses to decorate
338
the program window. It is also used when the application
339
is iconfified. This must be called before the first call
340
to <a href=#set_mode>pygame.display.set_mode()</a>.
342
You likely want this to be a smaller image, a size that
343
your system window manager will be able to deal with. It will
344
also use the Surface colorkey if available.
347
<a name=set_mode><font size=+2><b>set_mode
348
</b></font><br><font size=+1><tt>
349
pygame.display.set_mode(size, [flags, [depth]]) -> Surface
351
Sets the current display mode. If calling this after the mode has
352
already been set, this will change the display mode to the
353
desired type. Sometimes an exact match for the requested video
354
mode is not available. In this case SDL will try to find the
355
closest match and work with that instead.
357
The size is a 2-number-sequence containing the width and height
358
of the desired display mode. Flags represents a set of different
359
options for the new display mode. If omitted or given as 0, it
360
will default to a simple software window. You can mix several
361
flags together with the bitwise-or (|) operator. Possible flags
362
are HWSURFACE (or the value 1), HWPALETTE, DOUBLEBUF, and/or
363
FULLSCREEN. There are other flags available but these are the
364
most usual. A full list of flags can be found in the SDL
365
documentation. The optional depth arguement is the requested bits
366
per pixel. It will usually be left omitted, in which case the
367
display will use the best/fastest pixel depth available.
369
You can also create an OpenGL surface (for use with PyOpenGL)
370
by passing the OPENGL flag. You will likely want to use the
371
DOUBLEBUF flag when using OPENGL. In which case, the <a href=#flip>flip()</a>
372
function will perform the GL buffer swaps. When you are using
373
an OPENGL video mode, you will not be able to perform most of the
374
pygame drawing functions (fill, set_at, etc) on the display surface.
377
<a name=set_palette><font size=+2><b>set_palette
378
</b></font><br><font size=+1><tt>
379
pygame.display.set_palette([[r, g, b], ...]) -> None
381
Displays with a HWPALETTE have two palettes. The display Surface
382
palette and the visible 'onscreen' palette.
384
This will change the video display's visible colormap. It does
385
not effect the display Surface's base palette, only how it is
386
displayed. Setting the palette for the display Surface will
387
override this visible palette. Also passing no args will reset
388
the display palette back to the Surface's palette.
390
You can pass an incomplete list of RGB values, and
391
this will only change the first colors in the palette.
394
<a name=toggle_fullscreen><font size=+2><b>toggle_fullscreen
395
</b></font><br><font size=+1><tt>
396
pygame.display.toggle_fullscreen() -> bool
398
Tells the window manager (if available) to switch between
399
windowed and fullscreen mode. If available and successfull, will
400
return true. Note, there is currently limited platform support
404
<a name=update><font size=+2><b>update
405
</b></font><br><font size=+1><tt>
406
pygame.display.update([rectstyle]) -> None
408
This call will update a section (or sections) of the display
409
screen. You must update an area of your display when you change
410
its contents. If passed with no arguments, this will update the
411
entire display surface. If you have many rects that need
412
updating, it is best to combine them into a sequence and pass
413
them all at once. This call will accept a sequence of rectstyle
414
arguments. Any None's in the list will be ignored.
416
This call cannot be used on OPENGL displays, and will generate
added
removed
docs/ref/pygame_display.html
