sdl2.sdlgfx - Python bindings for SDL2_gfx

py-sdl2 provides bindings for SDL2_gfx, an unofficial addon library for SDL2 that contains a range of useful functions for rendering shapes, frame pacing, and SDL surface manipulation.

Note that unlike the other SDL2 modules supported by this package, SDL2_gfx is not an official part of the SDL2 project.

Framerate management classes and functions

class sdl2.sdlgfx.FPSManager[source]

A structure holding the state and timing of the framerate manager.

This class can be used with other SDL_gfx functions to set a custom framerate within a given rendering loop. When used with SDL_framerateDelay(), it uses its initial frame onset time (baseticks) and the duration per frame to try to present frames at consistent intervals from that initial point.

After an FPSManager is created, it needs to be initialized with SDL_initFramerate() before it can be used.

Note

This method of frame pacing may not play nicely with vsync in SDL2.

framecount

The number of frames counted by the manager since being initialized.

Type:int
rateticks

The time delay (in ms) between each frame.

Type:float
baseticks

The milliseconds since SDL initialization at which the manager was initialized with SDL_initFramerate(). Used internally as the initial frame onset time.

Type:int
lastticks

The milliseconds since SDL initialization at which the previous frame was displayed.

Type:int
rate

The framerate (in Hz) of the manager.

Type:int
sdl2.sdlgfx.SDL_initFramerate(manager)[source]

Initializes a framerate manager.

Calling this function on an FPSManager initializes it with a default framerate of 30 Hz and prepares it for counting and timing frames. If the manager was already initialized, calling this function will reset its framecount, initial frame onset time, and framerate.

Parameters:manager (sdlgfx.FPSManager) – The framerate manager to initialize.
sdl2.sdlgfx.SDL_setFramerate(manager, rate)[source]

Sets the framerate of a framerate manager.

Sets a new framerate for the manager, resetting both the framecount and the the initial frame onset time. Framerates must be between FPS_LOWER_LIMIT (1) and FPS_UPPER_LIMIT (200), inclusive, to be accepted.

Parameters:
  • manager (sdlgfx.FPSManager) – The framerate manager to configure.
  • rate (int) – The new framerate in Hz.
Returns:

0 on success, or -1 if an error occurred.

Return type:

int

sdl2.sdlgfx.SDL_getFramerate(manager)[source]

Gets the current framerate for a framerate manager.

Parameters:manager (sdlgfx.FPSManager) – The framerate manager for which the currently set framerate will be retrieved.
Returns:0 on success, or -1 if an error occurred.
Return type:int
sdl2.sdlgfx.SDL_getFramecount(manager)[source]

Gets the current number of frames counted by a framerate manager.

Note

This value is reset whenever a frame is dropped (i.e. the rendering loop takes longer than the set interval between frames) or the framerate is changed.

Parameters:manager (sdlgfx.FPSManager) – The framerate manager for which the current framecount will be retrieved.
Returns:0 on success, or -1 if an error occurred.
Return type:int
sdl2.sdlgfx.SDL_framerateDelay(manager)[source]

Delays execution until the next frame occurs.

This function waits for the next frame onset (as determined by the rate set by SDL_setFramerate()) to keep frame pacing consistent. This should be called once per loop within the program’s main rendering loop.

If the rendering loop takes longer than the set framerate, the delay will be zero and the framecount and initial frame onset time will be reset.

Parameters:manager (sdlgfx.FPSManager) – The framerate manager to use for frame pacing.
Returns:0 on success, or -1 if an error occurred.
Return type:int

Drawing functions

Pixel drawing functions

sdl2.sdlgfx.pixelColor(renderer, x, y, color)[source]

Draws a single pixel to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X (horizontal) coordinate of the pixel.
  • y (int) – The Y (vertical) coordinate of the pixel.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.pixelRGBA(renderer, x, y, r, g, b, a)[source]

Draws a single pixel to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X (horizontal) coordinate of the pixel.
  • y (int) – The Y (vertical) coordinate of the pixel.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

Line drawing functions

sdl2.sdlgfx.hlineColor(renderer, x1, x2, y, color)[source]

Draws a horizontal line to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the first point of the line.
  • x2 (int) – The X coordinate of the second point of the line.
  • y (int) – The Y (vertical) coordinate of the points of the line.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.hlineRGBA(renderer, x1, x2, y, r, g, b, a)[source]

Draws a horizontal line to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the first point of the line.
  • x2 (int) – The X coordinate of the second point of the line.
  • y (int) – The Y coordinate of the points of the line.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.vlineColor(renderer, x, y1, y2, color)[source]

Draws a vertical line to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the points of the line.
  • y1 (int) – The X coordinate of the first point of the line.
  • y2 (int) – The Y coordinate of the second point of the line.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.vlineRGBA(renderer, x, y1, y2, r, g, b, a)[source]

Draws a vertical line to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the points of the line.
  • y1 (int) – The X coordinate of the first point of the line.
  • y2 (int) – The Y coordinate of the second point of the line.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.lineColor(renderer, x1, y1, x2, y2, color)[source]

Draws a line to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the first point of the line.
  • y1 (int) – The Y coordinate of the first point of the line.
  • x2 (int) – The X coordinate of the second point of the line.
  • y2 (int) – The Y coordinate of the second point of the line.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.lineRGBA(renderer, x1, y1, x2, y2, r, g, b, a)[source]

Draws a line to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the first point of the line.
  • y1 (int) – The Y coordinate of the first point of the line.
  • x2 (int) – The X coordinate of the second point of the line.
  • y2 (int) – The Y coordinate of the second point of the line.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.aalineColor(renderer, x1, y1, x2, y2, color)[source]

Draws an anti-aliased line to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the first point of the line.
  • y1 (int) – The Y coordinate of the first point of the line.
  • x2 (int) – The X coordinate of the second point of the line.
  • y2 (int) – The Y coordinate of the second point of the line.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.aalineRGBA(renderer, x1, y1, x2, y2, r, g, b, a)[source]

Draws an anti-aliased line to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the first point of the line.
  • y1 (int) – The Y coordinate of the first point of the line.
  • x2 (int) – The X coordinate of the second point of the line.
  • y2 (int) – The Y coordinate of the second point of the line.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.thickLineColor(renderer, x1, y1, x2, y2, width, color)[source]

Draws a line with a given thickness to the renderer.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the first point of the line.
  • y1 (int) – The Y coordinate of the first point of the line.
  • x2 (int) – The X coordinate of the second point of the line.
  • y2 (int) – The Y coordinate of the second point of the line.
  • width (int) – The thickness of the line in pixels (from 1 to 255).
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.thickLineRGBA(renderer, x1, y1, x2, y2, width, r, g, b, a)[source]

Draws a line with a given thickness to the renderer.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the first point of the line.
  • y1 (int) – The Y coordinate of the first point of the line.
  • x2 (int) – The X coordinate of the second point of the line.
  • y2 (int) – The Y coordinate of the second point of the line.
  • width (int) – The thickness of the line in pixels (from 1 to 255).
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

Rectangle drawing functions

sdl2.sdlgfx.rectangleColor(renderer, x1, y1, x2, y2, color)[source]

Draws an unfilled rectangle to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the top-right point of the rectangle.
  • y1 (int) – The Y coordinate of the top-right point of the rectangle.
  • x2 (int) – The X coordinate of the bottom-left point of the rectangle.
  • y2 (int) – The Y coordinate of the bottom-left point of the rectangle.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.rectangleRGBA(renderer, x1, y1, x2, y2, r, g, b, a)[source]

Draws an unfilled rectangle to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the top-right point of the rectangle.
  • y1 (int) – The Y coordinate of the top-right point of the rectangle.
  • x2 (int) – The X coordinate of the bottom-left point of the rectangle.
  • y2 (int) – The Y coordinate of the bottom-left point of the rectangle.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.roundedRectangleColor(renderer, x1, y1, x2, y2, rad, color)[source]

Draws an unfilled rectangle with rounded corners to the renderer.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the top-right point of the rectangle.
  • y1 (int) – The Y coordinate of the top-right point of the rectangle.
  • x2 (int) – The X coordinate of the bottom-left point of the rectangle.
  • y2 (int) – The Y coordinate of the bottom-left point of the rectangle.
  • rad (int) – The radius of the arc of the rounded corners.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.roundedRectangleRGBA(renderer, x1, y1, x2, y2, rad, r, g, b, a)[source]

Draws an unfilled rectangle with rounded corners to the renderer.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the top-right point of the rectangle.
  • y1 (int) – The Y coordinate of the top-right point of the rectangle.
  • x2 (int) – The X coordinate of the bottom-left point of the rectangle.
  • y2 (int) – The Y coordinate of the bottom-left point of the rectangle.
  • rad (int) – The radius of the arc of the rounded corners.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.boxColor(renderer, x1, y1, x2, y2, color)[source]

Draws a filled rectangle to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the top-right point of the rectangle.
  • y1 (int) – The Y coordinate of the top-right point of the rectangle.
  • x2 (int) – The X coordinate of the bottom-left point of the rectangle.
  • y2 (int) – The Y coordinate of the bottom-left point of the rectangle.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.boxRGBA(renderer, x1, y1, x2, y2, r, g, b, a)[source]

Draws a filled rectangle to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the top-right point of the rectangle.
  • y1 (int) – The Y coordinate of the top-right point of the rectangle.
  • x2 (int) – The X coordinate of the bottom-left point of the rectangle.
  • y2 (int) – The Y coordinate of the bottom-left point of the rectangle.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.roundedBoxColor(renderer, x1, y1, x2, y2, rad, color)[source]

Draws a filled rectangle with rounded corners to the renderer.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the top-right point of the rectangle.
  • y1 (int) – The Y coordinate of the top-right point of the rectangle.
  • x2 (int) – The X coordinate of the bottom-left point of the rectangle.
  • y2 (int) – The Y coordinate of the bottom-left point of the rectangle.
  • rad (int) – The radius of the arc of the rounded corners.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.roundedBoxRGBA(renderer, x1, y1, x2, y2, rad, r, g, b, a)[source]

Draws a filled rectangle with rounded corners to the renderer.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – The X coordinate of the top-right point of the rectangle.
  • y1 (int) – The Y coordinate of the top-right point of the rectangle.
  • x2 (int) – The X coordinate of the bottom-left point of the rectangle.
  • y2 (int) – The Y coordinate of the bottom-left point of the rectangle.
  • rad (int) – The radius of the arc of the rounded corners.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

Circle drawing functions

sdl2.sdlgfx.circleColor(renderer, x, y, rad, color)[source]

Draws an unfilled circle to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the circle.
  • y (int) – The Y coordinate of the center of the circle.
  • rad (int) – The radius (in pixels) of the circle.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.circleRGBA(renderer, x, y, rad, r, g, b, a)[source]

Draws an unfilled circle to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the circle.
  • y (int) – The Y coordinate of the center of the circle.
  • rad (int) – The radius (in pixels) of the circle.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.arcColor(renderer, x, y, rad, start, end, color)[source]

Draws an arc to the renderer with a given color.

The start and end of the arc are defined in units of degrees, with 0 being the bottom of the arc circle and increasing counter-clockwise (e.g. 90 being the rightmost point of the circle).

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the circle.
  • y (int) – The Y coordinate of the center of the circle.
  • rad (int) – The radius (in pixels) of the circle.
  • start (int) – The start of the arc (in degrees).
  • end (int) – The end of the arc (in degrees).
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.arcRGBA(renderer, x, y, rad, start, end, r, g, b, a)[source]

Draws an arc to the renderer with a given color.

The start and end of the arc are defined in units of degrees, with 0 being the bottom of the arc circle and increasing counter-clockwise (e.g. 90 being the rightmost point of the circle).

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the circle.
  • y (int) – The Y coordinate of the center of the circle.
  • rad (int) – The radius (in pixels) of the circle.
  • start (int) – The start of the arc (in degrees).
  • end (int) – The end of the arc (in degrees).
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.aacircleColor(renderer, x, y, rad, color)[source]

Draws an anti-aliased unfilled circle to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the circle.
  • y (int) – The Y coordinate of the center of the circle.
  • rad (int) – The radius (in pixels) of the circle.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.aacircleRGBA(renderer, x, y, rad, r, g, b, a)[source]

Draws an anti-aliased unfilled circle to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the circle.
  • y (int) – The Y coordinate of the center of the circle.
  • rad (int) – The radius (in pixels) of the circle.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.filledCircleColor(renderer, x, y, rad, color)[source]

Draws a filled circle to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the circle.
  • y (int) – The Y coordinate of the center of the circle.
  • rad (int) – The radius (in pixels) of the circle.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.filledCircleRGBA(renderer, x, y, rad, r, g, b, a)[source]

Draws a filled circle to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the circle.
  • y (int) – The Y coordinate of the center of the circle.
  • rad (int) – The radius (in pixels) of the circle.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

Ellipse drawing functions

sdl2.sdlgfx.ellipseColor(renderer, x, y, rx, ry, color)[source]

Draws an unfilled ellipse to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the ellipse.
  • y (int) – The Y coordinate of the center of the ellipse.
  • rx (int) – The x-axis radius (i.e. width) of the ellipse.
  • ry (int) – The y-axis radius (i.e. height) of the ellipse.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.ellipseRGBA(renderer, x, y, rx, ry, r, g, b, a)[source]

Draws an unfilled ellipse to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the ellipse.
  • y (int) – The Y coordinate of the center of the ellipse.
  • rx (int) – The x-axis radius (i.e. width) of the ellipse.
  • ry (int) – The y-axis radius (i.e. height) of the ellipse.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.aaellipseColor(renderer, x, y, rx, ry, color)[source]

Draws an anti-aliased unfilled ellipse to the renderer in a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the ellipse.
  • y (int) – The Y coordinate of the center of the ellipse.
  • rx (int) – The x-axis radius (i.e. width) of the ellipse.
  • ry (int) – The y-axis radius (i.e. height) of the ellipse.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.aaellipseRGBA(renderer, x, y, rx, ry, r, g, b, a)[source]

Draws an anti-aliased unfilled ellipse to the renderer in a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the ellipse.
  • y (int) – The Y coordinate of the center of the ellipse.
  • rx (int) – The x-axis radius (i.e. width) of the ellipse.
  • ry (int) – The y-axis radius (i.e. height) of the ellipse.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.filledEllipseColor(renderer, x, y, rx, ry, color)[source]

Draws a filled ellipse to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the ellipse.
  • y (int) – The Y coordinate of the center of the ellipse.
  • rx (int) – The x-axis radius (i.e. width) of the ellipse.
  • ry (int) – The y-axis radius (i.e. height) of the ellipse.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.filledEllipseRGBA(renderer, x, y, rx, ry, r, g, b, a)[source]

Draws a filled ellipse to the renderer with a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the ellipse.
  • y (int) – The Y coordinate of the center of the ellipse.
  • rx (int) – The x-axis radius (i.e. width) of the ellipse.
  • ry (int) – The y-axis radius (i.e. height) of the ellipse.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

Pie slice drawing functions

sdl2.sdlgfx.pieColor(renderer, x, y, rad, start, end, color)[source]

Draws an unfilled pie slice (i.e. circle segment) to the renderer.

The start and end of the pie are defined in units of degrees, with 0 being the bottom of the circle and increasing counter-clockwise (e.g. 90 being the rightmost point of the circle).

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the pie (circle).
  • y (int) – The Y coordinate of the center of the pie (circle).
  • rad (int) – The radius (in pixels) of the pie.
  • start (int) – Start of the pie slice (in degrees).
  • end (int) – End of the pie slice (in degrees)
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.pieRGBA(renderer, x, y, rad, start, end, r, g, b, a)[source]

Draws an unfilled pie slice (i.e. circle segment) to the renderer.

The start and end of the pie are defined in units of degrees, with 0 being the bottom of the circle and increasing counter-clockwise (e.g. 90 being the rightmost point of the circle).

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the pie (circle).
  • y (int) – The Y coordinate of the center of the pie (circle).
  • rad (int) – The radius (in pixels) of the pie.
  • start (int) – Start of the pie slice (in degrees).
  • end (int) – End of the pie slice (in degrees)
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.filledPieColor(renderer, x, y, rad, start, end, color)[source]

Draws a filled pie slice (i.e. circle segment) to the renderer.

The start and end of the pie are defined in units of degrees, with 0 being the bottom of the circle and increasing counter-clockwise (e.g. 90 being the rightmost point of the circle).

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the pie (circle).
  • y (int) – The Y coordinate of the center of the pie (circle).
  • rad (int) – The radius (in pixels) of the pie.
  • start (int) – Start of the pie slice (in degrees).
  • end (int) – End of the pie slice (in degrees)
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.filledPieRGBA(renderer, x, y, rad, start, end, r, g, b, a)[source]

Draws a filled pie slice (i.e. circle segment) to the renderer.

The start and end of the pie are defined in units of degrees, with 0 being the bottom of the circle and increasing counter-clockwise (e.g. 90 being the rightmost point of the circle).

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the center of the pie (circle).
  • y (int) – The Y coordinate of the center of the pie (circle).
  • rad (int) – The radius (in pixels) of the pie.
  • start (int) – Start of the pie slice (in degrees).
  • end (int) – End of the pie slice (in degrees)
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

Triangle drawing functions

sdl2.sdlgfx.trigonColor(renderer, x1, y1, x2, y2, x3, y3, color)[source]

Draws a trigon (i.e. triangle outline) to the renderer in a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – X coordinate of the first point of the triangle.
  • y1 (int) – Y coordinate of the first point of the triangle.
  • x2 (int) – X coordinate of the second point of the triangle.
  • y2 (int) – Y coordinate of the second point of the triangle.
  • x3 (int) – X coordinate of the third point of the triangle.
  • y3 (int) – Y coordinate of the third point of the triangle.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.trigonRGBA(renderer, x1, y1, x2, y2, x3, y3, r, g, b, a)[source]

Draws a trigon (i.e. triangle outline) to the renderer in a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – X coordinate of the first point of the triangle.
  • y1 (int) – Y coordinate of the first point of the triangle.
  • x2 (int) – X coordinate of the second point of the triangle.
  • y2 (int) – Y coordinate of the second point of the triangle.
  • x3 (int) – X coordinate of the third point of the triangle.
  • y3 (int) – Y coordinate of the third point of the triangle.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.aatrigonColor(renderer, x1, y1, x2, y2, x3, y3, color)[source]

Draws an anti-aliased trigon (i.e. triangle outline) to the renderer.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – X coordinate of the first point of the triangle.
  • y1 (int) – Y coordinate of the first point of the triangle.
  • x2 (int) – X coordinate of the second point of the triangle.
  • y2 (int) – Y coordinate of the second point of the triangle.
  • x3 (int) – X coordinate of the third point of the triangle.
  • y3 (int) – Y coordinate of the third point of the triangle.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.aatrigonRGBA(renderer, x1, y1, x2, y2, x3, y3, r, g, b, a)[source]

Draws an anti-aliased trigon (i.e. triangle outline) to the renderer.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – X coordinate of the first point of the triangle.
  • y1 (int) – Y coordinate of the first point of the triangle.
  • x2 (int) – X coordinate of the second point of the triangle.
  • y2 (int) – Y coordinate of the second point of the triangle.
  • x3 (int) – X coordinate of the third point of the triangle.
  • y3 (int) – Y coordinate of the third point of the triangle.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.filledTrigonColor(renderer, x1, y1, x2, y2, x3, y3, color)[source]

Draws a filled triangle to the renderer in a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – X coordinate of the first point of the triangle.
  • y1 (int) – Y coordinate of the first point of the triangle.
  • x2 (int) – X coordinate of the second point of the triangle.
  • y2 (int) – Y coordinate of the second point of the triangle.
  • x3 (int) – X coordinate of the third point of the triangle.
  • y3 (int) – Y coordinate of the third point of the triangle.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.filledTrigonRGBA(renderer, x1, y1, x2, y2, x3, y3, r, g, b, a)[source]

Draws a filled triangle to the renderer in a given color.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x1 (int) – X coordinate of the first point of the triangle.
  • y1 (int) – Y coordinate of the first point of the triangle.
  • x2 (int) – X coordinate of the second point of the triangle.
  • y2 (int) – Y coordinate of the second point of the triangle.
  • x3 (int) – X coordinate of the third point of the triangle.
  • y3 (int) – Y coordinate of the third point of the triangle.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

Polygon drawing functions

sdl2.sdlgfx.polygonColor(renderer, vx, vy, n, color)[source]

Draws an unfilled polygon to the renderer in a given color.

Vertices are specified as ctypes.c_int16 arrays, with two arrays of equal size defining the x and y coordinates of the points making up the polygon. To create these vertex arrays in Python, you can create lists and cast them to ctypes arrays which can be passed directly to the function:

x_coords = [5, 5, 15, 15]
y_coords = [5, 10, 10, 5]
vx = (ctypes.c_int16 * len(x_coords))(*x_coords)
vy = (ctypes.c_int16 * len(y_coords))(*y_coords)

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • vx (POINTER(c_int16)) – Array containing the X coordinates of the polygon’s vertices.
  • vx – Array containing the Y coordinates of the polygon’s vertices.
  • n (int) – The number of vertices in the polygon.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.polygonRGBA(renderer, vx, vy, n, r, g, b, a)[source]

Draws an unfilled polygon to the renderer in a given color.

See polygonColor() for more information on usage.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • vx (POINTER(c_int16)) – Array containing the X coordinates of the polygon’s vertices.
  • vx – Array containing the Y coordinates of the polygon’s vertices.
  • n (int) – The number of vertices in the polygon.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.aapolygonColor(renderer, vx, vy, n, color)[source]

Draws an anti-aliased unfilled polygon to the renderer in a given color.

See polygonColor() for more information on usage.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • vx (POINTER(c_int16)) – Array containing the X coordinates of the polygon’s vertices.
  • vx – Array containing the Y coordinates of the polygon’s vertices.
  • n (int) – The number of vertices in the polygon.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.aapolygonRGBA(renderer, vx, vy, n, r, g, b, a)[source]

Draws an anti-aliased unfilled polygon to the renderer in a given color.

See polygonColor() for more information on usage.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • vx (POINTER(c_int16)) – Array containing the X coordinates of the polygon’s vertices.
  • vx – Array containing the Y coordinates of the polygon’s vertices.
  • n (int) – The number of vertices in the polygon.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.filledPolygonColor(renderer, vx, vy, n, color)[source]

Draws a filled polygon to the renderer in a given color.

See polygonColor() for more information on usage.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • vx (POINTER(c_int16)) – Array containing the X coordinates of the polygon’s vertices.
  • vx – Array containing the Y coordinates of the polygon’s vertices.
  • n (int) – The number of vertices in the polygon.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.filledPolygonRGBA(renderer, vx, vy, n, r, g, b, a)[source]

Draws a filled polygon to the renderer in a given color.

See polygonColor() for more information on usage.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • vx (POINTER(c_int16)) – Array containing the X coordinates of the polygon’s vertices.
  • vx – Array containing the Y coordinates of the polygon’s vertices.
  • n (int) – The number of vertices in the polygon.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.texturedPolygon(renderer, vx, vy, n, texture, texture_dx, texture_dy)[source]

Draws a polygon to the renderer with a given texture.

The location of the texture is relative to the top-left corner of the renderer, as opposed to being relative to the polygon itself. As such, both the vertex coordinates and texture coordinates need to be adjusted equally to render a polygon with the same texture placement at a different location.

The texture must be associated with the same renderer used to draw the polygon.

See polygonColor() for more information on usage.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • vx (POINTER(c_int16)) – Array containing the X coordinates of the polygon’s vertices.
  • vx – Array containing the Y coordinates of the polygon’s vertices.
  • n (int) – The number of vertices in the polygon.
  • texture (SDL_Texture) – The texture with which to fill the polygon.
  • texture_dx (int) – The X offset of the texture relative to the top-left corner of the renderer.
  • texture_dy (int) – The Y offset of the texture relative to the top-left corner of the renderer.
Returns:

0 on success, or -1 on failure.

Return type:

int

Bezier curve drawing functions

sdl2.sdlgfx.bezierColor(renderer, vx, vy, n, s, color)[source]

Draws a Bezier curve to the renderer in a given color.

The first and last vertex are the start and end points of the Bezier, respectively, with the points in between defining the control points of the curve. For example, a 3rd order (i.e. cubic) Bezier would be defined using 4 vertices, with the two middle vertices being the control points.

See polygonColor() for more information on creating the vertex arrays for this function.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • vx (POINTER(c_int16)) – Array containing the X coordinates of the points of the Bezier curve.
  • vx – Array containing the Y coordinates of the points of the Bezier curve.
  • n (int) – The number of points in the bezier curve (minimum of 3).
  • s (int) – The number of interpolation steps to use when drawing the curve (minimum of 2). The higher the value, the smoother the curve.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.bezierRGBA(renderer, vx, vy, n, s, r, g, b, a)[source]

Draws a Bezier curve to the renderer in a given color.

See bezierColor() for more details on usage.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • vx (POINTER(c_int16)) – Array containing the X coordinates of the points of the Bezier curve.
  • vx – Array containing the Y coordinates of the points of the Bezier curve.
  • n (int) – The number of points in the bezier curve (minimum of 3).
  • s (int) – The number of interpolation steps to use when drawing the curve (minimum of 2). The higher the value, the smoother the curve.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

Text rendering functions

sdl2.sdlgfx.gfxPrimitivesSetFont(fontdata, cw, ch)[source]

Sets or resets the current global GFX font.

The SDL_gfx library uses its own special format for bitmap fonts. Basically, fonts are byte arrays where each glyph is made up of the same number of bytes (as defined by the cw and ch arguments). The bytes are used as a binary bitmask with 1s indicating the pixels of the character and 0s indicating the transparent background. For example, the following is the definition of the capital H glyph in the default font:

/*
* 72 0x48 'H'
*/
0xc6,                    /* 11000110 */
0xc6,                    /* 11000110 */
0xc6,                    /* 11000110 */
0xfe,                    /* 11111110 */
0xc6,                    /* 11000110 */
0xc6,                    /* 11000110 */
0xc6,                    /* 11000110 */
0x00,                    /* 00000000 */

Each font must contain glyphs for all 256 ASCII characters. Since this is a pretty painful format for defining your own fonts, you can load and use any of the predefined SDL_gfx fonts from the following link: https://github.com/ferzkopp/SDL_gfx/tree/master/Fonts

If no font has been set, SDL_gfx defaults to rendering with a built-in 8x8 pixel font.

Note

If anyone comes up with a way of converting standard bitmap fonts into the SDL_gfx format, please let us know! That would be incredibly cool and handy.

Parameters:
  • fontdata (c_void_p) – A pointer to the start of the array containing the new global font data, or a null pointer to reset the global font to the default 8x8 font.
  • cw (int) – The width (in bytes) of each character of the font. Ignored if fontdata is null.
  • ch (int) – The height (in bytes) of each character of the font. Ignored if fontdata is null.
sdl2.sdlgfx.gfxPrimitivesSetFontRotation(rotation)[source]

Sets the global character rotation for GFX font rendering.

Characters can only be rotated in 90 degree increments. Calling this function will reset the character cache.

Parameters:rotation (int) – The number of clockwise 90-degree rotations to apply to font characters when rendering text.
sdl2.sdlgfx.characterColor(renderer, x, y, c, color)[source]

Draws a single character with the current GFX font to the renderer.

Python characters can be converted to ASCII integers for use with this function using the built-in ord() function (e.g. ord(u"A")).

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the upper-left corner of the character.
  • y (int) – The Y coordinate of the upper-left corner of the character.
  • c (int) – The ASCII number (from 0 to 255) of the character.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.characterRGBA(renderer, x, y, c, r, g, b, a)[source]

Draws a single character with the current GFX font to the renderer.

See characterColor() for more usage information.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the upper-left corner of the character.
  • y (int) – The Y coordinate of the upper-left corner of the character.
  • c (int) – The ASCII number (from 0 to 255) of the character.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.stringColor(renderer, x, y, s, color)[source]

Draws an ASCII string with the current GFX font to the renderer.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the upper-left corner of the string.
  • y (int) – The Y coordinate of the upper-left corner of the string.
  • s (bytes) – The ASCII-encoded bytestring of text to render.
  • color (int) – The color to draw with as a 32-bit 0xRRGGBBAA integer (e.g. 0xFF0000FF for solid red).
Returns:

0 on success, or -1 on failure.

Return type:

int

sdl2.sdlgfx.stringRGBA(renderer, x, y, s, r, g, b, a)[source]

Draws an ASCII string with the current GFX font to the renderer.

If the rendering color has any transparency, blending will be enabled.

Parameters:
  • renderer (SDL_Renderer) – The renderer to draw on.
  • x (int) – The X coordinate of the upper-left corner of the string.
  • y (int) – The Y coordinate of the upper-left corner of the string.
  • s (bytes) – The ASCII-encoded bytestring of text to render.
  • r (int) – The red value (from 0 to 255) of the color to draw with.
  • g (int) – The green value (from 0 to 255) of the color to draw with.
  • b (int) – The blue value (from 0 to 255) of the color to draw with.
  • a (int) – The alpha value (from 0 to 255) of the color to draw with.
Returns:

0 on success, or -1 on failure.

Return type:

int

Surface rotation and scaling functions

sdl2.sdlgfx.rotozoomSurface(src, angle, zoom, smooth)[source]

Rotates & zooms a surface.

Rotates and zooms an SDL_Surface to a new output surface, with optional anti-aliasing. If the surface is not 8-bit or 32-bit RGBA/ABGR, it will be converted into a 32-bit RGBA format on the fly.

Parameters:
  • src (SDL_Surface) – The surface to rotate and zoom.
  • angle (float) – The angle to rotate the surface (in degrees).
  • zoom (float) – The scaling factor for the surface.
  • smooth (int) – If set to 1, the output image will be anti-aliased. If set to 0, no anti-aliasing will be performed. Must be either 0 or 1.
Returns:

A new output surface with zoom & rotation applied.

Return type:

SDL_Surface

sdl2.sdlgfx.rotozoomSurfaceXY(src, angle, zoomx, zoomy, smooth)[source]

Rotates & zooms a surface with different x & y scaling factors.

Rotates and zooms an SDL_Surface to a new output surface, with optional anti-aliasing. If the surface is not 8-bit or 32-bit RGBA/ABGR, it will be converted into a 32-bit RGBA format on the fly.

Parameters:
  • src (SDL_Surface) – The surface to rotate and zoom.
  • angle (float) – The angle to rotate the surface (in degrees).
  • zoomx (float) – The x-axis (horizontal) scaling factor.
  • zoomy (float) – The y-axis (vertical) scaling factor.
  • smooth (int) – If set to 1, the output image will be anti-aliased. If set to 0, no anti-aliasing will be performed. Must be either 0 or 1.
Returns:

A new output surface with zoom & rotation applied.

Return type:

SDL_Surface

sdl2.sdlgfx.rotozoomSurfaceSize(width, height, angle, zoom, dstwidth, dstheight)[source]

Returns the output surface size of a rotozoomSurface() call.

This function outputs the calculated height and width by reference to the dstwidth and dstheight arguments, and does not return any value itself.

Parameters:
  • width (int) – The width (in pixels) of the source surface.
  • height (int) – The height (in pixels) of the source surface.
  • angle (float) – The angle to rotate the surface (in degrees).
  • zoom (float) – The scaling factor for the surface.
  • dstwidth (byref(c_int)) – A reference to the ctypes int where the calculated width of the output surface will be stored.
  • dstheight (byref(c_int)) – A reference to the ctypes int where the calculated height of the output surface will be stored.
sdl2.sdlgfx.rotozoomSurfaceSizeXY(width, height, angle, zoomx, zoomy, dstwidth, dstheight)[source]

Returns the output surface size of a rotozoomSurfaceXY() call.

This function outputs the calculated height and width by reference to the dstwidth and dstheight arguments, and does not return any value itself.

Parameters:
  • width (int) – The width (in pixels) of the source surface.
  • height (int) – The height (in pixels) of the source surface.
  • angle (float) – The angle to rotate the surface (in degrees).
  • zoomx (float) – The x-axis (horizontal) scaling factor.
  • zoomy (float) – The y-axis (vertical) scaling factor.
  • dstwidth (byref(c_int)) – A reference to the ctypes int where the calculated width of the output surface will be stored.
  • dstheight (byref(c_int)) – A reference to the ctypes int where the calculated height of the output surface will be stored.
sdl2.sdlgfx.zoomSurface(src, zoomx, zoomy, smooth)[source]

Zooms a surface with different x & y scaling factors.

This function renders to a new surface, with optional anti-aliasing. If a zoom factor is negative, the image will be flipped along that axis. If the surface is not 8-bit or 32-bit RGBA/ABGR, it will be converted into a 32-bit RGBA format on the fly.

Parameters:
  • src (SDL_Surface) – The surface to zoom.
  • zoomx (float) – The x-axis (horizontal) zoom factor.
  • zoomy (float) – The y-axis (vertical) zoom factor.
  • smooth (int) – If set to 1, the output image will be anti-aliased. If set to 0, no anti-aliasing will be performed. Must be either 0 or 1.
Returns:

A new output surface with zoom applied.

Return type:

SDL_Surface

sdl2.sdlgfx.zoomSurfaceSize(width, height, zoomx, zoomy, dstwidth, dstheight)[source]

Returns the output surface size of a zoomSurface() call.

This function outputs the calculated height and width by reference to the dstwidth and dstheight arguments, and does not return any value itself.

Parameters:
  • width (int) – The width (in pixels) of the source surface.
  • height (int) – The height (in pixels) of the source surface.
  • zoomx (float) – The x-axis (horizontal) scaling factor.
  • zoomy (float) – The y-axis (vertical) scaling factor.
  • dstwidth (byref(c_int)) – A reference to the ctypes int where the calculated width of the output surface will be stored.
  • dstheight (byref(c_int)) – A reference to the ctypes int where the calculated height of the output surface will be stored.
sdl2.sdlgfx.shrinkSurface(src, factorx, factory)[source]

Shrinks a surface by an integer ratio using averaging.

This function renders to a new surface, meaning that the original surface is not modified. The output surface is anti-aliased by averaging the source RGBA information. If the surface is not 8-bit or 32-bit RGBA/ABGR, it will be converted into a 32-bit RGBA format on the fly.

Parameters:
  • src (SDL_Surface) – The surface to zoom.
  • factorx (int) – The x-axis (horizontal) shrink factor (e.g. 2 = 2x smaller).
  • factory (int) – The y-axis (vertical) shrink factor (e.g. 2 = 2x smaller).
Returns:

The new shrunken surface.

Return type:

SDL_Surface

sdl2.sdlgfx.rotateSurface90Degrees(src, numClockwiseTurns)[source]

Rotates an SDL surface clockwise in increments of 90 degrees.

Faster than rotozoomer since no scanning or interpolation takes place. Input surface must be 8-bit, 16-bit, 24-bit, or 32-bit.

Parameters:
  • src (SDL_Surface) – The source surface to rotate.
  • numClockwiseTurns (int) – The number of clockwise 90 degree rotations to apply to the source.
Returns:

The new rotated surface, or None if the source surface was not a compatible format.

Return type:

SDL_Surface