Files
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

82 lines
3.6 KiB
Markdown

# FloorPlan3D — NetDeck demo map in real 3D (raylib-esp32 + rlsw)
A 320x240 emulator-only demo that renders the **NetDeck "Breach & Board"
demo ship** (`src/netdeck/nd_demomap.h`: airlock, L-shaped main corridor,
server room) as a 3D floor plan — bulkhead walls, blast door, cover
crates, airlock pad and terminal extruded from the 40x24 tile grid.
It is the first demo to run the **actual on-device 3D stack** on the
desktop: [raylib-esp32](https://github.com/jensroth-git/raylib-esp32)
(raylib 6.x + the `rlsw` **software renderer**, the same code that runs on
the T-Deck's ESP32-S3), vendored at `../lib/raylib-esp32`.
## Why this matters for NetDeck
Previous demos (cyberspace-demo, tron-demo) hand-rolled their 3D-ish
effects into `emuGfx::fb`. This one instead runs raylib's real 3D
pipeline (projection matrices, depth buffer, mesh batching) through
`rlsw`, with only the final display flush swapped:
| | On device (raylib-esp32) | This demo (desktop) |
|---|---|---|
| Renderer | `rlsw` software renderer, RGB565 + D16 | identical (`-DGRAPHICS_API_OPENGL_SOFTWARE`) |
| Platform layer | `src/platform/rcore_esp32.c` (SPI panel flush) | `rcore_emu.c` (blits into `emuGfx::fb`) |
| Config | `include/raylib_esp32_config.h` | `raylib_emu_config.h` (same module/limit defines) |
What renders correctly here is what the T-Deck would render — the demo
is a faithful preview of a firmware-side raylib integration.
## Build & run
```bash
make run # builds and opens a window
make smoke # headless: 240 frames, dumps smoke_frame.bmp
make clean
```
(The raylib core is compiled from `../lib/raylib-esp32/raylib/src` as C
objects in `build/`, then linked with the SDL3 host. First build takes a
few seconds longer than the plain template.)
## Controls
`a`/`d` spin the camera · `w`/`s` tilt · `q`/`e` zoom · `r` reset ·
auto-spin resumes on its own; the 10 s auto-exit safety hatch from the
template still applies (`--user-run` to disable, see template README).
## Architecture
```
emulator-template SDL3 host (src/main.cpp, shim.h)
└─ examples/FloorPlan/FloorPlan.cpp setup()/loop() sketch
├─ emu_raylib_set_framebuffer() tell the platform layer the size
├─ InitWindow/BeginDrawing/... plain raylib API
│ └─ rlsw software renderer RGB565 + D16 framebuffers
├─ rcore_emu.c (PLATFORM_CUSTOM) SwapScreenBuffer → present hook
├─ emu_raylib_present() RGB565 → emuGfx::fb (ABGR8888)
└─ HUD drawn straight into fb 3x5 bitmap font, raylib-2D-free
```
The platform layer mirrors raylib-esp32's `rcore_esp32.c`: same expected
symbols for a `PLATFORM_CUSTOM` rcore build, same `swSwapColorBuffer()`
double-buffer flow in `SwapScreenBuffer()` — only the flush target is the
emulator framebuffer instead of an SPI panel.
## Known limitation: rlsw 2D quads
The rlsw software renderer in raylib-esp32 1.0.3 misrenders the 2D
textured-quad path used by `DrawText`/`DrawRectangle`: glyph quads come
out vertically flipped and displaced, solid fills can sample wrong atlas
texels, and quad placement shifts with geometry (verified by dumping the
raw RGB565 buffer). The 3D path (cubes, planes, lines,
vertex colors, depth) is pixel-accurate. This demo therefore renders
**everything 3D through raylib** and draws the HUD with a 3x5 bitmap
font directly into `emuGfx::fb` (same approach as cyberspace-demo).
If you need raylib 2D on device, debug `rlsw`'s textured-quad sampler
first — the 3D-only workaround below sidesteps it entirely.
## License
MIT template + zlib raylib; raylib-esp32 is MIT/zlib (see
`../lib/raylib-esp32/LICENSE`).