a3d

A 3D rendering and animation component for low-poly objects on microcontrollers.
Header-only, no third-party dependency, and measured on real hardware.

Why · Install · Quickstart · Performance · Examples · Assets · What is verified

A microcontroller has no GPU. Every triangle here is set up, clipped, binned and filled by the same core that runs your application, in software, one pixel at a time. That is a slow way to draw a picture, and by any sensible engineering measure putting a 3D renderer on an MCU is a poor use of the parts.

If you want 3D and you have a choice, you almost certainly want a cheap SBC instead. A Raspberry Pi Zero 2 W costs about the same as a devkit, has a real GPU and a real OS, and will run circles around anything in the tables below. That is not a caveat buried at the bottom of this page; it is the honest first thing to say.

I built this anyway, because an animated low-poly character running on a microcontroller is a delightful thing to have. A little creature turning and walking on a 240x320 panel, driven by a part that costs a few dollars and boots in a second — that is the whole motivation. It is a toy in the good sense, and this repository is an attempt to make it a well-measured, honestly documented toy rather than a demo that works once.

So the goal here is not to compete with a GPU. It is to find out how far the idea actually goes, and to say precisely where it stops:

• On an ESP32-P4 an animated 4,672-triangle character runs at 55 fps at 240x320. There is real headroom.
• On an ESP32-S3 the same model is 24 fps. Usable, and the common case.
• On an ESP32-C6 it is 1.7 fps, because that part has no FPU and every float becomes a library call. It does not work, and the tables say so.

Every number on this page came off a board. Nothing is extrapolated, and where something has not been measured it is marked as not measured.

a3d draws animated low-poly 3D models and puts them on a panel. It is the whole path, not a piece of one:

• A binary asset container (.a3d) built from a .glb on your desktop - quantised vertices, RGB565 textures, skeleton and animation clips - read in place from memory-mapped flash, so a model costs no RAM until it is drawn.
• Skeletal animation. Clips, channels, linear and step interpolation, up to 255 bones, two weights a vertex.
• A tile binner and a software rasterizer. No GPU, no framebuffer: the screen is cut into horizontal strips and each is drawn into a small buffer and sent, so a 800x1280 panel does not need 2 MB of RAM.
• A 2D canvas with a 5x7 font, for the HUD over the top.
• A four-call wrapper (a3d::Viewer) that owns the slots, buffers, binners, camera and animation player, so a model on a screen is begin, open, frame.

It is header-only and depends on nothing but the C++17 standard library.

The core names no vendor API at all. There is no esp_lcd call, no FreeRTOS call and no vendor header in include/, in the rasterizer or in the viewer: a panel is five function pointers, and threading is one interface you implement with FreeRTOS, std::thread, or nothing. a3d_board.h detects the part it is compiled for and falls back to a conservative single-core default on anything it does not recognise, so an unknown target compiles and runs rather than failing.

That makes it portable in principle to any target with a C++17 compiler and enough RAM for one tile. Be careful with "in principle", though — this is what has actually been done:

Only two files are ESP-specific, and both are opt-in loaders you include by name: a3d_load_esp_partition.h and a3d_load_sd.h. Nothing else in the tree would stop a Cortex-M port — but nothing in the tree proves one either, and that is the difference this table exists to keep.

It is not a general 3D engine. There is no PBR, no shadow map, no post processing, no scene graph beyond a node hierarchy, and the vertex ceiling is 65,535 per mesh. It is built for the case an MCU can actually run: a low-poly character or object, animated, filling part of a small screen.

idf.py add-dependency "0015/a3d^0.9.4"

which is the same as writing it into main/idf_component.yml yourself:

dependencies:
  0015/a3d: "^0.9.4"

Then name it in your component's REQUIRES - the namespace is part of the dependency, not of the component:

idf_component_register(SRCS "main.cpp" INCLUDE_DIRS "." REQUIRES a3d)

idf.py build fetches it. a3d is header-only and registers its own include paths, so that is the whole integration.

The registry copy leaves out the Arduino examples and the README's images. To get the whole tree, or a commit that is not a release:

dependencies:
  a3d:
    git: "https://github.com/0015/a3d.git"
    version: "v0.9.4"

Pin a tag rather than a branch once you care about reproducible builds.

mkdir -p components && git clone https://github.com/0015/a3d.git components/a3d

add_subdirectory(a3d)
target_link_libraries(app PRIVATE a3d_viewer)

a3d_viewer brings the core and the rasterizer with it. Link a3d alone for the container reader and the scene runtime with no renderer.

a3d is a normal Arduino library. Put the whole repository - not just src/ - into your sketchbook's libraries/ folder under the name a3d, then restart the IDE: it reads the library index once at startup, so a library added while it is open is not found and #include <a3d.h> fails.

The sketchbook is whatever Preferences -> Sketchbook location says, so:

git clone https://github.com/0015/a3d.git "<sketchbook>/libraries/a3d"

The folder must contain library.properties at its top level and the headers in src/. Sketch -> Include Library -> a3d should then be listed, and:

#include <a3d.h>

That one include brings the container reader, the scene runtime, the rasterizer, the four-call viewer, the 2D canvas and - on ESP32 - the FreeRTOS executor. The loaders and the larger fonts are deliberately left out of it, so include those you want:

#include <loaders/a3d_load_stl.h>
#include <backends/soft/a3d_font_12x21.h>

Or download the repository as a ZIP and use Sketch -> Include Library -> Add .ZIP Library.

a3d needs one thing from your display: a function that moves a rectangle of RGB565 to it. Everything else has a default.

#include <a3d.h>
#include "model_a3d.h"          // see "no EMBED_FILES" below

static a3d::Viewer  viewer;
static a3d::Display panel;
static a3d::FreeRtosExecutor executor(A3D_CONFIG_MAX_WORKERS);   // one per core

// Must not return until `src` may be reused: a3d owns one tile buffer per
// worker and overwrites it as soon as that worker takes the next tile.
static void sendTile(void*, const uint16_t* src, int x, int y, int w, int h)
    { gfx->draw16bitBeRGBBitmap(x, y, (uint16_t*)src, w, h); }   // your driver

static uint64_t nowUs(void*) { return (uint64_t)esp_timer_get_time(); }

void setup()
    {
    gfx->begin();                                   // your driver

    panel.width  = 466;
    panel.height = 466;
    panel.sendTile = sendTile;
    panel.swapBytes = true;      // true if your panel reads big-endian RGB565

    a3d::ViewerConfig cfg;
    cfg.tileHeight = 40;         // a3d renders one strip at a time

    viewer.setExecutor(executor);   // BEFORE begin(): it decides how many
    viewer.setClock(nowUs, nullptr); //                tile buffers to allocate

    if (!viewer.begin(panel, cfg)) { Serial.println(viewer.error()); return; }

    viewer.openAsset(model_a3d, model_a3d_len);
    viewer.frameModel();                 // fit the camera to the model
    if (viewer.clipCount()) { viewer.selectClip(0); viewer.setPlaying(true); }
    }

void loop()
    {
    viewer.frame(16.0f);         // dtMs: what advances the animation
    viewer.orbit(0.02f, 0.0f);
    }

viewer.drag(dx, dy) turns it from a touch controller, and viewer.setOverlay() hands you each tile before it goes to the panel if you want a caption on it.

Getting the panel itself right is the step people stop at, and it is written out in full in docs/DISPLAY_ARDUINO.md: which entry point of your display library to call and why one of them costs a whole extra pass over the frame, the byte order that turns a black background pink, the bus mutex two workers need, where the tile buffers have to live on a board with PSRAM, and a symptom table.

On a board with PSRAM the Arduino core sends every allocation above 4 KB to the slow memory, tile framebuffers included. One line puts them back:

static void* fastAlloc(size_t n)
    { return heap_caps_malloc(n, MALLOC_CAP_INTERNAL | MALLOC_CAP_DMA | MALLOC_CAP_8BIT); }
static void  fastFree(void* p) { heap_caps_free(p); }

viewer.setAllocator(fastAlloc, fastFree);     // before begin()

Two sketches come with it:

The second renders off screen, so it uploads and runs on a board with nothing attached to it.

Arduino has no EMBED_FILES, so a container reaches a sketch one of two ways: as a byte array, or as a file.

python3 tools/a3d_export.py --header model.a3d -o model_a3d.h

#include "model_a3d.h"
viewer.openAsset(model_a3d, model_a3d_len);       // or
viewer.openAssetFile("/sd/model.a3d");            // SD.begin() first

The generated array is 4-byte aligned and that is load-bearing: a3d casts the base pointer straight to the file header, so an unaligned container is refused on the board rather than at compile time.

Arduino builds are slower than the tables below, which were measured on ESP-IDF. See Arduino is not the fast path.

lib_deps = https://github.com/0015/a3d.git

Works under framework = arduino and framework = espidf. Untested - the manifest names one include root for both, but nothing in this repository has built a PlatformIO project.

A model on a screen, in four calls. Everything else has a default.

#include "viewer/a3d_viewer.h"
#include "backends/freertos/a3d_freertos_executor.h"

// Your panel: a size and one function that moves a rectangle of RGB565.
// It must not return until `src` may be reused - see THE ONE RULE below.
void sendTile(void*, const uint16_t* src, int x, int y, int w, int h)
    { my_panel_draw(x, y, w, h, src); }

extern const uint8_t model_start[] asm("_binary_model_a3d_start");
extern const uint8_t model_end[]   asm("_binary_model_a3d_end");

extern "C" void app_main(void)
    {
    a3d::Display panel;
    panel.width    = 240;
    panel.height   = 320;
    panel.sendTile = &sendTile;

    // Built BEFORE the viewer: it is what decides how many tile buffers exist.
    static a3d::FreeRtosExecutor exec(2, 8192, 5);

    static a3d::Viewer viewer;
    viewer.setExecutor(exec);
    viewer.begin(panel);                                    // 1
    viewer.openAsset(model_start, model_end - model_start); // 2

    while (true)
        {
        viewer.frame(16.0f);                                // 3
        vTaskDelay(pdMS_TO_TICKS(16));
        }
    }

openStl(), openStlFile(), openFile() and openSphere() are the other sources. The camera frames the model on the first frame; orbit(), zoom() and setOrbit() move it after that.

THE ONE RULE. sendTile must not return until the buffer may be reused. The viewer owns one tile buffer per worker and hands it to the next tile immediately, so a driver that queues the pointer and returns will send whatever the next tile overwrote it with - half of one tile and half of the next, which reads as a rasterizer bug. If your driver is asynchronous, wait for its completion callback inside sendTile.

Every number below came off a board. The tables are generated from the device logs by a script that lives in the development tree - none of them is typed by hand, and none is an estimate.

All of them are ESP-IDF builds. An Arduino sketch is compiled differently and is slower; how much, and which part of it you can get back, is below.

Every column runs the same source above the panel: the benchmark lives in one shared component and each board supplies only a size, a sendTile and a touch read. That is the only reason a comparison between columns means anything - and it is worth saying "the same source" rather than "the same object code", because one of the five was compiled by a different ESP-IDF and the table says so directly below.

ESP32-P4 / headless was measured with a headless build of the same benchmark - the same shared demo component with no panel attached, which sends nothing to a display - so the Panel column is empty for it and it has no row in On the panel below. That build exists so a board with nothing wired to it still gets a column; the off-screen rows are the like-for-like comparison anyway, since they are the ones taken at the same viewport on every part.

Lower is better. xip = asset read in place from memory-mapped flash.

raster and clear are CORE time summed over workers, so on two workers they exceed the wall-clock frame.

The asset is only read; what changes is where the rasterizer samples the texture from.

Not comparable across boards - the resolutions differ. swap is the software byte swap a panel needs when it cannot be told to read little-endian. ESP32-P4 / headless is absent because that sweep was run headless.

bind is the vertex decode: positions, normals and texcoords go from int16 to float once, and that buffer is also where a skinned mesh writes every frame.

• The ESP32-C6 has no FPU, and that is the headline. Every float in the rasterizer becomes a libgcc call. Animated FOX at 240x320 is 27.7 ms on an S3 and 265.6 ms on a C6 - 9.6x, against a clock ratio of only 1.5x. The gap is widest where float density is highest: skinning is 2.6 ms against 60.1 ms, 23x.

• The viewport matters more than the triangle count. The rasterizer is paid per pixel. The same model is 55 fps at 240x320 and 4 fps at 800x1280.

• All five columns are ESP-IDF 5.5.4, and that took work rather than luck. The P4/JD9365 column was first captured on 6.0.2 and re-measured on 5.5.4 to join the others, because a table whose columns come from two compilers is comparing compilers.

• The two ESP32-P4 columns differ by 8.6%, and it is fully accounted for. Same silicon; the JD9365 build runs a live panel and configures a bigger L2 cache. Both were measured on the board one variable at a time:

  change	effect on frame time
  headless -> live DSI panel	+2.7% slower
  L2 cache 128 KB/64 B -> 256 KB/128 B	-11.0% faster
  product	-8.6%
  measured directly	-8.6%

  The two were measured separately and never together; their product is the direct comparison to within 0.05%. So the JD9365 column is faster off screen, and the reason is the cache setting, not the panel.

• ESP-IDF 6.0.2 is about 9% slower than 5.5.4 here. Measured twice on different builds - headless x0.908 and with the panel x0.908, agreeing to 0.05%. Every off-screen configuration got slower. The panel rows lose less, 4.6%, because they are dominated by clearing and blitting a million pixels rather than by code speed. Measured on the ESP32-P4 only; the S3 and C6 have not been checked, and nothing in a3d's own sources changed.

• The ESP32-P4's default L2 cache is the slow choice. IDF defaults to 128 KB with 64-byte lines. CONFIG_CACHE_L2_CACHE_256KB plus CONFIG_CACHE_L2_CACHE_LINE_128B double both and buy 11% of frame time - up to 28.5% on the two-worker rows, where memory pressure is highest. They cost internal SRAM, so it is a trade, but the default is not neutral.

• A live DSI panel costs about 2.7% even when nothing is sent to it, because it reads its 2 MB framebuffer out of PSRAM at ~60 Hz throughout. The rows that touch PSRAM most pay most.

• Two boards with the same silicon agree to 0.1%. The S3/ST7789 and S3/CO5300 columns are different panels on the same part, and their off-screen rows match on every configuration - 22.169 against 22.171, 19.505 against 19.528. That is the check on the method: it is what says fixing the viewport really does isolate the part from the panel.

• Wait about five seconds before believing a frame time. It falls for roughly the first five one-second windows after boot - 61, 52, 37, 32, 28 ms on one example.

• The spread of this benchmark is 0.19%, measured by flashing one binary and running it twice on an ESP32-P4: the worst row moved 0.19% and most moved less than 0.1%. That is what makes the numbers above worth quoting to three digits, and it is why the gap between the two P4 columns - up to 13%, seventy times the spread - cannot be dismissed as noise. It is also much tighter than a frame counter in an application, which drifts by more than a millisecond: the benchmark takes a median over 48 frames after discarding a warm-up budget.

Every table above is an ESP-IDF build. The same source compiled by the Arduino core is slower, and how much depends on which core release you have:

• The optimization level is recoverable, and it is the main one left. Put a file called build_opt.h next to your sketch containing one line, -O2. It is appended after the core's own flags, so it wins. Measured on 3.3.10: the Model_From_Header sketch goes from 393,400 to 424,342 bytes of flash on an ESP32-P4, which is what -O2 looks like.
• The ESP32-P4 L2 cache setting moved between core releases, so check yours. 3.2.0 shipped the ESP-IDF default, 128 KB with 64-byte lines, which this project measured on hardware as 11.0% of frame time slower than the 256 KB / 128-byte configuration its own benchmark uses. 3.3.10 ships the fast one. Either way a sketch cannot change it - it is fixed in the core's prebuilt bootloader - so the only thing to do is look: .../packages/esp32/tools/esp32p4-libs/<ver>/*/include/sdkconfig.h.
• The allocator default is worth one line of code. At 4 KB every buffer a3d asks for lands in PSRAM on a board that has it, including the tile framebuffers the rasterizer writes for every pixel of every frame. viewer.setAllocator() with heap_caps_malloc(n, MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT) puts them back; two of the sketches show it.

So: Arduino to get something on the glass, ESP-IDF when you want the frame rate. Nothing about the library changes between them - it is the same headers, the same single include root, and the same seam.

Two groups, and the directory you open says which toolchain it is for.

If you are here to learn a3d rather than to check a board, read Tutorial_01 first. Six lessons, one #define between them, from a black screen to a low-poly car on a race track that never ends: the model, a background behind it, light, the camera and animation arrive one lesson at a time, each with a picture of what the panel shows. It runs on the ESP32-P4-Nano's 10.1" panel, landscape on glass that scans portrait, and the half that knows about a3d names no vendor header, so the lessons paste into a project for any board.

The four board demos boot straight into the viewer.

cd examples/ESP-IDF/Waveshare_ESP32-S3-Touch-AMOLED-1.75C
idf.py set-target esp32s3 && idf.py -p <port> flash monitor

Use ESP-IDF 5.5.4. It is what these were built, flashed and measured on, and what every number above describes. They build and run on 6.x as well - checked on both majors before each release - but a3d measured about 9% slower on the ESP32-P4 under 6.0.2, so a 6.x build will not reproduce the tables. Each project says so at configure time.

Three of them share examples/ESP-IDF/common, which holds the whole board-independent half - loading the containers, binning, rasterizing, the on-screen HUD. A board supplies only a Display: its size, one sendTile, one touch read. That is the only reason the columns of the tables above mean anything, because every board runs the same object code above the panel.

The tables above were produced by a version of these that runs a full benchmark sweep before drawing. These do not: a three-minute sweep between power-on and the first picture is the wrong first impression. The numbers are real, they were captured on these boards, and they are not reproduced by flashing these.

The second renders off screen, which is the point: will a3d run here and how do I drive my panel are two questions, and an example that mixes them fails for whichever reason you did not expect.

Both were compiled and linked on arduino-esp32 3.3.10. Neither has been flashed, and their READMEs say so. See Arduino for installing the library, and Arduino is not the fast path before comparing anything to the tables above.

Three generated primitives, one directional light, turning slowly on a 240x320 panel. No asset files, no animation. Everything worth changing is in one SETTINGS block at the top of main/main.cpp: field of view, camera distance, light direction, ambient / diffuse / specular, spin rate, and how round the shapes are. Change a number, reflash, watch what moves.

It is also the example that shows the ST7789 trick worth knowing: a3d's framebuffer is native-endian RGB565 and an ST7789 defaults to big-endian, so every port that does not set data_endian = LCD_RGB_DATA_ENDIAN_LITTLE byte-swaps 76,800 halfwords a frame in software. One config field removes it.

Two skinned, textured, animated models on round 466x466 glass. Drag to orbit; the buttons change model, clip and distance.

Round glass is not a rectangle with a margin. At row y the glass spans 2*sqrt(R^2 - (y-R)^2), so the layout is computed per row: the caption goes top centre, because a corner is the one place on a circle guaranteed not to be glass, and the button bar became a tap-to-open overlay. A drag must not open it - dragging is how the model is turned.

The 3D view is deliberately not inset. It renders the full square and lets the corners fall off the glass, which is what a round panel is supposed to look like.

The same shared component on a single-core part with no FPU. It is here because it is the honest end of the range: RV32IMAC means every float in the rasterizer is a library call, and the numbers in the table above are what that costs. If your part is a C6, render smaller and keep the model tiny.

The same component on a 10.1" 800x1280 MIPI-DSI panel, with two workers. At that size a frame is a million pixels, and clearing them costs more than sending them: 12.5 ms of clear against 7.2 ms of blit.

One command answers the question you actually have, which is will my model run:

python3 tools/a3d_export.py --check model.glb

It imports the file, writes the .a3d, says whether it will run and on what, and draws a PNG contact sheet so you can look at the result before flashing it.

CesiumMan.glb
  animation keys 2736 -> 808 (30%) at tolerance x1
  -> CesiumMan.a3d (238,468 bytes)
  3,273 vertices, 4,672 triangles, 19 bones, 1 clip(s), 1 texture(s)
    clip 0: 'clip0'

budget: 3,273 vertices, 4,672 triangles, animated, viewport 240x320
  interpolated between two models measured on hardware; held out to +-14%. Assumes a
  model framed like a character: 23% of the viewport lit, 57% of triangles facing
  the camera. Yours will differ - a model that fills the frame costs more.

  part       cores      frame     fps  model RAM  verdict
  ESP32-C6   1           638ms     1.6       107K  TOO SLOW
  ESP32-P4   1            27ms    36.7       108K  smooth
  ESP32-P4   2            18ms    55.0       108K  smooth
  ESP32-S3   1            61ms    16.3       108K  usable
  ESP32-S3   2            44ms    22.5       108K  usable

  ESP32-C6 cannot reach 15 fps at 240x320 whatever the mesh: covering that many
    pixels already costs 126 ms. Render smaller, or cover less of the screen.

That budget is a measurement, not a guess. The per-stage costs are derived at import time from the device logs above, not stored as typed coefficients. What it cannot know is printed with it: how much of the screen your model covers and how many of its triangles face the camera.

python3 tools/a3d_export.py --project my_app --check model.glb \
        --target esp32s3 --panel spi_st7789 --touch cst816s

writes a buildable ESP-IDF project around the model - the partition sized for the asset, the sdkconfig the part needs, the EMBED_FILES symbol spelled the way the linker will spell it, and the panel glue for the bus you chose. --list-panels prints what --panel and --touch accept; --psram auto|on|off and --flash-size are the other two you are likely to want.

The generated project is a starting skeleton, not finished firmware. It cannot know your board. The pins in main/panel.c are a real, named board's and almost certainly not yours, and the ESP32 configuration is a default chosen from your target and your model's size. You must edit both to match your own hardware - pins, orientation, colour inversion, byte order and the panel init sequence. Read main/panel.c before you flash.

By default the generated app renders off screen and logs its frame rate. That is on purpose: idf.py flash monitor then works on the first try and prints the real cost of your model on your part, which beats any interpolation.

The catalogue is deliberately small: a bus is in it only if its bring-up was copied from a project that has driven real glass. Almost every board is therefore missing from it, and the way in is not a longer list.

If you already have the panel working - a vendor example, a BSP, an LVGL port, your own code - you have an esp_lcd_panel_handle_t, and that is all a3d needs:

#include "backends/esp_lcd/a3d_display_esp_lcd.h"

a3d::EspLcdDisplay glass;
a3d::EspLcdConfig  cfg;
cfg.panel  = my_panel;      // whatever your bring-up returned
cfg.io     = my_panel_io;   // the panel IO it was built on
cfg.width  = 466;
cfg.height = 466;
ESP_ERROR_CHECK(glass.begin(cfg));

viewer.begin(glass.display());

That covers every esp_lcd driver in the component registry, every vendor fork, and panels that do not exist yet.

What the adapter is actually for is the wait. esp_lcd_panel_draw_bitmap() does not finish with your buffer before it returns - on SPI, QSPI and I80 the colour transfer is queued with the DMA still reading it, and on MIPI-DSI with DMA2D the copy is asynchronous and the next call is rejected outright. a3d::Display::sendTile must not return until the buffer can be reused, because the viewer hands it to the next tile immediately. A send that does not wait puts half of one tile and half of the next on the glass, and that reads as a renderer bug rather than a driver one. The adapter registers the bus's completion callback, drains tokens left over from an earlier frame, waits with a timeout, and owns the mutex two workers need.

EspLcdWait::Auto uses the panel IO callback when you pass an IO handle. The other two modes have to be named: DpiCallback for MIPI-DSI, Synchronous for RGB parallel, where draw_bitmap really has finished on return. Auto refuses rather than guessing either - an RGB panel genuinely needs no wait, but so does a mistake.

If you would rather start from a generated project, --panel esp_lcd_custom writes a main/panel.c with one empty panel_bring_up() and everything else already written. It builds and flashes as generated and logs that the function is empty, so you are never stuck behind a project that will not compile until you have finished the hard part.

And if you would rather write it yourself, docs/DISPLAY_ESP_IDF.md is the long version: a complete SPI panel with the completion callback, what changes on MIPI-DSI, the byte order, the bus mutex, where the tile buffers have to live, what ESP-IDF 6.0 renamed, and a symptom table.

a3d draws text with a fixed-cell 1-bit bitmap font. A 5x7 is built in, and three larger sizes ship beside it - 8x14, 12x21 bold and 20x35 bold, one header each, so you pay only for the ones you include. On an 800x1280 panel the 5x7 is half a millimetre tall, which is what the larger ones are for.

#include "backends/soft/a3d_font.h"
#include "backends/soft/a3d_font_12x21.h"

a3d::drawText(fb, stride, w, h, 8, /*baseline*/ 40, "READY", 0xFFFF, a3d::kFont12x21);

tools/gen_font.py makes more from any monospace TTF you have the right to redistribute:

python3 tools/gen_font.py --size 24 --preview "Hamburg 0@"     # look first
python3 tools/gen_font.py --size 24 --output main/font_hud.h   # then keep it

Bitmaps are a derivative of the outlines they came from, so the tool refuses system fonts by name - /System/Library/Fonts and friends - and defaults to DejaVu Sans Mono. ASCII 32..126 only; there is no Unicode path. The full instructions are in docs/FONTS.md.

a3d has no alpha blending and no alpha test. Every covered pixel is written opaquely, so a glTF material with alphaMode: BLEND or MASK does not come out faint — it comes out solid. The importer warns for every such material.

This matters more than the triangle count suggests, because the shapes an artist authors for BLEND are exactly the ones meant to be nearly invisible: a propeller blur disc, a soft shadow quad, a glow card. They are large, and they sit in front of the model. On one stylized aircraft they were 40 triangles of 7,692 — and they were the first thing you saw.

The second half is worse, because it does not look like a transparency problem at all: those quads are in worldBounds() too, so they inflated the model's bounding box from 1.37 to 3.24 and pushed the framing camera 2.4x too far back. The picture does not say "something transparent is opaque", it says "my model imported tiny" — with the vertex, triangle, material and texture counts all exactly right.

python3 tools/a3d_export.py --check model.glb --drop-blend

--drop-blend leaves those primitives out. A node whose mesh loses all of them keeps its place in the hierarchy and simply draws nothing.

KHR_draco_mesh_compression is refused by name, with the command that fixes it. That is deliberate: a Draco primitive keeps its accessors and drops their bufferViews, so an importer that shrugs produces a container with the right vertex count, real materials, real textures - and every vertex at the origin. Nothing downstream can tell that from a legitimately small mesh.

gltf-transform draco model.glb out.glb --decode

This section exists because "supported" usually means "it compiled once".

• 65,535 vertices per mesh. The container indexes with uint16. Bigger meshes have to be split or decimated.
• Two bone weights per vertex, 255 bones per skeleton, one skeleton per container.
• Shading::Flat is a constant on the binned path. The rasterizer works from screen-space vertices there and cannot derive a face normal. Faceted shading comes from unwelded vertices plus Gouraud, which reads backwards and is right: with no vertex shared, each carries its own face's normal and three identical normals interpolate to a constant.
• No top-left fill rule. Measured overdraw on a back-face-culled closed mesh is exactly 1.000x, so the rule would add per-triangle setup to remove work that is not there. With setZBuffer(nullptr) a tie is settled by draw order rather than depth.
• Line art needs a dilation pass on a reflective panel. a3d draws 1px lines. A correct 3D scene measured 2.7% ink against the 17.7% of a 2D screen beside it, and on a panel with no backlight that is not "fainter", it is blank - with the geometry, the projection, the canvas contents and present() all provably right. Count dark pixels before concluding a panel is broken: "drew nothing" and "drew and the panel did not show it" have the same symptom and no overlap in where you would look.
• No PBR, shadows, post-processing or transparency sorting.

• Matrices are column-major, translation in M[12..14], matching glTF and OpenGL.
• multTranslate / multRotate / multScale pre-multiply: M = T * M. Post-multiplying makes an object orbit the origin instead of spinning in place, which reads as a wrong centre of rotation rather than a matrix bug.
• setCulling(-1) is the direction that matches the stored projection, whose y row is negated so clip space matches framebuffer rows.
• Sphere UV is u = i/sectors, v = 0.5*cos(phi) + 0.5, so v is 1 at the north pole. Equirectangular textures are authored for this.
• setZBuffer(nullptr) is a real fast path, not just a null check: it selects a template specialisation that drops depth work per pixel.
• Screen position is (ndc + 1) * half - 0.5. The - 0.5 is the part that gets dropped, and it matters: pixel centres sit at x + 0.5, and on a globe one pixel can be 20 km. Use a3d::projectToScreen() rather than restating it.

src/a3d.h           one include that brings up the renderer
src/a3d/            the core: types, math, container reader, scene runtime,
                    animation, tile binner, job interface, the panel seam
src/backends/soft/      the software rasterizer, the 2D canvas and the fonts
src/backends/freertos/  FreeRtosExecutor
src/backends/threads/   std::thread executor, for host tests
src/backends/esp_lcd/   a3d::Display from an esp_lcd panel you already have
src/loaders/        .a3d from memory, stdio, an ESP partition; STL; SD card
src/viewer/         a3d::Viewer - the four-call wrapper
tools/              the exporter chain and the host previewer
examples/ESP-IDF/   a tutorial and four boards, all run on the hardware they name
examples/Arduino/   two sketches
docs/DISPLAY_ESP_IDF.md  getting a panel lit under ESP-IDF
docs/DISPLAY_ARDUINO.md  the same under Arduino
docs/ASSET_FORMAT.md the container format

Why everything is under one src/: Arduino adds exactly <lib>/src to the include path and will not add a second root, so a library that needs two roots cannot be an Arduino library at all. One root serves both - ESP-IDF is told INCLUDE_DIRS "src" and every #include "a3d/...", "viewer/...", "backends/..." and "loaders/..." resolves from it unchanged. src/a3d.h is at the top because Arduino's resolver indexes only the headers sitting directly in src/; a library whose every header is one level down is never matched, and the error names the header rather than the library.

Why viewer/ is not in a3d/: it names SoftBackend - it owns one per tile worker - and the core's first rule is that no renderer type appears in it. src/a3d/a3d_display.h is in the core, because it names nothing: a size, a sendTile, and optional fill / touchRead / lockBus.

Apache-2.0. See LICENSE and NOTICE.

Apache rather than MIT for the clause MIT lacks: the notice must be reproduced for binary distribution, which is how a renderer actually ships.

Copyright 2026 Eric Nam.