framebuf — manipulação de frame buffer

O módulo framebuf fornece um pequeno buffer de pixels sem alocação, com operações primitivas de desenho. Ele é destinado ao controle de displays externos (OLEDs, LCDs, e-paper, etc.).

Nota

Para trabalho de processamento de imagem em quadros capturados, use a classe image.Image da OpenMV, muito mais rica – ela oferece muito mais primitivas de desenho, conversões de cor e recursos de análise do que 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.

Exemplo:

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)

Construtores

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

Constrói um objeto FrameBuffer.

• buffer – qualquer objeto que suporte o protocolo de buffer; deve ser grande o suficiente para conter stride * height pixels no format escolhido.

• width – largura do frame buffer em pixels.

• height – altura do frame buffer em pixels.

• format – formato de pixel; uma das constantes listadas em Constantes abaixo. O formato determina tanto o tamanho de cada pixel em buffer quanto como um inteiro de cor c passado a qualquer método de desenho é interpretado.

• stride – número de pixels por linha horizontal, incluindo qualquer preenchimento. Tem width como valor padrão. Defina isso para usar uma sub-região de um buffer maior.

Passar um buffer pequeno demais, ou dimensões inválidas, produzirá resultados indefinidos – o construtor não valida todas as combinações.

Métodos de desenho

FrameBuffer.fill(c: int) → None

Preenche todo o frame buffer com a cor c.

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

Preenche um retângulo w x h em (x, y) com a cor c. Equivalente a rect() com f=True.

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

Sem o argumento c, retorna o valor de cor do pixel em (x, y). Com c informado, define esse pixel para a cor 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

Desenha uma linha de 1 pixel de espessura na cor c. hline() e vline() desenham uma linha horizontal/vertical do comprimento informado; line() desenha uma linha entre dois pontos arbitrários.

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

Desenha um retângulo em (x, y) de tamanho w x h na cor c. Se f for True, o retângulo é preenchido; caso contrário, apenas um contorno de 1 pixel é desenhado.

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

Desenha uma elipse centrada em (x, y) com raio em x xr e raio em y yr na cor c. Raios iguais produzem um círculo. f=True preenche a forma em vez de apenas contorná-la.

m é uma máscara de bits que restringe o desenho a quadrantes específicos (numerados no sentido anti-horário a partir do superior direito):

Bit	Quadrante	Região
bit 0	Q1	Superior direito
bit 1	Q2	Superior esquerdo
bit 2	Q3	Inferior esquerdo
bit 3	Q4	Inferior direito

O padrão m=0 desenha todos os quatro quadrantes.

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

Desenha um polígono fechado arbitrário (convexo ou côncavo) no offset (x, y) na cor c. coords deve ser um array de inteiros de 16 bits com sinal, dispostos como array('h', [x0, y0, x1, y1, ..., xn, yn]). f=True preenche o polígono em vez de apenas contorná-lo.

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

Desenha a string s com seu canto superior esquerdo em (x, y) na cor c. A fonte embutida é fixa em 8x8 pixels e não pode ser alterada. c tem 1 como valor padrão.

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

Desloca o conteúdo do buffer em (xstep, ystep). Os pixels que entram a partir de fora do buffer não são limpos, de modo que um “fantasma” do conteúdo anterior pode permanecer na borda final.

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

Desenha outro frame buffer fbuf sobre este, com seu canto superior esquerdo em (x, y).

Se key for informado, qualquer pixel de origem que corresponda a esse valor de cor é tratado como transparente e não é desenhado. Quando uma palette é fornecida, a comparação é feita em relação à saída da paleta, não ao valor bruto de fbuf.

fbuf pode ser uma instância de FrameBuffer ou uma tupla/lista correspondente à assinatura do construtor:

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

Quando a origem é uma tupla/lista, buffer pode ser somente leitura.

palette permite o blitting entre buffers de formatos diferentes – por exemplo, renderizar um glifo monocromático em um buffer RGB565. É um FrameBuffer cujo formato corresponde ao destino, com altura 1 e largura igual ao número de cores da origem (2**N para uma origem de N bits por pixel). O valor de pixel de origem i é substituído pela cor em palette[i, 0] antes do desenho.

Constantes

Os seguintes valores de format são aceitos pelo construtor. A coluna “bytes por pixel” é o multiplicador necessário ao dimensionar o buffer de apoio.

Constante	Bytes/pixel	Layout de pixel
MONO_VLSB	0.125	Monocromático (1 bit). Cada byte armazena 8 pixels empilhados verticalmente, com o bit 0 mais próximo do topo. Linhas de 8 pixels avançam da esquerda para a direita pelo buffer e então passam para a próxima linha de 8 pixels.
MONO_HLSB	0.125	Monocromático (1 bit). Cada byte armazena 8 pixels horizontais, com o bit 7 mais à esquerda. As linhas avançam um pixel por vez verticalmente.
MONO_HMSB	0.125	Monocromático (1 bit). Como MONO_HLSB, mas com o bit 0 mais à esquerda.
GS2_HMSB	0.25	Escala de cinza de 2 bits (4 níveis), empacotada horizontalmente com o bit mais significativo primeiro.
GS4_HMSB	0.5	Escala de cinza de 4 bits (16 níveis), empacotada horizontalmente com o nibble mais significativo primeiro.
GS8	1	Escala de cinza de 8 bits (256 níveis).
RGB565	2	RGB de 16 bits com 5 bits de vermelho, 6 de verde e 5 de azul.

framebuf.MVLSB é um alias obsoleto de framebuf.MONO_VLSB; prefira o segundo em código novo.

Construtor legado

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

Atalho obsoleto para FrameBuffer(buffer, width, height, framebuf.MONO_VLSB, stride). Mantido por compatibilidade retroativa; use o construtor completo FrameBuffer em vez dele.