framebuf — manipularea tamponului de cadre (frame buffer)

Modulul framebuf oferă un tampon de pixeli mic, fără alocare, cu operații primitive de desenare. Este destinat acționării afișajelor externe (OLED-uri, LCD-uri, e-paper etc.).

Notă

Pentru prelucrarea imaginilor pe cadrele capturate, folosiți în schimb clasa mult mai bogată image.Image a OpenMV – aceasta oferă mult mai multe primitive de desenare, conversii de culoare și funcții de analiză decât 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.

Exemplu:

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)

Constructori

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

Construiește un obiect FrameBuffer.

• buffer – orice obiect care acceptă protocolul de tampon; trebuie să fie suficient de mare pentru a conține stride * height pixeli în formatul format ales.

• width – lățimea tamponului de cadre în pixeli.

• height – înălțimea tamponului de cadre în pixeli.

• format – formatul pixelilor; una dintre constantele enumerate sub Constante mai jos. Formatul determină atât dimensiunea fiecărui pixel din buffer, cât și modul în care un întreg de culoare c transmis oricărei metode de desenare este interpretat.

• stride – numărul de pixeli pe rând orizontal, inclusiv orice umplutură. Implicit este width. Setați acest parametru pentru a utiliza o subregiune a unui tampon mai mare.

Transmiterea unui buffer care este prea mic sau a unor dimensiuni nevalide va produce rezultate nedefinite – constructorul nu validează fiecare combinație.

Metode de desenare

FrameBuffer.fill(c: int) → None

Umple întregul tampon de cadre cu culoarea c.

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

Umple un dreptunghi w x h la (x, y) cu culoarea c. Echivalent cu rect() cu f=True.

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

Fără argumentul c, returnează valoarea de culoare a pixelului la (x, y). Cu c dat, setează acel pixel la culoarea 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

Desenează o linie groasă de 1 pixel în culoarea c. hline() și vline() desenează o linie orizontală/verticală de lungimea dată; line() desenează o linie între două puncte arbitrare.

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

Desenează un dreptunghi la (x, y) de dimensiune w x h în culoarea c. Dacă f este True, dreptunghiul este umplut; altfel se desenează doar un contur de 1 pixel.

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

Desenează o elipsă centrată pe (x, y) cu raza pe x xr și raza pe y yr în culoarea c. Raze egale produc un cerc. f=True umple forma în loc de a-i desena doar conturul.

m este o mască de biți care restricționează desenarea la cadrane specifice (numerotate în sens antiorar începând din dreapta-sus):

Bit	Cadran	Regiune
bit 0	Q1	Dreapta-sus
bit 1	Q2	Stânga-sus
bit 2	Q3	Stânga-jos
bit 3	Q4	Dreapta-jos

Valoarea implicită m=0 desenează toate cele patru cadrane.

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

Desenează un poligon închis arbitrar (convex sau concav) la offsetul (x, y) în culoarea c. coords trebuie să fie un array de întregi cu semn pe 16 biți, dispuși ca array('h', [x0, y0, x1, y1, ..., xn, yn]). f=True umple poligonul în loc de a-i desena doar conturul.

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

Desenează șirul s cu colțul din stânga-sus la (x, y) în culoarea c. Fontul încorporat este fix la 8x8 pixeli și nu poate fi schimbat. c este implicit 1.

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

Deplasează conținutul tamponului cu (xstep, ystep). Pixelii care intră din afara tamponului nu sunt șterși, așa că o „fantomă” a conținutului anterior poate rămâne la marginea de ieșire.

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

Desenează un alt tampon de cadre fbuf peste acesta, cu colțul din stânga-sus la (x, y).

Dacă key este dat, orice pixel sursă care corespunde acelei valori de culoare este tratat ca transparent și nu este desenat. Când este furnizată o palette, comparația se face cu ieșirea paletei, nu cu valoarea brută fbuf.

fbuf poate fi o instanță FrameBuffer sau un tuplu/listă care corespunde semnăturii constructorului:

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

Când sursa este un tuplu/listă, buffer poate fi doar pentru citire.

palette permite blitting între tampoane de formate diferite – de exemplu, randarea unui glif monocrom într-un tampon RGB565. Este un FrameBuffer al cărui format corespunde destinației, cu înălțimea 1 și lățimea egală cu numărul de culori sursă (2**N pentru o sursă de N biți pe pixel). Valoarea pixelului sursă i este înlocuită cu culoarea de la palette[i, 0] înainte de desenare.

Constante

Următoarele valori format sunt acceptate de constructor. Coloana „octeți pe pixel” este multiplicatorul necesar la dimensionarea tamponului de stocare.

Constantă	Octeți/pixel	Dispunerea pixelilor
MONO_VLSB	0.125	Monocrom (1 bit). Fiecare octet conține 8 pixeli stivuiți vertical, cu bitul 0 cel mai aproape de partea de sus. Rândurile de 8 pixeli avansează de la stânga la dreapta de-a lungul tamponului, apoi se înfășoară la următorul rând de 8 pixeli.
MONO_HLSB	0.125	Monocrom (1 bit). Fiecare octet conține 8 pixeli orizontali, cu bitul 7 cel mai la stânga. Rândurile avansează câte un pixel pe verticală.
MONO_HMSB	0.125	Monocrom (1 bit). Asemănător cu MONO_HLSB, dar cu bitul 0 cel mai la stânga.
GS2_HMSB	0.25	Tonuri de gri pe 2 biți (4 niveluri), împachetate orizontal cu bitul cel mai semnificativ primul.
GS4_HMSB	0.5	Tonuri de gri pe 4 biți (16 niveluri), împachetate orizontal cu nibble-ul cel mai semnificativ primul.
GS8	1	Tonuri de gri pe 8 biți (256 de niveluri).
RGB565	2	RGB pe 16 biți cu 5 biți roșu, 6 biți verde și 5 biți albastru.

framebuf.MVLSB este un alias depreciat pentru framebuf.MONO_VLSB; preferați-l pe acesta din urmă în codul nou.

Constructor moștenit

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

Scurtătură depreciată pentru FrameBuffer(buffer, width, height, framebuf.MONO_VLSB, stride). Păstrată pentru compatibilitate retroactivă; folosiți în schimb constructorul complet FrameBuffer.