pygraphics

pygraphics

pygraphics — cross-platform 2D drawing for *Python.

Extends MicroPython's framebuf with shape helpers, fonts, image loaders, and Area bounding boxes for partial updates. On CPython and CircuitPython the built-in pure-Python framebuf fallback is used automatically.

Framebuffer format constants (FrameBuffer format argument):

• MONO_VLSB, MONO_HLSB, MONO_HMSB — 1-bit monochrome
• GS2_HMSB, GS4_HMSB, GS8 — 2-, 4-, and 8-bit greyscale
• RGB565 — 16-bit color (MicroPython framebuf)
• RGB888 — 24-bit color (pygraphics extension)

Quick start::

import pygraphics

fb = pygraphics.FrameBuffer(bytearray(16 * 16 * 2), 16, 16, pygraphics.RGB565)
fb.fill(0)
area = fb.fill_rect(1, 1, 6, 6, 0xFFFF)
pygraphics.text8(fb, "Hi", 0, 0, 0xFFFF)

Area(x, y=None, w=None, h=None)

Rectangular geometry helper used for dirty-rectangle updates, hit testing, and clipping.

Area values are commonly returned by drawing helpers such as :func:fill_rect and :func:circle and can be used to refresh only the pixels that changed. They are also useful for widget hit testing, button bounds, and trimming a draw operation to a sub-region of the screen.

The constructor accepts either separate (x, y, w, h) values or a single tuple containing those four values.

Attributes:

Name	Type	Description
x	int | float	The x-coordinate of the top-left corner of the area.
y	int | float	The y-coordinate of the top-left corner of the area.
w	int | float	The width of the area.
h	int | float	The height of the area.

Create an area from explicit coordinates or from a single (x, y, w, h) tuple.

Parameters:

Name	Type	Description	Default
x	int | float | tuple	The left edge, or a tuple containing (x, y, w, h).	required
y	int | float	The top edge.	None
w	int | float	The width of the area.	None
h	int | float	The height of the area.	None

clip(other)

Clips the current Area object to the specified Area object.

Parameters:

Name	Type	Description	Default
other	Area	The other Area object to clip to.	required

Returns:

Type	Description
Area	A new Area object representing the clipped area.

contains(x, y=None)

Checks if the specified point is contained within the area.

Parameters:

Name	Type	Description	Default
x	int | tuple	The x-coordinate of the point to check or a tuple containing the x and y coordinates of the point.	required
y	int	The y-coordinate of the point to check.	None

Returns:

Type	Description
bool	True if the point is contained within the area, False otherwise.

contains_area(other)

Checks if the specified area is contained within the area.

Parameters:

Name	Type	Description	Default
other	Area	The other area to check.	required

Returns:

Type	Description
bool	True if the other area is contained within the area, False otherwise.

inset(d1, d2=None, d3=None, d4=None)

Returns a new Area inset by the specified amount(s).

If only one argument is provided, it is used as the inset in all 4 directions. If two arguments are provided, the first is used as the inset in the x direction and the second as the inset in the y direction. If three arguments are provided, they are used as the insets in the left, top/bottom, and right directions, respectively. If four arguments are provided, they are used as the insets in the left, top, right, and bottom directions, respectively.

Parameters:

Name	Type	Description	Default
d1	int | float	The inset in the x direction or the inset in all 4 directions.	required
d2	int | float	The inset in the y direction or the inset in the top/bottom direction.	None
d3	int | float	The inset in the right direction.	None
d4	int | float	The inset in the bottom direction.	None

Returns:

Type	Description
Area	A new Area object inset by the specified amount(s).

intersects(other)

Checks if the current Area object intersects with another Area object.

Parameters:

Name	Type	Description	Default
other	Area	The other Area object to check for overlap.	required

Returns:

Type	Description
bool	True if the two Area objects intersect, False otherwise.

offset(d1, d2=None, d3=None, d4=None)

Returns a new Area offset by the specified amount(s).

If only one argument is provided, it is used as the offset in all 4 directions. If two arguments are provided, the first is used as the offset in the x direction and the second as the offset in the y direction. If three arguments are provided, they are used as the offsets in the left, top/bottom, and right directions, respectively. If four arguments are provided, they are used as the offsets in the left, top, right, and bottom directions, respectively.

Parameters:

Name	Type	Description	Default
d1	int | float	The offset in the x direction or the offset in all 4 directions.	required
d2	int | float	The offset in the y direction or the offset in the top/bottom direction.	None
d3	int | float	The offset in the right direction.	None
d4	int | float	The offset in the bottom direction.	None

Returns:

Type	Description
Area	A new Area object offset by the specified amount(s).

shift(dx=0, dy=0)

Returns a new Area shifted by the specified amount in the x and y directions.

Parameters:

Name	Type	Description	Default
dx	int | float	The amount to shift the area in the x direction.	0
dy	int | float	The amount to shift the area in the y direction.	0

Returns:

Type	Description
Area	A new Area object shift by the specified amount in the x and y directions.

touches_or_intersects(other)

Checks if the current Area object touches or intersects with another Area object.

Parameters:

Name	Type	Description	Default
other	Area	The other Area object to check for overlap or touch.	required

Returns:

Type	Description
bool	True if the two Area objects touch or intersect, False otherwise.

Font(font_data=None, height=None, cached=True)

Load a bundled romfont and reuse it for multiple text draws.

Font is useful when the same UI needs to draw several labels, scores, or status strings with the same glyph set. It can load either an embedded font or a custom .bin file from disk or from memory.

Parameters:

Name	Type	Description	Default
font_data	str | byterray	Path to a font file or memoryview. Default is None.	None
height	int	The height of the font. Default is None.	None
cached	bool	If True (default), read the font into memory on init. If False, read it from disk each time it is needed.	True

Load a romfont from a path, memoryview, or embedded default.

Binary font layout: 256 glyphs in ASCII order, one byte per pixel row per glyph (fonts up to 8 pixels wide). If height is omitted and font_data is a path like font_8x14.bin, height is taken from the name; for a memoryview, height is len(data) // 256.

Parameters:

Name	Type	Description	Default
font_data	str | memoryview	Path to a .bin font file, or a memoryview of glyph bytes. Default uses the embedded font for height (or 8×8).	None
height	int	Glyph height in pixels. Overrides height inferred from the file name when both are set.	None
cached	bool	If True (default), read the whole file into memory. If False, seek the open file for each glyph row.	True

Raises:

Type	Description
FileNotFoundError	If font_data is a path that cannot be opened.
RuntimeError	If the file size does not match the expected font size.

height property

Return the height of the font in pixels.

width property

Return the width of the font in pixels.

deinit()

Close the font file as cleanup.

draw_char(char, x, y, canvas, color, scale=1, inverted=False)

Draw one character at position (x,y).

Parameters:

Name	Type	Description	Default
char	str	The character to draw.	required
x	int	The x position to draw the character.	required
y	int	The y position to draw the character.	required
canvas	Canvas	The DisplayDriver, FrameBuffer, or other canvas-like object to draw on.	required
color	int	The color to draw the character in.	required
scale	int	The scale factor to draw the character at. Default is 1.	1
inverted	bool	If True, draw the character inverted. Default is False.	False

Returns:

Type	Description
Area	The area that was drawn to.

export(filename)

Export the font data in self._cache to a .py file that can be imported. The format is a single bytes object named _FONT. There are 256 lines, one for each character. The last line is FONT = memoryview(_FONT).

Parameters:

Name	Type	Description	Default
filename	str	The path to save the file to.	required

text(canvas, string, x, y, color, scale=1, inverted=False)

Draw text to the canvas.

Parameters:

Name	Type	Description	Default
canvas	Canvas	The DisplayDriver, FrameBuffer, or other canvas-like object to draw on.	required
string	str	The text to draw.	required
x	int	The x position to start drawing the text.	required
y	int	The y position to start drawing the text.	required
color	int	The color to draw the text in.	required
scale	int	The scale factor to draw the text at. Default is 1.	1
inverted	bool	If True, draw the text inverted. Default is False.	False

Returns:

Type	Description
Area	The area that was drawn to.

text_width(text, scale=1)

Return the pixel width of the specified text message. Takes into account the scale factor, but not any newlines.

Parameters:

Name	Type	Description	Default
text	str	The text to measure.	required
scale	int	The scale factor to measure the text at. Default is 1.	1

Returns:

Name	Type	Description
int		Width in pixels.

FrameBuffer(buffer, width, height, format, *args, **kwargs)

Bases: FrameBuffer

Framebuffer surface for drawing either to the display itself or to an off-screen buffer.

This class preserves the standard framebuf API while adding helpers for shapes, text, and image I/O. Each draw operation returns an :class:Area describing the pixels that changed, which is ideal for dirty-rectangle updates and for compositing a pre-rendered scene before pushing it to the display.

Typical usage is to create a bytearray large enough for the target size, draw a frame with :meth:fill, :meth:fill_rect, :meth:circle, or :func:text8, then copy that buffer to a display driver or use the returned Area to refresh only the changed region.

Parameters:

Name	Type	Description	Default
buffer	bytearray	Framebuffer buffer.	required
width	int	Width in pixels.	required
height	int	Height in pixels.	required
format	int	Framebuffer format constant such as RGB565 or RGB888.	required

Create a framebuffer wrapping buffer.

Parameters:

Name	Type	Description	Default
buffer	bytearray	Pixel storage (writable).	required
width	int	Width in pixels.	required
height	int	Height in pixels.	required
format	int	Pixel format constant (RGB565, RGB888, etc.).	required
*args		Forwarded to the base framebuf.FrameBuffer (e.g. stride).	()
**kwargs		Forwarded to the base constructor (e.g. stride=).	{}

Raises:

Type	Description
ValueError	If format is not a supported constant.

buffer property

Underlying pixel buffer passed to the constructor.

color_depth property

Bits per pixel for the current format (1, 2, 4, 8, 16, or 24).

format property

Pixel format constant (RGB565, RGB888, MONO_HLSB, …).

height property

Framebuffer height in pixels.

width property

Framebuffer width in pixels.

arc(x, y, r, a0, a1, c)

Arc drawing function. Will draw a single pixel wide arc with a radius r centered at x, y from a0 to a1.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the arc's center.	required
y	int	Y-coordinate of the arc's center.	required
r	int	Radius of the arc.	required
a0	float	Starting angle in degrees.	required
a1	float	Ending angle in degrees.	required
c	int	color.	required

Returns:

Type	Description
Area	The bounding box of the arc.

blit(source, x, y, key=-1, palette=None)

Blit the given buffer at the given location.

Parameters:

Name	Type	Description	Default
source	FrameBuffer	FrameBuffer to blit	required
x	int	x coordinate	required
y	int	y coordinate	required
key	int	Color key (default: -1)	-1
palette	FrameBuffer	Palette (default: None)	None

Returns:

Type	Description
Area	Bounding box of the blitted buffer

blit_rect(buf, x, y, w, h)

Blit a rectangular area from a buffer to the canvas. Uses the canvas's blit_rect method if available, otherwise writes directly to the buffer.

Parameters:

Name	Type	Description	Default
buf	memoryview	Buffer to blit. Must already be byte-swapped if necessary.	required
x	int	X-coordinate to blit to.	required
y	int	Y-coordinate to blit to.	required
w	int	Width of the area to blit.	required
h	int	Height of the area to blit.	required

Returns:

Type	Description
Area	The bounding box of the blitted area.

blit_transparent(buf, x, y, w, h, key)

Blit a buffer with transparency.

Parameters:

Name	Type	Description	Default
buf	memoryview	Buffer to blit.	required
x	int	X-coordinate to blit to.	required
y	int	Y-coordinate to blit to.	required
w	int	Width of the area to blit.	required
h	int	Height of the area to blit.	required
key	int	Key value for transparency.	required

Returns:

Type	Description
Area	The bounding box of the blitted area.

circle(x0, y0, r, c, f=False)

Circle drawing function. Will draw a single pixel wide circle centered at x0, y0 and the specified r.

Parameters:

Name	Type	Description	Default
x0	int	Center x coordinate	required
y0	int	Center y coordinate	required
r	int	Radius	required
c	int	Color	required
f	bool	Fill the circle (default: False)	False

Returns:

Type	Description
Area	The bounding box of the circle.

ellipse(x, y, rx, ry, c, f=False, m=15)

Draw an ellipse at the given location, radii and color.

Parameters:

Name	Type	Description	Default
x	int	Center x coordinate	required
y	int	Center y coordinate	required
rx	int	X radius	required
ry	int	Y radius	required
c	int	color	required
f	bool	Fill the ellipse (default: False)	False
m	int	Bitmask to determine which quadrants to draw (default: 0b1111)	15

Returns:

Type	Description
Area	Bounding box of the ellipse

export(filename)

Export this framebuffer as an importable .py bitmap module.

See :func:pygraphics._files.export_framebuffer. Ships BITMAP as a bytearray for zero-copy :meth:from_bitmap on MicroPython.

fill(c)

Fill the buffer with the given color.

Parameters:

Name	Type	Description	Default
c	int	color	required

Returns:

Type	Description
Area	Bounding box of the filled buffer

fill_rect(x, y, w, h, c)

Fill a rectangle with a solid color.

This is the usual primitive for clearing a region, drawing panels, or staging a background before more detailed shapes or text are drawn.

Parameters:

Name	Type	Description	Default
x	int	X coordinate of the top-left corner.	required
y	int	Y coordinate of the top-left corner.	required
w	int	Width in pixels.	required
h	int	Height in pixels.	required
c	int	Color to write.	required

Returns:

Name	Type	Description
Area		Bounding box of the filled rectangle.

from_bitmap(buffer, width, height, format) staticmethod

Build a FrameBuffer from a bitmap buffer (export-module style).

If buffer is already a writable bytearray (or a writable memoryview), it is used without copying. Legacy bytes / memoryview(bytes) modules get one bytearray copy so MicroPython can own a writable pixel buffer.

from_file(filename) staticmethod

Load a framebuffer from a file.

Parameters:

Name	Type	Description	Default
filename	str	Filename to load from	required

Returns:

Name	Type	Description
FrameBuffer		Image loaded as a framebuffer.

from_module(mod) staticmethod

Load from a module with WIDTH, HEIGHT, FORMAT, BITMAP.

gradient_rect(x, y, w, h, c1, c2=None, vertical=True)

Fill a rectangle with a gradient.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the top-left corner of the rectangle.	required
y	int	Y-coordinate of the top-left corner of the rectangle.	required
w	int	Width of the rectangle.	required
h	int	Height of the rectangle.	required
c1	int	565 encoded color for the top or left edge.	required
c2	int	565 encoded color for the bottom or right edge. If None or the same as c1, fill_rect will be called instead.	None
vertical	bool	If True, the gradient will be vertical. If False, the gradient will be horizontal.	True

Returns:

Type	Description
Area	The bounding box of the filled area.

hline(x, y, w, c)

Draw a horizontal line at the given location, width and color.

Parameters:

Name	Type	Description	Default
x	int	x coordinate	required
y	int	y coordinate	required
w	int	Width in pixels	required
c	int	color	required

Returns:

Type	Description
Area	Bounding box of the horizontal line

line(x1, y1, x2, y2, c)

Draw a line between the given start and end points and color.

Parameters:

Name	Type	Description	Default
x1	int	Start x coordinate	required
y1	int	Start y coordinate	required
x2	int	End x coordinate	required
y2	int	End y coordinate	required
c	int	color	required

Returns:

Type	Description
Area	Bounding box of the line

pixel(x, y, c=None)

Draw a single pixel at the given location and color.

Parameters:

Name	Type	Description	Default
x	int	x coordinate	required
y	int	y coordinate	required
c	int	color (default: None)	None

Returns:

Type	Description
Area	Bounding box of the pixel

poly(x, y, coords, c, f=False)

Draw a polygon at the given location, coordinates and color.

Parameters:

Name	Type	Description	Default
x	int	x coordinate	required
y	int	y coordinate	required
coords	array	Array of x, y coordinate tuples	required
c	int	color	required
f	bool	Fill the polygon (default: False)	False

Returns:

Type	Description
Area	Bounding box of the polygon

polygon(points, x, y, color, angle=0, center_x=0, center_y=0)

Draw a polygon on the canvas.

Parameters:

Name	Type	Description	Default
points	list	List of points to draw.	required
x	int	X-coordinate of the polygon's position.	required
y	int	Y-coordinate of the polygon's position.	required
color	int	color.	required
angle	float	Rotation angle in radians (default: 0).	0
center_x	int	X-coordinate of the rotation center (default: 0).	0
center_y	int	Y-coordinate of the rotation center (default: 0).	0

Raises:

Type	Description
ValueError	If the polygon has less than 3 points.

Returns:

Type	Description
Area	The bounding box of the polygon.

rect(x, y, w, h, c, f=False)

Draw a rectangle at the given location, size and color.

Parameters:

Name	Type	Description	Default
x	int	Top left corner x coordinate	required
y	int	Top left corner y coordinate	required
w	int	Width in pixels	required
h	int	Height in pixels	required
c	int	color	required
f	bool	Fill the rectangle (default: False)	False

Returns:

Type	Description
Area	Bounding box of the rectangle

round_rect(x0, y0, w, h, r, c, f=False)

Rounded rectangle drawing function. Will draw a single pixel wide rounded rectangle starting at x0, y0 and extending w, h pixels with the specified radius.

Parameters:

Name	Type	Description	Default
x0	int	X-coordinate of the top-left corner of the rectangle.	required
y0	int	Y-coordinate of the top-left corner of the rectangle.	required
w	int	Width of the rectangle.	required
h	int	Height of the rectangle.	required
r	int	Radius of the corners.	required
c	int	color.	required
f	bool	Fill the rectangle (default: False).	False

Returns:

Type	Description
Area	The bounding box of the rectangle.

save(filename=None)

Save the framebuffer to a file. The file extension must match the format, otherwise the extension will be appended to the filename.

Saves 1-bit formats as PBM, 2-bit formats as PGM with max value 3, 4-bit formats as PGM with max value 15, 8-bit formats as PGM with max value 255, and 16-bit formats as BMP.

Parameters:

Name	Type	Description	Default
filename	str	Filename to save to	None

scroll(xstep, ystep)

Scroll buffer contents. Returns the full buffer bounds.

text(s, x, y, c=1, scale=1, inverted=False, font_data=None, height=8)

Draw text at the given location, using the given font and color.

Parameters:

Name	Type	Description	Default
s	str	Text to draw	required
x	int	x coordinate	required
y	int	y coordinate	required
c	int	color	1
scale	int	Scale factor (default: 1)	1
inverted	bool	Invert the text (default: False)	False
font_data	str	Path to the font file (default: None)	None
height	int	Height of the font (default: 8)	8

Returns:

Type	Description
Area	Bounding box of the text

text14(s, x, y, c=1, scale=1, inverted=False, font_data=None)

   Place text on the canvas with a 14 pixel high font.
   Breaks on

to next line. Does not break on line going off canvas.

   Args:
       s (str): The text to draw.
       x (int): The x position to start drawing the text.
       y (int): The y position to start drawing the text.
       c (int): The color to draw the text in.  Default is 1.
       scale (int): The scale factor to draw the text at.  Default is 1.
       inverted (bool): If True, draw the text inverted.  Default is False.
       font_data (str): The path to the font file to use.  Default is None.

   Returns:
       Area: The area that was drawn to.

text16(s, x, y, c=1, scale=1, inverted=False, font_data=None)

   Place text on the canvas with a 16 pixel high font.
   Breaks on

to next line. Does not break on line going off canvas.

   Args:
       s (str): The text to draw.
       x (int): The x position to start drawing the text.
       y (int): The y position to start drawing the text.
       c (int): The color to draw the text in.  Default is 1.
       scale (int): The scale factor to draw the text at.  Default is 1.
       inverted (bool): If True, draw the text inverted.  Default is False.
       font_data (str): The path to the font file to use.  Default is None.

   Returns:
       Area: The area that was drawn to.

text8(s, x, y, c=1, scale=1, inverted=False, font_data=None)

   Place text on the canvas with an 8 pixel high font.
   Breaks on

to next line. Does not break on line going off canvas.

   Args:
       s (str): The text to draw.
       x (int): The x position to start drawing the text.
       y (int): The y position to start drawing the text.
       c (int): The color to draw the text in.  Default is 1.
       scale (int): The scale factor to draw the text at.  Default is 1.
       inverted (bool): If True, draw the text inverted.  Default is False.
       font_data (str): The path to the font file to use.  Default is None.

   Returns:
       Area: The area that was drawn to.

triangle(x0, y0, x1, y1, x2, y2, c, f=False)

Triangle drawing function. Draws a single pixel wide triangle with vertices at (x0, y0), (x1, y1), and (x2, y2).

Parameters:

Name	Type	Description	Default
x0	int	X-coordinate of the first vertex.	required
y0	int	Y-coordinate of the first vertex.	required
x1	int	X-coordinate of the second vertex.	required
y1	int	Y-coordinate of the second vertex.	required
x2	int	X-coordinate of the third vertex.	required
y2	int	Y-coordinate of the third vertex.	required
c	int	color.	required
f	bool	Fill the triangle (default: False).	False

Returns:

Type	Description
Area	The bounding box of the triangle.

vline(x, y, h, c)

Draw a vertical line at the given location, height and color.

Parameters:

Name	Type	Description	Default
x	int	x coordinate	required
y	int	y coordinate	required
h	int	Height in pixels	required
c	int	color	required

Returns:

Type	Description
Area	Bounding box of the vertical line

arc(canvas, x, y, r, a0, a1, c)

Arc drawing function. Will draw a single pixel wide arc with a radius r centered at x, y from a0 to a1.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the arc's center.	required
y	int	Y-coordinate of the arc's center.	required
r	int	Radius of the arc.	required
a0	float	Starting angle in degrees.	required
a1	float	Ending angle in degrees.	required
c	int	color.	required

Returns:

Type	Description
Area	The bounding box of the arc.

blit(canvas, source, x, y, key=-1, palette=None)

Copy a source buffer or sprite onto a canvas.

This is useful for compositing an off-screen frame into the live display, for scrolling text and sprite animations, and for drawing pre-rendered tiles or bitmaps. The returned area is the region that was written so that it can be treated as a dirty rectangle.

Parameters:

Name	Type	Description	Default
source	FrameBuffer	Source framebuffer or canvas-like object.	required
x	int	X-coordinate to blit to.	required
y	int	Y-coordinate to blit to.	required
key	int	Key value for transparency (default: -1).	-1
palette	Palette	Palette object for color translation (default: None).	None

Returns:

Name	Type	Description
Area		The bounding box of the blitted area.

blit_rect(canvas, buf, x, y, w, h)

Blit a rectangular area from a buffer to the canvas. Uses the canvas's blit_rect method if available, otherwise writes directly to the buffer.

Parameters:

Name	Type	Description	Default
buf	memoryview	Buffer to blit. Must already be byte-swapped if necessary.	required
x	int	X-coordinate to blit to.	required
y	int	Y-coordinate to blit to.	required
w	int	Width of the area to blit.	required
h	int	Height of the area to blit.	required

Returns:

Type	Description
Area	The bounding box of the blitted area.

blit_transparent(canvas, buf, x, y, w, h, key)

Blit a buffer with transparency.

Parameters:

Name	Type	Description	Default
buf	memoryview	Buffer to blit.	required
x	int	X-coordinate to blit to.	required
y	int	Y-coordinate to blit to.	required
w	int	Width of the area to blit.	required
h	int	Height of the area to blit.	required
key	int	Key value for transparency.	required

Returns:

Type	Description
Area	The bounding box of the blitted area.

circle(canvas, x0, y0, r, c, f=False)

Draw a circle or filled disk centered at (x0, y0).

This is a common primitive for buttons, status indicators, animated balls, and other UI ornaments. Pass f=True for a filled circle.

Parameters:

Name	Type	Description	Default
x0	int	Center x coordinate.	required
y0	int	Center y coordinate.	required
r	int	Radius.	required
c	int	Color.	required
f	bool	Fill the circle (default: False).	False

Returns:

Name	Type	Description
Area		The bounding box of the circle.

ellipse(canvas, x0, y0, r1, r2, c, f=False, m=15, w=None, h=None)

Midpoint ellipse algorithm Draw an ellipse at the given location. Radii r1 and r2 define the geometry; equal values cause a circle to be drawn. The c parameter defines the color.

The optional f parameter can be set to True to fill the ellipse. Otherwise just a one pixel outline is drawn.

The optional m parameter enables drawing to be restricted to certain quadrants of the ellipse. The LS four bits determine which quadrants are to be drawn, with bit 0 specifying Q1, b1 Q2, b2 Q3 and b3 Q4. Quadrants are numbered counterclockwise with Q1 being top right.

Parameters:

Name	Type	Description	Default
x0	int	Center x coordinate	required
y0	int	Center y coordinate	required
r1	int	x radius	required
r2	int	y radius	required
c	int	color	required
f	bool	Fill the ellipse (default: False)	False
m	int	Bitmask to determine which quadrants to draw (default: 0b1111)	15
w	int	Width of the ellipse (default: None)	None
h	int	Height of the ellipse (default: None)	None

Returns:

Type	Description
Area	The bounding box of the ellipse.

fill(canvas, c)

Fill the entire canvas with a solid color.

This is the typical first step for each frame: clear the previous scene, then draw the next frame on top of it.

Parameters:

Name	Type	Description	Default
c	int	Color.	required

Returns:

Name	Type	Description
Area		The bounding box of the filled area.

fill_rect(canvas, x, y, w, h, c)

Draw a filled rectangle.

Use this for backgrounds, panels, status bars, and other simple UI blocks. It is also the workhorse for clipping and partial redraw operations.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the top-left corner.	required
y	int	Y-coordinate of the top-left corner.	required
w	int	Width of the rectangle.	required
h	int	Height of the rectangle.	required
c	int	Color.	required

Returns:

Name	Type	Description
Area		The bounding box of the filled area.

gradient_rect(canvas, x, y, w, h, c1, c2=None, vertical=True)

Fill a rectangle with a vertical or horizontal color ramp.

This is useful for scenery, backgrounds, and other effects where a smooth transition looks better than a flat fill. The pydisplay examples use it for animated skies and other stylized backdrops.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the top-left corner.	required
y	int	Y-coordinate of the top-left corner.	required
w	int	Width of the rectangle.	required
h	int	Height of the rectangle.	required
c1	int	Color for the top or left edge (format-native).	required
c2	int	Color for the bottom or right edge. If omitted or equal to c1, the helper falls back to :func:fill_rect.	None
vertical	bool	If True, draw a vertical gradient; otherwise a horizontal one.	True

Returns:

Name	Type	Description
Area		The bounding box of the filled area.

hline(canvas, x0, y0, w, c)

Horizontal line drawing function. Will draw a single pixel wide line.

Parameters:

Name	Type	Description	Default
x0	int	X-coordinate of the start of the line.	required
y0	int	Y-coordinate of the start of the line.	required
w	int	Width of the line.	required
c	int	color.	required

Returns:

Type	Description
Area	The bounding box of the line.

implementation()

Return pygraphics_python (this package) vs native_cmod for the C module.

line(canvas, x0, y0, x1, y1, c)

Draw a single-pixel line from (x0, y0) to (x1, y1).

Use this for outlines, rulers, charts, and small UI connectors where a solid stroke is more appropriate than a filled shape.

Parameters:

Name	Type	Description	Default
x0	int	X-coordinate of the start of the line.	required
y0	int	Y-coordinate of the start of the line.	required
x1	int	X-coordinate of the end of the line.	required
y1	int	Y-coordinate of the end of the line.	required
c	int	Color.	required

Returns:

Name	Type	Description
Area		The bounding box of the line.

pixel(canvas, x, y, c)

Draw a single pixel at the specified x, y location. Uses the canvas's pixel method if available, otherwise writes directly to the buffer.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the pixel.	required
y	int	Y-coordinate of the pixel.	required
c	int	color.	required

Returns:

Type	Description
Area	The bounding box of the pixel.

poly(canvas, x, y, coords, c, f=False)

Given a list of coordinates, draw an arbitrary (convex or concave) closed polygon at the given x, y location using the given color.

The coords must be specified as an array of integers, e.g. array('h', [x0, y0, x1, y1, ... xn, yn]) or a list or tuple of points, e.g. [(x0, y0), (x1, y1), ... (xn, yn)].

The optional f parameter can be set to True to fill the polygon. Otherwise, just a one-pixel outline is drawn.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the polygon's position.	required
y	int	Y-coordinate of the polygon's position.	required
coords	list	List of coordinates.	required
c	int	color.	required
f	bool	Fill the polygon (default: False).	False

Returns:

Type	Description
Area	The bounding box of the polygon.

polygon(canvas, points, x, y, color, angle=0, center_x=0, center_y=0)

Draw a polygon on the canvas.

Parameters:

Name	Type	Description	Default
points	list	List of points to draw.	required
x	int	X-coordinate of the polygon's position.	required
y	int	Y-coordinate of the polygon's position.	required
color	int	color.	required
angle	float	Rotation angle in radians (default: 0).	0
center_x	int	X-coordinate of the rotation center (default: 0).	0
center_y	int	Y-coordinate of the rotation center (default: 0).	0

Raises:

Type	Description
ValueError	If the polygon has less than 3 points.

Returns:

Type	Description
Area	The bounding box of the polygon.

rect(canvas, x0, y0, w, h, c, f=False)

Rectangle drawing function. Will draw a single pixel wide rectangle starting at x0, y0 and extending w, h pixels.

Parameters:

Name	Type	Description	Default
x0	int	X-coordinate of the top-left corner of the rectangle.	required
y0	int	Y-coordinate of the top-left corner of the rectangle.	required
w	int	Width of the rectangle.	required
h	int	Height of the rectangle.	required
c	int	color.	required
f	bool	Fill the rectangle (default: False).	False

Returns:

Type	Description
Area	The bounding box of the rectangle.

round_rect(canvas, x0, y0, w, h, r, c, f=False)

Rounded rectangle drawing function. Will draw a single pixel wide rounded rectangle starting at x0, y0 and extending w, h pixels with the specified radius.

Parameters:

Name	Type	Description	Default
x0	int	X-coordinate of the top-left corner of the rectangle.	required
y0	int	Y-coordinate of the top-left corner of the rectangle.	required
w	int	Width of the rectangle.	required
h	int	Height of the rectangle.	required
r	int	Radius of the corners.	required
c	int	color.	required
f	bool	Fill the rectangle (default: False).	False

Returns:

Type	Description
Area	The bounding box of the rectangle.

text(*args, height=8, **kwargs)

Selector to call the correct text function based on the height of the font. See text8, text14, and text16 for more information.

Parameters:

Name	Type	Description	Default
height	int	The height of the font to use. Default is 8.	8

text14(canvas, s, x, y, c=1, scale=1, inverted=False, font_data=None)

Place text on the canvas with a 14 pixel high font. Breaks on to next line. Does not break on line going off canvas.

Args: canvas (Canvas): The DisplayDriver, FrameBuffer, or other canvas-like object to draw on. s (str): The text to draw. x (int): The x position to start drawing the text. y (int): The y position to start drawing the text. c (int): The color to draw the text in. Default is 1. scale (int): The scale factor to draw the text at. Default is 1. inverted (bool): If True, draw the text inverted. Default is False. font_data (str | byterray): The path to the font .bin file or memoryview. Default is None.

Returns: Area: The area that was drawn to.

text16(canvas, s, x, y, c=1, scale=1, inverted=False, font_data=None)

Place text on the canvas with a 16 pixel high font. Breaks on to next line. Does not break on line going off canvas.

Args: canvas (Canvas): The DisplayDriver, FrameBuffer, or other canvas-like object to draw on. s (str): The text to draw. x (int): The x position to start drawing the text. y (int): The y position to start drawing the text. c (int): The color to draw the text in. Default is 1. scale (int): The scale factor to draw the text at. Default is 1. inverted (bool): If True, draw the text inverted. Default is False. font_data (str | byterray): The path to the font .bin file or memoryview. Default is None.

Returns: Area: The area that was drawn to.

text8(canvas, s, x, y, c=1, scale=1, inverted=False, font_data=None)

Draw a single line of text with the built-in 8-pixel font.

This helper is used throughout pydisplay examples for labels, status text, and scrolling captions. The text is written into the given canvas at (x, y) and returns the region that was updated so that it can be used as a dirty rectangle.

Parameters:

Name	Type	Description	Default
canvas	Canvas	The display driver, framebuffer, or other canvas-like object to draw on.	required
s	str	The text to draw.	required
x	int	The x position to start drawing the text.	required
y	int	The y position to start drawing the text.	required
c	int	The color to draw the text in. Default is 1.	1
scale	int	The scale factor to draw the text at. Default is 1.	1
inverted	bool	If True, draw the text inverted. Default is False.	False
font_data	str | byterray	Path to a font file or memoryview. Default is None.	None

Returns:

Name	Type	Description
Area		The area that was drawn to.

triangle(canvas, x0, y0, x1, y1, x2, y2, c, f=False)

Triangle drawing function. Draws a single pixel wide triangle with vertices at (x0, y0), (x1, y1), and (x2, y2).

Parameters:

Name	Type	Description	Default
x0	int	X-coordinate of the first vertex.	required
y0	int	Y-coordinate of the first vertex.	required
x1	int	X-coordinate of the second vertex.	required
y1	int	Y-coordinate of the second vertex.	required
x2	int	X-coordinate of the third vertex.	required
y2	int	Y-coordinate of the third vertex.	required
c	int	color.	required
f	bool	Fill the triangle (default: False).	False

Returns:

Type	Description
Area	The bounding box of the triangle.

vline(canvas, x0, y0, h, c)

Horizontal line drawing function. Will draw a single pixel wide line.

Parameters:

Name	Type	Description	Default
x0	int	X-coordinate of the start of the line.	required
y0	int	Y-coordinate of the start of the line.	required
h	int	Height of the line.	required
c	int	color.	required

Returns:

Type	Description
Area	The bounding box of the line.