|
16
|
1 <!--
|
|
89
|
2 TUTORIAL:Choosing and Configuring Display Modes
|
|
19
|
3 --><html><head>
|
|
|
4
|
|
|
5 <title>Pygame Tutorials - Setting Display Modes</title>
|
|
|
6 </head><body>
|
|
16
|
7
|
|
|
8 <h1 align=center><font size=-1>Pygame Tutorials</font><br>Setting Display Modes</h1>
|
|
|
9 <h2 align=center>by Pete Shinners<br><font size=-1>pete@shinners.org</font></h2>
|
|
384
|
10 <h3 align=center>Revision 1.1, May 21, 2002</h3>
|
|
16
|
11 <br><br>
|
|
|
12
|
|
|
13 <h2>Introduction</h2>
|
|
|
14 Setting the display mode in <i>pygame</i> creates a visible image surface
|
|
|
15 on the monitor. This surface can either cover the full screen, or be windowed
|
|
|
16 on platforms that support a window manager. The display surface is nothing
|
|
|
17 more than a standard <i>pygame</i> surface object. There are special functions
|
|
|
18 needed in the <u>pygame.display</u> module to keep the image surface contents
|
|
|
19 updated on the monitor.<br>
|
|
|
20 <br>
|
|
|
21 Setting the display mode in <i>pygame</i> is an easier task than with most
|
|
|
22 graphic libraries. The advantage is if your display mode is not available,
|
|
|
23 <i>pygame</i> will emulate the display mode that you asked for. <i>Pygame</i>
|
|
|
24 will select a display resolution and color depth that best matches the settings
|
|
|
25 you have requested, then allow you to access the display with the format
|
|
|
26 you have requested. In reality, since the <u>pygame.display</u> module is
|
|
|
27 a binding around the SDL library, SDL is really doing all this work.<br>
|
|
|
28 <br>
|
|
|
29 There are advantages and disadvantages to setting the display mode in this
|
|
|
30 manner. The advantage is that if your game requires a specific display mode,
|
|
|
31 your game will run on platforms that do not support your requirements. It
|
|
|
32 also makes life easier when your getting something started, it is always easy
|
|
|
33 to go back later and make the mode selection a little more particular. The
|
|
|
34 disadvantage is that what you request is not always what you will get. There
|
|
|
35 is also a performance penalty when the display mode must be emulated. This
|
|
|
36 tutorial will help you understand the different methods for querying the platforms
|
|
|
37 display capabilities, and setting the display mode for your game.<br>
|
|
|
38 <br>
|
|
|
39 <br>
|
|
|
40
|
|
|
41 <h2>Setting Basics</h2>
|
|
|
42 The first thing to learn about is how to actually set the current display
|
|
|
43 mode. The display mode may be set at anytime after the <u>pygame.display</u>
|
|
|
44 module has been initialized. If you have previously set the display mode,
|
|
|
45 setting it again will change the current mode. Setting the display mode is
|
|
384
|
46 handled with the function <u><tt>pygame.display.set_mode((width, height), flags, depth)</tt></u>.
|
|
|
47 The only required argument in this function is a sequence containing
|
|
16
|
48 the width and height of the new display mode. The depth flag is the requested
|
|
|
49 bits per pixel for the surface. If the given depth is 8, <i>pygame</i> will
|
|
|
50 create a color-mapped surface. When given a higher bit depth, <i>pygame</i>
|
|
|
51 will use a packed color mode. Much more information about depths and color
|
|
|
52 modes can be found in the documentation for the display and surface modules.
|
|
|
53 The default value for depth is 0. When given an argument of 0, <i>pygame</i>
|
|
|
54 will select the best bit depth to use, usually the same as the system's
|
|
|
55 current bit depth. The flags argument lets you control extra features for
|
|
|
56 the display mode. You can create the display surface in hardware memory with
|
|
|
57 the HWSURFACE flag. Again, more information about this is found in the <i>
|
|
|
58 pygame</i> reference documents.<br>
|
|
|
59 <br>
|
|
|
60 <br>
|
|
|
61
|
|
|
62 <h2>How to Decide</h2>
|
|
|
63 So how do you select a display mode that is going to work best with your
|
|
|
64 graphic resources and the platform your game is running on? There are several
|
|
|
65 methods for gathering information about the display device. All of these methods
|
|
|
66 must be called after the display module has been initialized, but you likely
|
|
|
67 want to call them before setting the display mode. First, <u><tt>pygame.display.get_info()</tt></u>
|
|
|
68 will return a special object type of VidInfo, which can tell you a lot about
|
|
|
69 the graphics driver capabilities. The function <u><tt>pygame.display.list_modes(depth,
|
|
|
70 flags)</tt></u> can be used to find the supported graphic modes by the system.
|
|
384
|
71 <u><tt>Pygame.display.mode_ok((width, height), flags, depth)</tt></u> takes the same
|
|
16
|
72 arguments as <u><tt>set_mode()</tt></u>, but returns the closest matching bit depth
|
|
|
73 to the one you request. Lastly, <u><tt>pygame.display.get_driver()</tt></u> will return
|
|
|
74 the name of the graphics driver selected by <i>pygame</i>.<br>
|
|
|
75 <br>
|
|
|
76 Just remember the golden rule. <i>Pygame</i> will work with pretty much
|
|
19
|
77 any display mode you request. Some display modes will need to be emulated,
|
|
16
|
78 which will slow your game down, since <i>pygame</i> will need to convert
|
|
19
|
79 every update you make to the "real" display mode. The best bet is to
|
|
|
80 always let <i>pygame</i> choose the best bit depth, and convert all
|
|
|
81 your graphic resources to that format when they are loaded. You let
|
|
16
|
82 <i>pygame</i> choose it's bit depth by calling set_mode() with no depth argument
|
|
19
|
83 or a depth of 0, or you can call mode_ok() to find a closest matching
|
|
16
|
84 bit depth to what you need.<br>
|
|
|
85 <br>
|
|
384
|
86 When your display mode is windowed, you usually must math the same
|
|
|
87 bit depth as the desktop. When you are fullscreen, some platforms can switch
|
|
|
88 to any bit depth that best suits your needs. You can find the depth of the
|
|
19
|
89 current desktop if you get a VidInfo object before ever setting your display
|
|
|
90 mode.<br>
|
|
|
91 <br>
|
|
16
|
92 After setting the display mode, you can find out information about it's
|
|
384
|
93 settings by getting a VidInfo object, or by calling any of the Surface.get*
|
|
|
94 methods on the display surface.<br>
|
|
16
|
95 <br>
|
|
|
96 <br>
|
|
|
97
|
|
|
98 <h2>Functions</h2>
|
|
|
99 These are the routines you can use to determine the most appropriate display
|
|
|
100 mode. You can find more information about these functions in the display module
|
|
|
101 documentation. <br>
|
|
|
102 <br>
|
|
|
103
|
|
384
|
104 <blockquote><u><tt>pygame.display.mode_ok(size, flags, depth)</tt></u><br>
|
|
16
|
105
|
|
|
106 <blockquote> This function takes the exact same arguments as pygame.display.set_mode().
|
|
19
|
107 It returns the best available bit depth for the mode you have described.
|
|
|
108 If this returns zero, then the desired display mode is not available
|
|
16
|
109 without emulation.<br>
|
|
|
110 </blockquote>
|
|
|
111 <br>
|
|
|
112 <u><tt>pygame.display.list_modes(depth, flags)</tt></u><br>
|
|
|
113
|
|
|
114 <blockquote> Returns a list of supported display modes with the requested
|
|
19
|
115 depth and flags. An empty list is returned when there are no modes.
|
|
|
116 The flags argument defaults to FULLSCREEN. If you specify your own flags
|
|
|
117 without FULLSCREEN, you will likely get a return value of -1. This
|
|
|
118 means that any display size is fine, since the display will be windowed. Note
|
|
16
|
119 that the listed modes are sorted largest to smallest.<br>
|
|
|
120 </blockquote>
|
|
|
121 <br>
|
|
|
122 <u><tt>pygame.display.get_info()</tt></u><br>
|
|
|
123
|
|
|
124 <blockquote> This function returns an object with many members describing
|
|
|
125 the display devic. Printing the VidInfo object will quickly show you all the
|
|
|
126 members and values for this object. <br>
|
|
|
127
|
|
|
128 <blockquote><tt> >>> <b>import pygame.display</b><br>
|
|
|
129 >>> <b>pygame.display.init()</b><br>
|
|
|
130 >>> <b>info = pygame.display.get_info()</b><br>
|
|
|
131 >>> <b>print info</b><br>
|
|
|
132 <VideoInfo(hw = 1, wm = 1,video_mem = 27354<br>
|
|
|
133 blit_hw = 1, blit_hw_CC = 1, blit_hw_A = 0,<br>
|
|
|
134 blit_sw = 1, blit_sw_CC = 1, blit_sw_A = 0,<br>
|
|
|
135 bitsize = 32, bytesize = 4,<br>
|
|
|
136 masks = (16711680, 65280, 255, 0),<br>
|
|
|
137 shifts = (16, 8, 0, 0),<br>
|
|
|
138 losses = (0, 0, 0, 8)></tt><br>
|
|
|
139 </blockquote>
|
|
|
140 You can test all these flags as simply members of the VidInfo object. The
|
|
|
141 different blit flags tell if hardware acceleration is supported when blitting
|
|
|
142 from the various types of surfaces to a hardware surface.<br>
|
|
|
143 </blockquote>
|
|
|
144 </blockquote>
|
|
|
145 <br>
|
|
|
146 <br>
|
|
|
147
|
|
|
148 <h2>Examples</h2>
|
|
|
149 Here are some examples of different methods to init the graphics display.
|
|
|
150 They should help you get an idea of how to go about setting your display mode.<br>
|
|
|
151 <br>
|
|
|
152
|
|
|
153 <blockquote><tt> >>> #give me the best depth with a 640
|
|
|
154 x 480 windowed display<br>
|
|
|
155 >>> <b>pygame.display.set_mode((640, 480))</b><br>
|
|
|
156 <br>
|
|
|
157 >>> #give me the biggest 16bit display available<br>
|
|
384
|
158 >>> <b>modes = pygame.display.list_modes(16)</b><br>
|
|
16
|
159 >>> <b>if not modes:</b><br>
|
|
19
|
160 ... <b> print '16bit not supported'</b><br>
|
|
16
|
161 ... <b>else:</b><br>
|
|
19
|
162 ... <b> print 'Found Resolution:', modes[0]</b><br>
|
|
897
|
163 ... <b> pygame.display.set_mode(modes[0], FULLSCREEN, 16)</b><br>
|
|
16
|
164 <br>
|
|
|
165 >>> #need an 8bit surface, nothing else will do<br>
|
|
412
|
166 >>> <b>if pygame.display.mode_ok((800, 600), 0, 8) != 8:</b><br>
|
|
19
|
167 ... <b> print 'Can only work with an 8bit display, sorry'</b><br>
|
|
16
|
168 ... <b>else:</b><br>
|
|
412
|
169 ... <b> pygame.display.set_mode((800, 600), 0, 8)</b><br>
|
|
16
|
170 <br>
|
|
|
171 </tt></blockquote>
|
|
|
172
|
|
|
173 </body>
|
|
|
174 </html>
|
