This module offers control over the pygame display. Pygame has a single display Surface that is either contained in a window or runs full screen. Once you create the display you treat it as a regular Surface. Changes are not immediately visible onscreen; you must choose one of the two flipping functions to update the actual display.
The origin of the display, where x = 0 and y = 0, is the top left of the screen. Both axes increase positively towards the bottom right of the screen.
The pygame display can actually be initialized in one of several modes. By default, the display is a basic software driven framebuffer. You can request special modules like hardware acceleration and OpenGL support. These are controlled by flags passed to pygame.display.set_mode().
Pygame can only have a single display active at any time. Creating a new one with pygame.display.set_mode() will close the previous display. If precise control is needed over the pixel format or display resolutions, use the functions pygame.display.mode_ok(), pygame.display.list_modes(), and pygame.display.Info() to query information about the display.
Once the display Surface is created, the functions from this module affect the single existing display. The Surface becomes invalid if the module is uninitialized. If a new display mode is set, the existing Surface will automatically switch to operate on the new display.
When the display mode is set, several events are placed on the pygame event queue. pygame.QUIT is sent when the user has requested the program to shut down. The window will receive pygame.ACTIVEEVENT events as the display gains and loses input focus. If the display is set with the pygame.RESIZABLE flag, pygame.VIDEORESIZE events will be sent when the user adjusts the window dimensions. Hardware displays that draw direct to the screen will get pygame.VIDEOEXPOSE events when portions of the window must be redrawn.
In pygame 2, there is a new type of event called pygame.WINDOWEVENT that is meant to replace all window related events like pygame.VIDEORESIZE, pygame.VIDEOEXPOSE and pygame.ACTIVEEVENT.
Note that the WINDOWEVENT API is considered experimental, and may change in future releases.
The new events of type pygame.WINDOWEVENT have an event attribute that can take the following values.
If SDL version used is less than 2.0.5, the last two values WINDOWEVENT_TAKE_FOCUS and WINDOWEVENT_HIT_TEST will not work. See the SDL implementation (in C programming) of the same over here.
Some display environments have an option for automatically stretching all windows. When this option is enabled, this automatic stretching distorts the appearance of the pygame window. In the pygame examples directory, there is example code (prevent_display_stretching.py) which shows how to disable this automatic stretching of the pygame display on Microsoft Windows (Vista or newer required).
Initializes the pygame display module. The display module cannot do anything until it is initialized. This is usually handled for you automatically when you call the higher level pygame.init().
Pygame will select from one of several internal display backends when it is initialized. The display mode will be chosen depending on the platform and permissions of current user. Before the display module is initialized the environment variable SDL_VIDEODRIVER can be set to control which backend is used. The systems with multiple choices are listed here.
On some platforms it is possible to embed the pygame display into an already existing window. To do this, the environment variable SDL_WINDOWID must be set to a string containing the window id or handle. The environment variable is checked when the pygame display is initialized. Be aware that there can be many strange side effects when running in an embedded display.
It is harmless to call this more than once, repeated calls have no effect.
This will shut down the entire display module. This means any active displays will be closed. This will also be handled automatically when the program exits.
It is harmless to call this more than once, repeated calls have no effect.
Returns True if the pygame.display module is currently initialized.
This function will create a display Surface. The arguments passed in are requests for a display type. The actual created display will be the best possible match supported by the system.
The size argument is a pair of numbers representing the width and height. The flags argument is a collection of additional options. The depth argument represents the number of bits to use for color.
The Surface that gets returned can be drawn to like a regular Surface but changes will eventually be seen on the monitor.
If no size is passed or is set to (0, 0) and pygame uses SDL version 1.2.10 or above, the created Surface will have the same size as the current screen resolution. If only the width or height are set to 0, the Surface will have the same width or height as the screen resolution. Using a SDL version prior to 1.2.10 will raise an exception.
It is usually best to not pass the depth argument. It will default to the best and fastest color depth for the system. If your game requires a specific color format you can control the depth with this argument. Pygame will emulate an unavailable color depth which can be slow.
When requesting fullscreen display modes, sometimes an exact match for the requested size cannot be made. In these situations pygame will select the closest compatible match. The returned surface will still always match the requested size.
On high resolution displays(4k, 1080p) and tiny graphics games (640x480) show up very small so that they are unplayable. SCALED scales up the window for you. The game thinks it's a 640x480 window, but really it can be bigger. Mouse events are scaled for you, so your game doesn't need to do it. Note that SCALED is considered an experimental API and may change in future releases.
The flags argument controls which type of display you want. There are several to choose from, and you can even combine multiple types using the bitwise or operator, (the pipe "|" character). If you pass 0 or no flags argument it will default to a software driven window. Here are the display flags you will want to choose from:
Pygame 2 has the following additional flags available.
New in pygame 2.0.0: SCALED, SHOWN and HIDDEN
By setting the vsync parameter to 1, it is possible to get a display with vertical sync, but you are not guaranteed to get one. The request only works at all for calls to set_mode() with the pygame.OPENGL or pygame.SCALED flags set, and is still not guaranteed even with one of those set. What you get depends on the hardware and driver configuration of the system pygame is running on. Here is an example usage of a call to set_mode() that may give you a display with vsync:
Vsync behaviour is considered experimental, and may change in future releases.
New in pygame 2.0.0: vsync
Basic example:
The display index 0 means the default display is used.
Changed in pygame 1.9.5: display argument added
Return a reference to the currently set display Surface. If no display mode has been set this will return None.
This will update the contents of the entire display. If your display mode is using the flags pygame.HWSURFACE and pygame.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 pygame.OPENGL display mode this will perform a gl buffer swap.
This function is like an optimized version of pygame.display.flip() for software displays. It allows only a portion of the screen to updated, instead of the entire area. If no argument is passed it updates the entire Surface area like pygame.display.flip().
You can pass the function a single rectangle, or a sequence of rectangles. It is more efficient to pass many rectangles at once than to call update multiple times with single or a partial list of rectangles. If passing a sequence of rectangles it is safe to include None values in the list, which will be skipped.
This call cannot be used on pygame.OPENGL displays and will generate an exception.
Pygame chooses one of many available display backends when it is initialized. This returns the internal name used for the display backend. This can be used to provide limited information about what display capabilities might be accelerated. See the SDL_VIDEODRIVER flags in pygame.display.set_mode() to see some of the common options.
Creates a simple object containing several attributes to describe the current graphics environment. If this is called before pygame.display.set_mode() some platforms can provide information about the default display mode. This can also be called after setting the display mode to verify specific display options were satisfied. The VidInfo object has several attributes:
Creates a dictionary filled with string keys. The strings and values are arbitrarily created by the system. Some systems may have no information and an empty dictionary will be returned. Most platforms will return a "window" key with the value set to the system id for the current display.
New in pygame 1.7.1.
This function returns a list of possible sizes 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 size should work (this is likely the case for windowed modes). Mode sizes are sorted from biggest to smallest.
If depth is 0, the current/best color depth for the display is used. The flags defaults to pygame.FULLSCREEN, but you may need to add additional flags for specific fullscreen modes.
The display index 0 means the default display is used.
Changed in pygame 1.9.5: display argument added
This function uses the same arguments as pygame.display.set_mode(). It is used to determine if a requested display mode is available. It will return 0 if the display mode cannot be set. Otherwise it will return a pixel depth that best matches the display asked for.
Usually the depth argument is not passed, but some platforms can support multiple display depths. If passed it will hint to which depth is a better match.
The most useful flags to pass will be pygame.HWSURFACE, pygame.DOUBLEBUF, and maybe pygame.FULLSCREEN. The function will return 0 if these display flags cannot be set.
The display index 0 means the default display is used.
Changed in pygame 1.9.5: display argument added
After calling pygame.display.set_mode() with the pygame.OPENGL flag, it is a good idea to check the value of any requested OpenGL attributes. See pygame.display.gl_set_attribute() for a list of valid flags.
When calling pygame.display.set_mode() with the pygame.OPENGL flag, Pygame automatically handles setting the OpenGL attributes like color and double-buffering. 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().
Many settings are the requested minimum. Creating a window with an OpenGL context will fail if OpenGL cannot provide the requested attribute, but it may for example give you a stencil buffer even if you request none, or it may give you a larger one than requested.
The OPENGL flags are:
GL_MULTISAMPLEBUFFERS
Whether to enable multisampling anti-aliasing. Defaults to 0 (disabled).
Set GL_MULTISAMPLESAMPLES to a value above 0 to control the amount of anti-aliasing. A typical value is 2 or 3.
GL_STENCIL_SIZE
GL_DEPTH_SIZE
GL_STEREO
GL_BUFFER_SIZE
New in pygame 2.0.0: Additional attributes:
GL_CONTEXT_PROFILE_MASK
Sets the OpenGL profile to one of these values:
GL_ACCELERATED_VISUAL
Returns True when the display Surface is considered actively renderable on the screen and may be visible to the user. This is the default state immediately after pygame.display.set_mode(). This method may return True even if the application is fully hidden behind another application window.
This will return False if the display Surface has been iconified or minimized (either via pygame.display.iconify() or via an OS specific method such as the minimize-icon available on most desktops).
The method can also return False for other reasons without the application being explicitly iconified or minimized by the user. A notable example being if the user has multiple virtual desktops and the display Surface is not on the active virtual desktop.
Note
This function returning True is unrelated to whether the application has input focus. Please see pygame.key.get_focused() and pygame.mouse.get_focused() for APIs related to input focus.
Request the window for the display surface be iconified or hidden. Not all systems and displays support an iconified display. The function will return True if successful.
When the display is iconified pygame.display.get_active() will return False. The event queue should receive an ACTIVEEVENT event when the window has been iconified. Additionally, the event queue also recieves a WINDOWEVENT_MINIMIZED event when the window has been iconified on pygame 2.
Switches the display window between windowed and fullscreen modes. Display driver support is not great when using pygame 1, but with pygame 2 it is the most reliable method to switch to and from fullscreen.
Supported display drivers in pygame 1:
Supported display drivers in pygame 2:
Set the red, green, and blue gamma values on the display hardware. If the green and blue arguments are not passed, they will both be the same as red. Not all systems and hardware support gamma ramps, if the function succeeds it will return True.
A gamma value of 1.0 creates a linear color table. Lower values will darken the display and higher values will brighten.
Set the red, green, and blue gamma ramps with an explicit lookup table. Each argument should be sequence of 256 integers. The integers should range between 0 and 0xffff. Not all systems and hardware support gamma ramps, if the function succeeds it will return True.
Sets the runtime icon the system will use to represent the display window. All windows default to a simple pygame logo for the window icon.
You can pass any surface, but most systems want a smaller image around 32x32. The image can have colorkey transparency which will be passed to the system.
Some systems do not allow the window icon to change after it has been shown. This function can be called before pygame.display.set_mode() to create the icon before the display mode is set.
If the display has a window title, this function will change the name on the window. Some systems support an alternate shorter title to be used for minimized displays.
Returns the title and icontitle for the display Surface. These will often be the same value.
This will change the video display color palette for 8-bit displays. This does not change the palette for the actual display Surface, only the palette that is used to display the Surface. If no palette argument is passed, the system default palette will be restored. The palette is a sequence of RGB triplets.
Returns the number of available displays. This is always 1 if pygame.get_sdl_version() returns a major version number below 2.
New in pygame 1.9.5.
Returns the size of the window initialized with pygame.display.set_mode(). This may differ from the size of the display surface if SCALED is used.
New in pygame 2.0.0.
Return whether screensaver is allowed to run whilst the app is running. Default is False. By default pygame does not allow the screensaver during game play.
Note
Some platforms do not have a screensaver or support disabling the screensaver. Please see pygame.display.set_allow_screensaver() for caveats with screensaver support.
New in pygame 2.0.0.
Change whether screensavers should be allowed whilst the app is running. The default is False. By default pygame does not allow the screensaver during game play.
If the screensaver has been disallowed due to this function, it will automatically be allowed to run when pygame.quit() is called.
It is possible to influence the default value via the environment variable SDL_HINT_VIDEO_ALLOW_SCREENSAVER, which can be set to either 0 (disable) or 1 (enable).
Note
Disabling screensaver is subject to platform support. When platform support is absent, this function will silently appear to work even though the screensaver state is unchanged. The lack of feedback is due to SDL not providing any supported method for determining whether it supports changing the screensaver state. SDL_HINT_VIDEO_ALLOW_SCREENSAVER is available in SDL 2.0.2 or later. SDL1.2 does not implement this.
New in pygame 2.0.0.


This will update the contents of the entire display. If your display mode is using the flags pygame.HWSURFACE and pygame.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 pygame.OPENGL display mode this will perform a gl buffer swap.


Returns True when the display Surface is considered actively renderable on the screen and may be visible to the user. This is the default state immediately after pygame.display.set_mode(). This method may return True even if the application is fully hidden behind another application window.
This will return False if the display Surface has been iconified or minimized (either via pygame.display.iconify() or via an OS specific method such as the minimize-icon available on most desktops).
The method can also return False for other reasons without the application being explicitly iconified or minimized by the user. A notable example being if the user has multiple virtual desktops and the display Surface is not on the active virtual desktop.
Note
This function returning True is unrelated to whether the application has input focus. Please see pygame.key.get_focused() and pygame.mouse.get_focused() for APIs related to input focus.


Return whether screensaver is allowed to run whilst the app is running. Default is False. By default pygame does not allow the screensaver during game play.
Note
Some platforms do not have a screensaver or support disabling the screensaver. Please see pygame.display.set_allow_screensaver() for caveats with screensaver support.
New in pygame 2.0.0.


Returns the title and icontitle for the display Surface. These will often be the same value.


Pygame chooses one of many available display backends when it is initialized. This returns the internal name used for the display backend. This can be used to provide limited information about what display capabilities might be accelerated. See the SDL_VIDEODRIVER flags in pygame.display.set_mode() to see some of the common options.


Returns True if the pygame.display module is currently initialized.


Returns the number of available displays. This is always 1 if pygame.get_sdl_version() returns a major version number below 2.
New in pygame 1.9.5.


Return a reference to the currently set display Surface. If no display mode has been set this will return None.


Returns the size of the window initialized with pygame.display.set_mode(). This may differ from the size of the display surface if SCALED is used.
New in pygame 2.0.0.


Creates a dictionary filled with string keys. The strings and values are arbitrarily created by the system. Some systems may have no information and an empty dictionary will be returned. Most platforms will return a "window" key with the value set to the system id for the current display.
New in pygame 1.7.1.


After calling pygame.display.set_mode() with the pygame.OPENGL flag, it is a good idea to check the value of any requested OpenGL attributes. See pygame.display.gl_set_attribute() for a list of valid flags.


When calling pygame.display.set_mode() with the pygame.OPENGL flag, Pygame automatically handles setting the OpenGL attributes like color and double-buffering. 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().
Many settings are the requested minimum. Creating a window with an OpenGL context will fail if OpenGL cannot provide the requested attribute, but it may for example give you a stencil buffer even if you request none, or it may give you a larger one than requested.
The OPENGL flags are:
GL_MULTISAMPLEBUFFERS
Whether to enable multisampling anti-aliasing. Defaults to 0 (disabled).
Set GL_MULTISAMPLESAMPLES to a value above 0 to control the amount of anti-aliasing. A typical value is 2 or 3.
GL_STENCIL_SIZE
GL_DEPTH_SIZE
GL_STEREO
GL_BUFFER_SIZE
New in pygame 2.0.0: Additional attributes:
GL_CONTEXT_PROFILE_MASK
Sets the OpenGL profile to one of these values:
GL_ACCELERATED_VISUAL


Request the window for the display surface be iconified or hidden. Not all systems and displays support an iconified display. The function will return True if successful.
When the display is iconified pygame.display.get_active() will return False. The event queue should receive an ACTIVEEVENT event when the window has been iconified. Additionally, the event queue also recieves a WINDOWEVENT_MINIMIZED event when the window has been iconified on pygame 2.


Creates a simple object containing several attributes to describe the current graphics environment. If this is called before pygame.display.set_mode() some platforms can provide information about the default display mode. This can also be called after setting the display mode to verify specific display options were satisfied. The VidInfo object has several attributes:


Initializes the pygame display module. The display module cannot do anything until it is initialized. This is usually handled for you automatically when you call the higher level pygame.init().
Pygame will select from one of several internal display backends when it is initialized. The display mode will be chosen depending on the platform and permissions of current user. Before the display module is initialized the environment variable SDL_VIDEODRIVER can be set to control which backend is used. The systems with multiple choices are listed here.
On some platforms it is possible to embed the pygame display into an already existing window. To do this, the environment variable SDL_WINDOWID must be set to a string containing the window id or handle. The environment variable is checked when the pygame display is initialized. Be aware that there can be many strange side effects when running in an embedded display.
It is harmless to call this more than once, repeated calls have no effect.


This function returns a list of possible sizes 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 size should work (this is likely the case for windowed modes). Mode sizes are sorted from biggest to smallest.
If depth is 0, the current/best color depth for the display is used. The flags defaults to pygame.FULLSCREEN, but you may need to add additional flags for specific fullscreen modes.
The display index 0 means the default display is used.
Changed in pygame 1.9.5: display argument added


This function uses the same arguments as pygame.display.set_mode(). It is used to determine if a requested display mode is available. It will return 0 if the display mode cannot be set. Otherwise it will return a pixel depth that best matches the display asked for.
Usually the depth argument is not passed, but some platforms can support multiple display depths. If passed it will hint to which depth is a better match.
The most useful flags to pass will be pygame.HWSURFACE, pygame.DOUBLEBUF, and maybe pygame.FULLSCREEN. The function will return 0 if these display flags cannot be set.
The display index 0 means the default display is used.
Changed in pygame 1.9.5: display argument added


This will shut down the entire display module. This means any active displays will be closed. This will also be handled automatically when the program exits.
It is harmless to call this more than once, repeated calls have no effect.


Change whether screensavers should be allowed whilst the app is running. The default is False. By default pygame does not allow the screensaver during game play.
If the screensaver has been disallowed due to this function, it will automatically be allowed to run when pygame.quit() is called.
It is possible to influence the default value via the environment variable SDL_HINT_VIDEO_ALLOW_SCREENSAVER, which can be set to either 0 (disable) or 1 (enable).
Note
Disabling screensaver is subject to platform support. When platform support is absent, this function will silently appear to work even though the screensaver state is unchanged. The lack of feedback is due to SDL not providing any supported method for determining whether it supports changing the screensaver state. SDL_HINT_VIDEO_ALLOW_SCREENSAVER is available in SDL 2.0.2 or later. SDL1.2 does not implement this.
New in pygame 2.0.0.


If the display has a window title, this function will change the name on the window. Some systems support an alternate shorter title to be used for minimized displays.


Set the red, green, and blue gamma values on the display hardware. If the green and blue arguments are not passed, they will both be the same as red. Not all systems and hardware support gamma ramps, if the function succeeds it will return True.
A gamma value of 1.0 creates a linear color table. Lower values will darken the display and higher values will brighten.


Set the red, green, and blue gamma ramps with an explicit lookup table. Each argument should be sequence of 256 integers. The integers should range between 0 and 0xffff. Not all systems and hardware support gamma ramps, if the function succeeds it will return True.


Sets the runtime icon the system will use to represent the display window. All windows default to a simple pygame logo for the window icon.
You can pass any surface, but most systems want a smaller image around 32x32. The image can have colorkey transparency which will be passed to the system.
Some systems do not allow the window icon to change after it has been shown. This function can be called before pygame.display.set_mode() to create the icon before the display mode is set.


This function will create a display Surface. The arguments passed in are requests for a display type. The actual created display will be the best possible match supported by the system.
The size argument is a pair of numbers representing the width and height. The flags argument is a collection of additional options. The depth argument represents the number of bits to use for color.
The Surface that gets returned can be drawn to like a regular Surface but changes will eventually be seen on the monitor.
If no size is passed or is set to (0, 0) and pygame uses SDL version 1.2.10 or above, the created Surface will have the same size as the current screen resolution. If only the width or height are set to 0, the Surface will have the same width or height as the screen resolution. Using a SDL version prior to 1.2.10 will raise an exception.
It is usually best to not pass the depth argument. It will default to the best and fastest color depth for the system. If your game requires a specific color format you can control the depth with this argument. Pygame will emulate an unavailable color depth which can be slow.
When requesting fullscreen display modes, sometimes an exact match for the requested size cannot be made. In these situations pygame will select the closest compatible match. The returned surface will still always match the requested size.
On high resolution displays(4k, 1080p) and tiny graphics games (640x480) show up very small so that they are unplayable. SCALED scales up the window for you. The game thinks it's a 640x480 window, but really it can be bigger. Mouse events are scaled for you, so your game doesn't need to do it. Note that SCALED is considered an experimental API and may change in future releases.
The flags argument controls which type of display you want. There are several to choose from, and you can even combine multiple types using the bitwise or operator, (the pipe "|" character). If you pass 0 or no flags argument it will default to a software driven window. Here are the display flags you will want to choose from:
Pygame 2 has the following additional flags available.
New in pygame 2.0.0: SCALED, SHOWN and HIDDEN
By setting the vsync parameter to 1, it is possible to get a display with vertical sync, but you are not guaranteed to get one. The request only works at all for calls to set_mode() with the pygame.OPENGL or pygame.SCALED flags set, and is still not guaranteed even with one of those set. What you get depends on the hardware and driver configuration of the system pygame is running on. Here is an example usage of a call to set_mode() that may give you a display with vsync:
Vsync behaviour is considered experimental, and may change in future releases.
New in pygame 2.0.0: vsync
Basic example:
The display index 0 means the default display is used.
Changed in pygame 1.9.5: display argument added


This will change the video display color palette for 8-bit displays. This does not change the palette for the actual display Surface, only the palette that is used to display the Surface. If no palette argument is passed, the system default palette will be restored. The palette is a sequence of RGB triplets.


Switches the display window between windowed and fullscreen modes. Display driver support is not great when using pygame 1, but with pygame 2 it is the most reliable method to switch to and from fullscreen.
Supported display drivers in pygame 1:
Supported display drivers in pygame 2:


This function is like an optimized version of pygame.display.flip() for software displays. It allows only a portion of the screen to updated, instead of the entire area. If no argument is passed it updates the entire Surface area like pygame.display.flip().
You can pass the function a single rectangle, or a sequence of rectangles. It is more efficient to pass many rectangles at once than to call update multiple times with single or a partial list of rectangles. If passing a sequence of rectangles it is safe to include None values in the list, which will be skipped.
This call cannot be used on pygame.OPENGL displays and will generate an exception.


Draw several simple shapes to a surface. These functions will work for rendering to any format of surface. Rendering to hardware surfaces will be slower than regular software surfaces.
Most of the functions take a width argument to represent the size of stroke (thickness) around the edge of the shape. If a width of 0 is passed the shape will be filled (solid).
All the drawing functions respect the clip area for the surface and will be constrained to that area. The functions return a rectangle representing the bounding area of changed pixels. This bounding rectangle is the 'minimum' bounding box that encloses the affected area.
All the drawing functions accept a color argument that can be one of the following formats:
A color's alpha value will be written directly into the surface (if the surface contains pixel alphas), but the draw function will not draw transparently.
These functions temporarily lock the surface they are operating on. Many sequential drawing calls can be sped up by locking and unlocking the surface object around the draw calls (see pygame.Surface.lock() and pygame.Surface.unlock()).
Note
See the pygame.gfxdraw module for alternative draw methods.
Draws a rectangle on the given surface.
(optional) used for line thickness or to indicate that the rectangle is to be filled (not to be confused with the width value of the rect parameter)
Note
When using width values > 1, the edge lines will grow outside the original boundary of the rect. For more details on how the thickness for edge lines grow, refer to the width notes of the pygame.draw.line() function.
(optional) used for setting the value of bottom right border. If you don't set this value, it will use the border_radius value.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the given rect parameter and its width and height will be 0
Rect
Note
The pygame.Surface.fill() method works just as well for drawing filled rectangles and can be hardware accelerated on some platforms with both software and hardware display modes.
Changed in pygame 2.0.0: Added support for keyword arguments.
Changed in pygame 2.0.0.dev8: Added support for border radius.
Draws a polygon on the given surface.
(optional) used for line thickness or to indicate that the polygon is to be filled
Note
When using width values > 1, the edge lines will grow outside the original boundary of the polygon. For more details on how the thickness for edge lines grow, refer to the width notes of the pygame.draw.line() function.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the first point in the points parameter (float values will be truncated) and its width and height will be 0
Rect
Note
For an aapolygon, use aalines() with closed=True.
Changed in pygame 2.0.0: Added support for keyword arguments.
Draws a circle on the given surface.
(optional) used for line thickness or to indicate that the circle is to be filled
Note
When using width values > 1, the edge lines will only grow inward.
(optional) if this is set to True then the bottom right corner of the circle will be drawn
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the center parameter value (float values will be truncated) and its width and height will be 0
Rect
Changed in pygame 2.0.0: Added support for keyword arguments. Nothing is drawn when the radius is 0 (a pixel at the center coordinates used to be drawn when the radius equaled 0). Floats, and Vector2 are accepted for the center param. The drawing algorithm was improved to look more like a circle.
Changed in pygame 2.0.0.dev8: Added support for drawing circle quadrants.
Draws an ellipse on the given surface.
(optional) used for line thickness or to indicate that the ellipse is to be filled (not to be confused with the width value of the rect parameter)
Note
When using width values > 1, the edge lines will only grow inward from the original boundary of the rect parameter.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the given rect parameter and its width and height will be 0
Rect
Changed in pygame 2.0.0: Added support for keyword arguments.
Draws an elliptical arc on the given surface.
The two angle arguments are given in radians and indicate the start and stop positions of the arc. The arc is drawn in a counterclockwise direction from the start_angle to the stop_angle.
stop angle of the arc in radians
(optional) used for line thickness (not to be confused with the width value of the rect parameter)
Note
When using width values > 1, the edge lines will only grow inward from the original boundary of the rect parameter.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the given rect parameter and its width and height will be 0
Rect
Changed in pygame 2.0.0: Added support for keyword arguments.
Draws a straight line on the given surface. There are no endcaps. For thick lines the ends are squared off.
(optional) used for line thickness
Note
When using width values > 1, lines will grow as follows.
For odd width values, the thickness of each line grows with the original line being in the center.
For even width values, the thickness of each line grows with the original line being offset from the center (as there is no exact center line drawn). As a result, lines with a slope < 1 (horizontal-ish) will have 1 more pixel of thickness below the original line (in the y direction). Lines with a slope >= 1 (vertical-ish) will have 1 more pixel of thickness to the right of the original line (in the x direction).
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the start_pos parameter value (float values will be truncated) and its width and height will be 0
Rect
TypeError -- if start_pos or end_pos is not a sequence of two numbers
Changed in pygame 2.0.0: Added support for keyword arguments.
Draws a sequence of contiguous straight lines on the given surface. There are no endcaps or miter joints. For thick lines the ends are squared off. Drawing thick lines with sharp corners can have undesired looking results.
(optional) used for line thickness
Note
When using width values > 1 refer to the width notes of line() for details on how thick lines grow.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the first point in the points parameter (float values will be truncated) and its width and height will be 0
Rect
Changed in pygame 2.0.0: Added support for keyword arguments.
Draws a straight antialiased line on the given surface.
The line has a thickness of one pixel and the endpoints have a height and width of one pixel each.
If both endpoints are equal, only a single pixel is drawn (after rounding floats to nearest integer).
Otherwise if the line is not steep (i.e. if the length along the x-axis is greater than the height along the y-axis):
For each endpoint:
If x, the endpoint's x-coordinate, is a whole number find which pixels would be covered by it and draw them.
Otherwise:
Calculate the position of the nearest point with a whole number for it's x-coordinate, when extending the line past the endpoint.
Find which pixels would be covered and how much by that point.
If the endpoint is the left one, multiply the coverage by (1 - the decimal part of x).
Otherwise multiply the coverage by the decimal part of x.
Then draw those pixels.
Then for each point between the endpoints, along the line, whose x-coordinate is a whole number:
Find which pixels would be covered and how much by that point and draw them.
Otherwise do the same for steep lines as for non-steep lines except along the y-axis instead of the x-axis (using y instead of x, top instead of left and bottom instead of right).
Note
Regarding float values for coordinates, a point with coordinate consisting of two whole numbers is considered being right in the center of said pixel (and having a height and width of 1 pixel would therefore completely cover it), while a point with coordinate where one (or both) of the numbers have non-zero decimal parts would be partially covering two (or four if both numbers have decimal parts) adjacent pixels, e.g. the point (1.4, 2) covers 60% of the pixel (1, 2) and 40% of the pixel (2,2).
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the start_pos parameter value (float values will be truncated) and its width and height will be 0
Rect
TypeError -- if start_pos or end_pos is not a sequence of two numbers
Changed in pygame 2.0.0: Added support for keyword arguments.
Draws a sequence of contiguous straight antialiased lines on the given surface.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the first point in the points parameter (float values will be truncated) and its width and height will be 0
Rect
Changed in pygame 2.0.0: Added support for keyword arguments.
Example code for draw module.


Draws a straight antialiased line on the given surface.
The line has a thickness of one pixel and the endpoints have a height and width of one pixel each.
If both endpoints are equal, only a single pixel is drawn (after rounding floats to nearest integer).
Otherwise if the line is not steep (i.e. if the length along the x-axis is greater than the height along the y-axis):
For each endpoint:
If x, the endpoint's x-coordinate, is a whole number find which pixels would be covered by it and draw them.
Otherwise:
Calculate the position of the nearest point with a whole number for it's x-coordinate, when extending the line past the endpoint.
Find which pixels would be covered and how much by that point.
If the endpoint is the left one, multiply the coverage by (1 - the decimal part of x).
Otherwise multiply the coverage by the decimal part of x.
Then draw those pixels.
Then for each point between the endpoints, along the line, whose x-coordinate is a whole number:
Find which pixels would be covered and how much by that point and draw them.
Otherwise do the same for steep lines as for non-steep lines except along the y-axis instead of the x-axis (using y instead of x, top instead of left and bottom instead of right).
Note
Regarding float values for coordinates, a point with coordinate consisting of two whole numbers is considered being right in the center of said pixel (and having a height and width of 1 pixel would therefore completely cover it), while a point with coordinate where one (or both) of the numbers have non-zero decimal parts would be partially covering two (or four if both numbers have decimal parts) adjacent pixels, e.g. the point (1.4, 2) covers 60% of the pixel (1, 2) and 40% of the pixel (2,2).
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the start_pos parameter value (float values will be truncated) and its width and height will be 0
Rect
TypeError -- if start_pos or end_pos is not a sequence of two numbers
Changed in pygame 2.0.0: Added support for keyword arguments.


Draws a sequence of contiguous straight antialiased lines on the given surface.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the first point in the points parameter (float values will be truncated) and its width and height will be 0
Rect
Changed in pygame 2.0.0: Added support for keyword arguments.


Draws an elliptical arc on the given surface.
The two angle arguments are given in radians and indicate the start and stop positions of the arc. The arc is drawn in a counterclockwise direction from the start_angle to the stop_angle.
stop angle of the arc in radians
(optional) used for line thickness (not to be confused with the width value of the rect parameter)
Note
When using width values > 1, the edge lines will only grow inward from the original boundary of the rect parameter.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the given rect parameter and its width and height will be 0
Rect
Changed in pygame 2.0.0: Added support for keyword arguments.


Draws a circle on the given surface.
(optional) used for line thickness or to indicate that the circle is to be filled
Note
When using width values > 1, the edge lines will only grow inward.
(optional) if this is set to True then the bottom right corner of the circle will be drawn
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the center parameter value (float values will be truncated) and its width and height will be 0
Rect
Changed in pygame 2.0.0: Added support for keyword arguments. Nothing is drawn when the radius is 0 (a pixel at the center coordinates used to be drawn when the radius equaled 0). Floats, and Vector2 are accepted for the center param. The drawing algorithm was improved to look more like a circle.
Changed in pygame 2.0.0.dev8: Added support for drawing circle quadrants.


Draws an ellipse on the given surface.
(optional) used for line thickness or to indicate that the ellipse is to be filled (not to be confused with the width value of the rect parameter)
Note
When using width values > 1, the edge lines will only grow inward from the original boundary of the rect parameter.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the given rect parameter and its width and height will be 0
Rect
Changed in pygame 2.0.0: Added support for keyword arguments.


Draws a straight line on the given surface. There are no endcaps. For thick lines the ends are squared off.
(optional) used for line thickness
Note
When using width values > 1, lines will grow as follows.
For odd width values, the thickness of each line grows with the original line being in the center.
For even width values, the thickness of each line grows with the original line being offset from the center (as there is no exact center line drawn). As a result, lines with a slope < 1 (horizontal-ish) will have 1 more pixel of thickness below the original line (in the y direction). Lines with a slope >= 1 (vertical-ish) will have 1 more pixel of thickness to the right of the original line (in the x direction).
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the start_pos parameter value (float values will be truncated) and its width and height will be 0
Rect
TypeError -- if start_pos or end_pos is not a sequence of two numbers
Changed in pygame 2.0.0: Added support for keyword arguments.


Draws a sequence of contiguous straight lines on the given surface. There are no endcaps or miter joints. For thick lines the ends are squared off. Drawing thick lines with sharp corners can have undesired looking results.
(optional) used for line thickness
Note
When using width values > 1 refer to the width notes of line() for details on how thick lines grow.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the first point in the points parameter (float values will be truncated) and its width and height will be 0
Rect
Changed in pygame 2.0.0: Added support for keyword arguments.


Draws a polygon on the given surface.
(optional) used for line thickness or to indicate that the polygon is to be filled
Note
When using width values > 1, the edge lines will grow outside the original boundary of the polygon. For more details on how the thickness for edge lines grow, refer to the width notes of the pygame.draw.line() function.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the first point in the points parameter (float values will be truncated) and its width and height will be 0
Rect
Note
For an aapolygon, use aalines() with closed=True.
Changed in pygame 2.0.0: Added support for keyword arguments.


Draws a rectangle on the given surface.
(optional) used for line thickness or to indicate that the rectangle is to be filled (not to be confused with the width value of the rect parameter)
Note
When using width values > 1, the edge lines will grow outside the original boundary of the rect. For more details on how the thickness for edge lines grow, refer to the width notes of the pygame.draw.line() function.
(optional) used for setting the value of bottom right border. If you don't set this value, it will use the border_radius value.
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the given rect parameter and its width and height will be 0
Rect
Note
The pygame.Surface.fill() method works just as well for drawing filled rectangles and can be hardware accelerated on some platforms with both software and hardware display modes.
Changed in pygame 2.0.0: Added support for keyword arguments.
Changed in pygame 2.0.0.dev8: Added support for border radius.


obj: If Unicode, encode; if bytes, return unaltered; if anything else, return None; if not given, raise SyntaxError.
etype (exception type): If given, the exception type to raise for an encoding error. The default is UnicodeEncodeError, as returned by PyUnicode_AsEncodedString().
This function is used to encode file paths in pygame. Encoding is to the codec as returned by sys.getfilesystemencoding(). Keyword arguments are supported.
New in pygame 1.9.2: (primarily for use in unit tests)


obj: If Unicode, encode; if bytes, return unaltered; if anything else, return None; if not given, raise SyntaxError.
encoding (string): If present, encoding to use. The default is 'unicode_escape'.
errors (string): If given, how to handle unencodable characters. The default is 'backslashreplace'.
etype (exception type): If given, the exception type to raise for an encoding error. The default is UnicodeEncodeError, as returned by PyUnicode_AsEncodedString(). For the default encoding and errors values there should be no encoding errors.
This function is used in encoding file paths. Keyword arguments are supported.
New in pygame 1.9.2: (primarily for use in unit tests)


This exception is raised whenever a pygame or SDL operation fails. You can catch any anticipated problems and deal with the error. The exception is always raised with a descriptive message about the problem.
Derived from the RuntimeError exception, which can also be used to catch these raised errors.


Pygame handles all its event messaging through an event queue. The routines in this module help you manage that event queue. The input queue is heavily dependent on the pygame.display module. If the display has not been initialized and a video mode not set, the event queue may not work properly. The event subsystem should be called from the main thread. If you want to post events into the queue from other threads, please use the pygame.fastevent module.
The event queue has an upper limit on the number of events it can hold (128 for standard SDL 1.2). When the queue becomes full new events are quietly dropped. To prevent lost events, especially input events which signal a quit command, your program must handle events every frame (with pygame.event.get(), pygame.event.pump(), pygame.event.wait(), pygame.event.peek() or pygame.event.clear()) and process them. Not handling events may cause your system to decide your program has locked up. To speed up queue processing use pygame.event.set_blocked() to limit which events get queued.
To get the state of various input devices, you can forego the event queue and access the input devices directly with their appropriate modules: pygame.mouse, pygame.key, and pygame.joystick. If you use this method, remember that pygame requires some form of communication with the system window manager and other parts of the platform. To keep pygame in sync with the system, you will need to call pygame.event.pump() to keep everything current. Usually, this should be called once per game loop. Note: Joysticks will not send any events until the device has been initialized.
The event queue contains pygame.event.EventType event objects. There are a variety of ways to access the queued events, from simply checking for the existence of events, to grabbing them directly off the stack. The event queue also offers some simple filtering which can slightly help performance by blocking certain event types from the queue. Use pygame.event.set_allowed() and pygame.event.set_blocked() to change this filtering. By default, all event types can be placed on the queue.
All pygame.event.EventType instances contain an event type identifier and attributes specific to that event type. The event type identifier is accessible as the pygame.event.EventType.type property. Any of the event specific attributes can be accessed through the pygame.event.EventType.__dict__ attribute or directly as an attribute of the event object (as member lookups are passed through to the object's dictionary values). The event object has no method functions. Users can create their own new events with the pygame.event.Event() function.
The event type identifier is in between the values of NOEVENT and NUMEVENTS. User defined events should have a value in the inclusive range of USEREVENT to NUMEVENTS - 1. It is recommended all user events follow this system.
Events support equality and inequality comparisons. Two events are equal if they are the same type and have identical attribute values.
While debugging and experimenting, you can print an event object for a quick display of its type and members. The function pygame.event.event_name() can be used to get a string representing the name of the event type.
Events that come from the system will have a guaranteed set of member attributes based on the type. The following is a list event types with their specific attributes.
Changed in pygame 2.0.0: The joy attribute was deprecated, instance_id was added.
You can also find a list of constants for keyboard keys here.
On MacOSX when a file is opened using a pygame application, a USEREVENT with its code attribute set to pygame.USEREVENT_DROPFILE is generated. There is an additional attribute called filename where the name of the file being accessed is stored.
New in pygame 1.9.2.
When compiled with SDL2, pygame has these additional events and their attributes.
New in pygame 1.9.5.
pygame can recognize text or files dropped in its window. If a file is dropped, file will be its path. The DROPTEXT event is only supported on X11.
New in pygame 2.0.0.
Events reserved for pygame.midi use.
New in pygame 2.0.0.
SDL2 supports controller hotplugging:
Also in this version, instance_id attributes were added to joystick events, and the joy attribute was deprecated.
New in pygame 2.0.0.
For each frame of your game, you will need to make some sort of call to the event queue. This ensures your program can internally interact with the rest of the operating system. If you are not using other event functions in your game, you should call pygame.event.pump() to allow pygame to handle internal actions.
This function is not necessary if your program is consistently processing events on the queue through the other pygame.event functions.
There are important things that must be dealt with internally in the event queue. The main window may need to be repainted or respond to the system. If you fail to make a call to the event queue for too long, the system may decide your program has locked up.
Caution
This function should only be called in the thread that initialized pygame.display.
This will get all the messages and remove them from the queue. If a type or sequence of types is given only those messages will be removed from the queue.
If you are only taking specific events from the queue, be aware that the queue could eventually fill up with the events you are not interested.
If pump is True (the default), then pygame.event.pump() will be called.
Changed in pygame 1.9.5: Added pump argument
Returns a single event from the queue. If the event queue is empty an event of type pygame.NOEVENT will be returned immediately. The returned event is removed from the queue.
Caution
This function should only be called in the thread that initialized pygame.display.
Returns a single event from the queue. If the queue is empty this function will wait until one is created. From pygame 2.0.0, if a timeout argument is given, the function will return an event of type pygame.NOEVENT if no events enter the queue in timeout milliseconds. The event is removed from the queue once it has been returned. While the program is waiting it will sleep in an idle state. This is important for programs that want to share the system with other applications.
Changed in pygame 2.0.0.dev13: Added timeout argument
Caution
This function should only be called in the thread that initialized pygame.display.
Returns True if there are any events of the given type waiting on the queue. If a sequence of event types is passed, this will return True if any of those events are on the queue.
If pump is True (the default), then pygame.event.pump() will be called.
Changed in pygame 1.9.5: Added pump argument
Removes all events from the queue. If eventtype is given, removes the given event or sequence of events. This has the same effect as pygame.event.get() except None is returned. It can be slightly more efficient when clearing a full event queue.
If pump is True (the default), then pygame.event.pump() will be called.
Changed in pygame 1.9.5: Added pump argument
Returns a string representing the name (in CapWords style) of the given event type.
"UserEvent" is returned for all values in the user event id range. "Unknown" is returned when the event type does not exist.
The given event types are not allowed to appear on the event queue. By default all events can be placed on the queue. It is safe to disable an event type multiple times.
If None is passed as the argument, ALL of the event types are blocked from being placed on the queue.
The given event types are allowed to appear on the event queue. By default, all event types can be placed on the queue. It is safe to enable an event type multiple times.
If None is passed as the argument, ALL of the event types are allowed to be placed on the queue.
Returns True if the given event type is blocked from the queue. If a sequence of event types is passed, this will return True if any of those event types are blocked.
When your program runs in a windowed environment, it will share the mouse and keyboard devices with other applications that have focus. If your program sets the event grab to True, it will lock all input into your program.
It is best to not always grab the input, since it prevents the user from doing other things on their system.
Returns True when the input events are grabbed for this application.
Places the given event at the end of the event queue.
This is usually used for placing pygame.USEREVENT events on the queue. Although any type of event can be placed, if using the system event types your program should be sure to create the standard attributes with appropriate values.
If the event queue is full a pygame.error is raised.
Caution: In pygame 2.0, calling this function with event types defined by pygame (such as pygame.KEYDOWN) may put events into the SDL2 event queue. In this case, an error may be raised if standard attributes of that event are missing or have incompatible values, and unexpected properties may be silently omitted. In order to avoid this behaviour, custom event properties should be used with custom event types. This behaviour is not guaranteed.
Reserves a pygame.USEREVENT for a custom use.
If too many events are made a pygame.error is raised.
New in pygame 2.0.0.dev3.
Creates a new event with the given type and attributes. The attributes can come from a dictionary argument with string keys or from keyword arguments.
A pygame object that represents an event. User event instances are created with an pygame.event.Event() function call. The EventType type is not directly callable. EventType instances support attribute assignment and deletion.
Read-only. The event type identifier. For user created event objects, this is the type argument passed to pygame.event.Event().
For example, some predefined event identifiers are QUIT and MOUSEMOTION.
Read-only. The event type specific attributes of an event. The dict attribute is a synonym for backward compatibility.
For example, the attributes of a KEYDOWN event would be unicode, key, and mod
New in pygame 1.9.2: Mutable attributes.


Removes all events from the queue. If eventtype is given, removes the given event or sequence of events. This has the same effect as pygame.event.get() except None is returned. It can be slightly more efficient when clearing a full event queue.
If pump is True (the default), then pygame.event.pump() will be called.
Changed in pygame 1.9.5: Added pump argument


Reserves a pygame.USEREVENT for a custom use.
If too many events are made a pygame.error is raised.
New in pygame 2.0.0.dev3.


Creates a new event with the given type and attributes. The attributes can come from a dictionary argument with string keys or from keyword arguments.


Returns a string representing the name (in CapWords style) of the given event type.
"UserEvent" is returned for all values in the user event id range. "Unknown" is returned when the event type does not exist.


A pygame object that represents an event. User event instances are created with an pygame.event.Event() function call. The EventType type is not directly callable. EventType instances support attribute assignment and deletion.
Read-only. The event type identifier. For user created event objects, this is the type argument passed to pygame.event.Event().
For example, some predefined event identifiers are QUIT and MOUSEMOTION.
Read-only. The event type specific attributes of an event. The dict attribute is a synonym for backward compatibility.
For example, the attributes of a KEYDOWN event would be unicode, key, and mod
New in pygame 1.9.2: Mutable attributes.


Read-only. The event type specific attributes of an event. The dict attribute is a synonym for backward compatibility.
For example, the attributes of a KEYDOWN event would be unicode, key, and mod


Read-only. The event type identifier. For user created event objects, this is the type argument passed to pygame.event.Event().
For example, some predefined event identifiers are QUIT and MOUSEMOTION.


This will get all the messages and remove them from the queue. If a type or sequence of types is given only those messages will be removed from the queue.
If you are only taking specific events from the queue, be aware that the queue could eventually fill up with the events you are not interested.
If pump is True (the default), then pygame.event.pump() will be called.
Changed in pygame 1.9.5: Added pump argument


Returns True if the given event type is blocked from the queue. If a sequence of event types is passed, this will return True if any of those event types are blocked.


Returns True when the input events are grabbed for this application.


Returns True if there are any events of the given type waiting on the queue. If a sequence of event types is passed, this will return True if any of those events are on the queue.
If pump is True (the default), then pygame.event.pump() will be called.
Changed in pygame 1.9.5: Added pump argument


Returns a single event from the queue. If the event queue is empty an event of type pygame.NOEVENT will be returned immediately. The returned event is removed from the queue.
Caution
This function should only be called in the thread that initialized pygame.display.


Places the given event at the end of the event queue.
This is usually used for placing pygame.USEREVENT events on the queue. Although any type of event can be placed, if using the system event types your program should be sure to create the standard attributes with appropriate values.
If the event queue is full a pygame.error is raised.
Caution: In pygame 2.0, calling this function with event types defined by pygame (such as pygame.KEYDOWN) may put events into the SDL2 event queue. In this case, an error may be raised if standard attributes of that event are missing or have incompatible values, and unexpected properties may be silently omitted. In order to avoid this behaviour, custom event properties should be used with custom event types. This behaviour is not guaranteed.


For each frame of your game, you will need to make some sort of call to the event queue. This ensures your program can internally interact with the rest of the operating system. If you are not using other event functions in your game, you should call pygame.event.pump() to allow pygame to handle internal actions.
This function is not necessary if your program is consistently processing events on the queue through the other pygame.event functions.
There are important things that must be dealt with internally in the event queue. The main window may need to be repainted or respond to the system. If you fail to make a call to the event queue for too long, the system may decide your program has locked up.
Caution
This function should only be called in the thread that initialized pygame.display.


The given event types are allowed to appear on the event queue. By default, all event types can be placed on the queue. It is safe to enable an event type multiple times.
If None is passed as the argument, ALL of the event types are allowed to be placed on the queue.


The given event types are not allowed to appear on the event queue. By default all events can be placed on the queue. It is safe to disable an event type multiple times.
If None is passed as the argument, ALL of the event types are blocked from being placed on the queue.


When your program runs in a windowed environment, it will share the mouse and keyboard devices with other applications that have focus. If your program sets the event grab to True, it will lock all input into your program.
It is best to not always grab the input, since it prevents the user from doing other things on their system.


Returns a single event from the queue. If the queue is empty this function will wait until one is created. From pygame 2.0.0, if a timeout argument is given, the function will return an event of type pygame.NOEVENT if no events enter the queue in timeout milliseconds. The event is removed from the queue once it has been returned. While the program is waiting it will sleep in an idle state. This is important for programs that want to share the system with other applications.
Changed in pygame 2.0.0.dev13: Added timeout argument
Caution
This function should only be called in the thread that initialized pygame.display.


These examples should help get you started with pygame. Here is a brief rundown of what you get. The source code for these examples is in the public domain. Feel free to use for your own projects.
There are several ways to run the examples. First they can be run as stand-alone programs. Second they can be imported and their main() methods called (see below). Finally, the easiest way is to use the python -m option:
eg:
Resources such as images and sounds for the examples are found in the pygame/examples/data subdirectory.
You can find where the example files are installed by using the following commands inside the python interpreter.
On each OS and version of Python the location will be slightly different. For example on Windows it might be in 'C:/Python26/Lib/site-packages/pygame/examples/' On Mac OS X it might be in '/Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/site-packages/pygame/examples/'
You can also run the examples in the python interpreter by calling each modules main() function.
We're always on the lookout for more examples and/or example requests. Code like this is probably the best way to start getting involved with python gaming.
examples as a package is new to pygame 1.9.0. But most of the examples came with pygame much earlier.
This started off as a port of the SDL demonstration, Aliens. Now it has evolved into something sort of resembling fun. This demonstrates a lot of different uses of sprites and optimized blitting. Also transparency, colorkeys, fonts, sound, music, joystick, and more. (PS, my high score is 117! goodluck)
This more closely resembles a port of the SDL Aliens demo. The code is a lot simpler, so it makes a better starting point for people looking at code for the first times. These blitting routines are not as optimized as they should/could be, but the code is easier to follow, and it plays quick enough.
A simple starfield example. You can change the center of perspective by leftclicking the mouse on the screen.
This simple example is derived from the line-by-line tutorial that comes with pygame. It is based on a 'popular' web banner. Note there are comments here, but for the full explanation, follow along in the tutorial.
This is the full and final example from the Pygame Tutorial, "How Do I Make It Move". It creates 10 objects and animates them on the screen.
Note it's a bit scant on error checking, but it's easy to read. :] Fortunately, this is python, and we needn't wrestle with a pile of error codes.
Super quick, super simple application demonstrating the different ways to render fonts with the font module
A showcase of rendering features the pygame.freetype.Font class provides in addition to those available with pygame.font.Font. It is a demonstration of direct to surface rendering, with vertical text and rotated text, opaque text and semi transparent text, horizontally stretched text and vertically stretched text.
Demonstrates creating a vertical gradient with pixelcopy and NumPy python. The app will create a new gradient every half second and report the time needed to create and display the image. If you're not prepared to start working with the NumPy arrays, don't worry about the source for this one :]
Eventlist is a sloppy style of pygame, but is a handy tool for learning about pygame events and input. At the top of the screen are the state of several device values, and a scrolling list of events are displayed on the bottom.
This is not quality 'ui' code at all, but you can see how to implement very non-interactive status displays, or even a crude text output control.
Another example filled with various surfarray effects. It requires the surfarray and image modules to be installed. This little demo can also make a good starting point for any of your own tests with surfarray
The arraytype parameter is deprecated; passing any value besides 'numpy' will raise ValueError.
Extremely basic testing of the mixer module. Load a sound and play it. All from the command shell, no graphics.
If provided, use the audio file 'file_path', otherwise use a default file.
sound.py optional command line argument: an audio file
Uses sndarray and NumPy to create offset faded copies of the original sound. Currently it just uses hardcoded values for the number of echoes and the delay. Easy for you to recreate as needed.
The arraytype parameter is deprecated; passing any value besides 'numpy' will raise ValueError.
This example was created in a quick comparison with the BlitzBasic gaming language. Nonetheless, it demonstrates a quick 8-bit setup (with colormap).
Using PyOpenGL and pygame, this creates a spinning 3D multicolored cube.
A simple demonstration example for the clipboard support.
Positional arguments:
This pygame.masks demo will display multiple moving sprites bouncing off each other. More than one sprite image can be provided.
If run as a program then mask.py takes one or more image files as command line arguments.
Optional keyword arguments:
Like the testsprite.c that comes with SDL, this pygame version shows lots of sprites moving around.
If run as a stand-alone program then no command line arguments are taken.
arguments:
How to use pygame with no windowing system, like on headless servers.
Thumbnail generation with scaling is an example of what you can do with pygame.
NOTE: the pygame scale function uses MMX/SSE if available, and can be run in multiple threads.
If headless_no_windows_needed.py is run as a program it takes the following command line arguments:
This is a stress test for the fastevents module.
So far it looks like normal pygame.event is faster by up to two times. So maybe fastevent isn't fast at all.
Tested on Windows XP SP2 Athlon, and FreeBSD.
However... on my Debian Duron 850 machine fastevents is faster.
Play the .pgm video file given by a path fname.
If run as a program overlay.py takes the file name as a command line argument.
A interactive demo that lets one choose which BLEND_xxx option to apply to a surface.
Fake additive blending. Using NumPy. it doesn't clamp. Press r,g,b Somewhat like blend_fill.
Display an arrow or circle with crossbar cursor.
Display various pixelarray generated effects.
arguments:
A smoothscale example that resized an image on the screen. Vertical and horizontal arrow keys are used to change the width and height of the displayed image. If the convert_alpha option is True then the source image is forced to have source alpha, whether or not the original images does. If run_speed_test is True then a background timing test is performed instead of the interactive scaler.
If scaletest.py is run as a program then the command line options are:
Arguments:
The output example shows how to translate mouse clicks or computer keyboard events into midi notes. It implements a rudimentary button widget and state machine.
The input example shows how to translate midi input to pygame events.
With the use of a virtual midi patch cord the output and input examples can be run as separate processes and connected so the keyboard output is displayed on a console.
new to pygame 1.9.0
This example shows a scrollable image that has a zoom factor of eight. It uses the Surface.scroll() function to shift the image on the display surface. A clip rectangle protects a margin area. If called as a function, the example accepts an optional image file path. If run as a program it takes an optional file path command line argument. If no file is provided a default image file is used.
When running click on a black triangle to move one pixel in the direction the triangle points. Or use the arrow keys. Close the window or press ESC to quit.
A simple live video player, it uses the first available camera it finds on the system.
A simple music player with window and keyboard playback control. Playback can be paused and rewound to the beginning.


This started off as a port of the SDL demonstration, Aliens. Now it has evolved into something sort of resembling fun. This demonstrates a lot of different uses of sprites and optimized blitting. Also transparency, colorkeys, fonts, sound, music, joystick, and more. (PS, my high score is 117! goodluck)


Another example filled with various surfarray effects. It requires the surfarray and image modules to be installed. This little demo can also make a good starting point for any of your own tests with surfarray
The arraytype parameter is deprecated; passing any value besides 'numpy' will raise ValueError.


A interactive demo that lets one choose which BLEND_xxx option to apply to a surface.


Fake additive blending. Using NumPy. it doesn't clamp. Press r,g,b Somewhat like blend_fill.


A simple live video player, it uses the first available camera it finds on the system.


This simple example is derived from the line-by-line tutorial that comes with pygame. It is based on a 'popular' web banner. Note there are comments here, but for the full explanation, follow along in the tutorial.


Display an arrow or circle with crossbar cursor.


Eventlist is a sloppy style of pygame, but is a handy tool for learning about pygame events and input. At the top of the screen are the state of several device values, and a scrolling list of events are displayed on the bottom.
This is not quality 'ui' code at all, but you can see how to implement very non-interactive status displays, or even a crude text output control.


This is a stress test for the fastevents module.
So far it looks like normal pygame.event is faster by up to two times. So maybe fastevent isn't fast at all.
Tested on Windows XP SP2 Athlon, and FreeBSD.
However... on my Debian Duron 850 machine fastevents is faster.


Super quick, super simple application demonstrating the different ways to render fonts with the font module


A showcase of rendering features the pygame.freetype.Font class provides in addition to those available with pygame.font.Font. It is a demonstration of direct to surface rendering, with vertical text and rotated text, opaque text and semi transparent text, horizontally stretched text and vertically stretched text.


Using PyOpenGL and pygame, this creates a spinning 3D multicolored cube.


arguments:
How to use pygame with no windowing system, like on headless servers.
Thumbnail generation with scaling is an example of what you can do with pygame.
NOTE: the pygame scale function uses MMX/SSE if available, and can be run in multiple threads.
If headless_no_windows_needed.py is run as a program it takes the following command line arguments:


This example was created in a quick comparison with the BlitzBasic gaming language. Nonetheless, it demonstrates a quick 8-bit setup (with colormap).


Positional arguments:
This pygame.masks demo will display multiple moving sprites bouncing off each other. More than one sprite image can be provided.
If run as a program then mask.py takes one or more image files as command line arguments.


Arguments:
The output example shows how to translate mouse clicks or computer keyboard events into midi notes. It implements a rudimentary button widget and state machine.
The input example shows how to translate midi input to pygame events.
With the use of a virtual midi patch cord the output and input examples can be run as separate processes and connected so the keyboard output is displayed on a console.
new to pygame 1.9.0


This is the full and final example from the Pygame Tutorial, "How Do I Make It Move". It creates 10 objects and animates them on the screen.
Note it's a bit scant on error checking, but it's easy to read. :] Fortunately, this is python, and we needn't wrestle with a pile of error codes.


This more closely resembles a port of the SDL Aliens demo. The code is a lot simpler, so it makes a better starting point for people looking at code for the first times. These blitting routines are not as optimized as they should/could be, but the code is easier to follow, and it plays quick enough.


Play the .pgm video file given by a path fname.
If run as a program overlay.py takes the file name as a command line argument.


Display various pixelarray generated effects.


A simple music player with window and keyboard playback control. Playback can be paused and rewound to the beginning.


arguments:
A smoothscale example that resized an image on the screen. Vertical and horizontal arrow keys are used to change the width and height of the displayed image. If the convert_alpha option is True then the source image is forced to have source alpha, whether or not the original images does. If run_speed_test is True then a background timing test is performed instead of the interactive scaler.
If scaletest.py is run as a program then the command line options are:


A simple demonstration example for the clipboard support.


This example shows a scrollable image that has a zoom factor of eight. It uses the Surface.scroll() function to shift the image on the display surface. A clip rectangle protects a margin area. If called as a function, the example accepts an optional image file path. If run as a program it takes an optional file path command line argument. If no file is provided a default image file is used.
When running click on a black triangle to move one pixel in the direction the triangle points. Or use the arrow keys. Close the window or press ESC to quit.


Extremely basic testing of the mixer module. Load a sound and play it. All from the command shell, no graphics.
If provided, use the audio file 'file_path', otherwise use a default file.
sound.py optional command line argument: an audio file


Uses sndarray and NumPy to create offset faded copies of the original sound. Currently it just uses hardcoded values for the number of echoes and the delay. Easy for you to recreate as needed.
The arraytype parameter is deprecated; passing any value besides 'numpy' will raise ValueError.


A simple starfield example. You can change the center of perspective by leftclicking the mouse on the screen.


Optional keyword arguments:
Like the testsprite.c that comes with SDL, this pygame version shows lots of sprites moving around.
If run as a stand-alone program then no command line arguments are taken.


Demonstrates creating a vertical gradient with pixelcopy and NumPy python. The app will create a new gradient every half second and report the time needed to create and display the image. If you're not prepared to start working with the NumPy arrays, don't worry about the source for this one :]


pygame.fastevent is a wrapper for Bob Pendleton's fastevent library. It provides fast events for use in multithreaded environments. When using pygame.fastevent, you can not use any of the pump, wait, poll, post, get, peek, etc. functions from pygame.event, but you should use the Event objects.
Initialize the pygame.fastevent module.
Returns True if the pygame.fastevent module is currently initialized.
For each frame of your game, you will need to make some sort of call to the event queue. This ensures your program can internally interact with the rest of the operating system.
This function is not necessary if your program is consistently processing events on the queue through the other pygame.fastevent functions.
There are important things that must be dealt with internally in the event queue. The main window may need to be repainted or respond to the system. If you fail to make a call to the event queue for too long, the system may decide your program has locked up.
Returns the current event on the queue. If there are no messages waiting on the queue, this will not return until one is available. Sometimes it is important to use this wait to get events from the queue, it will allow your application to idle when the user isn't doing anything with it.
Returns next event on queue. If there is no event waiting on the queue, this will return an event with type NOEVENT.
This will get all the messages and remove them from the queue.
This will post your own event objects onto the event queue. You can post any event type you want, but some care must be taken. For example, if you post a MOUSEBUTTONDOWN event to the queue, it is likely any code receiving the event will expect the standard MOUSEBUTTONDOWN attributes to be available, like 'pos' and 'button'.
Because pygame.fastevent.post() may have to wait for the queue to empty, you can get into a dead lock if you try to append an event on to a full queue from the thread that processes events. For that reason I do not recommend using this function in the main thread of an SDL program.


This will get all the messages and remove them from the queue.


Returns True if the pygame.fastevent module is currently initialized.


Returns next event on queue. If there is no event waiting on the queue, this will return an event with type NOEVENT.


This will post your own event objects onto the event queue. You can post any event type you want, but some care must be taken. For example, if you post a MOUSEBUTTONDOWN event to the queue, it is likely any code receiving the event will expect the standard MOUSEBUTTONDOWN attributes to be available, like 'pos' and 'button'.
Because pygame.fastevent.post() may have to wait for the queue to empty, you can get into a dead lock if you try to append an event on to a full queue from the thread that processes events. For that reason I do not recommend using this function in the main thread of an SDL program.


For each frame of your game, you will need to make some sort of call to the event queue. This ensures your program can internally interact with the rest of the operating system.
This function is not necessary if your program is consistently processing events on the queue through the other pygame.fastevent functions.
There are important things that must be dealt with internally in the event queue. The main window may need to be repainted or respond to the system. If you fail to make a call to the event queue for too long, the system may decide your program has locked up.


Returns the current event on the queue. If there are no messages waiting on the queue, this will not return until one is available. Sometimes it is important to use this wait to get events from the queue, it will allow your application to idle when the user isn't doing anything with it.


The font module allows for rendering TrueType fonts into a new Surface object. It accepts any UCS-2 character ('u0001' to 'uFFFF'). This module is optional and requires SDL_ttf as a dependency. You should test that pygame.font is available and initialized before attempting to use the module.
Most of the work done with fonts are done by using the actual Font objects. The module by itself only has routines to initialize the module and create Font objects with pygame.font.Font().
You can load fonts from the system by using the pygame.font.SysFont() function. There are a few other functions to help lookup the system fonts.
Pygame comes with a builtin default font. This can always be accessed by passing None as the font name.
To use the pygame.freetype based pygame.ftfont as pygame.font define the environment variable PYGAME_FREETYPE before the first import of pygame. Module pygame.ftfont is a pygame.font compatible module that passes all but one of the font module unit tests: it does not have the UCS-2 limitation of the SDL_ttf based font module, so fails to raise an exception for a code point greater than 'uFFFF'. If pygame.freetype is unavailable then the SDL_ttf font module will be loaded instead.
This method is called automatically by pygame.init(). It initializes the font module. The module must be initialized before any other functions will work.
It is safe to call this function more than once.
Manually uninitialize SDL_ttf's font system. This is called automatically by pygame.quit().
It is safe to call this function even if font is currently not initialized.
Test if the font module is initialized or not.
Return the filename of the system font. This is not the full path to the file. This file can usually be found in the same directory as the font module, but it can also be bundled in separate archives.
Returns a list of all the fonts available on the system. The names of the fonts will be set to lowercase with all spaces and punctuation removed. This works on most systems, but some will return an empty list if they cannot find fonts.
Returns the full path to a font file on the system. If bold or italic are set to true, this will attempt to find the correct family of font.
The font name can also be an iterable of font names, a string of comma-separated font names, or a bytes of comma-separated font names, in which case the set of names will be searched in order. If none of the given names are found, None is returned.
New in pygame 2.0.1: Accept an iterable of font names.
Example:
Return a new Font object that is loaded from the system fonts. The font will match the requested bold and italic flags. Pygame uses a small set of common font aliases. If the specific font you ask for is not available, a reasonable alternative may be used. If a suitable system font is not found this will fall back on loading the default pygame font.
The font name can also be an iterable of font names, a string of comma-separated font names, or a bytes of comma-separated font names, in which case the set of names will be searched in order.
New in pygame 2.0.1: Accept an iterable of font names.
Load a new font from a given filename or a python file object. The size is the height of the font in pixels. If the filename is None the pygame default font will be loaded. If a font cannot be loaded from the arguments given an exception will be raised. Once the font is created the size cannot be changed.
Font objects are mainly used to render text into new Surface objects. The render can emulate bold or italic features, but it is better to load from a font with actual italic or bold glyphs. The rendered text can be regular strings or unicode.
Whether the font should be rendered in bold.
When set to True, this enables the bold rendering of text. This is a fake stretching of the font that doesn't look good on many font types. If possible load the font from a real bold font file. While bold, the font will have a different width than when normal. This can be mixed with the italic and underline modes.
New in pygame 2.0.0.
Whether the font should be rendered in italic.
When set to True, this enables fake rendering of italic text. This is a fake skewing of the font that doesn't look good on many font types. If possible load the font from a real italic font file. While italic the font will have a different width than when normal. This can be mixed with the bold and underline modes.
New in pygame 2.0.0.
Whether the font should be rendered in underline.
When set to True, all rendered fonts will include an underline. The underline is always one pixel thick, regardless of font size. This can be mixed with the bold and italic modes.
New in pygame 2.0.0.
This creates a new Surface with the specified text rendered on it. pygame provides no way to directly draw text on an existing Surface: instead you must use Font.render() to create an image (Surface) of the text, then blit this image onto another Surface.
The text can only be a single line: newline characters are not rendered. Null characters ('x00') raise a TypeError. Both Unicode and char (byte) strings are accepted. For Unicode strings only UCS-2 characters ('u0001' to 'uFFFF') are recognized. Anything greater raises a UnicodeError. For char strings a LATIN1 encoding is assumed. The antialias argument is a boolean: if true the characters will have smooth edges. The color argument is the color of the text [e.g.: (0,0,255) for blue]. The optional background argument is a color to use for the text background. If no background is passed the area outside the text will be transparent.
The Surface returned will be of the dimensions required to hold the text. (the same as those returned by Font.size()). If an empty string is passed for the text, a blank surface will be returned that is zero pixel wide and the height of the font.
Depending on the type of background and antialiasing used, this returns different types of Surfaces. For performance reasons, it is good to know what type of image will be used. If antialiasing is not used, the return image will always be an 8-bit image with a two-color palette. If the background is transparent a colorkey will be set. Antialiased images are rendered to 24-bit RGB images. If the background is transparent a pixel alpha will be included.
Optimization: if you know that the final destination for the text (on the screen) will always have a solid background, and the text is antialiased, you can improve performance by specifying the background color. This will cause the resulting image to maintain transparency information by colorkey rather than (much less efficient) alpha values.
If you render '\n' an unknown char will be rendered. Usually a rectangle. Instead you need to handle new lines yourself.
Font rendering is not thread safe: only a single thread can render text at any time.
Returns the dimensions needed to render the text. This can be used to help determine the positioning needed for text before it is rendered. It can also be used for wordwrapping and other layout effects.
Be aware that most fonts use kerning which adjusts the widths for specific letter pairs. For example, the width for "ae" will not always match the width for "a" + "e".
When enabled, all rendered fonts will include an underline. The underline is always one pixel thick, regardless of font size. This can be mixed with the bold and italic modes.
Note
This is the same as the underline attribute.
Return True when the font underline is enabled.
Note
This is the same as the underline attribute.
Enables the bold rendering of text. This is a fake stretching of the font that doesn't look good on many font types. If possible load the font from a real bold font file. While bold, the font will have a different width than when normal. This can be mixed with the italic and underline modes.
Note
This is the same as the bold attribute.
Return True when the font bold rendering mode is enabled.
Note
This is the same as the bold attribute.
Enables fake rendering of italic text. This is a fake skewing of the font that doesn't look good on many font types. If possible load the font from a real italic font file. While italic the font will have a different width than when normal. This can be mixed with the bold and underline modes.
Note
This is the same as the italic attribute.
The list contains tuples for each character, which contain the minimum X offset, the maximum X offset, the minimum Y offset, the maximum Y offset and the advance offset (bearing plus width) of the character. [(minx, maxx, miny, maxy, advance), (minx, maxx, miny, maxy, advance), ...]. None is entered in the list for each unrecognized character.
Return True when the font italic rendering mode is enabled.
Note
This is the same as the italic attribute.
Return the height in pixels for a line of text with the font. When rendering multiple lines of text this is the recommended amount of space between lines.
Return the height in pixels of the actual rendered text. This is the average size for each glyph in the font.
Return the height in pixels for the font ascent. The ascent is the number of pixels from the font baseline to the top of the font.
Return the height in pixels for the font descent. The descent is the number of pixels from the font baseline to the bottom of the font.


Load a new font from a given filename or a python file object. The size is the height of the font in pixels. If the filename is None the pygame default font will be loaded. If a font cannot be loaded from the arguments given an exception will be raised. Once the font is created the size cannot be changed.
Font objects are mainly used to render text into new Surface objects. The render can emulate bold or italic features, but it is better to load from a font with actual italic or bold glyphs. The rendered text can be regular strings or unicode.
Whether the font should be rendered in bold.
When set to True, this enables the bold rendering of text. This is a fake stretching of the font that doesn't look good on many font types. If possible load the font from a real bold font file. While bold, the font will have a different width than when normal. This can be mixed with the italic and underline modes.
New in pygame 2.0.0.
Whether the font should be rendered in italic.
When set to True, this enables fake rendering of italic text. This is a fake skewing of the font that doesn't look good on many font types. If possible load the font from a real italic font file. While italic the font will have a different width than when normal. This can be mixed with the bold and underline modes.
New in pygame 2.0.0.
Whether the font should be rendered in underline.
When set to True, all rendered fonts will include an underline. The underline is always one pixel thick, regardless of font size. This can be mixed with the bold and italic modes.
New in pygame 2.0.0.
This creates a new Surface with the specified text rendered on it. pygame provides no way to directly draw text on an existing Surface: instead you must use Font.render() to create an image (Surface) of the text, then blit this image onto another Surface.
The text can only be a single line: newline characters are not rendered. Null characters ('x00') raise a TypeError. Both Unicode and char (byte) strings are accepted. For Unicode strings only UCS-2 characters ('u0001' to 'uFFFF') are recognized. Anything greater raises a UnicodeError. For char strings a LATIN1 encoding is assumed. The antialias argument is a boolean: if true the characters will have smooth edges. The color argument is the color of the text [e.g.: (0,0,255) for blue]. The optional background argument is a color to use for the text background. If no background is passed the area outside the text will be transparent.
The Surface returned will be of the dimensions required to hold the text. (the same as those returned by Font.size()). If an empty string is passed for the text, a blank surface will be returned that is zero pixel wide and the height of the font.
Depending on the type of background and antialiasing used, this returns different types of Surfaces. For performance reasons, it is good to know what type of image will be used. If antialiasing is not used, the return image will always be an 8-bit image with a two-color palette. If the background is transparent a colorkey will be set. Antialiased images are rendered to 24-bit RGB images. If the background is transparent a pixel alpha will be included.
Optimization: if you know that the final destination for the text (on the screen) will always have a solid background, and the text is antialiased, you can improve performance by specifying the background color. This will cause the resulting image to maintain transparency information by colorkey rather than (much less efficient) alpha values.
If you render '\n' an unknown char will be rendered. Usually a rectangle. Instead you need to handle new lines yourself.
Font rendering is not thread safe: only a single thread can render text at any time.
Returns the dimensions needed to render the text. This can be used to help determine the positioning needed for text before it is rendered. It can also be used for wordwrapping and other layout effects.
Be aware that most fonts use kerning which adjusts the widths for specific letter pairs. For example, the width for "ae" will not always match the width for "a" + "e".
When enabled, all rendered fonts will include an underline. The underline is always one pixel thick, regardless of font size. This can be mixed with the bold and italic modes.
Note
This is the same as the underline attribute.
Return True when the font underline is enabled.
Note
This is the same as the underline attribute.
Enables the bold rendering of text. This is a fake stretching of the font that doesn't look good on many font types. If possible load the font from a real bold font file. While bold, the font will have a different width than when normal. This can be mixed with the italic and underline modes.
Note
This is the same as the bold attribute.
Return True when the font bold rendering mode is enabled.
Note
This is the same as the bold attribute.
Enables fake rendering of italic text. This is a fake skewing of the font that doesn't look good on many font types. If possible load the font from a real italic font file. While italic the font will have a different width than when normal. This can be mixed with the bold and underline modes.
Note
This is the same as the italic attribute.
The list contains tuples for each character, which contain the minimum X offset, the maximum X offset, the minimum Y offset, the maximum Y offset and the advance offset (bearing plus width) of the character. [(minx, maxx, miny, maxy, advance), (minx, maxx, miny, maxy, advance), ...]. None is entered in the list for each unrecognized character.
Return True when the font italic rendering mode is enabled.
Note
This is the same as the italic attribute.
Return the height in pixels for a line of text with the font. When rendering multiple lines of text this is the recommended amount of space between lines.
Return the height in pixels of the actual rendered text. This is the average size for each glyph in the font.
Return the height in pixels for the font ascent. The ascent is the number of pixels from the font baseline to the top of the font.
Return the height in pixels for the font descent. The descent is the number of pixels from the font baseline to the bottom of the font.


Whether the font should be rendered in bold.
When set to True, this enables the bold rendering of text. This is a fake stretching of the font that doesn't look good on many font types. If possible load the font from a real bold font file. While bold, the font will have a different width than when normal. This can be mixed with the italic and underline modes.
New in pygame 2.0.0.


Return the height in pixels for the font ascent. The ascent is the number of pixels from the font baseline to the top of the font.


Return True when the font bold rendering mode is enabled.
Note
This is the same as the bold attribute.