framebuf — manipulace se snímkovým bufferem (frame buffer)

Modul framebuf poskytuje malý pixelový buffer bez alokace s primitivními kreslicími operacemi. Je určen pro řízení externích displejů (OLED, LCD, e-paper atd.).

Poznámka

Pro zpracování obrazu na zachycených snímcích použijte raději mnohem bohatší třídu image.Image od OpenMV – nabízí mnohem více kreslicích primitiv, převodů barev a analytických funkcí než 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.

Příklad:

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)

Konstruktory

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

Vytvoří objekt FrameBuffer.

• buffer – jakýkoli objekt podporující protokol buffer; musí být dostatečně velký, aby pojal stride * height pixelů ve zvoleném formátu format.

• width – šířka snímkového bufferu v pixelech.

• height – výška snímkového bufferu v pixelech.

• format – pixelový formát; jedna z konstant uvedených v sekci Konstanty níže. Formát určuje jak velikost každého pixelu v buffer, tak způsob interpretace celočíselné hodnoty barvy c předané kterékoli kreslicí metodě.

• stride – počet pixelů na vodorovný řádek, včetně případné výplně. Výchozí hodnotou je width. Nastavte tuto hodnotu pro použití podoblasti většího bufferu.

Předání buffer, který je příliš malý, nebo neplatných rozměrů povede k nedefinovaným výsledkům – konstruktor neověřuje každou kombinaci.

Kreslicí metody

FrameBuffer.fill(c: int) → None

Vyplní celý snímkový buffer barvou c.

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

Vyplní obdélník w x h na pozici (x, y) barvou c. Ekvivalent metody rect() s f=True.

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

Bez argumentu c vrátí hodnotu barvy pixelu na pozici (x, y). Pokud je c zadáno, nastaví tento pixel na barvu 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

Nakreslí čáru o tloušťce 1 pixelu v barvě c. Metody hline() a vline() kreslí vodorovnou/svislou čáru dané délky; metoda line() kreslí čáru mezi dvěma libovolnými body.

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

Nakreslí obdélník na pozici (x, y) o velikosti w x h v barvě c. Pokud je f True, je obdélník vyplněn; jinak je nakreslen pouze obrys o tloušťce 1 pixelu.

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

Nakreslí elipsu se středem v (x, y) s poloměrem xr ve směru osy x a poloměrem yr ve směru osy y v barvě c. Stejné poloměry vytvoří kruh. f=True tvar vyplní místo pouhého nakreslení obrysu.

m je bitová maska, která omezuje kreslení na konkrétní kvadranty (číslované proti směru hodinových ručiček od pravého horního):

Bit	Kvadrant	Oblast
bit 0	Q1	Vpravo nahoře
bit 1	Q2	Vlevo nahoře
bit 2	Q3	Vlevo dole
bit 3	Q4	Vpravo dole

Výchozí hodnota m=0 nakreslí všechny čtyři kvadranty.

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

Nakreslí libovolný uzavřený polygon (konvexní nebo konkávní) na offsetu (x, y) v barvě c. coords musí být array znaménkových 16bitových celých čísel uspořádané jako array('h', [x0, y0, x1, y1, ..., xn, yn]). f=True polygon vyplní místo pouhého nakreslení obrysu.

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

Nakreslí řetězec s s jeho levým horním rohem na pozici (x, y) v barvě c. Vestavěný font má pevnou velikost 8x8 pixelů a nelze jej změnit. Výchozí hodnota c je 1.

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

Posune obsah bufferu o (xstep, ystep). Pixely vstupující zvenčí bufferu se nevymažou, takže na koncové hraně může zůstat „duch“ předchozího obsahu.

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

Nakreslí další snímkový buffer fbuf přes tento s jeho levým horním rohem na pozici (x, y).

Pokud je zadáno key, je jakýkoli zdrojový pixel odpovídající této hodnotě barvy považován za průhledný a nenakreslí se. Pokud je poskytnut palette, provádí se porovnání proti výstupu palety, nikoli proti surové hodnotě fbuf.

fbuf může být instance FrameBuffer nebo n-tice/seznam odpovídající signatuře konstruktoru:

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

Pokud je zdrojem n-tice/seznam, může být buffer jen pro čtení.

palette umožňuje blitting mezi buffery různých formátů – například vykreslení monochromatického glyfu do bufferu RGB565. Jedná se o FrameBuffer, jehož formát odpovídá cíli, s výškou 1 a šířkou rovnou počtu zdrojových barev (2**N pro zdroj s N bity na pixel). Hodnota zdrojového pixelu i je před nakreslením nahrazena barvou na pozici palette[i, 0].

Konstanty

Konstruktor přijímá následující hodnoty format. Sloupec „bajtů na pixel“ je násobitel potřebný při dimenzování podkladového bufferu.

Konstanta	Bajtů/pixel	Rozložení pixelů
MONO_VLSB	0.125	Monochromatický (1bitový). Každý bajt obsahuje 8 svisle naskládaných pixelů s bitem 0 nejblíže k vrchu. Řádky po 8 pixelech postupují zleva doprava napříč bufferem a poté se zalomí na další 8pixelový řádek.
MONO_HLSB	0.125	Monochromatický (1bitový). Každý bajt obsahuje 8 vodorovných pixelů s bitem 7 nejvíce vlevo. Řádky postupují svisle po jednom pixelu.
MONO_HMSB	0.125	Monochromatický (1bitový). Jako MONO_HLSB, ale s bitem 0 nejvíce vlevo.
GS2_HMSB	0.25	2bitové stupně šedi (4 úrovně), zabalené vodorovně s nejvýznamnějším bitem napřed.
GS4_HMSB	0.5	4bitové stupně šedi (16 úrovní), zabalené vodorovně s nejvýznamnějším nibblem napřed.
GS8	1	8bitové stupně šedi (256 úrovní).
RGB565	2	16bitové RGB s 5 bity pro červenou, 6 bity pro zelenou a 5 bity pro modrou.

framebuf.MVLSB je zastaralý alias pro framebuf.MONO_VLSB; v novém kódu preferujte ten druhý.

Zastaralý konstruktor

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

Zastaralá zkratka pro FrameBuffer(buffer, width, height, framebuf.MONO_VLSB, stride). Zachována kvůli zpětné kompatibilitě; použijte raději úplný konstruktor FrameBuffer.