Fontes

As fontes no Lopaka são específicas de cada plataforma. Cada biblioteca de destino tem seu próprio formato de fonte e seu próprio conjunto de fontes integradas — você não pode misturar fontes livremente entre plataformas. Esta página explica quais formatos de fonte cada plataforma usa, como escolher e importar fontes no editor e o que acontece com sua escolha de fonte quando você gera código.

Formatos de fonte

O Lopaka trabalha internamente com três formatos de fonte:

Formato	Descrição	Usado por
BDF	Bitmap Distribution Format — um padrão de fonte bitmap em texto simples	U8g2, CircuitPython
GFX	Adafruit GFX — um cabeçalho C (.h) com um array de bitmap e uma tabela de glifos	TFT_eSPI, AdafruitGFX, ArduinoGFX, GxEPD2
TTF / OTF / WOFF	Fontes vetoriais TrueType e OpenType	LVGL, ESPHome

Algumas plataformas (Flipper Zero, MicroPython) não usam nenhum desses formatos — suas fontes são fixas e compiladas dentro da própria biblioteca. Elas são abordadas nas seções de plataformas abaixo.

Quando você envia uma fonte personalizada, o Lopaka a converte para o formato que a plataforma ativa precisa — você nunca precisa lidar com a conversão manualmente (com algumas exceções descritas abaixo).

Importar uma fonte personalizada

Para importar uma fonte, selecione uma camada de texto, abra o menu suspenso de fontes no Inspetor e clique em Importar fonte…. Escolha um arquivo no seu sistema de arquivos. O que acontece em seguida depende do formato do arquivo e da plataforma ativa.

Cabeçalho GFX (.h)

Compatível com: TFT_eSPI, AdafruitGFX, ArduinoGFX, GxEPD2

O arquivo é usado como está, sem conversão. Depois do envio, a fonte fica disponível na lista de fontes e seus dados de bitmap são incorporados ao código gerado.

Fonte BDF

Compatível com: U8g2, TFT_eSPI, AdafruitGFX, ArduinoGFX, GxEPD2

• Na U8g2 — o arquivo é enviado diretamente. Caracteres não compatíveis no título da fonte são substituídos quando o Lopaka gera o símbolo C e o nome do arquivo .h.
• Em plataformas baseadas em GFX — o arquivo BDF é convertido automaticamente para o formato GFX antes do envio. A conversão cobre o intervalo ASCII imprimível (0x20–0x7E). O resultado é tratado de forma idêntica a uma fonte GFX nativa.

TTF / OTF / WOFF

Compatível com: U8g2, TFT_eSPI, AdafruitGFX, ArduinoGFX, GxEPD2

Enviar uma fonte vetorial abre o Assistente de fontes:

1. Altura da fonte — defina a altura de destino em pixels. Isso controla como os glifos são rasterizados. Valores menores produzem bitmaps compactos; valores maiores produzem glifos mais nítidos ao custo de mais memória flash.
2. Zoom da pré-visualização — dimensione a pré-visualização (1×–5×) para inspecionar o resultado. Isso não afeta a saída.
3. Clique em Importar — a fonte é rasterizada e salva no projeto.

O assistente cobre apenas o ASCII imprimível (espaço até til, 95 caracteres). Caracteres estendidos, letras acentuadas e glifos CJK não são incluídos na saída.

Tamanho e escala da fonte

Plataforma	Controle de tamanho	Como funciona
U8g2	Nenhum — escolha outra fonte	Cada fonte BDF tem um tamanho fixo
TFT_eSPI / AdafruitGFX / ArduinoGFX / GxEPD2	Escala inteira (1×, 2×, …)	Dobra os pixels do bitmap
LVGL	Nenhum — Montserrat fixa	Estágio inicial; sem controles de tamanho ou fonte
ESPHome	Numérico livre (px)	Define o campo size: no YAML
Flipper Zero	Nenhum	Fontes fixas do sistema
MicroPython / CircuitPython	Nenhum	Uma única fonte integrada

O que acaba no código gerado

Plataformas baseadas em GFX

Para cada fonte GFX que não seja a fonte integrada 5×7 da Adafruit, o gerador insere:

#include <Fonts/FontName.h>
const GFXfont *font_FontName = &FontName;

Se a mesma fonte for usada por mais de uma camada, a declaração é deduplicada — ela aparece uma vez.

U8g2

Somente o identificador da fonte aparece em linha:

u8g2.setFont(u8g2_font_helvB08_tr);

Sem cabeçalho e sem variável.

Flipper Zero

A constante da fonte é incorporada diretamente:

canvas_set_font(canvas, FontPrimary);

ESPHome

Um bloco font: é adicionado à raiz do documento YAML. Várias camadas de texto que usam tamanhos diferentes da mesma fonte produzem entradas separadas.

LVGL

A fonte integrada Montserrat é referenciada diretamente. Nenhuma variável de fonte ou include é emitida.

Dicas práticas

• Tamanho mínimo legível em OLEDs monocromáticos. Fontes BDF de 4–6 px são tecnicamente válidas, mas ficam difíceis de ler em hardware real. 8 px (por exemplo, helvB08) é o mínimo prático para a maioria dos displays.
• Orçamento de RAM para fontes GFX. Cada fonte GFX que você inclui ocupa flash no microcontrolador. A FreeMono12pt7b tem cerca de 1,7 KB; a FreeMonoBold24pt7b tem cerca de 4,5 KB. Verifique as restrições de flash do seu dispositivo antes de adicionar fontes grandes.
• Cobertura de caracteres de fontes personalizadas. Os conversores BDF→GFX e de importação de fontes vetoriais do Lopaka codificam apenas o intervalo ASCII imprimível (espaço 0x20 até til 0x7E, 95 caracteres). Para uma cobertura estendida na U8g2, importe um BDF que contenha esses glifos. Para plataformas GFX, use um arquivo .h pré-compilado que já os contenha.
• Fontes personalizadas precisam corresponder à plataforma do projeto. As fontes enviadas são armazenadas como recursos do projeto — uma fonte GFX .h não funcionará na U8g2, e uma fonte BDF não funcionará na TFT_eSPI.

Fontes por plataforma

U8g2

A U8g2 vem com uma grande coleção de fontes derivadas de BDF compiladas diretamente na biblioteca. O Lopaka expõe essa coleção completa no seletor de fontes. Os nomes das fontes no código gerado seguem o esquema de nomes da própria biblioteca:

u8g2.setFont(u8g2_font_haxrcorp4089_tr);

Nenhum dado de fonte é emitido no seu sketch — o nome sozinho basta, porque a fonte já está dentro da biblioteca U8g2. As fontes integradas da U8g2 também são omitidas de Configurações de código → Fontes, porque não há um arquivo adicional para baixar.

O tamanho da fonte é fixo. Cada fonte BDF tem uma única altura de pixel incorporada. Para exibir um texto maior, você precisa escolher outra fonte, não dimensionar a atual.

Enviar fontes personalizadas: a U8g2 aceita arquivos .bdf, .ttf, .otf e .woff. Os arquivos BDF são importados diretamente. As fontes vetoriais abrem o Assistente de fontes, em que você escolhe uma altura fixa em pixels antes de o Lopaka convertê-las para BDF. O Lopaka armazena o BDF resultante inalterado para pré-visualizações e edição. As fontes personalizadas aparecem em Configurações de código → Fontes, onde você pode baixar cada uma como um arquivo .h da U8g2.

Por padrão, o cabeçalho baixado contém todos os glifos do BDF. Ative Renderizar somente os glifos usados para incluir apenas os caracteres Unicode usados por camadas de texto e de área de texto que referenciam essa fonte. Se qualquer camada desse tipo usar texto de variável em tempo de execução, o Lopaka exporta a fonte completa para que caracteres de tempo de execução desconhecidos não sejam omitidos.

Com Incluir fontes ativado, o código-fonte gerado da tela inclui cada cabeçalho de fonte baixado.

TFT_eSPI, AdafruitGFX, ArduinoGFX, GxEPD2

Todas essas plataformas usam o formato de fonte Adafruit GFX — um arquivo de cabeçalho C que incorpora os dados de bitmap diretamente. O conjunto integrado inclui a fonte Adafruit 5×7 e dezenas de fontes da família Free em vários tamanhos (FreeMono, FreeSans, FreeSerif em regular, negrito, itálico e negrito-itálico em 9, 12, 18 e 24 pt, e mais).

A fonte 5×7 é o padrão da própria biblioteca. Ela não exige uma declaração de cabeçalho. Para as outras fontes, o que o gerador coloca antes depende de onde os dados da fonte vêm:

Plataforma	Fontes que vêm com a biblioteca	Outras fontes (enviadas ou não presentes na biblioteca)
TFT_eSPI	FreeMono/FreeSans/FreeSerif em 9, 12, 18 e 24 pt: sem #include, a TFT_eSPI as compila com LOAD_GFXFF; não listadas para download	#include "FontName.h"
AdafruitGFX, GxEPD2, Inkplate	A família Free, Org_01, Picopixel, Tiny3x3a2pt7b e TomThumb: #include <Fonts/FontName.h> da biblioteca Adafruit GFX	#include "FontName.h"
ArduinoGFX	—	#include "FontName.h" para cada fonte

A chamada de texto então referencia o símbolo da fonte diretamente:

#include <Fonts/FreeMono12pt7b.h>
// ...
display.setFont(&FreeMono12pt7b);

Para cada #include "FontName.h", baixe o cabeçalho em Configurações de código → Fontes e coloque-o ao lado do seu sketch.

O tamanho da fonte é escalável. As fontes GFX oferecem suporte a um multiplicador de escala inteiro. Um multiplicador de 1 renderiza no tamanho de pixel nativo; 2 dobra as duas dimensões.

Ajuste da posição Y. As fontes GFX usam uma linha de base descendente — a coordenada Y se refere à linha de base, não ao topo do glifo. O Lopaka compensa automaticamente quando você arrasta texto na tela de desenho e emite a coordenada corrigida no código gerado.

Enviar fontes personalizadas. Aceita arquivos .h (cabeçalho GFX pré-compilado), .bdf, .ttf, .otf e .woff.

• .h — usado como está, sem conversão.
• .bdf — convertido para o formato GFX automaticamente antes do envio.
• .ttf / .otf / .woff — abre o assistente de fontes (consulte acima).

LVGL

O suporte à LVGL no Lopaka está em estágio inicial. No momento, apenas uma fonte está disponível — a Montserrat integrada — em tamanho fixo. Os controles de seleção e tamanho de fonte não são expostos. Isso será expandido em uma versão futura.

ESPHome

O ESPHome resolve fontes do Google Fonts em tempo de compilação. O YAML gerado contém um bloco font: que baixa a fonte por nome quando você grava o dispositivo:

font:
    - file: gfonts://Roboto
      id: font_roboto
      size: 16

O tamanho da fonte é configurável. As fontes disponíveis são as fontes TTF incluídas no conjunto integrado do Lopaka (Roboto, Montserrat, Ubuntu e outras). O envio de fontes personalizadas não é compatível com o ESPHome.

Flipper Zero e Flipper One

O Flipper oferece exatamente quatro fontes do sistema:

Nome no Lopaka	Constante do Flipper	Uso típico
Primary	FontPrimary	Texto regular da interface
Secondary	FontSecondary	Rótulos secundários pequenos
Keyboard	FontKeyboard	Teclado na tela
Big Numbers	FontBigNumbers	Exibição de dígitos grandes

Não há controles de tamanho nem envio de fontes personalizadas.

MicroPython

O MicroPython usa uma única fonte integrada fixa (Petme 8×8). Todas as camadas de texto a usam automaticamente.

CircuitPython

O CircuitPython usa a fonte BDF Terminus. O envio de fontes personalizadas não é compatível.