framebuf — manipolazione del frame buffer

Il modulo framebuf fornisce un piccolo buffer di pixel privo di allocazioni con operazioni di disegno primitive. È pensato per pilotare display esterni (OLED, LCD, e-paper, ecc.).

Nota

Per il lavoro di elaborazione delle immagini su frame catturati, usa invece la ben più ricca classe image.Image di OpenMV: offre molte più primitive di disegno, conversioni di colore e funzionalità di analisi rispetto a 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.

Esempio:

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)

Costruttori

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

Costruisce un oggetto FrameBuffer.

• buffer – qualsiasi oggetto che supporti il protocollo buffer; deve essere abbastanza grande da contenere stride * height pixel nel format scelto.

• width – larghezza del frame buffer in pixel.

• height – altezza del frame buffer in pixel.

• format – formato dei pixel; uno dei costanti elencati sotto Costanti qui sotto. Il formato determina sia la dimensione di ciascun pixel in buffer sia come viene interpretato un intero di colore c passato a un qualsiasi metodo di disegno.

• stride – numero di pixel per riga orizzontale, incluso eventuale padding. Il valore predefinito è width. Imposta questo parametro per usare una sotto-regione di un buffer più grande.

Passare un buffer troppo piccolo, o dimensioni non valide, produrrà risultati indefiniti: il costruttore non valida ogni combinazione.

Metodi di disegno

FrameBuffer.fill(c: int) → None

Riempie l’intero frame buffer con il colore c.

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

Riempie un rettangolo w x h in (x, y) con il colore c. Equivalente a rect() con f=True.

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

Senza l’argomento c, restituisce il valore di colore del pixel in (x, y). Se c è fornito, imposta quel pixel al colore 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

Disegna una linea spessa 1 pixel nel colore c. hline() e vline() disegnano una linea orizzontale/verticale della lunghezza data; line() disegna una linea tra due punti arbitrari.

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

Disegna un rettangolo in (x, y) di dimensione w x h nel colore c. Se f è True il rettangolo viene riempito; altrimenti viene disegnato solo un contorno di 1 pixel.

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

Disegna un’ellisse centrata in (x, y) con raggio x xr e raggio y yr nel colore c. Raggi uguali producono un cerchio. f=True riempie la forma invece di disegnarne solo il contorno.

m è una bitmask che limita il disegno a quadranti specifici (numerati in senso antiorario a partire dall’alto a destra):

Bit	Quadrante	Regione
bit 0	Q1	Alto a destra
bit 1	Q2	Alto a sinistra
bit 2	Q3	Basso a sinistra
bit 3	Q4	Basso a destra

Il valore predefinito m=0 disegna tutti e quattro i quadranti.

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

Disegna un poligono chiuso arbitrario (convesso o concavo) all’offset (x, y) nel colore c. coords deve essere un array di interi a 16 bit con segno disposti come array('h', [x0, y0, x1, y1, ..., xn, yn]). f=True riempie il poligono invece di disegnarne solo il contorno.

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

Disegna la stringa s con l’angolo in alto a sinistra in (x, y) nel colore c. Il font integrato è fisso a 8x8 pixel e non può essere cambiato. c ha valore predefinito 1.

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

Sposta il contenuto del buffer di (xstep, ystep). I pixel che entrano dall’esterno del buffer non vengono cancellati, quindi un «fantasma» del contenuto precedente può rimanere sul bordo finale.

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

Disegna un altro frame buffer fbuf sopra a questo con l’angolo in alto a sinistra in (x, y).

Se key è fornito, qualsiasi pixel sorgente che corrisponde a quel valore di colore viene trattato come trasparente e non viene disegnato. Quando è fornita una palette, il confronto viene effettuato rispetto all’output della palette, non al valore grezzo di fbuf.

fbuf può essere un’istanza di FrameBuffer oppure una tupla/lista che corrisponde alla firma del costruttore:

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

Quando la sorgente è una tupla/lista, buffer può essere di sola lettura.

palette consente il blitting tra buffer di formati diversi – ad esempio, il rendering di un glifo monocromatico in un buffer RGB565. È un FrameBuffer il cui formato corrisponde alla destinazione, con altezza 1 e larghezza pari al numero di colori sorgente (2**N per una sorgente a N bit per pixel). Il valore di pixel sorgente i viene sostituito con il colore in palette[i, 0] prima del disegno.

Costanti

I seguenti valori di format sono accettati dal costruttore. La colonna «byte per pixel» è il moltiplicatore necessario per dimensionare il buffer di supporto.

Costante	Byte/pixel	Disposizione dei pixel
MONO_VLSB	0.125	Monocromatico (1 bit). Ogni byte contiene 8 pixel impilati verticalmente con il bit 0 più vicino alla cima. Le righe di 8 pixel avanzano da sinistra a destra attraverso il buffer, poi passano alla successiva riga di 8 pixel.
MONO_HLSB	0.125	Monocromatico (1 bit). Ogni byte contiene 8 pixel orizzontali con il bit 7 all’estrema sinistra. Le righe avanzano un pixel alla volta verticalmente.
MONO_HMSB	0.125	Monocromatico (1 bit). Come MONO_HLSB ma con il bit 0 all’estrema sinistra.
GS2_HMSB	0.25	Scala di grigi a 2 bit (4 livelli), impacchettata orizzontalmente con il bit più significativo per primo.
GS4_HMSB	0.5	Scala di grigi a 4 bit (16 livelli), impacchettata orizzontalmente con il nibble più significativo per primo.
GS8	1	Scala di grigi a 8 bit (256 livelli).
RGB565	2	RGB a 16 bit con 5 bit di rosso, 6 di verde e 5 di blu.

framebuf.MVLSB è un alias deprecato di framebuf.MONO_VLSB; nel nuovo codice preferisci quest’ultimo.

Costruttore legacy

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

Scorciatoia deprecata per FrameBuffer(buffer, width, height, framebuf.MONO_VLSB, stride). Mantenuta per retrocompatibilità; usa invece il costruttore completo FrameBuffer.