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.


Return the height in pixels of the actual rendered text. This is the average size for each glyph in the font.


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 True when the font underline is enabled.
Note
This is the same as the underline attribute.


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.


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.


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.


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.


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.


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.


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".


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.


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.


Test if the font module is initialized or not.


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.


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:


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.


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.


The pygame.freetype module is a replacement for pygame.font. It has all of the functionality of the original, plus many new features. Yet is has absolutely no dependencies on the SDL_ttf library. It is implemented directly on the FreeType 2 library. The pygame.freetype module is not itself backward compatible with pygame.font. Instead, use the pygame.ftfont module as a drop-in replacement for pygame.font.
All font file formats supported by FreeType can be rendered by pygame.freetype, namely TTF, Type1, CFF, OpenType, SFNT, PCF, FNT, BDF, PFR and Type42 fonts. All glyphs having UTF-32 code points are accessible (see Font.ucs4).
Most work on fonts is done using Font instances. The module itself only has routines for initialization and creation of Font objects. You can load fonts from the system using the SysFont() function.
Extra support of bitmap fonts is available. Available bitmap sizes can be listed (see Font.get_sizes()). For bitmap only fonts Font can set the size for you (see the Font.size property).
For now undefined character codes are replaced with the .notdef (not defined) character. How undefined codes are handled may become configurable in a future release.
Pygame comes with a built-in default font. This can always be accessed by passing None as the font name to the Font constructor.
Extra rendering features available to pygame.freetype.Font are direct to surface rendering (see Font.render_to()), character kerning (see Font.kerning), vertical layout (see Font.vertical), rotation of rendered text (see Font.rotation), and the strong style (see Font.strong). Some properties are configurable, such as strong style strength (see Font.strength) and underline positioning (see Font.underline_adjustment). Text can be positioned by the upper right corner of the text box or by the text baseline (see Font.origin). Finally, a font's vertical and horizontal size can be adjusted separately (see Font.size). The pygame.examples.freetype_misc example shows these features in use.
The pygame package does not import freetype automatically when loaded. This module must be imported explicitly to be used.
New in pygame 1.9.2: freetype
Return a description of the last error which occurred in the FreeType2 library, or None if no errors have occurred.
Returns the version of the FreeType library in use by this module.
Note that the freetype module depends on the FreeType 2 library. It will not compile with the original FreeType 1.0. Hence, the first element of the tuple will always be "2".
This function initializes the underlying FreeType library and must be called before trying to use any of the functionality of the freetype module.
However, pygame.init() will automatically call this function if the freetype module is already imported. It is safe to call this function more than once.
Optionally, you may specify a default cache_size for the Glyph cache: the maximum number of glyphs that will be cached at any given time by the module. Exceedingly small values will be automatically tuned for performance. Also a default pixel resolution, in dots per inch, can be given to adjust font scaling.
This function closes the freetype module. After calling this function, you should not invoke any class, method or function related to the freetype module as they are likely to fail or might give unpredictable results. It is safe to call this function even if the module hasn't been initialized yet.
Returns True if the pygame.freetype module is currently initialized.
New in pygame 1.9.5.
DEPRECATED: Returns True if the pygame.freetype module is currently initialized. Use get_init() instead.
See pygame.freetype.init().
Returns the default pixel size, in dots per inch, for the module. The default is 72 DPI.
Set the default pixel size, in dots per inch, for the module. If the optional argument is omitted or zero the resolution is reset to 72 DPI.
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.
Return the filename of the default pygame font. This is not the full path to the file. The file is usually in the same directory as the font module, but can also be bundled in a separate archive.
Argument file can be either a string representing the font's filename, a file-like object containing the font, or None; if None, a default, Pygame, font is used.
Optionally, a size argument may be specified to set the default size in points, which determines the size of the rendered characters. The size can also be passed explicitly to each method call. Because of the way the caching system works, specifying a default size on the constructor doesn't imply a performance gain over manually passing the size on each function call. If the font is bitmap and no size is given, the default size is set to the first available size for the font.
If the font file has more than one font, the font to load can be chosen with the index argument. An exception is raised for an out-of-range font index value.
The optional resolution argument sets the pixel size, in dots per inch, for use in scaling glyphs for this Font instance. If 0 then the default module value, set by init(), is used. The Font object's resolution can only be changed by re-initializing the Font instance.
The optional ucs4 argument, an integer, sets the default text translation mode: 0 (False) recognize UTF-16 surrogate pairs, any other value (True), to treat Unicode text as UCS-4, with no surrogate pairs. See Font.ucs4.
Read only. Returns the real (long) name of the font, as recorded in the font file.
Read only. Returns the path of the loaded font file
Get or set the default size for text metrics and rendering. It can be a single point size, given as a Python int or float, or a font ppem (width, height) tuple. Size values are non-negative. A zero size or width represents an undefined size. In this case the size must be given as a method argument, or an exception is raised. A zero width but non-zero height is a ValueError.
For a scalable font, a single number value is equivalent to a tuple with width equal height. A font can be stretched vertically with height set greater than width, or horizontally with width set greater than height. For embedded bitmaps, as listed by get_sizes(), use the nominal width and height to select an available size.
Font size differs for a non-scalable, bitmap, font. During a method call it must match one of the available sizes returned by method get_sizes(). If not, an exception is raised. If the size is a single number, the size is first matched against the point size value. If no match, then the available size with the same nominal width and height is chosen.
Gets the final dimensions and origin, in pixels, of text using the optional size in points, style, and rotation. For other relevant render properties, and for any optional argument not given, the default values set for the Font instance are used.
Returns a Rect instance containing the width and height of the text's bounding box and the position of the text's origin. The origin is useful in aligning separately rendered pieces of text. It gives the baseline position and bearing at the start of the text. See the render_to() method for an example.
If text is a char (byte) string, its encoding is assumed to be LATIN1.
Optionally, text can be None, which will return the bounding rectangle for the text passed to a previous get_rect(), render(), render_to(), render_raw(), or render_raw_to() call. See render_to() for more details.
Returns the glyph metrics for each character in text.
The glyph metrics are returned as a list of tuples. Each tuple gives metrics of a single character glyph. The glyph metrics are:
The bounding box min_x, max_x, min_y, and max_y values are returned as grid-fitted pixel coordinates of type int. The advance values are float values.
The calculations are done using the font's default size in points. Optionally you may specify another point size with the size argument.
The metrics are adjusted for the current rotation, strong, and oblique settings.
If text is a char (byte) string, then its encoding is assumed to be LATIN1.
Read only. Gets the height of the font. This is the average value of all glyphs in the font.
Read only. Return the number of units from the font's baseline to the top of the bounding box.
Read only. Return the height in font units for the font descent. The descent is the number of units from the font's baseline to the bottom of the bounding box.
Return the number of units from the font's baseline to the top of the bounding box. It is not adjusted for strong or rotation.
Return the number of pixels from the font's baseline to the top of the bounding box. It is not adjusted for strong or rotation.
Returns the height of the font. This is the average value of all glyphs in the font. It is not adjusted for strong or rotation.
Return the glyph bounding box height of the font in pixels. This is the average value of all glyphs in the font. It is not adjusted for strong or rotation.
Returns a list of tuple records, one for each point size supported. Each tuple containing the point size, the height in pixels, width in pixels, horizontal ppem (nominal width) in fractional pixels, and vertical ppem (nominal height) in fractional pixels.
Returns a new Surface, with the text rendered to it in the color given by 'fgcolor'. If no foreground color is given, the default foreground color, fgcolor is used. If bgcolor is given, the surface will be filled with this color. When no background color is given, the surface background is transparent, zero alpha. Normally the returned surface has a 32 bit pixel size. However, if bgcolor is None and anti-aliasing is disabled a monochrome 8 bit colorkey surface, with colorkey set for the background color, is returned.
The return value is a tuple: the new surface and the bounding rectangle giving the size and origin of the rendered text.
If an empty string is passed for text then the returned Rect is zero width and the height of the font.
Optional fgcolor, style, rotation, and size arguments override the default values set for the Font instance.
If text is a char (byte) string, then its encoding is assumed to be LATIN1.
Optionally, text can be None, which will render the text passed to a previous get_rect(), render(), render_to(), render_raw(), or render_raw_to() call. See render_to() for details.
Renders the string text to the pygame.Surface surf, at position dest, a (x, y) surface coordinate pair. If either x or y is not an integer it is converted to one if possible. Any sequence where the first two items are x and y positional elements is accepted, including a Rect instance. As with render(), optional fgcolor, style, rotation, and size argument are available.
If a background color bgcolor is given, the text bounding box is first filled with that color. The text is blitted next. Both the background fill and text rendering involve full alpha blits. That is, the alpha values of the foreground, background, and destination target surface all affect the blit.
The return value is a rectangle giving the size and position of the rendered text within the surface.
If an empty string is passed for text then the returned Rect is zero width and the height of the font. The rect will test False.
Optionally, text can be set None, which will re-render text passed to a previous render_to(), get_rect(), render(), render_raw(), or render_raw_to() call. Primarily, this feature is an aid to using render_to() in combination with get_rect(). An example:
When render_to() is called with the same font properties ― size, style, strength, wide, antialiased, vertical, rotation, kerning, and use_bitmap_strikes ― as get_rect(), render_to() will use the layout calculated by get_rect(). Otherwise, render_to() will recalculate the layout if called with a text string or one of the above properties has changed after the get_rect() call.
If text is a char (byte) string, then its encoding is assumed to be LATIN1.
Like render() but with the pixels returned as a byte string of 8-bit gray-scale values. The foreground color is 255, the background 0, useful as an alpha mask for a foreground pattern.
Render to an array object exposing an array struct interface. The array must be two dimensional with integer items. The default dest value, None, is equivalent to position (0, 0). See render_to(). As with the other render methods, text can be None to render a text string passed previously to another method.
The return value is a pygame.Rect() giving the size and position of the rendered text.
Gets or sets the default style of the Font. This default style will be used for all text rendering and size calculations unless overridden specifically a render or get_rect() call. The style value may be a bit-wise OR of one or more of the following constants:
These constants may be found on the FreeType constants module. Optionally, the default style can be modified or obtained accessing the individual style attributes (underline, oblique, strong).
The STYLE_OBLIQUE and STYLE_STRONG styles are for scalable fonts only. An attempt to set either for a bitmap font raises an AttributeError. An attempt to set either for an inactive font, as returned by Font.__new__(), raises a RuntimeError.
Assigning STYLE_DEFAULT to the style property leaves the property unchanged, as this property defines the default. The style property will never return STYLE_DEFAULT.
Gets or sets whether the font will be underlined when drawing text. This default style value will be used for all text rendering and size calculations unless overridden specifically in a render or get_rect() call, via the 'style' parameter.
Gets or sets whether the font will be bold when drawing text. This default style value will be used for all text rendering and size calculations unless overridden specifically in a render or get_rect() call, via the 'style' parameter.
Gets or sets whether the font will be rendered as oblique. This default style value will be used for all text rendering and size calculations unless overridden specifically in a render or get_rect() call, via the style parameter.
The oblique style is only supported for scalable (outline) fonts. An attempt to set this style on a bitmap font will raise an AttributeError. If the font object is inactive, as returned by Font.__new__(), setting this property raises a RuntimeError.
Gets or sets whether the font will be stretched horizontally when drawing text. It produces a result similar to pygame.font.Font's bold. This style not available for rotated text.
The amount by which a font glyph's size is enlarged for the strong or wide transformations, as a fraction of the untransformed size. For the wide style only the horizontal dimension is increased. For strong text both the horizontal and vertical dimensions are enlarged. A wide style of strength 0.08333 ( 1/12 ) is equivalent to the pygame.font.Font bold style. The default is 0.02778 ( 1/36 ).
The strength style is only supported for scalable (outline) fonts. An attempt to set this property on a bitmap font will raise an AttributeError. If the font object is inactive, as returned by Font.__new__(), assignment to this property raises a RuntimeError.
Gets or sets a factor which, when positive, is multiplied with the font's underline offset to adjust the underline position. A negative value turns an underline into a strike-through or overline. It is multiplied with the ascender. Accepted values range between -2.0 and 2.0 inclusive. A value of 0.5 closely matches Tango underlining. A value of 1.0 mimics pygame.font.Font underlining.
Read only. Returns True if the font contains fixed-width characters (for example Courier, Bitstream Vera Sans Mono, Andale Mono).
Read only. Returns the number of point sizes for which the font contains bitmap character images. If zero then the font is not a bitmap font. A scalable font may contain pre-rendered point sizes as strikes.
Read only. Returns True if the font contains outline glyphs. If so, the point size is not limited to available bitmap sizes.
Some scalable fonts include embedded bitmaps for particular point sizes. This property controls whether or not those bitmap strikes are used. Set it False to disable the loading of any bitmap strike. Set it True, the default, to permit bitmap strikes for a non-rotated render with no style other than wide or underline. This property is ignored for bitmap fonts.
See also fixed_sizes and get_sizes().
Gets or sets the font's anti-aliasing mode. This defaults to True on all fonts, which are rendered with full 8 bit blending.
Set to False to do monochrome rendering. This should provide a small speed gain and reduce cache memory size.
Gets or sets the font's kerning mode. This defaults to False on all fonts, which will be rendered without kerning.
Set to True to add kerning between character pairs, if supported by the font, when positioning glyphs.
Gets or sets whether the characters are laid out vertically rather than horizontally. May be useful when rendering Kanji or some other vertical script.
Set to True to switch to a vertical text layout. The default is False, place horizontally.
Note that the Font class does not automatically determine script orientation. Vertical layout must be selected explicitly.
Also note that several font formats (especially bitmap based ones) don't contain the necessary metrics to draw glyphs vertically, so drawing in those cases will give unspecified results.
Gets or sets the baseline angle of the rendered text. The angle is represented as integer degrees. The default angle is 0, with horizontal text rendered along the X-axis, and vertical text along the Y-axis. A positive value rotates these axes counterclockwise that many degrees. A negative angle corresponds to a clockwise rotation. The rotation value is normalized to a value within the range 0 to 359 inclusive (eg. 390 -> 390 - 360 -> 30, -45 -> 360 + -45 -> 315, 720 -> 720 - (2 * 360) -> 0).
Only scalable (outline) fonts can be rotated. An attempt to change the rotation of a bitmap font raises an AttributeError. An attempt to change the rotation of an inactive font instance, as returned by Font.__new__(), raises a RuntimeError.
Gets or sets the default glyph rendering color. It is initially opaque black ― (0, 0, 0, 255). Applies to render() and render_to().
Gets or sets the default background rendering color. Initially it is unset and text will render with a transparent background by default. Applies to render() and render_to().
New in pygame 2.0.0.
If set True, render_to() and render_raw_to() will take the dest position to be that of the text origin, as opposed to the top-left corner of the bounding box. See get_rect() for details.
If set True, then the text boundary rectangle will be inflated to match that of font.Font. Otherwise, the boundary rectangle is just large enough for the text.
Gets or sets the decoding of Unicode text. By default, the freetype module performs UTF-16 surrogate pair decoding on Unicode text. This allows 32-bit escape sequences ('Uxxxxxxxx') between 0x10000 and 0x10FFFF to represent their corresponding UTF-32 code points on Python interpreters built with a UCS-2 Unicode type (on Windows, for instance). It also means character values within the UTF-16 surrogate area (0xD800 to 0xDFFF) are considered part of a surrogate pair. A malformed surrogate pair will raise a UnicodeEncodeError. Setting ucs4 True turns surrogate pair decoding off, allowing access the full UCS-4 character range to a Python interpreter built with four-byte Unicode character support.
Read only. Gets pixel size used in scaling font glyphs for this Font instance.


Argument file can be either a string representing the font's filename, a file-like object containing the font, or None; if None, a default, Pygame, font is used.
Optionally, a size argument may be specified to set the default size in points, which determines the size of the rendered characters. The size can also be passed explicitly to each method call. Because of the way the caching system works, specifying a default size on the constructor doesn't imply a performance gain over manually passing the size on each function call. If the font is bitmap and no size is given, the default size is set to the first available size for the font.
If the font file has more than one font, the font to load can be chosen with the index argument. An exception is raised for an out-of-range font index value.
The optional resolution argument sets the pixel size, in dots per inch, for use in scaling glyphs for this Font instance. If 0 then the default module value, set by init(), is used. The Font object's resolution can only be changed by re-initializing the Font instance.
The optional ucs4 argument, an integer, sets the default text translation mode: 0 (False) recognize UTF-16 surrogate pairs, any other value (True), to treat Unicode text as UCS-4, with no surrogate pairs. See Font.ucs4.
Read only. Returns the real (long) name of the font, as recorded in the font file.
Read only. Returns the path of the loaded font file
Get or set the default size for text metrics and rendering. It can be a single point size, given as a Python int or float, or a font ppem (width, height) tuple. Size values are non-negative. A zero size or width represents an undefined size. In this case the size must be given as a method argument, or an exception is raised. A zero width but non-zero height is a ValueError.
For a scalable font, a single number value is equivalent to a tuple with width equal height. A font can be stretched vertically with height set greater than width, or horizontally with width set greater than height. For embedded bitmaps, as listed by get_sizes(), use the nominal width and height to select an available size.
Font size differs for a non-scalable, bitmap, font. During a method call it must match one of the available sizes returned by method get_sizes(). If not, an exception is raised. If the size is a single number, the size is first matched against the point size value. If no match, then the available size with the same nominal width and height is chosen.
Gets the final dimensions and origin, in pixels, of text using the optional size in points, style, and rotation. For other relevant render properties, and for any optional argument not given, the default values set for the Font instance are used.
Returns a Rect instance containing the width and height of the text's bounding box and the position of the text's origin. The origin is useful in aligning separately rendered pieces of text. It gives the baseline position and bearing at the start of the text. See the render_to() method for an example.
If text is a char (byte) string, its encoding is assumed to be LATIN1.
Optionally, text can be None, which will return the bounding rectangle for the text passed to a previous get_rect(), render(), render_to(), render_raw(), or render_raw_to() call. See render_to() for more details.
Returns the glyph metrics for each character in text.
The glyph metrics are returned as a list of tuples. Each tuple gives metrics of a single character glyph. The glyph metrics are:
The bounding box min_x, max_x, min_y, and max_y values are returned as grid-fitted pixel coordinates of type int. The advance values are float values.
The calculations are done using the font's default size in points. Optionally you may specify another point size with the size argument.
The metrics are adjusted for the current rotation, strong, and oblique settings.
If text is a char (byte) string, then its encoding is assumed to be LATIN1.
Read only. Gets the height of the font. This is the average value of all glyphs in the font.
Read only. Return the number of units from the font's baseline to the top of the bounding box.
Read only. Return the height in font units for the font descent. The descent is the number of units from the font's baseline to the bottom of the bounding box.
Return the number of units from the font's baseline to the top of the bounding box. It is not adjusted for strong or rotation.
Return the number of pixels from the font's baseline to the top of the bounding box. It is not adjusted for strong or rotation.
Returns the height of the font. This is the average value of all glyphs in the font. It is not adjusted for strong or rotation.
Return the glyph bounding box height of the font in pixels. This is the average value of all glyphs in the font. It is not adjusted for strong or rotation.
Returns a list of tuple records, one for each point size supported. Each tuple containing the point size, the height in pixels, width in pixels, horizontal ppem (nominal width) in fractional pixels, and vertical ppem (nominal height) in fractional pixels.
Returns a new Surface, with the text rendered to it in the color given by 'fgcolor'. If no foreground color is given, the default foreground color, fgcolor is used. If bgcolor is given, the surface will be filled with this color. When no background color is given, the surface background is transparent, zero alpha. Normally the returned surface has a 32 bit pixel size. However, if bgcolor is None and anti-aliasing is disabled a monochrome 8 bit colorkey surface, with colorkey set for the background color, is returned.
The return value is a tuple: the new surface and the bounding rectangle giving the size and origin of the rendered text.
If an empty string is passed for text then the returned Rect is zero width and the height of the font.
Optional fgcolor, style, rotation, and size arguments override the default values set for the Font instance.
If text is a char (byte) string, then its encoding is assumed to be LATIN1.
Optionally, text can be None, which will render the text passed to a previous get_rect(), render(), render_to(), render_raw(), or render_raw_to() call. See render_to() for details.
Renders the string text to the pygame.Surface surf, at position dest, a (x, y) surface coordinate pair. If either x or y is not an integer it is converted to one if possible. Any sequence where the first two items are x and y positional elements is accepted, including a Rect instance. As with render(), optional fgcolor, style, rotation, and size argument are available.
If a background color bgcolor is given, the text bounding box is first filled with that color. The text is blitted next. Both the background fill and text rendering involve full alpha blits. That is, the alpha values of the foreground, background, and destination target surface all affect the blit.
The return value is a rectangle giving the size and position of the rendered text within the surface.
If an empty string is passed for text then the returned Rect is zero width and the height of the font. The rect will test False.
Optionally, text can be set None, which will re-render text passed to a previous render_to(), get_rect(), render(), render_raw(), or render_raw_to() call. Primarily, this feature is an aid to using render_to() in combination with get_rect(). An example:
When render_to() is called with the same font properties ― size, style, strength, wide, antialiased, vertical, rotation, kerning, and use_bitmap_strikes ― as get_rect(), render_to() will use the layout calculated by get_rect(). Otherwise, render_to() will recalculate the layout if called with a text string or one of the above properties has changed after the get_rect() call.
If text is a char (byte) string, then its encoding is assumed to be LATIN1.
Like render() but with the pixels returned as a byte string of 8-bit gray-scale values. The foreground color is 255, the background 0, useful as an alpha mask for a foreground pattern.
Render to an array object exposing an array struct interface. The array must be two dimensional with integer items. The default dest value, None, is equivalent to position (0, 0). See render_to(). As with the other render methods, text can be None to render a text string passed previously to another method.
The return value is a pygame.Rect() giving the size and position of the rendered text.
Gets or sets the default style of the Font. This default style will be used for all text rendering and size calculations unless overridden specifically a render or get_rect() call. The style value may be a bit-wise OR of one or more of the following constants:
These constants may be found on the FreeType constants module. Optionally, the default style can be modified or obtained accessing the individual style attributes (underline, oblique, strong).
The STYLE_OBLIQUE and STYLE_STRONG styles are for scalable fonts only. An attempt to set either for a bitmap font raises an AttributeError. An attempt to set either for an inactive font, as returned by Font.__new__(), raises a RuntimeError.
Assigning STYLE_DEFAULT to the style property leaves the property unchanged, as this property defines the default. The style property will never return STYLE_DEFAULT.
Gets or sets whether the font will be underlined when drawing text. This default style value will be used for all text rendering and size calculations unless overridden specifically in a render or get_rect() call, via the 'style' parameter.
Gets or sets whether the font will be bold when drawing text. This default style value will be used for all text rendering and size calculations unless overridden specifically in a render or get_rect() call, via the 'style' parameter.
Gets or sets whether the font will be rendered as oblique. This default style value will be used for all text rendering and size calculations unless overridden specifically in a render or get_rect() call, via the style parameter.
The oblique style is only supported for scalable (outline) fonts. An attempt to set this style on a bitmap font will raise an AttributeError. If the font object is inactive, as returned by Font.__new__(), setting this property raises a RuntimeError.
Gets or sets whether the font will be stretched horizontally when drawing text. It produces a result similar to pygame.font.Font's bold. This style not available for rotated text.
The amount by which a font glyph's size is enlarged for the strong or wide transformations, as a fraction of the untransformed size. For the wide style only the horizontal dimension is increased. For strong text both the horizontal and vertical dimensions are enlarged. A wide style of strength 0.08333 ( 1/12 ) is equivalent to the pygame.font.Font bold style. The default is 0.02778 ( 1/36 ).
The strength style is only supported for scalable (outline) fonts. An attempt to set this property on a bitmap font will raise an AttributeError. If the font object is inactive, as returned by Font.__new__(), assignment to this property raises a RuntimeError.
Gets or sets a factor which, when positive, is multiplied with the font's underline offset to adjust the underline position. A negative value turns an underline into a strike-through or overline. It is multiplied with the ascender. Accepted values range between -2.0 and 2.0 inclusive. A value of 0.5 closely matches Tango underlining. A value of 1.0 mimics pygame.font.Font underlining.
Read only. Returns True if the font contains fixed-width characters (for example Courier, Bitstream Vera Sans Mono, Andale Mono).
Read only. Returns the number of point sizes for which the font contains bitmap character images. If zero then the font is not a bitmap font. A scalable font may contain pre-rendered point sizes as strikes.
Read only. Returns True if the font contains outline glyphs. If so, the point size is not limited to available bitmap sizes.
Some scalable fonts include embedded bitmaps for particular point sizes. This property controls whether or not those bitmap strikes are used. Set it False to disable the loading of any bitmap strike. Set it True, the default, to permit bitmap strikes for a non-rotated render with no style other than wide or underline. This property is ignored for bitmap fonts.
See also fixed_sizes and get_sizes().
Gets or sets the font's anti-aliasing mode. This defaults to True on all fonts, which are rendered with full 8 bit blending.
Set to False to do monochrome rendering. This should provide a small speed gain and reduce cache memory size.
Gets or sets the font's kerning mode. This defaults to False on all fonts, which will be rendered without kerning.
Set to True to add kerning between character pairs, if supported by the font, when positioning glyphs.
Gets or sets whether the characters are laid out vertically rather than horizontally. May be useful when rendering Kanji or some other vertical script.
Set to True to switch to a vertical text layout. The default is False, place horizontally.
Note that the Font class does not automatically determine script orientation. Vertical layout must be selected explicitly.
Also note that several font formats (especially bitmap based ones) don't contain the necessary metrics to draw glyphs vertically, so drawing in those cases will give unspecified results.
Gets or sets the baseline angle of the rendered text. The angle is represented as integer degrees. The default angle is 0, with horizontal text rendered along the X-axis, and vertical text along the Y-axis. A positive value rotates these axes counterclockwise that many degrees. A negative angle corresponds to a clockwise rotation. The rotation value is normalized to a value within the range 0 to 359 inclusive (eg. 390 -> 390 - 360 -> 30, -45 -> 360 + -45 -> 315, 720 -> 720 - (2 * 360) -> 0).
Only scalable (outline) fonts can be rotated. An attempt to change the rotation of a bitmap font raises an AttributeError. An attempt to change the rotation of an inactive font instance, as returned by Font.__new__(), raises a RuntimeError.
Gets or sets the default glyph rendering color. It is initially opaque black ― (0, 0, 0, 255). Applies to render() and render_to().
Gets or sets the default background rendering color. Initially it is unset and text will render with a transparent background by default. Applies to render() and render_to().
New in pygame 2.0.0.
If set True, render_to() and render_raw_to() will take the dest position to be that of the text origin, as opposed to the top-left corner of the bounding box. See get_rect() for details.
If set True, then the text boundary rectangle will be inflated to match that of font.Font. Otherwise, the boundary rectangle is just large enough for the text.
Gets or sets the decoding of Unicode text. By default, the freetype module performs UTF-16 surrogate pair decoding on Unicode text. This allows 32-bit escape sequences ('Uxxxxxxxx') between 0x10000 and 0x10FFFF to represent their corresponding UTF-32 code points on Python interpreters built with a UCS-2 Unicode type (on Windows, for instance). It also means character values within the UTF-16 surrogate area (0xD800 to 0xDFFF) are considered part of a surrogate pair. A malformed surrogate pair will raise a UnicodeEncodeError. Setting ucs4 True turns surrogate pair decoding off, allowing access the full UCS-4 character range to a Python interpreter built with four-byte Unicode character support.
Read only. Gets pixel size used in scaling font glyphs for this Font instance.


Gets or sets the font's anti-aliasing mode. This defaults to True on all fonts, which are rendered with full 8 bit blending.
Set to False to do monochrome rendering. This should provide a small speed gain and reduce cache memory size.


Read only. Return the number of units from the font's baseline to the top of the bounding box.


Gets or sets the default background rendering color. Initially it is unset and text will render with a transparent background by default. Applies to render() and render_to().


Read only. Return the height in font units for the font descent. The descent is the number of units from the font's baseline to the bottom of the bounding box.


Gets or sets the default glyph rendering color. It is initially opaque black ― (0, 0, 0, 255). Applies to render() and render_to().


Read only. Returns the number of point sizes for which the font contains bitmap character images. If zero then the font is not a bitmap font. A scalable font may contain pre-rendered point sizes as strikes.


Read only. Returns True if the font contains fixed-width characters (for example Courier, Bitstream Vera Sans Mono, Andale Mono).


Returns the glyph metrics for each character in text.
The glyph metrics are returned as a list of tuples. Each tuple gives metrics of a single character glyph. The glyph metrics are:
The bounding box min_x, max_x, min_y, and max_y values are returned as grid-fitted pixel coordinates of type int. The advance values are float values.
The calculations are done using the font's default size in points. Optionally you may specify another point size with the size argument.
The metrics are adjusted for the current rotation, strong, and oblique settings.
If text is a char (byte) string, then its encoding is assumed to be LATIN1.


Gets the final dimensions and origin, in pixels, of text using the optional size in points, style, and rotation. For other relevant render properties, and for any optional argument not given, the default values set for the Font instance are used.
Returns a Rect instance containing the width and height of the text's bounding box and the position of the text's origin. The origin is useful in aligning separately rendered pieces of text. It gives the baseline position and bearing at the start of the text. See the render_to() method for an example.
If text is a char (byte) string, its encoding is assumed to be LATIN1.
Optionally, text can be None, which will return the bounding rectangle for the text passed to a previous get_rect(), render(), render_to(), render_raw(), or render_raw_to() call. See render_to() for more details.


Return the number of units from the font's baseline to the top of the bounding box. It is not adjusted for strong or rotation.


Return the number of pixels from the font's baseline to the top of the bounding box. It is not adjusted for strong or rotation.


Return the glyph bounding box height of the font in pixels. This is the average value of all glyphs in the font. It is not adjusted for strong or rotation.


Returns the height of the font. This is the average value of all glyphs in the font. It is not adjusted for strong or rotation.


Returns a list of tuple records, one for each point size supported. Each tuple containing the point size, the height in pixels, width in pixels, horizontal ppem (nominal width) in fractional pixels, and vertical ppem (nominal height) in fractional pixels.


Read only. Gets the height of the font. This is the average value of all glyphs in the font.


Gets or sets the font's kerning mode. This defaults to False on all fonts, which will be rendered without kerning.
Set to True to add kerning between character pairs, if supported by the font, when positioning glyphs.


Read only. Returns the real (long) name of the font, as recorded in the font file.


Gets or sets whether the font will be rendered as oblique. This default style value will be used for all text rendering and size calculations unless overridden specifically in a render or get_rect() call, via the style parameter.
The oblique style is only supported for scalable (outline) fonts. An attempt to set this style on a bitmap font will raise an AttributeError. If the font object is inactive, as returned by Font.__new__(), setting this property raises a RuntimeError.


If set True, render_to() and render_raw_to() will take the dest position to be that of the text origin, as opposed to the top-left corner of the bounding box. See get_rect() for details.


If set True, then the text boundary rectangle will be inflated to match that of font.Font. Otherwise, the boundary rectangle is just large enough for the text.


Read only. Returns the path of the loaded font file


Returns a new Surface, with the text rendered to it in the color given by 'fgcolor'. If no foreground color is given, the default foreground color, fgcolor is used. If bgcolor is given, the surface will be filled with this color. When no background color is given, the surface background is transparent, zero alpha. Normally the returned surface has a 32 bit pixel size. However, if bgcolor is None and anti-aliasing is disabled a monochrome 8 bit colorkey surface, with colorkey set for the background color, is returned.
The return value is a tuple: the new surface and the bounding rectangle giving the size and origin of the rendered text.
If an empty string is passed for text then the returned Rect is zero width and the height of the font.
Optional fgcolor, style, rotation, and size arguments override the default values set for the Font instance.
If text is a char (byte) string, then its encoding is assumed to be LATIN1.
Optionally, text can be None, which will render the text passed to a previous get_rect(), render(), render_to(), render_raw(), or render_raw_to() call. See render_to() for details.


Like render() but with the pixels returned as a byte string of 8-bit gray-scale values. The foreground color is 255, the background 0, useful as an alpha mask for a foreground pattern.


Render to an array object exposing an array struct interface. The array must be two dimensional with integer items. The default dest value, None, is equivalent to position (0, 0). See render_to(). As with the other render methods, text can be None to render a text string passed previously to another method.
The return value is a pygame.Rect() giving the size and position of the rendered text.


Renders the string text to the pygame.Surface surf, at position dest, a (x, y) surface coordinate pair. If either x or y is not an integer it is converted to one if possible. Any sequence where the first two items are x and y positional elements is accepted, including a Rect instance. As with render(), optional fgcolor, style, rotation, and size argument are available.
If a background color bgcolor is given, the text bounding box is first filled with that color. The text is blitted next. Both the background fill and text rendering involve full alpha blits. That is, the alpha values of the foreground, background, and destination target surface all affect the blit.
The return value is a rectangle giving the size and position of the rendered text within the surface.
If an empty string is passed for text then the returned Rect is zero width and the height of the font. The rect will test False.
Optionally, text can be set None, which will re-render text passed to a previous render_to(), get_rect(), render(), render_raw(), or render_raw_to() call. Primarily, this feature is an aid to using render_to() in combination with get_rect(). An example:
When render_to() is called with the same font properties ― size, style, strength, wide, antialiased, vertical, rotation, kerning, and use_bitmap_strikes ― as get_rect(), render_to() will use the layout calculated by get_rect(). Otherwise, render_to() will recalculate the layout if called with a text string or one of the above properties has changed after the get_rect() call.
If text is a char (byte) string, then its encoding is assumed to be LATIN1.


Read only. Gets pixel size used in scaling font glyphs for this Font instance.


Gets or sets the baseline angle of the rendered text. The angle is represented as integer degrees. The default angle is 0, with horizontal text rendered along the X-axis, and vertical text along the Y-axis. A positive value rotates these axes counterclockwise that many degrees. A negative angle corresponds to a clockwise rotation. The rotation value is normalized to a value within the range 0 to 359 inclusive (eg. 390 -> 390 - 360 -> 30, -45 -> 360 + -45 -> 315, 720 -> 720 - (2 * 360) -> 0).
Only scalable (outline) fonts can be rotated. An attempt to change the rotation of a bitmap font raises an AttributeError. An attempt to change the rotation of an inactive font instance, as returned by Font.__new__(), raises a RuntimeError.


Read only. Returns True if the font contains outline glyphs. If so, the point size is not limited to available bitmap sizes.


Get or set the default size for text metrics and rendering. It can be a single point size, given as a Python int or float, or a font ppem (width, height) tuple. Size values are non-negative. A zero size or width represents an undefined size. In this case the size must be given as a method argument, or an exception is raised. A zero width but non-zero height is a ValueError.
For a scalable font, a single number value is equivalent to a tuple with width equal height. A font can be stretched vertically with height set greater than width, or horizontally with width set greater than height. For embedded bitmaps, as listed by get_sizes(), use the nominal width and height to select an available size.
Font size differs for a non-scalable, bitmap, font. During a method call it must match one of the available sizes returned by method get_sizes(). If not, an exception is raised. If the size is a single number, the size is first matched against the point size value. If no match, then the available size with the same nominal width and height is chosen.


The amount by which a font glyph's size is enlarged for the strong or wide transformations, as a fraction of the untransformed size. For the wide style only the horizontal dimension is increased. For strong text both the horizontal and vertical dimensions are enlarged. A wide style of strength 0.08333 ( 1/12 ) is equivalent to the pygame.font.Font bold style. The default is 0.02778 ( 1/36 ).
The strength style is only supported for scalable (outline) fonts. An attempt to set this property on a bitmap font will raise an AttributeError. If the font object is inactive, as returned by Font.__new__(), assignment to this property raises a RuntimeError.


Gets or sets whether the font will be bold when drawing text. This default style value will be used for all text rendering and size calculations unless overridden specifically in a render or get_rect() call, via the 'style' parameter.


Gets or sets the default style of the Font. This default style will be used for all text rendering and size calculations unless overridden specifically a render or get_rect() call. The style value may be a bit-wise OR of one or more of the following constants:
These constants may be found on the FreeType constants module. Optionally, the default style can be modified or obtained accessing the individual style attributes (underline, oblique, strong).
The STYLE_OBLIQUE and STYLE_STRONG styles are for scalable fonts only. An attempt to set either for a bitmap font raises an AttributeError. An attempt to set either for an inactive font, as returned by Font.__new__(), raises a RuntimeError.
Assigning STYLE_DEFAULT to the style property leaves the property unchanged, as this property defines the default. The style property will never return STYLE_DEFAULT.


Gets or sets the decoding of Unicode text. By default, the freetype module performs UTF-16 surrogate pair decoding on Unicode text. This allows 32-bit escape sequences ('Uxxxxxxxx') between 0x10000 and 0x10FFFF to represent their corresponding UTF-32 code points on Python interpreters built with a UCS-2 Unicode type (on Windows, for instance). It also means character values within the UTF-16 surrogate area (0xD800 to 0xDFFF) are considered part of a surrogate pair. A malformed surrogate pair will raise a UnicodeEncodeError. Setting ucs4 True turns surrogate pair decoding off, allowing access the full UCS-4 character range to a Python interpreter built with four-byte Unicode character support.


Gets or sets whether the font will be underlined when drawing text. This default style value will be used for all text rendering and size calculations unless overridden specifically in a render or get_rect() call, via the 'style' parameter.


Gets or sets a factor which, when positive, is multiplied with the font's underline offset to adjust the underline position. A negative value turns an underline into a strike-through or overline. It is multiplied with the ascender. Accepted values range between -2.0 and 2.0 inclusive. A value of 0.5 closely matches Tango underlining. A value of 1.0 mimics pygame.font.Font underlining.


Some scalable fonts include embedded bitmaps for particular point sizes. This property controls whether or not those bitmap strikes are used. Set it False to disable the loading of any bitmap strike. Set it True, the default, to permit bitmap strikes for a non-rotated render with no style other than wide or underline. This property is ignored for bitmap fonts.
See also fixed_sizes and get_sizes().


Gets or sets whether the characters are laid out vertically rather than horizontally. May be useful when rendering Kanji or some other vertical script.
Set to True to switch to a vertical text layout. The default is False, place horizontally.
Note that the Font class does not automatically determine script orientation. Vertical layout must be selected explicitly.
Also note that several font formats (especially bitmap based ones) don't contain the necessary metrics to draw glyphs vertically, so drawing in those cases will give unspecified results.


Gets or sets whether the font will be stretched horizontally when drawing text. It produces a result similar to pygame.font.Font's bold. This style not available for rotated text.


Return the filename of the default pygame font. This is not the full path to the file. The file is usually in the same directory as the font module, but can also be bundled in a separate archive.


Returns the default pixel size, in dots per inch, for the module. The default is 72 DPI.


Return a description of the last error which occurred in the FreeType2 library, or None if no errors have occurred.


Returns True if the pygame.freetype module is currently initialized.
New in pygame 1.9.5.


Returns the version of the FreeType library in use by this module.
Note that the freetype module depends on the FreeType 2 library. It will not compile with the original FreeType 1.0. Hence, the first element of the tuple will always be "2".


This function initializes the underlying FreeType library and must be called before trying to use any of the functionality of the freetype module.
However, pygame.init() will automatically call this function if the freetype module is already imported. It is safe to call this function more than once.
Optionally, you may specify a default cache_size for the Glyph cache: the maximum number of glyphs that will be cached at any given time by the module. Exceedingly small values will be automatically tuned for performance. Also a default pixel resolution, in dots per inch, can be given to adjust font scaling.


This function closes the freetype module. After calling this function, you should not invoke any class, method or function related to the freetype module as they are likely to fail or might give unpredictable results. It is safe to call this function even if the module hasn't been initialized yet.


Set the default pixel size, in dots per inch, for the module. If the optional argument is omitted or zero the resolution is reset to 72 DPI.


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.


DEPRECATED: Returns True if the pygame.freetype module is currently initialized. Use get_init() instead.


SDL maintains an internal error message. This message will usually be given to you when pygame.error() is raised, so this function will rarely be needed.


Returns True if pygame is currently initialized.
New in pygame 1.9.5.


Returns the byte order of the SDL library. It returns 1234 for little endian byte order and 4321 for big endian byte order.
New in pygame 1.8.


Returns the three version numbers of the SDL library. This version is built at compile time. It can be used to detect which features may or may not be available through pygame.
New in pygame 1.7.0.


EXPERIMENTAL!: This API may change or disappear in later pygame releases. If you use this, your code may break with the next pygame release.
The pygame package does not import gfxdraw automatically when loaded, so it must imported explicitly to be used.
For all functions the arguments are strictly positional and integers are accepted for coordinates and radii. The color argument can be one of the following formats:
The functions rectangle() and box() will accept any (x, y, w, h) sequence for their rect argument, though pygame.Rect instances are preferred.
To draw a filled antialiased shape, first use the antialiased (aa*) version of the function, and then use the filled (filled_*) version. For example:
Note
For threading, each of the functions releases the GIL during the C part of the call.
Note
See the pygame.draw module for alternative draw methods. The pygame.gfxdraw module differs from the pygame.draw module in the API it uses and the different draw functions available. pygame.gfxdraw wraps the primitives from the library called SDL_gfx, rather than using modified versions.
New in pygame 1.9.0.
Draws a single pixel, at position (x ,y), on the given surface.
None
NoneType
Draws a straight horizontal line ((x1, y) to (x2, y)) on the given surface. There are no endcaps.
None
NoneType
Draws a straight vertical line ((x, y1) to (x, y2)) on the given surface. There are no endcaps.
None
NoneType
Draws a straight line ((x1, y1) to (x2, y2)) on the given surface. There are no endcaps.
None
NoneType
Draws an unfilled rectangle on the given surface. For a filled rectangle use box().
None
NoneType
Note
The rect.bottom and rect.right attributes of a pygame.Rect always lie one pixel outside of its actual border. Therefore, these values will not be included as part of the drawing.
Draws a filled rectangle on the given surface. For an unfilled rectangle use rectangle().
None
NoneType
Note
The rect.bottom and rect.right attributes of a pygame.Rect always lie one pixel outside of its actual border. Therefore, these values will not be included as part of the drawing.
Note
The pygame.Surface.fill() method works just as well for drawing filled rectangles. In fact pygame.Surface.fill() can be hardware accelerated on some platforms with both software and hardware display modes.
Draws an unfilled circle on the given surface. For a filled circle use filled_circle().
None
NoneType
Draws an unfilled antialiased circle on the given surface.
None
NoneType
Draws a filled circle on the given surface. For an unfilled circle use circle().
None
NoneType
Draws an unfilled ellipse on the given surface. For a filled ellipse use filled_ellipse().
None
NoneType
Draws an unfilled antialiased ellipse on the given surface.
None
NoneType
Draws a filled ellipse on the given surface. For an unfilled ellipse use ellipse().
None
NoneType
Draws an arc on the given surface. For an arc with its endpoints connected to its center use pie().
The two angle arguments are given in degrees and indicate the start and stop positions of the arc. The arc is drawn in a clockwise direction from the start_angle to the stop_angle. If start_angle == stop_angle, nothing will be drawn
None
NoneType
Note
This function uses degrees while the pygame.draw.arc() function uses radians.
Draws an unfilled pie on the given surface. A pie is an arc() with its endpoints connected to its center.
The two angle arguments are given in degrees and indicate the start and stop positions of the pie. The pie is drawn in a clockwise direction from the start_angle to the stop_angle. If start_angle == stop_angle, a straight line will be drawn from the center position at the given angle, to a length of the radius.
None
NoneType
Draws an unfilled trigon (triangle) on the given surface. For a filled trigon use filled_trigon().
A trigon can also be drawn using polygon() e.g. polygon(surface, ((x1, y1), (x2, y2), (x3, y3)), color)
None
NoneType
Draws an unfilled antialiased trigon (triangle) on the given surface.
An aatrigon can also be drawn using aapolygon() e.g. aapolygon(surface, ((x1, y1), (x2, y2), (x3, y3)), color)
None
NoneType
Draws a filled trigon (triangle) on the given surface. For an unfilled trigon use trigon().
A filled_trigon can also be drawn using filled_polygon() e.g. filled_polygon(surface, ((x1, y1), (x2, y2), (x3, y3)), color)
None
NoneType
Draws an unfilled polygon on the given surface. For a filled polygon use filled_polygon().
The adjacent coordinates in the points argument, as well as the first and last points, will be connected by line segments. e.g. For the points [(x1, y1), (x2, y2), (x3, y3)] a line segment will be drawn from (x1, y1) to (x2, y2), from (x2, y2) to (x3, y3), and from (x3, y3) to (x1, y1).
None
NoneType
Draws an unfilled antialiased polygon on the given surface.
The adjacent coordinates in the points argument, as well as the first and last points, will be connected by line segments. e.g. For the points [(x1, y1), (x2, y2), (x3, y3)] a line segment will be drawn from (x1, y1) to (x2, y2), from (x2, y2) to (x3, y3), and from (x3, y3) to (x1, y1).
None
NoneType
Draws a filled polygon on the given surface. For an unfilled polygon use polygon().
The adjacent coordinates in the points argument, as well as the first and last points, will be connected by line segments. e.g. For the points [(x1, y1), (x2, y2), (x3, y3)] a line segment will be drawn from (x1, y1) to (x2, y2), from (x2, y2) to (x3, y3), and from (x3, y3) to (x1, y1).
None
NoneType
Draws a textured polygon on the given surface. For better performance, the surface and the texture should have the same format.
A per-pixel alpha texture blit to a per-pixel alpha surface will differ from a pygame.Surface.blit() blit. Also, a per-pixel alpha texture cannot be used with an 8-bit per pixel destination.
The adjacent coordinates in the points argument, as well as the first and last points, will be connected by line segments. e.g. For the points [(x1, y1), (x2, y2), (x3, y3)] a line segment will be drawn from (x1, y1) to (x2, y2), from (x2, y2) to (x3, y3), and from (x3, y3) to (x1, y1).
None
NoneType
Draws a Bézier curve on the given surface.
None
NoneType


Draws an unfilled antialiased circle on the given surface.
None
NoneType


Draws an unfilled antialiased ellipse on the given surface.
None
NoneType


Draws an unfilled antialiased polygon on the given surface.
The adjacent coordinates in the points argument, as well as the first and last points, will be connected by line segments. e.g. For the points [(x1, y1), (x2, y2), (x3, y3)] a line segment will be drawn from (x1, y1) to (x2, y2), from (x2, y2) to (x3, y3), and from (x3, y3) to (x1, y1).
None
NoneType


Draws an unfilled antialiased trigon (triangle) on the given surface.
An aatrigon can also be drawn using aapolygon() e.g. aapolygon(surface, ((x1, y1), (x2, y2), (x3, y3)), color)
None
NoneType


Draws an arc on the given surface. For an arc with its endpoints connected to its center use pie().
The two angle arguments are given in degrees and indicate the start and stop positions of the arc. The arc is drawn in a clockwise direction from the start_angle to the stop_angle. If start_angle == stop_angle, nothing will be drawn
None
NoneType
Note
This function uses degrees while the pygame.draw.arc() function uses radians.


Draws a Bézier curve on the given surface.
None
NoneType


Draws a filled rectangle on the given surface. For an unfilled rectangle use rectangle().
None
NoneType
Note
The rect.bottom and rect.right attributes of a pygame.Rect always lie one pixel outside of its actual border. Therefore, these values will not be included as part of the drawing.
Note
The pygame.Surface.fill() method works just as well for drawing filled rectangles. In fact pygame.Surface.fill() can be hardware accelerated on some platforms with both software and hardware display modes.


Draws an unfilled circle on the given surface. For a filled circle use filled_circle().
None
NoneType


Draws an unfilled ellipse on the given surface. For a filled ellipse use filled_ellipse().
None
NoneType


Draws a filled circle on the given surface. For an unfilled circle use circle().
None
NoneType


Draws a filled ellipse on the given surface. For an unfilled ellipse use ellipse().
None
NoneType


Draws a filled polygon on the given surface. For an unfilled polygon use polygon().
The adjacent coordinates in the points argument, as well as the first and last points, will be connected by line segments. e.g. For the points [(x1, y1), (x2, y2), (x3, y3)] a line segment will be drawn from (x1, y1) to (x2, y2), from (x2, y2) to (x3, y3), and from (x3, y3) to (x1, y1).
None
NoneType


Draws a filled trigon (triangle) on the given surface. For an unfilled trigon use trigon().
A filled_trigon can also be drawn using filled_polygon() e.g. filled_polygon(surface, ((x1, y1), (x2, y2), (x3, y3)), color)
None
NoneType


Draws a straight horizontal line ((x1, y) to (x2, y)) on the given surface. There are no endcaps.
None
NoneType


Draws a straight line ((x1, y1) to (x2, y2)) on the given surface. There are no endcaps.
None
NoneType


Draws an unfilled pie on the given surface. A pie is an arc() with its endpoints connected to its center.
The two angle arguments are given in degrees and indicate the start and stop positions of the pie. The pie is drawn in a clockwise direction from the start_angle to the stop_angle. If start_angle == stop_angle, a straight line will be drawn from the center position at the given angle, to a length of the radius.
None
NoneType


Draws a single pixel, at position (x ,y), on the given surface.
None
NoneType


Draws an unfilled polygon on the given surface. For a filled polygon use filled_polygon().
The adjacent coordinates in the points argument, as well as the first and last points, will be connected by line segments. e.g. For the points [(x1, y1), (x2, y2), (x3, y3)] a line segment will be drawn from (x1, y1) to (x2, y2), from (x2, y2) to (x3, y3), and from (x3, y3) to (x1, y1).
None
NoneType


Draws an unfilled rectangle on the given surface. For a filled rectangle use box().
None
NoneType
Note
The rect.bottom and rect.right attributes of a pygame.Rect always lie one pixel outside of its actual border. Therefore, these values will not be included as part of the drawing.


Draws a textured polygon on the given surface. For better performance, the surface and the texture should have the same format.
A per-pixel alpha texture blit to a per-pixel alpha surface will differ from a pygame.Surface.blit() blit. Also, a per-pixel alpha texture cannot be used with an 8-bit per pixel destination.
The adjacent coordinates in the points argument, as well as the first and last points, will be connected by line segments. e.g. For the points [(x1, y1), (x2, y2), (x3, y3)] a line segment will be drawn from (x1, y1) to (x2, y2), from (x2, y2) to (x3, y3), and from (x3, y3) to (x1, y1).
None
NoneType


Draws an unfilled trigon (triangle) on the given surface. For a filled trigon use filled_trigon().
A trigon can also be drawn using polygon() e.g. polygon(surface, ((x1, y1), (x2, y2), (x3, y3)), color)
None
NoneType


Draws a straight vertical line ((x, y1) to (x, y2)) on the given surface. There are no endcaps.
None
NoneType


The image module contains functions for loading and saving pictures, as well as transferring Surfaces to formats usable by other packages.
Note that there is no Image class; an image is loaded as a Surface object. The Surface class allows manipulation (drawing lines, setting pixels, capturing regions, etc.).
The image module is a required dependency of pygame, but it only optionally supports any extended file formats. By default it can only load uncompressed BMP images. When built with full image support, the pygame.image.load() function can support the following formats.
Saving images only supports a limited set of formats. You can save to the following formats.
JPEG and JPG refer to the same file format
New in pygame 1.8: Saving PNG and JPEG files.
Load an image from a file source. You can pass either a filename or a Python file-like object.
This function only supports loading "basic" image format, ie BMP format. This function is always available, no matter how pygame was built.
Load an image from a file source. You can pass either a filename or a Python file-like object.
Pygame will automatically determine the image type (e.g., GIF or bitmap) and create a new Surface object from the data. In some cases it will need to know the file extension (e.g., GIF images should end in ".gif"). If you pass a raw file-like object, you may also want to pass the original filename as the namehint argument.
The returned Surface will contain the same color format, colorkey and alpha transparency as the file it came from. You will often want to call Surface.convert() with no arguments, to create a copy that will draw more quickly on the screen.
For alpha transparency, like in .png images, use the convert_alpha() method after loading so that the image has per pixel transparency.
pygame may not always be built to support all image formats. At minimum it will support uncompressed BMP. If pygame.image.get_extended() returns 'True', you should be able to load most images (including PNG, JPG and GIF).
You should use os.path.join() for compatibility.
This function is similar to pygame.image.load(), except that this function can only be used if pygame was built with extended image format support.
From version 2.0.1, this function is always available, but raises an error if extended image formats are not supported. Previously, this function may or may not be available, depending on the state of extended image format support.
Changed in pygame 2.0.1.
This will save your Surface as either a BMP, TGA, PNG, or JPEG image. If the filename extension is unrecognized it will default to TGA. Both TGA, and BMP file formats create uncompressed files. You can pass a filename or a Python file-like object. For file-like object, the image is saved to TGA format unless a namehint with a recognizable extension is passed in.
Note
To be able to save the JPEG file format to a file-like object, SDL2_Image version 2.0.2 or newer is needed.
Note
When saving to a file-like object, it seems that for most formats, the object needs to be flushed after saving to it to make loading from it possible.
Changed in pygame 1.8: Saving PNG and JPEG files.
Changed in pygame 2.0.0.dev11: The namehint parameter was added to make it possible to save other formats than TGA to a file-like object.
This will save your Surface as either a PNG or JPEG image.
Incase the image is being saved to a file-like object, this function uses the namehint argument to determine the format of the file being saved. Saves to JPEG incase the namehint was not specified while saving to file-like object.
From version 2.0.1, this function is always available, but raises an error if extended image formats are not supported. Previously, this function may or may not be available, depending on the state of extended image format support.
Changed in pygame 2.0.1.
If pygame is built with extended image formats, then this function will return the SDL_Image library's version number as a tuple of 3 integers (major, minor, patch). If not, then it will return None.
New in pygame 2.0.0.dev11.
If pygame is built with extended image formats this function will return True. It is still not possible to determine which formats will be available, but generally you will be able to load them all.
Creates a string that can be transferred with the 'fromstring' method in other Python imaging packages. Some Python image packages prefer their images in bottom-to-top format (PyOpenGL for example). If you pass True for the flipped argument, the string buffer will be vertically flipped.
The format argument is a string of one of the following values. Note that only 8-bit Surfaces can use the "P" format. The other formats will work for any Surface. Also note that other Python image packages support more formats than pygame.
This function takes arguments similar to pygame.image.tostring(). The size argument is a pair of numbers representing the width and height. Once the new Surface is created you can destroy the string buffer.
The size and format image must compute the exact same size as the passed string buffer. Otherwise an exception will be raised.
See the pygame.image.frombuffer() method for a potentially faster way to transfer images into pygame.
Create a new Surface that shares pixel data directly from a bytes buffer. This method takes similar arguments to pygame.image.fromstring(), but is unable to vertically flip the source data.
This will run much faster than pygame.image.fromstring(), since no pixel data must be allocated and copied.
It accepts the following 'format' arguments:


Create a new Surface that shares pixel data directly from a bytes buffer. This method takes similar arguments to pygame.image.fromstring(), but is unable to vertically flip the source data.
This will run much faster than pygame.image.fromstring(), since no pixel data must be allocated and copied.
It accepts the following 'format' arguments:


This function takes arguments similar to pygame.image.tostring(). The size argument is a pair of numbers representing the width and height. Once the new Surface is created you can destroy the string buffer.
The size and format image must compute the exact same size as the passed string buffer. Otherwise an exception will be raised.
See the pygame.image.frombuffer() method for a potentially faster way to transfer images into pygame.


If pygame is built with extended image formats this function will return True. It is still not possible to determine which formats will be available, but generally you will be able to load them all.


If pygame is built with extended image formats, then this function will return the SDL_Image library's version number as a tuple of 3 integers (major, minor, patch). If not, then it will return None.
New in pygame 2.0.0.dev11.


Load an image from a file source. You can pass either a filename or a Python file-like object.
Pygame will automatically determine the image type (e.g., GIF or bitmap) and create a new Surface object from the data. In some cases it will need to know the file extension (e.g., GIF images should end in ".gif"). If you pass a raw file-like object, you may also want to pass the original filename as the namehint argument.
The returned Surface will contain the same color format, colorkey and alpha transparency as the file it came from. You will often want to call Surface.convert() with no arguments, to create a copy that will draw more quickly on the screen.
For alpha transparency, like in .png images, use the convert_alpha() method after loading so that the image has per pixel transparency.
pygame may not always be built to support all image formats. At minimum it will support uncompressed BMP. If pygame.image.get_extended() returns 'True', you should be able to load most images (including PNG, JPG and GIF).
You should use os.path.join() for compatibility.


Load an image from a file source. You can pass either a filename or a Python file-like object.
This function only supports loading "basic" image format, ie BMP format. This function is always available, no matter how pygame was built.


This function is similar to pygame.image.load(), except that this function can only be used if pygame was built with extended image format support.
From version 2.0.1, this function is always available, but raises an error if extended image formats are not supported. Previously, this function may or may not be available, depending on the state of extended image format support.
Changed in pygame 2.0.1.


This will save your Surface as either a BMP, TGA, PNG, or JPEG image. If the filename extension is unrecognized it will default to TGA. Both TGA, and BMP file formats create uncompressed files. You can pass a filename or a Python file-like object. For file-like object, the image is saved to TGA format unless a namehint with a recognizable extension is passed in.
Note
To be able to save the JPEG file format to a file-like object, SDL2_Image version 2.0.2 or newer is needed.
Note
When saving to a file-like object, it seems that for most formats, the object needs to be flushed after saving to it to make loading from it possible.
Changed in pygame 1.8: Saving PNG and JPEG files.
Changed in pygame 2.0.0.dev11: The namehint parameter was added to make it possible to save other formats than TGA to a file-like object.


This will save your Surface as either a PNG or JPEG image.
Incase the image is being saved to a file-like object, this function uses the namehint argument to determine the format of the file being saved. Saves to JPEG incase the namehint was not specified while saving to file-like object.
From version 2.0.1, this function is always available, but raises an error if extended image formats are not supported. Previously, this function may or may not be available, depending on the state of extended image format support.
Changed in pygame 2.0.1.


Creates a string that can be transferred with the 'fromstring' method in other Python imaging packages. Some Python image packages prefer their images in bottom-to-top format (PyOpenGL for example). If you pass True for the flipped argument, the string buffer will be vertically flipped.
The format argument is a string of one of the following values. Note that only 8-bit Surfaces can use the "P" format. The other formats will work for any Surface. Also note that other Python image packages support more formats than pygame.


Initialize all imported pygame modules. No exceptions will be raised if a module fails, but the total number if successful and failed inits will be returned as a tuple. You can always initialize individual modules manually, but pygame.init() is a convenient way to get everything started. The init() functions for individual modules will raise exceptions when they fail.
You may want to initialize the different modules separately to speed up your program or to not use modules your game does not require.
It is safe to call this init() more than once as repeated calls will have no effect. This is true even if you have pygame.quit() all the modules.


The joystick module manages the joystick devices on a computer. Joystick devices include trackballs and video-game-style gamepads, and the module allows the use of multiple buttons and "hats". Computers may manage multiple joysticks at a time.
Each instance of the Joystick class represents one gaming device plugged into the computer. If a gaming pad has multiple joysticks on it, than the joystick object can actually represent multiple joysticks on that single game device.
For a quick way to initialise the joystick module and get a list of Joystick instances use the following code:
The following event types will be generated by the joysticks
And in pygame 2, which supports hotplugging:
Note that in pygame 2, joysticks events use a unique "instance ID". The device index passed in the constructor to a Joystick object is not unique after devices have been added and removed. You must call Joystick.get_instance_id() to find the instance ID that was assigned to a Joystick on opening.
The event queue needs to be pumped frequently for some of the methods to work. So call one of pygame.event.get, pygame.event.wait, or pygame.event.pump regularly.
This function is called automatically by pygame.init().
It initializes the joystick module. The module must be initialized before any other functions will work.
It is safe to call this function more than once.
Uninitialize the joystick module. After you call this any existing joystick objects will no longer work.
It is safe to call this function more than once.
Test if the pygame.joystick.init() function has been called.
Return the number of joystick devices on the system. The count will be 0 if there are no joysticks on the system.
When you create Joystick objects using Joystick(id), you pass an integer that must be lower than this count.
Create a new joystick to access a physical device. The id argument must be a value from 0 to pygame.joystick.get_count() - 1.
Joysticks are initialised on creation and are shut down when deallocated. Once the device is initialized the pygame event queue will start receiving events about its input.
Changed in pygame 2.0.0: Joystick objects are now opened immediately on creation.
Initialize the joystick, if it has been closed. It is safe to call this even if the joystick is already initialized.
Deprecated since pygame 2.0.0: In future it will not be possible to reinitialise a closed Joystick object. Will be removed in Pygame 2.1.
Close a Joystick object. After this the pygame event queue will no longer receive events from the device.
It is safe to call this more than once.
Return True if the Joystick object is currently initialised.
Returns the original device index for this device. This is the same value that was passed to the Joystick() constructor. This method can safely be called while the Joystick is not initialized.
Deprecated since pygame 2.0.0: The original device index is not useful in pygame 2. Use get_instance_id() instead. Will be removed in Pygame 2.1.
Get the joystick instance ID. This matches the instance_id field that is given in joystick events.
New in pygame 2.0.0dev11.
Get the GUID string. This identifies the exact hardware of the joystick device.
New in pygame 2.0.0dev11.
Get a string giving the power status of the device.
One of: empty, low, medium, full, wired, max, or unknown.
New in pygame 2.0.0dev11.
Returns the system name for this joystick device. It is unknown what name the system will give to the Joystick, but it should be a unique name that identifies the device. This method can safely be called while the Joystick is not initialized.
Returns the number of input axes are on a Joystick. There will usually be two for the position. Controls like rudders and throttles are treated as additional axes.
The pygame.JOYAXISMOTION events will be in the range from -1.0 to 1.0. A value of 0.0 means the axis is centered. Gamepad devices will usually be -1, 0, or 1 with no values in between. Older analog joystick axes will not always use the full -1 to 1 range, and the centered value will be some area around 0.
Analog joysticks usually have a bit of noise in their axis, which will generate a lot of rapid small motion events.
Returns the current position of a joystick axis. The value will range from -1 to 1 with a value of 0 being centered. You may want to take into account some tolerance to handle jitter, and joystick drift may keep the joystick from centering at 0 or using the full range of position values.
The axis number must be an integer from 0 to get_numaxes() - 1.
When using gamepads both the control sticks and the analog triggers are usually reported as axes.
Returns the number of trackball devices on a Joystick. These devices work similar to a mouse but they have no absolute position; they only have relative amounts of movement.
The pygame.JOYBALLMOTION event will be sent when the trackball is rolled. It will report the amount of movement on the trackball.
Returns the relative movement of a joystick button. The value is a x, y pair holding the relative movement since the last call to get_ball.
The ball number must be an integer from 0 to get_numballs() - 1.
Returns the number of pushable buttons on the joystick. These buttons have a boolean (on or off) state.
Buttons generate a pygame.JOYBUTTONDOWN and pygame.JOYBUTTONUP event when they are pressed and released.
Returns the current state of a joystick button.
Returns the number of joystick hats on a Joystick. Hat devices are like miniature digital joysticks on a joystick. Each hat has two axes of input.
The pygame.JOYHATMOTION event is generated when the hat changes position. The position attribute for the event contains a pair of values that are either -1, 0, or 1. A position of (0, 0) means the hat is centered.
Returns the current position of a position hat. The position is given as two values representing the x and y position for the hat. (0, 0) means centered. A value of -1 means left/down and a value of 1 means right/up: so (-1, 0) means left; (1, 0) means right; (0, 1) means up; (1, 1) means upper-right; etc.
This value is digital, i.e., each coordinate can be -1, 0 or 1 but never in-between.
The hat number must be between 0 and get_numhats() - 1.
Example code for joystick module.
Common Controller Axis Mappings
Controller mappings are drawn from the underlying SDL library which pygame uses and they differ between pygame 1 and pygame 2. Below are a couple of mappings for two popular game pads.
Pygame 2
Axis and hat mappings are listed from -1 to +1.
X-Box 360 Controller (name: "Xbox 360 Controller")
In pygame 2 the X360 controller mapping has 6 Axes, 11 buttons and 1 hat.
Left Stick:
Right Stick:
Left Trigger:
Right Trigger:
Buttons:
Hat/D-pad:
Playstation 4 Controller (name: "PS4 Controller")
In pygame 2 the PS4 controller mapping has 6 Axes and 16 buttons.
Left Stick:
Right Stick:
Left Trigger:
Right Trigger:
Buttons:
Pygame 1
Axis and hat mappings are listed from -1 to +1.
X-Box 360 Controller (name: "Controller (XBOX 360 For Windows)")
In pygame 1 the X360 controller mapping has 5 Axes, 10 buttons and 1 hat.
Left Stick:
Right Stick:
Left Trigger & Right Trigger:
Buttons:
Hat/D-pad:
Playstation 4 Controller (name: "Wireless Controller")
In pygame 1 the PS4 controller mapping has 6 Axes and 14 buttons and 1 hat.
Left Stick:
Right Stick:
Left Trigger:
Right Trigger:
Buttons:
Hat/D-pad:


Return the number of joystick devices on the system. The count will be 0 if there are no joysticks on the system.
When you create Joystick objects using Joystick(id), you pass an integer that must be lower than this count.


Test if the pygame.joystick.init() function has been called.


This function is called automatically by pygame.init().
It initializes the joystick module. The module must be initialized before any other functions will work.
It is safe to call this function more than once.


Create a new joystick to access a physical device. The id argument must be a value from 0 to pygame.joystick.get_count() - 1.
Joysticks are initialised on creation and are shut down when deallocated. Once the device is initialized the pygame event queue will start receiving events about its input.
Changed in pygame 2.0.0: Joystick objects are now opened immediately on creation.
Initialize the joystick, if it has been closed. It is safe to call this even if the joystick is already initialized.
Deprecated since pygame 2.0.0: In future it will not be possible to reinitialise a closed Joystick object. Will be removed in Pygame 2.1.
Close a Joystick object. After this the pygame event queue will no longer receive events from the device.
It is safe to call this more than once.
Return True if the Joystick object is currently initialised.
Returns the original device index for this device. This is the same value that was passed to the Joystick() constructor. This method can safely be called while the Joystick is not initialized.
Deprecated since pygame 2.0.0: The original device index is not useful in pygame 2. Use get_instance_id() instead. Will be removed in Pygame 2.1.
Get the joystick instance ID. This matches the instance_id field that is given in joystick events.
New in pygame 2.0.0dev11.
Get the GUID string. This identifies the exact hardware of the joystick device.
New in pygame 2.0.0dev11.
Get a string giving the power status of the device.
One of: empty, low, medium, full, wired, max, or unknown.
New in pygame 2.0.0dev11.
Returns the system name for this joystick device. It is unknown what name the system will give to the Joystick, but it should be a unique name that identifies the device. This method can safely be called while the Joystick is not initialized.
Returns the number of input axes are on a Joystick. There will usually be two for the position. Controls like rudders and throttles are treated as additional axes.
The pygame.JOYAXISMOTION events will be in the range from -1.0 to 1.0. A value of 0.0 means the axis is centered. Gamepad devices will usually be -1, 0, or 1 with no values in between. Older analog joystick axes will not always use the full -1 to 1 range, and the centered value will be some area around 0.
Analog joysticks usually have a bit of noise in their axis, which will generate a lot of rapid small motion events.
Returns the current position of a joystick axis. The value will range from -1 to 1 with a value of 0 being centered. You may want to take into account some tolerance to handle jitter, and joystick drift may keep the joystick from centering at 0 or using the full range of position values.
The axis number must be an integer from 0 to get_numaxes() - 1.
When using gamepads both the control sticks and the analog triggers are usually reported as axes.
Returns the number of trackball devices on a Joystick. These devices work similar to a mouse but they have no absolute position; they only have relative amounts of movement.
The pygame.JOYBALLMOTION event will be sent when the trackball is rolled. It will report the amount of movement on the trackball.
Returns the relative movement of a joystick button. The value is a x, y pair holding the relative movement since the last call to get_ball.
The ball number must be an integer from 0 to get_numballs() - 1.
Returns the number of pushable buttons on the joystick. These buttons have a boolean (on or off) state.
Buttons generate a pygame.JOYBUTTONDOWN and pygame.JOYBUTTONUP event when they are pressed and released.
Returns the current state of a joystick button.
Returns the number of joystick hats on a Joystick. Hat devices are like miniature digital joysticks on a joystick. Each hat has two axes of input.
The pygame.JOYHATMOTION event is generated when the hat changes position. The position attribute for the event contains a pair of values that are either -1, 0, or 1. A position of (0, 0) means the hat is centered.
Returns the current position of a position hat. The position is given as two values representing the x and y position for the hat. (0, 0) means centered. A value of -1 means left/down and a value of 1 means right/up: so (-1, 0) means left; (1, 0) means right; (0, 1) means up; (1, 1) means upper-right; etc.
This value is digital, i.e., each coordinate can be -1, 0 or 1 but never in-between.
The hat number must be between 0 and get_numhats() - 1.


Returns the current position of a joystick axis. The value will range from -1 to 1 with a value of 0 being centered. You may want to take into account some tolerance to handle jitter, and joystick drift may keep the joystick from centering at 0 or using the full range of position values.
The axis number must be an integer from 0 to get_numaxes() - 1.
When using gamepads both the control sticks and the analog triggers are usually reported as axes.


Returns the relative movement of a joystick button. The value is a x, y pair holding the relative movement since the last call to get_ball.
The ball number must be an integer from 0 to get_numballs() - 1.


Returns the current state of a joystick button.


Get the GUID string. This identifies the exact hardware of the joystick device.
New in pygame 2.0.0dev11.


Returns the current position of a position hat. The position is given as two values representing the x and y position for the hat. (0, 0) means centered. A value of -1 means left/down and a value of 1 means right/up: so (-1, 0) means left; (1, 0) means right; (0, 1) means up; (1, 1) means upper-right; etc.
This value is digital, i.e., each coordinate can be -1, 0 or 1 but never in-between.
The hat number must be between 0 and get_numhats() - 1.


Returns the original device index for this device. This is the same value that was passed to the Joystick() constructor. This method can safely be called while the Joystick is not initialized.
Deprecated since pygame 2.0.0: The original device index is not useful in pygame 2. Use get_instance_id() instead. Will be removed in Pygame 2.1.


Return True if the Joystick object is currently initialised.


Get the joystick instance ID. This matches the instance_id field that is given in joystick events.
New in pygame 2.0.0dev11.


Returns the system name for this joystick device. It is unknown what name the system will give to the Joystick, but it should be a unique name that identifies the device. This method can safely be called while the Joystick is not initialized.


Returns the number of input axes are on a Joystick. There will usually be two for the position. Controls like rudders and throttles are treated as additional axes.
The pygame.JOYAXISMOTION events will be in the range from -1.0 to 1.0. A value of 0.0 means the axis is centered. Gamepad devices will usually be -1, 0, or 1 with no values in between. Older analog joystick axes will not always use the full -1 to 1 range, and the centered value will be some area around 0.
Analog joysticks usually have a bit of noise in their axis, which will generate a lot of rapid small motion events.


Returns the number of trackball devices on a Joystick. These devices work similar to a mouse but they have no absolute position; they only have relative amounts of movement.
The pygame.JOYBALLMOTION event will be sent when the trackball is rolled. It will report the amount of movement on the trackball.


Returns the number of pushable buttons on the joystick. These buttons have a boolean (on or off) state.
Buttons generate a pygame.JOYBUTTONDOWN and pygame.JOYBUTTONUP event when they are pressed and released.


Returns the number of joystick hats on a Joystick. Hat devices are like miniature digital joysticks on a joystick. Each hat has two axes of input.
The pygame.JOYHATMOTION event is generated when the hat changes position. The position attribute for the event contains a pair of values that are either -1, 0, or 1. A position of (0, 0) means the hat is centered.


Get a string giving the power status of the device.
One of: empty, low, medium, full, wired, max, or unknown.
New in pygame 2.0.0dev11.


Initialize the joystick, if it has been closed. It is safe to call this even if the joystick is already initialized.
Deprecated since pygame 2.0.0: In future it will not be possible to reinitialise a closed Joystick object. Will be removed in Pygame 2.1.


Close a Joystick object. After this the pygame event queue will no longer receive events from the device.
It is safe to call this more than once.


Uninitialize the joystick module. After you call this any existing joystick objects will no longer work.
It is safe to call this function more than once.