framebuf — frame buffer manipulation

The framebuf module provides a small, allocation-free pixel buffer with primitive drawing operations. It is intended for driving external displays (OLEDs, LCDs, e-paper, etc.).

Note

For image-processing work on captured frames, use OpenMV’s much richer image.Image class instead – it offers far more drawing primitives, colour conversions and analysis features than framebuf.

class FrameBuffer

A FrameBuffer wraps a user-supplied buffer-protocol object (typically a bytearray) and exposes methods to draw pixels, lines, rectangles, ellipses, polygons, text and other FrameBuffers into it.

Example:

import framebuf

# FrameBuffer needs 2 bytes for every RGB565 pixel.
fbuf = framebuf.FrameBuffer(bytearray(100 * 10 * 2), 100, 10, framebuf.RGB565)

fbuf.fill(0)
fbuf.text("MicroPython!", 0, 0, 0xffff)
fbuf.hline(0, 9, 96, 0xffff)

Constructors

class framebuf.FrameBuffer(buffer: Any, width: int, height: int, format: int, stride: int | None = None, /)

Construct a FrameBuffer object.

• buffer – any object supporting the buffer protocol; must be large enough to hold stride * height pixels at the chosen format.

• width – width of the frame buffer in pixels.

• height – height of the frame buffer in pixels.

• format – pixel format; one of the constants listed under Constants below. The format determines both the size of each pixel in buffer and how a colour integer c passed to any drawing method is interpreted.

• stride – number of pixels per horizontal row, including any padding. Defaults to width. Set this to use a sub-region of a larger buffer.

Passing a buffer that is too small, or invalid dimensions, will produce undefined results – the constructor does not validate every combination.

Drawing methods

FrameBuffer.fill(c: int) → None

Fill the entire frame buffer with colour c.

FrameBuffer.fill_rect(x: int, y: int, w: int, h: int, c: int) → None

Fill a w x h rectangle at (x, y) with colour c. Equivalent to rect() with f=True.

FrameBuffer.pixel(x: int, y: int, c: int | None = None) → int | None

With no c argument, return the colour value of the pixel at (x, y). With c given, set that pixel to colour c.

FrameBuffer.hline(x: int, y: int, w: int, c: int) → None

FrameBuffer.vline(x: int, y: int, h: int, c: int) → None

FrameBuffer.line(x1: int, y1: int, x2: int, y2: int, c: int) → None

Draw a 1-pixel-thick line in colour c. hline() and vline() draw a horizontal/vertical line of the given length; line() draws a line between two arbitrary points.

FrameBuffer.rect(x: int, y: int, w: int, h: int, c: int, f: bool = False) → None

Draw a rectangle at (x, y) of size w x h in colour c. If f is True the rectangle is filled; otherwise only a 1-pixel outline is drawn.

FrameBuffer.ellipse(x: int, y: int, xr: int, yr: int, c: int, f: bool = False, m: int = 0) → None

Draw an ellipse centred on (x, y) with x-radius xr and y-radius yr in colour c. Equal radii produce a circle. f=True fills the shape instead of just outlining it.

m is a bitmask that restricts drawing to specific quadrants (numbered counter-clockwise from the top-right):

Bit	Quadrant	Region
bit 0	Q1	Top-right
bit 1	Q2	Top-left
bit 2	Q3	Bottom-left
bit 3	Q4	Bottom-right

The default m=0 draws all four quadrants.

FrameBuffer.poly(x: int, y: int, coords: Any, c: int, f: bool = False) → None

Draw an arbitrary closed polygon (convex or concave) at offset (x, y) in colour c. coords must be an array of signed 16-bit integers laid out as array('h', [x0, y0, x1, y1, ..., xn, yn]). f=True fills the polygon instead of just outlining it.

FrameBuffer.text(s: str, x: int, y: int, c: int = 1) → None

Draw the string s with its top-left corner at (x, y) in colour c. The built-in font is fixed at 8x8 pixels and cannot be changed. c defaults to 1.

FrameBuffer.scroll(xstep: int, ystep: int) → None

Shift the buffer contents by (xstep, ystep). Pixels shifted in from outside the buffer are not cleared, so a “ghost” of the previous contents may remain at the trailing edge.

FrameBuffer.blit(fbuf: FrameBuffer | Tuple, x: int, y: int, key: int = -1, palette: FrameBuffer | None = None) → None

Draw another frame buffer fbuf on top of this one with its top-left corner at (x, y).

If key is given, any source pixel matching that colour value is treated as transparent and not drawn. When a palette is provided, the comparison is made against the palette output, not the raw fbuf value.

fbuf can be a FrameBuffer instance or a tuple/list matching the constructor signature:

(buffer, width, height, format)
(buffer, width, height, format, stride)

When the source is a tuple/list, buffer may be read-only.

palette allows blitting between buffers of different formats – for example, rendering a monochrome glyph into an RGB565 buffer. It is a FrameBuffer whose format matches the destination, with height 1 and width equal to the number of source colours (2**N for an N-bit-per-pixel source). Source pixel value i is replaced with the colour at palette[i, 0] before drawing.

Constants

The following format values are accepted by the constructor. The “bytes per pixel” column is the multiplier needed when sizing the backing buffer.

Constant	Bytes/pixel	Pixel layout
MONO_VLSB	0.125	Monochrome (1-bit). Each byte holds 8 vertically-stacked pixels with bit 0 nearest the top. Rows of 8 pixels advance left-to-right across the buffer, then wrap to the next 8-pixel row.
MONO_HLSB	0.125	Monochrome (1-bit). Each byte holds 8 horizontal pixels with bit 7 leftmost. Rows advance one pixel at a time vertically.
MONO_HMSB	0.125	Monochrome (1-bit). Like MONO_HLSB but with bit 0 leftmost.
GS2_HMSB	0.25	2-bit greyscale (4 levels), packed horizontally most-significant bit first.
GS4_HMSB	0.5	4-bit greyscale (16 levels), packed horizontally most-significant nibble first.
GS8	1	8-bit greyscale (256 levels).
RGB565	2	16-bit RGB with 5 red, 6 green and 5 blue bits.

framebuf.MVLSB is a deprecated alias for framebuf.MONO_VLSB; prefer the latter in new code.

Legacy constructor

framebuf.FrameBuffer1(buffer: Any, width: int, height: int, stride: int | None = None, /) → FrameBuffer

Deprecated shortcut for FrameBuffer(buffer, width, height, framebuf.MONO_VLSB, stride). Retained for backwards compatibility; use the full FrameBuffer constructor instead.