# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Cross-platform 2D drawing for MicroPython, CircuitPython and CPython.
Draw shapes, text and images into a framebuffer. Every drawing call returns
the `Area` it changed, so you can send just that part to a screen.
The compiled module and the pure-Python package have the same names, except
four that write or read Python source and exist only in the pure-Python
package; each says so. `implementation()` tells you which one you have.
Example::
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)
"""
from __future__ import annotations
from typing import Any, Iterator
__revision__: str
"""Which source this build came from, from `git describe`: a release tag, or
the nearest one and the commit. Only the compiled module has it."""
# -- pixel formats ------------------------------------------------------------
MONO_VLSB: int
"""1 bit per pixel; each byte is 8 pixels down a column, low bit at the top."""
MONO_HLSB: int
"""1 bit per pixel; bytes run across a row, high bit on the left."""
MONO_HMSB: int
"""1 bit per pixel; bytes run across a row, low bit on the left."""
GS2_HMSB: int
"""2 bits per pixel: four-level greyscale."""
GS4_HMSB: int
"""4 bits per pixel: sixteen-level greyscale."""
GS8: int
"""8 bits per pixel: 256-level greyscale."""
RGB565: int
"""16 bits per pixel, the format of most small colour screens."""
RGB888: int
"""24 bits per pixel, stored red, green, blue. pygraphics' own format, not
`framebuf`'s."""
[docs]
class Area:
"""Rectangular geometry helper used for dirty-rectangle updates, hit testing,
and clipping.
`Area` values are commonly returned by drawing helpers such as
`fill_rect` and `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:
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.
"""
x: int | float
y: int | float
w: int | float
h: int | float
def __init__(self, x: int | float | tuple[int | float, int | float, int | float, int | float], y: int | float | None = None, w: int | float | None = None, h: int | float | None = None) -> None:
"""Create an area from explicit coordinates or from a single ``(x, y, w, h)`` tuple.
Args:
x (int | float | tuple): The left edge, or a tuple containing
``(x, y, w, h)``.
y (int | float): The top edge.
w (int | float): The width of the area.
h (int | float): The height of the area.
"""
[docs]
def contains(self, x: int | tuple, y: int | None = None) -> bool:
"""Checks if the specified point is contained within the area.
Args:
x (int | tuple): The x-coordinate of the point to check
or a tuple containing the x and y coordinates of the point.
y (int): The y-coordinate of the point to check.
Returns:
(bool): True if the point is contained within the area, False otherwise.
"""
[docs]
def contains_area(self, other: Area) -> bool:
"""Checks if the specified area is contained within the area.
Args:
other (Area): The other area to check.
Returns:
(bool): True if the other area is contained within the area, False otherwise.
"""
[docs]
def intersects(self, other: Area) -> bool:
"""Checks if the current Area object intersects with another Area object.
Args:
other (Area): The other Area object to check for overlap.
Returns:
(bool): True if the two Area objects intersect, False otherwise.
"""
[docs]
def touches_or_intersects(self, other: Area) -> bool:
"""Checks if the current Area object touches or intersects with another Area object.
Args:
other (Area): The other Area object to check for overlap or touch.
Returns:
(bool): True if the two Area objects touch or intersect, False otherwise.
"""
[docs]
def shift(self, dx: int | float = 0, dy: int | float = 0) -> Area:
"""Returns a new Area shifted by the specified amount in the x and y directions.
Args:
dx (int | float): The amount to shift the area in the x direction.
dy (int | float): The amount to shift the area in the y direction.
Returns:
(Area): A new Area object shift by the specified amount in the x and y directions.
"""
[docs]
def clip(self, other: Area) -> Area:
"""Clips the current Area object to the specified Area object.
Args:
other (Area): The other Area object to clip to.
Returns:
(Area): A new Area object representing the clipped area.
"""
[docs]
def offset(self, d1: int | float, d2: int | float | None = None, d3: int | float | None = None, d4: int | float | None = None) -> Area:
"""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.
Args:
d1 (int | float): The offset in the x direction or the offset in all 4 directions.
d2 (int | float): The offset in the y direction or the offset in the top/bottom direction.
d3 (int | float): The offset in the right direction.
d4 (int | float): The offset in the bottom direction.
Returns:
(Area): A new Area object offset by the specified amount(s).
"""
[docs]
def inset(self, d1: int | float, d2: int | float | None = None, d3: int | float | None = None, d4: int | float | None = None) -> Area:
"""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.
Args:
d1 (int | float): The inset in the x direction or the inset in all 4 directions.
d2 (int | float): The inset in the y direction or the inset in the top/bottom direction.
d3 (int | float): The inset in the right direction.
d4 (int | float): The inset in the bottom direction.
Returns:
(Area): A new Area object inset by the specified amount(s).
"""
def __eq__(self, other: object) -> bool:
"""Checks if the current Area object is equal to another Area object.
Args:
other (Area): The other Area object to compare with.
Returns:
(bool): True if the two Area objects are equal, False otherwise.
"""
def __ne__(self, other: object) -> bool:
"""Checks if the current Area object is not equal to another Area object.
Args:
other (Area): The other Area object to compare with.
Returns:
(bool): True if the two Area objects are not equal, False otherwise.
"""
def __add__(self, other: Area) -> Area:
"""Computes the union of the current Area object and another Area object.
Args:
other (Area): The other Area object to compute the union with.
Returns:
(Area): A new Area object representing the union of the two areas.
"""
def __bool__(self) -> bool:
"""True when the area has positive width and height."""
def __iter__(self) -> Iterator[int | float]:
"""Returns an iterator over the elements of the Area object.
Returns:
(iterator): An iterator over the elements of the Area object.
"""
[docs]
class 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 `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 `fill`, `fill_rect`, `circle`, or
`text8`, then copy that buffer to a display driver or use the returned
``Area`` to refresh only the changed region.
Args:
buffer (bytearray): Framebuffer buffer.
width (int): Width in pixels.
height (int): Height in pixels.
format (int): Framebuffer format constant such as ``RGB565`` or ``RGB888``.
"""
def __init__(self, buffer: bytearray, width: int, height: int, format: int, *args: Any, **kwargs: Any) -> None:
"""Create a framebuffer wrapping ``buffer``.
Args:
buffer (bytearray): Pixel storage (writable).
width (int): Width in pixels.
height (int): Height in pixels.
format (int): Pixel format constant (``RGB565``, ``RGB888``, etc.).
*args (Any): Forwarded to the base ``framebuf.FrameBuffer`` (e.g. stride).
**kwargs (Any): Forwarded to the base constructor (e.g. ``stride=``).
Raises:
ValueError: If ``format`` is not a supported constant.
"""
@property
def color_depth(self) -> int:
"""Bits per pixel for the current format (1, 2, 4, 8, 16, or 24)."""
@property
def width(self) -> int:
"""Framebuffer width in pixels."""
@property
def height(self) -> int:
"""Framebuffer height in pixels."""
@property
def buffer(self) -> bytearray | memoryview:
"""Underlying pixel buffer passed to the constructor."""
@property
def format(self) -> int:
"""Pixel format constant (``RGB565``, ``RGB888``, ``MONO_HLSB``, …)."""
[docs]
def fill_rect(self, x: int, y: int, w: int, h: int, c: int) -> Area:
"""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.
Args:
x (int): X coordinate of the top-left corner.
y (int): Y coordinate of the top-left corner.
w (int): Width in pixels.
h (int): Height in pixels.
c (int): Color to write.
Returns:
Area: Bounding box of the filled rectangle.
"""
[docs]
def pixel(self, x: int, y: int, c: int | None = None) -> Area | int:
"""Read or draw a single pixel.
With ``c`` it draws the pixel; without, it reads the pixel's color.
Args:
x (int): x coordinate
y (int): y coordinate
c (int): color to draw (default: None, to read the pixel)
Returns:
(Area | int): The bounding box of the pixel when drawing, or the
pixel's color when reading.
"""
[docs]
def fill(self, c: int) -> Area:
"""Fill the buffer with the given color.
Args:
c (int): color
Returns:
(Area): Bounding box of the filled buffer
"""
[docs]
def ellipse(self, x: int, y: int, rx: int, ry: int, c: int, f: bool = False, m: int = 15) -> Area:
"""Draw an ellipse at the given location, radii and color.
Args:
x (int): Center x coordinate
y (int): Center y coordinate
rx (int): X radius
ry (int): Y radius
c (int): color
f (bool): Fill the ellipse (default: False)
m (int): Bitmask to determine which quadrants to draw (default: 0b1111)
Returns:
(Area): Bounding box of the ellipse
"""
[docs]
def hline(self, x: int, y: int, w: int, c: int) -> Area:
"""Draw a horizontal line at the given location, width and color.
Args:
x (int): x coordinate
y (int): y coordinate
w (int): Width in pixels
c (int): color
Returns:
(Area): Bounding box of the horizontal line
"""
[docs]
def line(self, x1: int, y1: int, x2: int, y2: int, c: int) -> Area:
"""Draw a line between the given start and end points and color.
Args:
x1 (int): Start x coordinate
y1 (int): Start y coordinate
x2 (int): End x coordinate
y2 (int): End y coordinate
c (int): color
Returns:
(Area): Bounding box of the line
"""
[docs]
def poly(self, x: int, y: int, coords: list[int] | tuple[int, ...], c: int, f: bool = False) -> Area:
"""Draw a polygon at the given location, coordinates and color.
Args:
x (int): x coordinate
y (int): y coordinate
coords (array): Array of x, y coordinate tuples
c (int): color
f (bool): Fill the polygon (default: False)
Raises:
MemoryError: In the compiled module, a filled polygon of more than 256 vertices needs one int of
scratch memory per vertex, and there wasn't enough. Nothing is drawn. A polygon of any
size fills; 256 vertices or fewer allocates nothing.
Returns:
(Area): Bounding box of the polygon
"""
[docs]
def rect(self, x: int, y: int, w: int, h: int, c: int, f: bool = False) -> Area:
"""Draw a rectangle at the given location, size and color.
Args:
x (int): Top left corner x coordinate
y (int): Top left corner y coordinate
w (int): Width in pixels
h (int): Height in pixels
c (int): color
f (bool): Fill the rectangle (default: False)
Returns:
(Area): Bounding box of the rectangle
"""
[docs]
def vline(self, x: int, y: int, h: int, c: int) -> Area:
"""Draw a vertical line at the given location, height and color.
Args:
x (int): x coordinate
y (int): y coordinate
h (int): Height in pixels
c (int): color
Returns:
(Area): Bounding box of the vertical line
"""
[docs]
def text(self, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data: str | None = None, height: int = 8) -> Area:
"""Draw text at the given location, using the given font and color.
Args:
s (str): Text to draw
x (int): x coordinate
y (int): y coordinate
c (int): color
scale (int): Scale factor (default: 1)
inverted (bool): Invert the text (default: False)
font_data (str): Path to the font file (default: None)
height (int): Height of the font (default: 8)
Returns:
(Area): Bounding box of the text
"""
[docs]
def blit(self, source, x: int, y: int, key: int = -1, palette: Any = None) -> Area:
"""Blit the given buffer at the given location.
Args:
source (FrameBuffer): FrameBuffer to blit
x (int): x coordinate
y (int): y coordinate
key (int): Color key (default: -1)
palette (FrameBuffer): Palette (default: None)
Returns:
(Area): Bounding box of the blitted buffer
"""
[docs]
def arc(self, x: int, y: int, r: int, a0: float, a1: float, c: int) -> Area:
"""Arc drawing function. Will draw a single pixel wide arc with a radius r
centered at x, y from a0 to a1.
Args:
x (int): X-coordinate of the arc's center.
y (int): Y-coordinate of the arc's center.
r (int): Radius of the arc.
a0 (float): Starting angle in degrees.
a1 (float): Ending angle in degrees.
c (int): color.
Returns:
(Area): The bounding box of the arc.
"""
[docs]
def blit_rect(self, buf, x: int, y: int, w: int, h: int) -> Area:
"""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.
Args:
buf (memoryview): Buffer to blit. Must already be byte-swapped if necessary.
x (int): X-coordinate to blit to.
y (int): Y-coordinate to blit to.
w (int): Width of the area to blit.
h (int): Height of the area to blit.
Returns:
(Area): The bounding box of the blitted area.
"""
[docs]
def blit_transparent(self, buf, x: int, y: int, w: int, h: int, key: int) -> Area:
"""Blit a buffer with transparency.
Args:
buf (memoryview): Buffer to blit.
x (int): X-coordinate to blit to.
y (int): Y-coordinate to blit to.
w (int): Width of the area to blit.
h (int): Height of the area to blit.
key (int): Key value for transparency.
Returns:
(Area): The bounding box of the blitted area.
"""
[docs]
def blit_alpha(self, buf, x: int, y: int, w: int, h: int, color: int) -> Area:
"""Tint ``color`` onto the framebuffer through an 8-bit alpha mask.
``buf`` holds ``w * h`` alpha values, one byte each, row by row. Each
pixel becomes ``(color * a + old * (255 - a) + 127) // 255``, worked out
per channel (5, 6 and 5 bits for ``RGB565``, 8 each for ``RGB888``, one
for ``GS8``), so alpha 0 leaves the pixel alone and 255 writes ``color``.
``color`` is a pixel value in the framebuffer's own format, the same
number ``pixel`` takes. The mask is read where it lives and never
copied, so a ``memoryview`` over a frozen ``bytes`` literal stays in
flash. Parts of the mask outside the framebuffer are clipped.
Args:
buf (bytes): Alpha mask: ``bytes``, ``bytearray`` or ``memoryview``.
x (int): X-coordinate of the mask's top-left corner.
y (int): Y-coordinate of the mask's top-left corner.
w (int): Mask width in pixels.
h (int): Mask height in pixels.
color (int): Tint, in the framebuffer's pixel format.
Returns:
(Area): The bounding box of the mask.
Raises:
ValueError: If the format is not ``RGB565``, ``RGB888`` or ``GS8``,
if ``w`` or ``h`` is negative, or if ``buf`` is shorter than
``w * h``.
"""
[docs]
def circle(self, x0: int, y0: int, r: int, c: int, f: bool = False) -> Area:
"""Circle drawing function. Will draw a single pixel wide circle
centered at x0, y0 and the specified r.
Args:
x0 (int): Center x coordinate
y0 (int): Center y coordinate
r (int): Radius
c (int): Color
f (bool): Fill the circle (default: False)
Returns:
(Area): The bounding box of the circle.
"""
[docs]
def gradient_rect(self, x: int, y: int, w: int, h: int, c1: int, c2: int | None = None, vertical: bool = True) -> Area:
"""Fill a rectangle with a gradient.
Args:
x (int): X-coordinate of the top-left corner of the rectangle.
y (int): Y-coordinate of the top-left corner of the rectangle.
w (int): Width of the rectangle.
h (int): Height of the rectangle.
c1 (int): 565 encoded color for the top or left edge.
c2 (int): 565 encoded color for the bottom or right edge. If None or the same as c1,
fill_rect will be called instead.
vertical (bool): If True, the gradient will be vertical. If False, the gradient will be horizontal.
Returns:
(Area): The bounding box of the filled area.
"""
[docs]
def polygon(self, points: list, x: int, y: int, color: int, angle: float = 0, center_x: int = 0, center_y: int = 0) -> Area:
"""Draw a polygon on the canvas.
Args:
points (list): List of points to draw.
x (int): X-coordinate of the polygon's position.
y (int): Y-coordinate of the polygon's position.
color (int): color.
angle (float): Rotation angle in radians (default: 0).
center_x (int): X-coordinate of the rotation center (default: 0).
center_y (int): Y-coordinate of the rotation center (default: 0).
Raises:
ValueError: If the polygon has less than 3 points.
Returns:
(Area): The bounding box of the polygon.
"""
[docs]
def round_rect(self, x0: int, y0: int, w: int, h: int, r: int, c: int, f: bool = False) -> Area:
"""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.
Args:
x0 (int): X-coordinate of the top-left corner of the rectangle.
y0 (int): Y-coordinate of the top-left corner of the rectangle.
w (int): Width of the rectangle.
h (int): Height of the rectangle.
r (int): Radius of the corners.
c (int): color.
f (bool): Fill the rectangle (default: False).
Returns:
(Area): The bounding box of the rectangle.
"""
[docs]
def triangle(self, x0: int, y0: int, x1: int, y1: int, x2: int, y2: int, c: int, f: bool = False) -> Area:
"""Triangle drawing function. Draws a single pixel wide triangle with vertices at
(x0, y0), (x1, y1), and (x2, y2).
Args:
x0 (int): X-coordinate of the first vertex.
y0 (int): Y-coordinate of the first vertex.
x1 (int): X-coordinate of the second vertex.
y1 (int): Y-coordinate of the second vertex.
x2 (int): X-coordinate of the third vertex.
y2 (int): Y-coordinate of the third vertex.
c (int): color.
f (bool): Fill the triangle (default: False).
Returns:
(Area): The bounding box of the triangle.
"""
[docs]
def text8(self, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data: str | None = None) -> Area:
"""Place text on the canvas with an 8 pixel high font.
Breaks on ``\\n`` 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.
"""
[docs]
def text14(self, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data: str | None = None) -> Area:
"""Place text on the canvas with a 14 pixel high font.
Breaks on ``\\n`` 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.
"""
[docs]
def text16(self, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data: str | None = None) -> Area:
"""Place text on the canvas with a 16 pixel high font.
Breaks on ``\\n`` 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.
"""
[docs]
def save(self, filename: str | None = None) -> str:
"""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.
Args:
filename (str): Filename to save to
"""
[docs]
def export(self, filename: str) -> str:
"""Export this framebuffer as an importable ``.py`` bitmap module.
Only the pure-Python package has this.
See `pygraphics._files.export_framebuffer`. Ships ``BITMAP`` as a
``bytearray`` for zero-copy `from_bitmap` on MicroPython.
"""
[docs]
@staticmethod
def from_file(filename: str) -> FrameBuffer:
"""Load a framebuffer from a file.
Args:
filename (str): Filename to load from
Returns:
FrameBuffer: Image loaded as a framebuffer.
"""
[docs]
@staticmethod
def from_bitmap(buffer: bytearray | memoryview | bytes, width: int, height: int, format: int) -> FrameBuffer:
"""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.
Only the pure-Python package has this.
"""
[docs]
@staticmethod
def from_module(mod: Any) -> FrameBuffer:
"""Load from a module with ``WIDTH``, ``HEIGHT``, ``FORMAT``, ``BITMAP``.
Only the pure-Python package has this.
"""
[docs]
def arc(canvas, x: int, y: int, r: int, a0: float, a1: float, c: int) -> Area:
"""Arc drawing function. Will draw a single pixel wide arc with a radius r
centered at x, y from a0 to a1.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x (int): X-coordinate of the arc's center.
y (int): Y-coordinate of the arc's center.
r (int): Radius of the arc.
a0 (float): Starting angle in degrees.
a1 (float): Ending angle in degrees.
c (int): color.
Returns:
(Area): The bounding box of the arc.
"""
[docs]
def blit(canvas, source, x: int, y: int, key: int = -1, palette: Any = None) -> Area:
"""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.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
source (FrameBuffer): Source framebuffer or canvas-like object.
x (int): X-coordinate to blit to.
y (int): Y-coordinate to blit to.
key (int): Key value for transparency (default: -1).
palette (Palette): Palette object for color translation (default: None).
Returns:
Area: The bounding box of the blitted area.
"""
[docs]
def blit_rect(canvas, buf, x: int, y: int, w: int, h: int) -> Area:
"""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.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
buf (memoryview): Buffer to blit. Must already be byte-swapped if necessary.
x (int): X-coordinate to blit to.
y (int): Y-coordinate to blit to.
w (int): Width of the area to blit.
h (int): Height of the area to blit.
Returns:
(Area): The bounding box of the blitted area.
"""
[docs]
def blit_transparent(canvas, buf, x: int, y: int, w: int, h: int, key: int) -> Area:
"""Blit a buffer with transparency.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
buf (memoryview): Buffer to blit.
x (int): X-coordinate to blit to.
y (int): Y-coordinate to blit to.
w (int): Width of the area to blit.
h (int): Height of the area to blit.
key (int): Key value for transparency.
Returns:
(Area): The bounding box of the blitted area.
"""
[docs]
def circle(canvas, x0: int, y0: int, r: int, c: int, f: bool = False) -> Area:
"""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.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x0 (int): Center x coordinate.
y0 (int): Center y coordinate.
r (int): Radius.
c (int): Color.
f (bool): Fill the circle (default: ``False``).
Returns:
Area: The bounding box of the circle.
"""
[docs]
def ellipse(canvas, x0: int, y0: int, r1: int, r2: int, c: int, f: bool = False, m: int = 15, w: int | None = None, h: int | None = None) -> Area:
"""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.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x0 (int): Center x coordinate
y0 (int): Center y coordinate
r1 (int): x radius
r2 (int): y radius
c (int): color
f (bool): Fill the ellipse (default: False)
m (int): Bitmask to determine which quadrants to draw (default: 0b1111)
w (int): Width of the ellipse (default: None)
h (int): Height of the ellipse (default: None)
Returns:
(Area): The bounding box of the ellipse.
"""
[docs]
def fill(canvas, c: int) -> Area:
"""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.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
c (int): Color.
Returns:
Area: The bounding box of the filled area.
"""
[docs]
def fill_rect(canvas, x: int, y: int, w: int, h: int, c: int) -> Area:
"""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.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x (int): X-coordinate of the top-left corner.
y (int): Y-coordinate of the top-left corner.
w (int): Width of the rectangle.
h (int): Height of the rectangle.
c (int): Color.
Returns:
Area: The bounding box of the filled area.
"""
[docs]
def gradient_rect(canvas, x: int, y: int, w: int, h: int, c1: int, c2: int | None = None, vertical: bool = True) -> Area:
"""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 gallery applications use it for
animated skies and other stylized backdrops.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x (int): X-coordinate of the top-left corner.
y (int): Y-coordinate of the top-left corner.
w (int): Width of the rectangle.
h (int): Height of the rectangle.
c1 (int): Color for the top or left edge (format-native).
c2 (int): Color for the bottom or right edge. If omitted or equal to
``c1``, the helper falls back to `fill_rect`.
vertical (bool): If ``True``, draw a vertical gradient; otherwise a horizontal one.
Returns:
Area: The bounding box of the filled area.
"""
[docs]
def hline(canvas, x0: int, y0: int, w: int, c: int) -> Area:
"""Horizontal line drawing function. Will draw a single pixel wide line.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x0 (int): X-coordinate of the start of the line.
y0 (int): Y-coordinate of the start of the line.
w (int): Width of the line.
c (int): color.
Returns:
(Area): The bounding box of the line.
"""
[docs]
def line(canvas, x0: int, y0: int, x1: int, y1: int, c: int) -> Area:
"""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.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x0 (int): X-coordinate of the start of the line.
y0 (int): Y-coordinate of the start of the line.
x1 (int): X-coordinate of the end of the line.
y1 (int): Y-coordinate of the end of the line.
c (int): Color.
Returns:
Area: The bounding box of the line.
"""
[docs]
def pixel(canvas, x: int, y: int, c: int) -> Area:
"""Draw a single pixel at the specified x, y location. Uses the canvas's pixel method if available,
otherwise writes directly to the buffer.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x (int): X-coordinate of the pixel.
y (int): Y-coordinate of the pixel.
c (int): color.
Returns:
(Area): The bounding box of the pixel.
"""
[docs]
def poly(canvas, x: int, y: int, coords: list, c: int, f: bool = False) -> Area:
"""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.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x (int): X-coordinate of the polygon's position.
y (int): Y-coordinate of the polygon's position.
coords (list): List of coordinates.
c (int): color.
f (bool): Fill the polygon (default: False).
Raises:
MemoryError: In the compiled module, a filled polygon of more than 256 vertices needs one int of
scratch memory per vertex, and there wasn't enough. Nothing is drawn. A polygon of any
size fills; 256 vertices or fewer allocates nothing.
Returns:
(Area): The bounding box of the polygon.
"""
[docs]
def polygon(canvas, points: list, x: int, y: int, color: int, angle: float = 0, center_x: int = 0, center_y: int = 0) -> Area:
"""Draw a polygon on the canvas.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
points (list): List of points to draw.
x (int): X-coordinate of the polygon's position.
y (int): Y-coordinate of the polygon's position.
color (int): color.
angle (float): Rotation angle in radians (default: 0).
center_x (int): X-coordinate of the rotation center (default: 0).
center_y (int): Y-coordinate of the rotation center (default: 0).
Raises:
ValueError: If the polygon has less than 3 points.
Returns:
(Area): The bounding box of the polygon.
"""
[docs]
def rect(canvas, x0: int, y0: int, w: int, h: int, c: int, f: bool = False) -> Area:
"""Rectangle drawing function. Will draw a single pixel wide rectangle starting at
x0, y0 and extending w, h pixels.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x0 (int): X-coordinate of the top-left corner of the rectangle.
y0 (int): Y-coordinate of the top-left corner of the rectangle.
w (int): Width of the rectangle.
h (int): Height of the rectangle.
c (int): color.
f (bool): Fill the rectangle (default: False).
Returns:
(Area): The bounding box of the rectangle.
"""
[docs]
def round_rect(canvas, x0: int, y0: int, w: int, h: int, r: int, c: int, f: bool = False) -> Area:
"""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.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x0 (int): X-coordinate of the top-left corner of the rectangle.
y0 (int): Y-coordinate of the top-left corner of the rectangle.
w (int): Width of the rectangle.
h (int): Height of the rectangle.
r (int): Radius of the corners.
c (int): color.
f (bool): Fill the rectangle (default: False).
Returns:
(Area): The bounding box of the rectangle.
"""
[docs]
def triangle(canvas, x0: int, y0: int, x1: int, y1: int, x2: int, y2: int, c: int, f: bool = False) -> Area:
"""Triangle drawing function. Draws a single pixel wide triangle with vertices at
(x0, y0), (x1, y1), and (x2, y2).
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x0 (int): X-coordinate of the first vertex.
y0 (int): Y-coordinate of the first vertex.
x1 (int): X-coordinate of the second vertex.
y1 (int): Y-coordinate of the second vertex.
x2 (int): X-coordinate of the third vertex.
y2 (int): Y-coordinate of the third vertex.
c (int): color.
f (bool): Fill the triangle (default: False).
Returns:
(Area): The bounding box of the triangle.
"""
[docs]
def vline(canvas, x0: int, y0: int, h: int, c: int) -> Area:
"""Horizontal line drawing function. Will draw a single pixel wide line.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
x0 (int): X-coordinate of the start of the line.
y0 (int): Y-coordinate of the start of the line.
h (int): Height of the line.
c (int): color.
Returns:
(Area): The bounding box of the line.
"""
[docs]
def text(*args, height: int = 8, **kwargs) -> Area:
"""Selector to call the correct text function based on the height of the font.
See text8, text14, and text16 for more information.
Args:
height (int): The height of the font to use. Default is 8.
"""
[docs]
def text8(canvas, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data=None) -> Area:
"""Draw a single line of text with the built-in 8-pixel font.
This helper suits 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.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
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 | bytearray): Path to a font file or memoryview. Default is ``None``.
Returns:
Area: The area that was drawn to.
"""
[docs]
def text14(canvas, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data=None) -> Area:
"""Place text on the canvas with a 14 pixel high font.
Breaks on ``\\n`` to next line. Does not break on line going off canvas.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
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 | bytearray): The path to the font .bin file or memoryview. Default is None.
Returns:
Area: The area that was drawn to.
"""
[docs]
def text16(canvas, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data=None) -> Area:
"""Place text on the canvas with a 16 pixel high font.
Breaks on ``\\n`` to next line. Does not break on line going off canvas.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
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 | bytearray): The path to the font .bin file or memoryview. Default is None.
Returns:
Area: The area that was drawn to.
"""
[docs]
class Font:
"""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.
Args:
font_data (str | bytearray): Path to a font file or memoryview. Default is ``None``.
height (int): The height of the font. Default is ``None``.
cached (bool): If ``True`` (default), read the font into memory on init.
If ``False``, read it from disk each time it is needed.
"""
font_name: str
"""What the font is called: ``"default"``, the file's base name, or ``"memoryview"``."""
def __init__(self, font_data: str | memoryview | bytes | None = None, height: int | None = None, cached: bool = True) -> None:
"""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``.
Args:
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).
height (int): Glyph height in pixels. Overrides height inferred from
the file name when both are set.
cached (bool): If True (default), read the whole file into memory.
If False, seek the open file for each glyph row.
Raises:
FileNotFoundError: If ``font_data`` is a path that cannot be opened.
RuntimeError: If the file size does not match the expected font size.
"""
@property
def width(self) -> int:
"""Return the width of the font in pixels."""
@property
def height(self) -> int:
"""Return the height of the font in pixels."""
[docs]
def deinit(self) -> None:
"""Close the font file as cleanup."""
def __enter__(self) -> Font:
"""Open the font for a ``with`` block.
Only the pure-Python package has this.
"""
def __exit__(self, exception_type, exception_value, traceback) -> None:
"""Close the font at the end of a ``with`` block.
Only the pure-Python package has this.
"""
[docs]
def draw_char(self, char: str, x: int, y: int, canvas, color: int, scale: int = 1, inverted: bool = False) -> Area:
"""Draw one character at position (x,y).
Args:
char (str): The character to draw.
x (int): The x position to draw the character.
y (int): The y position to draw the character.
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
color (int): The color to draw the character in.
scale (int): The scale factor to draw the character at. Default is 1.
inverted (bool): If True, draw the character inverted. Default is False.
Returns:
(Area): The area that was drawn to.
"""
[docs]
def text(self, canvas, string: str, x: int, y: int, color: int, scale: int = 1, inverted: bool = False) -> Area:
"""Draw text to the canvas.
Args:
canvas (FrameBuffer): The surface to draw on; any object with the same drawing methods works.
string (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.
color (int): The color to draw the text in.
scale (int): The scale factor to draw the text at. Default is 1.
inverted (bool): If True, draw the text inverted. Default is False.
Returns:
(Area): The area that was drawn to.
"""
[docs]
def text_width(self, text: str, scale: int = 1) -> int:
"""Return the pixel width of the specified text message.
Takes into account the scale factor, but not any newlines.
Args:
text (str): The text to measure.
scale (int): The scale factor to measure the text at. Default is 1.
Returns:
int: Width in pixels.
"""
[docs]
def export(self, filename: str) -> None:
"""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)`.
Args:
filename (str): The path to save the file to.
"""
[docs]
class Draw:
"""Draw shapes on a canvas (display, FrameBuffer, or compatible object).
Each method delegates to ``pygraphics._shapes`` and returns an ``Area`` bounding box.
Args:
canvas: Object with framebuf-compatible drawing methods.
Example::
draw = Draw(display)
draw.fill(0x0000)
draw.rect(10, 10, 100, 100, 0xFFFF)
with draw.clip(5, 5, 50, 30):
draw.fill_rect(0, 0, 200, 200, 0xF800) # clipped to the 50x30 region
"""
canvas: Any
"""The canvas this object draws on."""
def __init__(self, canvas: Any) -> None:
"""Attach drawing helpers to ``canvas``.
Args:
canvas: Object with framebuf-compatible drawing methods (e.g.
`FrameBuffer <pygraphics.FrameBuffer>` or a display driver).
"""
[docs]
def clip(self, x: int, y: int | None = None, w: int | None = None, h: int | None = None) -> ClipContext:
"""Return a context manager that clips drawing to a rectangle.
Accepts ``clip(x, y, w, h)`` or ``clip(Area(...))``. Nested clips intersect.
"""
[docs]
def arc(self, x: int, y: int, r: int, a0: float, a1: float, c: int) -> Area:
"""Draw an arc. Returns Area bounds."""
[docs]
def blit(self, source, x: int, y: int, key: int = -1, palette: Any = None) -> Area:
"""Blit a source buffer. Returns Area bounds."""
[docs]
def blit_rect(self, buf, x: int, y: int, w: int, h: int) -> Area:
"""Blit a raw rectangle buffer. Returns Area bounds."""
[docs]
def blit_transparent(self, buf, x: int, y: int, w: int, h: int, key: int | None = None) -> Area:
"""Blit with transparency. Returns Area bounds."""
[docs]
def circle(self, x: int, y: int, r: int, c: int, f: bool = False) -> Area:
"""Draw a circle. Returns Area bounds."""
[docs]
def ellipse(self, x: int, y: int, r1: int, r2: int, c: int, f: bool = False, m: int = 15, w: int | None = None, h: int | None = None) -> Area:
"""Draw an ellipse. Returns Area bounds."""
[docs]
def fill(self, c: int) -> Area:
"""Fill the canvas. Returns Area bounds."""
[docs]
def fill_rect(self, x: int, y: int, w: int, h: int, c: int) -> Area:
"""Fill a rectangle. Returns Area bounds."""
[docs]
def gradient_rect(self, x: int, y: int, w: int, h: int, c1: int, c2: int | None = None, vertical: bool = True) -> Area:
"""Fill a rectangle with a gradient. Returns Area bounds."""
[docs]
def hline(self, x: int, y: int, w: int, c: int) -> Area:
"""Draw a horizontal line. Returns Area bounds."""
[docs]
def line(self, x1: int, y1: int, x2: int, y2: int, c: int) -> Area:
"""Draw a line. Returns Area bounds."""
[docs]
def pixel(self, x: int, y: int, c: int) -> Area:
"""Draw a pixel. Returns Area bounds."""
[docs]
def poly(self, x: int, y: int, coords: list[int] | tuple[int, ...], c: int, f: bool = False) -> Area:
"""Draw a polygon from flat coordinates. Returns Area bounds."""
[docs]
def polygon(self, points: list[tuple[int, int]], x: int, y: int, c: int, angle: int = 0, center_x: int = 0, center_y: int = 0) -> Area:
"""Draw a polygon from point list. Returns Area bounds."""
[docs]
def rect(self, x: int, y: int, w: int, h: int, c: int, f: bool = False) -> Area:
"""Draw a rectangle. Returns Area bounds."""
[docs]
def round_rect(self, x: int, y: int, w: int, h: int, r: int, c: int, f: bool = False) -> Area:
"""Draw a rounded rectangle. Returns Area bounds."""
[docs]
def triangle(self, x1: int, y1: int, x2: int, y2: int, x3: int, y3: int, c: int, f: bool = False) -> Area:
"""Draw a triangle. Returns Area bounds."""
[docs]
def vline(self, x: int, y: int, h: int, c: int) -> Area:
"""Draw a vertical line. Returns Area bounds."""
[docs]
def text(self, *args, **kwargs) -> Area:
"""Draw text using height from kwargs. Returns Area bounds."""
[docs]
def text8(self, *args, **kwargs) -> Area:
"""Draw 8px-high text. Returns Area bounds."""
[docs]
def text14(self, *args, **kwargs) -> Area:
"""Draw 14px-high text. Returns Area bounds."""
[docs]
def text16(self, *args, **kwargs) -> Area:
"""Draw 16px-high text. Returns Area bounds."""
[docs]
class ClippedCanvas:
"""Proxy that restricts drawing on ``canvas`` to ``clip``.
Drawing methods that intersect the clip region are forwarded to the
underlying canvas; pixels outside the clip are ignored. Unknown attributes
fall through to ``canvas`` via ``__getattr__``.
"""
def __init__(self, canvas, clip: Area) -> None:
"""Wrap ``canvas`` so drawing is limited to ``clip``.
Args:
canvas: Framebuf-compatible draw target.
clip (Area): Inclusive rectangle in canvas coordinates.
"""
@property
def width(self) -> int:
"""Underlying canvas width in pixels."""
@property
def height(self) -> int:
"""Underlying canvas height in pixels."""
[docs]
def pixel(self, x: int, y: int, c: int | None = None) -> Area | int:
"""Get or set a pixel if ``(x, y)`` is inside the clip.
Args:
x: X coordinate.
y: Y coordinate.
c: Color to set. If ``None``, read the existing pixel color.
Returns:
On set: ``Area`` of the pixel, or ``None`` if outside the clip.
On get: pixel color, or ``None`` if outside the clip.
"""
[docs]
def fill(self, c: int) -> Area:
"""Fill the entire clip rectangle with color ``c``.
Args:
c: Fill color.
Returns:
``Area`` of the filled clip, or ``None`` if empty.
"""
[docs]
def fill_rect(self, x: int, y: int, w: int, h: int, c: int) -> Area:
"""Fill the intersection of the given rectangle with the clip.
Args:
x: Left edge.
y: Top edge.
w: Width.
h: Height.
c: Fill color.
Returns:
Clipped ``Area`` that was filled, or ``None`` if no overlap.
"""
[docs]
def hline(self, x: int, y: int, w: int, c: int) -> Area:
"""Draw a horizontal line clipped to this region.
Args:
x: Start x.
y: Y coordinate.
w: Width in pixels.
c: Color.
Returns:
Clipped ``Area``, or ``None`` if no overlap.
"""
[docs]
def vline(self, x: int, y: int, h: int, c: int) -> Area:
"""Draw a vertical line clipped to this region.
Args:
x: X coordinate.
y: Start y.
h: Height in pixels.
c: Color.
Returns:
Clipped ``Area``, or ``None`` if no overlap.
"""
[docs]
def blit_rect(self, buf, x: int, y: int, w: int, h: int) -> Area:
"""Blit a packed buffer, cropping to the clip region.
Args:
buf: Source bytes for a ``w`` x ``h`` rectangle (canvas bpp).
x: Destination x.
y: Destination y.
w: Source width.
h: Source height.
Returns:
Clipped destination ``Area``, or ``None`` if no overlap.
"""
[docs]
def blit_transparent(self, buf, x: int, y: int, w: int, h: int, key: int) -> Area:
"""Blit a packed buffer with transparency, cropped to the clip.
Args:
buf: Source bytes for a ``w`` x ``h`` rectangle (canvas bpp).
x: Destination x.
y: Destination y.
w: Source width.
h: Source height.
key: Transparent color key.
Returns:
Clipped destination ``Area``, or ``None`` if no overlap.
"""
[docs]
def text(self, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data=None, height=8) -> Area:
"""Draw romfont text clipped to this region.
Glyphs are rendered via `fill_rect` on ``self``, so pixels
outside the clip are discarded (unlike falling through to the
underlying canvas ``text``, which draws unclipped).
Args:
s: Text to draw.
x: Left edge.
y: Top edge.
c: Foreground color.
scale: Glyph scale factor.
inverted: Mirror glyphs when True.
font_data: Optional romfont bytes / path.
height: Romfont height (8, 14, or 16).
Returns:
Unclipped text ``Area`` (same contract as ``FrameBuffer.text``).
"""
[docs]
def text8(self, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data=None) -> Area:
"""Draw 8px-high romfont text clipped to this region."""
[docs]
def text14(self, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data=None) -> Area:
"""Draw 14px-high romfont text clipped to this region."""
[docs]
def text16(self, s: str, x: int, y: int, c: int = 1, scale: int = 1, inverted: bool = False, font_data=None) -> Area:
"""Draw 16px-high romfont text clipped to this region."""
[docs]
class ClipContext:
"""Context manager that pushes a clip rectangle onto a `Draw` stack.
Entering returns the effective (intersected) clip ``Area``. Nested
``with draw.clip(...)`` blocks intersect.
"""
def __init__(self, draw, area: Area) -> None:
"""Bind this context to ``draw`` and the clip ``area``.
Args:
draw (Draw): Draw instance whose clip stack is updated.
area (Area): Clip rectangle to push on enter.
"""
def __enter__(self) -> ClipContext:
"""Push the clip and return the effective clip ``Area``."""
def __exit__(self, exc_type, exc, tb) -> None:
"""Pop the clip rectangle from the draw stack."""
[docs]
class BMP565:
"""Read a 16-bit RGB565 BMP as a sliceable, optionally streamed asset.
Provide either ``filename`` (path to a BMP file) or ``source`` (an in-memory
RGB565 buffer with ``width`` and ``height``).
"""
width: int
"""Image width in pixels."""
height: int
"""Image height in pixels."""
bpp: int
"""Bits per pixel: 16."""
BPP: int
"""Bytes per pixel: 2."""
def __init__(self, filename: str | None = None, source: bytearray | memoryview | None = None, streamed: bool = False, mirrored: bool = False, width: int | None = None, height: int | None = None) -> None:
"""Load from a file path or an existing RGB565 buffer.
Args:
filename: Path to an RGB565 BMP file. Mutually exclusive with ``source``.
source: Existing RGB565 pixel buffer. Requires ``width`` and ``height``.
streamed: If True with ``filename``, keep the file open and read rows
on demand instead of loading the full image into memory.
mirrored: When streaming, reverse each row read (rarely needed).
width: Pixel width when constructing from ``source``.
height: Pixel height when constructing from ``source``.
Raises:
ValueError: If neither ``filename`` nor ``source`` is given, or the
file is not a valid RGB565 BMP.
"""
def __call__(self, x: int, y: int, w: int, h: int) -> bytes | bytearray | memoryview:
"""Return the RGB565 bytes for the rectangle at ``(x, y)`` size ``w`` × ``h``.
Equivalent to ``self[x : x + w, y : y + h]``.
Args:
x: Left edge in pixels.
y: Top edge in pixels.
w: Width in pixels.
h: Height in pixels.
Returns:
Raw RGB565 bytes for the requested region.
"""
@property
def buffer(self) -> memoryview | None:
"""Writable ``memoryview`` of the full RGB565 pixel buffer, or ``None`` if streamed."""
[docs]
def save(self, filename: str | None = None) -> str:
"""Write this image as an RGB565 BMP file.
If ``filename`` already exists, a numeric suffix is appended
(``image.bmp`` → ``image_1.bmp``, etc.).
Args:
filename: Output path. Defaults to the source filename or ``image.bmp``.
Returns:
The path actually written.
"""
def __getitem__(self, key: int | slice | tuple[int | slice, int | slice]) -> int | bytes | bytearray | memoryview:
"""Index or slice pixel data.
Args:
key: One of:
* ``(x, y)`` — single pixel as an ``int`` (RGB565)
* ``(x_slice, y_slice)`` — rectangular region as ``bytearray``
* ``int`` — flat pixel index as an ``int``
* ``slice`` — full-width row range as ``bytearray``
Returns:
Pixel value(s) for the requested key.
Raises:
ValueError: If ``key`` is not a supported index form.
"""
[docs]
def deinit(self) -> None:
"""Close the open file handle when constructed with ``streamed=True``."""
def __exit__(self, exception_type, exception_value, traceback) -> None:
"""Close the image at the end of a ``with`` block, as `deinit` does.
Only the pure-Python package has this.
"""
[docs]
def load_image(filename: str) -> FrameBuffer:
"""Load a ``FrameBuffer`` from a PBM, PGM, or RGB565 BMP file."""
[docs]
def save_image(fb: FrameBuffer, filename: str | None = None) -> str:
"""Save a ``FrameBuffer`` to PBM, PGM, BMP, or PNG based on format or filename.
MONO_HLSB → PBM, GS2/GS4/GS8 → PGM, RGB565 → BMP (or PNG if filename ends in .png),
RGB888 → PNG. Other formats raise ``ValueError``.
"""
[docs]
def pbm_to_framebuffer(filename: str) -> FrameBuffer:
"""Convert a PBM file to a MONO_HLSB FrameBuffer.
Allocates one pixel buffer and reads pixels with ``readinto`` (peak ~1x).
Args:
filename (str): Filename of the PBM file
Returns:
FrameBuffer: Loaded monochrome framebuffer.
"""
[docs]
def pgm_to_framebuffer(filename: str) -> FrameBuffer:
"""Convert a PGM file to a GS2_HMSB, GS4_HMSB or GS8 FrameBuffer.
Allocates one pixel buffer and reads pixels with ``readinto`` (peak ~1x).
Args:
filename (str): Filename of the PGM file
Returns:
FrameBuffer: Loaded greyscale framebuffer (format from max value).
"""
[docs]
def bmp_to_framebuffer(filename: str) -> FrameBuffer:
"""Convert an RGB565 BMP file to a FrameBuffer.
Args:
filename (str): Path to the BMP file.
Returns:
FrameBuffer: Loaded RGB565 framebuffer.
"""
[docs]
def export_framebuffer(fb: FrameBuffer, filename: str) -> str:
"""Export a ``FrameBuffer`` as an importable ``.py`` bitmap module.
Only the pure-Python package has this.
Format::
WIDTH = …
HEIGHT = …
FORMAT = …
BITMAP = bytearray(
b'…'\
b'…'
)
``BITMAP`` is a writable ``bytearray`` so MicroPython can wrap it in a
``FrameBuffer`` without copying. Prefer `FrameBuffer.from_bitmap` to
load. Differs from `Font.export`, which keeps a read-only
``memoryview`` for glyph indexing.
"""
[docs]
def implementation() -> str:
"""Say which package this is: ``"native_cmod"`` for the compiled module, ``"pygraphics_python"`` for the pure-Python one."""