raylib-esp32

Raylib 6.x for ESP32 — software-rendered 2D/3D graphics on embedded SPI displays.

Runs on ESP32-S3 (and other ESP32 variants with PSRAM) using raylib's software renderer (rlsw). No GPU required.

Demo Video

Supported displays

Driver	Resolution	Notes
GC9A01	240x240	Round display, bundled driver
ST7789	up to 320x240	Uses ESP-IDF built-in driver
ILI9341	320x240	Uses ESP-IDF built-in driver

Quick start

platformio.ini

[env:esp32s3]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
framework = arduino
board = esp32-s3-devkitc-1

lib_deps =
    jensroth-pio/raylib-esp32

build_flags = -DBOARD_HAS_PSRAM
board_build.arduino.memory_type = qio_opi

main.cpp

#include <Arduino.h>
#include <raylib_esp32.h>
#include <raylib.h>

Camera3D camera = {0};

void setup() {
    raylib_esp32_display_config_t disp = {
        .driver   = RAYLIB_DRIVER_GC9A01,
        .spi_host = SPI2_HOST,
        .pin_sclk = 12, .pin_mosi = 11,
        .pin_cs   = 10, .pin_dc   = 9,
        .pin_rst  = 8,  .pin_bl   = 7,
        .width    = 240, .height  = 240,
    };
    raylib_esp32_init(&disp);
    InitWindow(240, 240, "hello");

    camera.position   = (Vector3){4, 4, 4};
    camera.target     = (Vector3){0, 0, 0};
    camera.up         = (Vector3){0, 1, 0};
    camera.fovy       = 45.0f;
    camera.projection = CAMERA_PERSPECTIVE;
}

void loop() {
    BeginDrawing();
        ClearBackground(RAYWHITE);
        BeginMode3D(camera);
            DrawCube((Vector3){0}, 2, 2, 2, RED);
            DrawCubeWires((Vector3){0}, 2, 2, 2, MAROON);
            DrawGrid(10, 1.0f);
        EndMode3D();
        DrawFPS(4, 4);
    EndDrawing();
}

Loading assets (models, textures, fonts)

1. Set board_build.filesystem = littlefs in platformio.ini.
2. Create a data/ folder in your project root with your assets.
3. Upload with pio run -t uploadfs.
4. Mount in code:

raylib_esp32_mount_fs("/data", "spiffs");  // partition label is "spiffs" even for LittleFS

5. Load normally:

Model model = LoadModel("/data/model.glb");
Texture tex = LoadTexture("/data/texture.png");

Architecture

User code (setup / loop)
  |
  +-- raylib_esp32_init()        one-call display setup
  |     +-- SPI bus init
  |     +-- Display driver       GC9A01 / ST7789 / ILI9341
  |     +-- Port layer           DMA flush, semaphore sync
  |
  +-- InitWindow()               standard raylib
  +-- BeginDrawing / EndDrawing
        |
        +-- rlsw software renderer (RGB565, 16-bit depth)
        +-- SwapScreenBuffer()   vertical flip + port flush

Memory usage (240x240 display)

Buffer	Size	Location
SW color buffer (R5G6B5)	112 KB	PSRAM
SW depth buffer (D16)	112 KB	PSRAM
Display framebuffer	112 KB	PSRAM
DMA chunk buffer	~23 KB	Internal SRAM

Total PSRAM: ~336 KB. Fits comfortably on ESP32-S3 with 2-8 MB PSRAM.

License

Raylib is licensed under the zlib/libpng license. This wrapper follows the same license.