Files
lilygo-t-deck/lib/raylib-esp32/README.md
T
Dejvino 0f22c6afca Add raylib-esp32 lib and FloorPlan3D demo (3D floor plan via rlsw)
Vendor raylib-esp32 v1.0.3 (63db94b) under lib/ — raylib 6.x core with
the rlsw software renderer plus the ESP32-S3 port layer (SPI display
drivers, async double-buffered flush). raylib/examples, projects, tools
and logo are trimmed (~80 MB of content nothing here compiles); see
lib/raylib-esp32/VENDOR.md for provenance.

New floorplan3d-demo (emulator-template base) renders the NetDeck demo
map (nd_demomap.h) as a 3D floor plan — bulkhead walls, blast door,
cover crates, airlock pad, terminal — through the real on-device 3D
stack on the desktop:

- rcore_emu.c: desktop PLATFORM_CUSTOM layer mirroring rcore_esp32.c,
  flushing the RGB565 sw-renderer buffer into emuGfx::fb instead of SPI
- raylib_emu_config.h: same module/limit defines as the device build
- HUD via 3x5 bitmap font into fb: rlsw's 2D textured-quad path
  (DrawText/DrawRectangle) misplaces/flips quads and samples wrong
  atlas texels in this build; the 3D path is pixel-accurate

Verified: dual build (make netdeck) green, demo smoke test clean at
~59 FPS, 600-frame stability run OK.
2026-11-16 21:46:31 +01:00

126 lines
3.2 KiB
Markdown

# 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](https://www.youtube.com/shorts/21pVBDuoufk)
## 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
```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
```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:
```cpp
raylib_esp32_mount_fs("/data", "spiffs"); // partition label is "spiffs" even for LittleFS
```
5. Load normally:
```cpp
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.