Pygame Tutorials
Setting Display Modes

by Pete Shinners
pete@shinners.org

Revision 1.01, November 14th, 2000



Introduction

Setting the display mode in pygame creates a visible image surface on the monitor. This surface can either cover the full screen, or be windowed on platforms that support a window manager. The display surface is nothing more than a standard pygame surface object. There are special functions needed in the pygame.display module to keep the image surface contents updated on the monitor.

Setting the display mode in pygame is an easier task than with most graphic libraries. The advantage is if your display mode is not available, pygame will emulate the display mode that you asked for. Pygame will select a display resolution and color depth that best matches the settings you have requested, then allow you to access the display with the format you have requested. In reality, since the pygame.display module is a binding around the SDL library, SDL is really doing all this work.

There are advantages and disadvantages to setting the display mode in this manner. The advantage is that if your game requires a specific display mode, your game will run on platforms that do not support your requirements. It also makes life easier when your getting something started, it is always easy to go back later and make the mode selection a little more particular. The disadvantage is that what you request is not always what you will get. There is also a performance penalty when the display mode must be emulated. This tutorial will help you understand the different methods for querying the platforms display capabilities, and setting the display mode for your game.


Setting Basics

The first thing to learn about is how to actually set the current display mode. The display mode may be set at anytime after the pygame.display module has been initialized. If you have previously set the display mode, setting it again will change the current mode. Setting the display mode is handled with the function pygame.display.set_mode((width, height), depth, flags). The only required argument in this function is a sequence containing the width and height of the new display mode. The depth flag is the requested bits per pixel for the surface. If the given depth is 8, pygame will create a color-mapped surface. When given a higher bit depth, pygame will use a packed color mode. Much more information about depths and color modes can be found in the documentation for the display and surface modules. The default value for depth is 0. When given an argument of 0, pygame will select the best bit depth to use, usually the same as the system's current bit depth. The flags argument lets you control extra features for the display mode. You can create the display surface in hardware memory with the HWSURFACE flag. Again, more information about this is found in the pygame reference documents.


How to Decide

So how do you select a display mode that is going to work best with your graphic resources and the platform your game is running on? There are several methods for gathering information about the display device. All of these methods must be called after the display module has been initialized, but you likely want to call them before setting the display mode. First, pygame.display.get_info() will return a special object type of VidInfo, which can tell you a lot about the graphics driver capabilities. The function pygame.display.list_modes(depth, flags) can be used to find the supported graphic modes by the system. Pygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_driver() will return the nameygame.display.mode_ok((width, height), depth, flags) takes the same arguments as set_mode(), but returns the closest matching bit depth to the one you request. Lastly, pygame.display.get_dri