framebuf — manipulação de buffer de fotograma

O módulo framebuf fornece um pequeno buffer de pixels sem alocações, com operações de desenho primitivas. Destina-se ao controlo de ecrãs externos (OLEDs, LCDs, e-paper, etc.).

Nota

Para processamento de imagem em fotogramas capturados, utilize a classe image.Image do OpenMV, muito mais completa – oferece muito mais primitivas de desenho, conversões de cor e funcionalidades de análise do que framebuf.

class FrameBuffer

Um FrameBuffer envolve um objeto que suporta o protocolo de buffer fornecido pelo utilizador (tipicamente um bytearray) e expõe métodos para desenhar pixels, linhas, retângulos, elipses, polígonos, texto e outros FrameBuffers no seu interior.

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 suficientemente grande para conter stride * height pixels no format escolhido.

• width – largura do buffer de fotograma em pixels.

• height – altura do buffer de fotograma em pixels.

• format – formato de pixel; um das constantes listadas em Constantes abaixo. O formato determina tanto o tamanho de cada pixel no buffer como a forma 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. Por omissão é width. Defina este valor para usar uma sub-região de um buffer maior.

Passar um buffer demasiado pequeno, 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 buffer de fotograma com a cor c.

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

Preenche um retângulo de 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 argumento c, devolve o valor de cor do pixel em (x, y). Com c fornecido, define esse pixel com 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 com 1 pixel de espessura na cor c. hline() e vline() desenham uma linha horizontal/vertical com o comprimento dado; 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 é desenhado um contorno de 1 pixel.

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 x xr e raio y yr na cor c. Raios iguais produzem um círculo. f=True preenche a forma em vez de apenas a contornar.

m é uma máscara de bits que restringe o desenho a quadrantes específicos (numerados no sentido contrário ao dos ponteiros do relógio a partir do canto 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 valor padrão m=0 desenha 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) com deslocamento (x, y) na cor c. coords deve ser um array de inteiros com sinal de 16 bits dispostos como array('h', [x0, y0, x1, y1, ..., xn, yn]). f=True preenche o polígono em vez de apenas o contornar.

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

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

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

Desloca o conteúdo do buffer em (xstep, ystep). Os pixels deslocados para dentro a partir do exterior do buffer não são limpos, pelo que pode permanecer um «fantasma» do conteúdo anterior na aresta traseira.

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

Desenha outro buffer de fotograma fbuf sobre este com o canto superior esquerdo em (x, y).

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

fbuf pode ser uma instância de FrameBuffer ou um tuplo/lista que corresponda à assinatura do construtor:

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

Quando a origem é um tuplo/lista, buffer pode ser só de leitura.

palette permite fazer blit entre buffers de formatos diferentes – por exemplo, renderizar um glifo monocromático num buffer RGB565. É um FrameBuffer cujo formato corresponde ao destino, com altura 1 e largura igual ao número de cores de 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 aceites pelo construtor. A coluna «bytes por pixel» é o multiplicador necessário ao dimensionar o buffer de suporte.

Constante	Bytes/pixel	Disposição de pixels
MONO_VLSB	0.125	Monocromático (1 bit). Cada byte contém 8 pixels empilhados verticalmente com o bit 0 mais próximo do topo. As linhas de 8 pixels avançam da esquerda para a direita no buffer e depois passam para a linha seguinte de 8 pixels.
MONO_HLSB	0.125	Monocromático (1 bit). Cada byte contém 8 pixels horizontais com o bit 7 mais à esquerda. As linhas avançam um pixel de cada 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 cinzentos de 2 bits (4 níveis), compactado horizontalmente com o bit mais significativo em primeiro lugar.
GS4_HMSB	0.5	Escala de cinzentos de 4 bits (16 níveis), compactado horizontalmente com o nibble mais significativo em primeiro lugar.
GS8	1	Escala de cinzentos de 8 bits (256 níveis).
RGB565	2	RGB de 16 bits com 5 bits de vermelho, 6 bits de verde e 5 bits de azul.

framebuf.MVLSB é um alias obsoleto de framebuf.MONO_VLSB; prefira o último 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 para compatibilidade retroativa; utilize o construtor completo de FrameBuffer em alternativa.