@typecad/cuttlefish 0.1.0-alpha.1

package/dist/api/shared/display-adapter.js

@@ -0,0 +1,145 @@
+// ---------------------------------------------------------------------------
+// Display adapter generator: produces zero-cost display-specific C++ code
+// based on the display profile's driver type. The transpiler emits the
+// adapter (includes + declaration + inline functions) before the runtime
+// header, so the runtime never names a specific display class.
+//
+// To add a new display driver:
+// 1. Write a generator function matching the DisplayAdapterGenerator signature
+// 2. Register it: registerDisplayAdapter("driver-name", generator)
+// 3. Reference it from cuttlefish.config.ts: display: { profile: "driver-name-spi" }
+// ---------------------------------------------------------------------------
+// ── Adapter registry ────────────────────────────────────────────────────────
+const adapters = new Map();
+export function registerDisplayAdapter(driver, gen) {
+    adapters.set(driver, gen);
+}
+export function generateDisplayAdapter(display) {
+    const driver = display.driver;
+    const gen = adapters.get(driver);
+    if (!gen) {
+        throw new Error(`No display adapter registered for driver "${driver}". ` +
+            `Registered: ${[...adapters.keys()].join(", ")}.`);
+    }
+    return gen(display);
+}
+// ── ST7796S adapter (RGB565 + RGB666 modes) ─────────────────────────────────
+import { st7796Adapter } from "./display-adapters/st7796.js";
+registerDisplayAdapter("st7796", st7796Adapter);
+// ── eink-mono adapter (SSD1680-class, 1-bit, deferred partial refresh) ───────
+import { einkMonoAdapter } from "./display-adapters/eink-mono.js";
+registerDisplayAdapter("ssd1680", einkMonoAdapter);
+// ── SSD1309 OLED adapter (1-bit mono, I2C, page-buffered) ───────────────────
+import { ssd1309Adapter } from "./display-adapters/ssd1309.js";
+registerDisplayAdapter("ssd1309", ssd1309Adapter);
+// ── SDL2 adapter (native desktop window, RGB888) ────────────────────────────
+import { sdlAdapter } from "./display-adapters/sdl.js";
+registerDisplayAdapter("sdl", sdlAdapter);
+// ── ILI9341 adapter ─────────────────────────────────────────────────────────
+// The first built-in adapter. Mirrors the code previously hardcoded in
+// ui-emitter.ts and runtime-header.ts.
+registerDisplayAdapter("ili9341", (display) => {
+    const cs = display._mountCs;
+    const dc = display._mountDc;
+    const rst = display._mountRst;
+    const rotation = display.rotation ?? 1;
+    const spiFreq = display.spiFrequency;
+    return {
+        includes: [
+            `#define CuttlefishDisplayTarget Adafruit_GFX`,
+            `#define CuttlefishCanvas16 GFXcanvas16`,
+            `#include <Adafruit_GFX.h>`,
+            `#include <Adafruit_ILI9341.h>`,
+        ].join("\n"),
+        declaration: `Adafruit_ILI9341 __tc_display = Adafruit_ILI9341(${cs}, ${dc}, ${rst});`,
+        functions: [
+            `// --- Display adapter: ILI9341 ---`,
+            ``,
+            `static inline void display_init() {`,
+            spiFreq
+                ? `  __tc_display.begin(${spiFreq});`
+                : `  __tc_display.begin();`,
+            `  __tc_display.setRotation(${rotation});`,
+            `  __tc_display.fillScreen(0x0000);`,
+            `}`,
+            ``,
+            `static inline void display_fillScreen(uint16_t color) {`,
+            `  __tc_display.fillScreen(color);`,
+            `}`,
+            ``,
+            `static inline CuttlefishDisplayTarget* display_defaultTarget() { return &__tc_display; }`,
+            `static inline int16_t display_width() { return __tc_display.width(); }`,
+            `static inline int16_t display_height() { return __tc_display.height(); }`,
+            ``,
+            `static inline void display_startWrite() { __tc_display.startWrite(); }`,
+            `static inline void display_endWrite() { __tc_display.endWrite(); }`,
+            `static inline void display_setAddrWindow(int16_t x, int16_t y, int16_t w, int16_t h) {`,
+            `  __tc_display.setAddrWindow(x, y, w, h);`,
+            `}`,
+            `static inline void display_writePixels(uint16_t* pixels, uint32_t count) {`,
+            `  __tc_display.writePixels(pixels, count);`,
+            `}`,
+            ``,
+            `static inline CuttlefishCanvas16* display_createCanvas(int16_t w, int16_t h) {`,
+            `  return new GFXcanvas16(w, h);`,
+            `}`,
+            `static inline CuttlefishCanvas16* display_createCanvasPsram(int16_t w, int16_t h) {`,
+            `#if defined(ESP32) && defined(BOARD_HAS_PSRAM)`,
+            `  return new (ps_malloc(sizeof(GFXcanvas16))) GFXcanvas16(w, h);`,
+            `#else`,
+            `  (void)w; (void)h;`,
+            `  return nullptr;`,
+            `#endif`,
+            `}`,
+            `static inline void display_deleteCanvas(CuttlefishCanvas16* canvas) { delete canvas; }`,
+            `static inline int16_t display_canvasWidth(CuttlefishCanvas16* canvas) { return canvas->width(); }`,
+            `static inline int16_t display_canvasHeight(CuttlefishCanvas16* canvas) { return canvas->height(); }`,
+            `static inline uint16_t* display_canvasBuffer(CuttlefishCanvas16* canvas) { return canvas->getBuffer(); }`,
+            `static inline uint16_t display_canvasGetPixel(CuttlefishCanvas16* canvas, int16_t x, int16_t y) { return canvas->getPixel(x, y); }`,
+            `static inline void display_canvasFillScreen(CuttlefishCanvas16* canvas, UI_COLOR_T color) { canvas->fillScreen((uint16_t)color); }`,
+            `static inline void display_canvasFillRect(CuttlefishCanvas16* canvas, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) {`,
+            `  canvas->fillRect(x, y, w, h, (uint16_t)color);`,
+            `}`,
+            ``,
+            `static inline void display_targetDrawPixel(CuttlefishDisplayTarget* target, int16_t x, int16_t y, UI_COLOR_T color) { target->drawPixel(x, y, (uint16_t)color); }`,
+            `static inline int16_t display_targetWidth(CuttlefishDisplayTarget* target) { return target->width(); }`,
+            `static inline int16_t display_targetHeight(CuttlefishDisplayTarget* target) { return target->height(); }`,
+            `static inline void display_targetDrawRGBBitmap(CuttlefishDisplayTarget* target, int16_t x, int16_t y, const uint16_t* bitmap, int16_t w, int16_t h) {`,
+            `  target->drawRGBBitmap(x, y, bitmap, w, h);`,
+            `}`,
+            `static inline void display_targetFillRect(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) {`,
+            `  target->fillRect(x, y, w, h, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawFastHLine(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t w, UI_COLOR_T color) {`,
+            `  target->drawFastHLine(x, y, w, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawFastVLine(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t h, UI_COLOR_T color) {`,
+            `  target->drawFastVLine(x, y, h, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetFillRoundRect(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, UI_COLOR_T color) {`,
+            `  target->fillRoundRect(x, y, w, h, r, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawRect(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) {`,
+            `  target->drawRect(x, y, w, h, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawRoundRect(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, UI_COLOR_T color) {`,
+            `  target->drawRoundRect(x, y, w, h, r, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawLine(CuttlefishDisplayTarget* target, int16_t x0, int16_t y0, int16_t x1, int16_t y1, UI_COLOR_T color) {`,
+            `  target->drawLine(x0, y0, x1, y1, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetFillCircle(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t r, UI_COLOR_T color) {`,
+            `  target->fillCircle(x, y, r, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawCircle(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t r, UI_COLOR_T color) {`,
+            `  target->drawCircle(x, y, r, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetSetCursor(CuttlefishDisplayTarget* target, int16_t x, int16_t y) { target->setCursor(x, y); }`,
+            `static inline void display_targetSetTextColor(CuttlefishDisplayTarget* target, UI_COLOR_T fg) { target->setTextColor((uint16_t)fg); }`,
+            `static inline void display_targetSetTextColorBg(CuttlefishDisplayTarget* target, UI_COLOR_T fg, UI_COLOR_T bg) { target->setTextColor((uint16_t)fg, (uint16_t)bg); }`,
+            `static inline void display_targetSetTextSize(CuttlefishDisplayTarget* target, uint8_t size) { target->setTextSize(size); }`,
+            `static inline void display_targetSetTextWrap(CuttlefishDisplayTarget* target, bool wrap) { target->setTextWrap(wrap); }`,
+            `static inline void display_targetPrint(CuttlefishDisplayTarget* target, const char* text) { target->print(text); }`,
+        ].join("\n"),
+    };
+});

package/dist/api/shared/display-adapters/eink-mono.d.ts

@@ -0,0 +1,2 @@
+import type { DisplayAdapterGenerator } from "../display-adapter.js";
+export declare const einkMonoAdapter: DisplayAdapterGenerator;

package/dist/api/shared/display-adapters/eink-mono.js

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// eink-mono display adapter — 1-bit B&W e-ink panels (SSD1680-class, e.g. the
+// common 296×128 / 250×122 breakouts). Deferred refresh: no fillScreen on init
+// (a full clear flashes), and a partial-refresh entry point the runtime's dirty-
+// rect union calls once per frame.
+//
+// Library note: targets Adafruit_EPD (Adafruit_SSD168x). The exact partial-
+// refresh method name varies by library (Adafruit_EPD: refreshPartial / GxEPD:
+// updateWindow). Verify against the target library before flashing — the shim
+// shape is correct; the method call is library-specific. TODO Phase 5.
+// ---------------------------------------------------------------------------
+export const einkMonoAdapter = (display) => {
+    const cs = display._mountCs;
+    const dc = display._mountDc;
+    const rst = display._mountRst;
+    const rotation = display.rotation ?? 0;
+    const w = display.width;
+    const h = display.height;
+    return {
+        includes: [
+            "#include <Adafruit_GFX.h>",
+            "#include <Adafruit_EPD.h>",
+        ].join("\n"),
+        // busy pin = -1 (unused); SRCS+D/C+RST+CS wiring. Adafruit_SSD168x(width, height, dc, rst, cs, busy).
+        declaration: `Adafruit_SSD168x __tc_display(${w}, ${h}, ${dc}, ${rst}, ${cs}, -1);`,
+        functions: [
+            "// --- Display adapter: eink-mono (SSD1680-class, 1-bit, deferred refresh) ---",
+            "static inline void display_init() {",
+            "  __tc_display.begin();",
+            `  __tc_display.setRotation(${rotation});`,
+            "  // No full-screen clear here — e-ink flashes on a full clear. The runtime",
+            "  // marks all nodes dirty (UI_REFRESH_DEFERRED) and the first flush repaints",
+            "  // via partial refresh instead.",
+            "}",
+            "",
+            "static inline CuttlefishDisplayTarget* display_defaultTarget() { return &__tc_display; }",
+            "static inline int16_t display_width() { return __tc_display.width(); }",
+            "static inline int16_t display_height() { return __tc_display.height(); }",
+            "static inline void display_startWrite() {}",
+            "static inline void display_endWrite() {}",
+            "static inline void display_setAddrWindow(int16_t x, int16_t y, int16_t w, int16_t h) { (void)x; (void)y; (void)w; (void)h; }",
+            // Partial refresh: push just the dirty region. The runtime draws into the
+            // EPD's built-in GFX buffer (the display IS the backing store for 1-bit),
+            // then calls this with the unioned dirty rect. TODO Phase 5: verify the
+            // exact partial-refresh API for the target EPD library.
+            "static inline void display_partial_refresh(int16_t x, int16_t y, int16_t w, int16_t h) {",
+            "  __tc_display.refreshPartial(x, y, (uint16_t)w, (uint16_t)h);",
+            "}",
+            // drawPixel goes through GFX into the EPD buffer; partial_refresh publishes it.
+            "static inline void display_fillScreen(uint32_t color) { __tc_display.fillScreen(color ? EPD_WHITE : EPD_BLACK); }",
+        ].join("\n"),
+    };
+};

package/dist/api/shared/display-adapters/sdl.d.ts

@@ -0,0 +1,2 @@
+import type { DisplayAdapterGenerator } from "../display-adapter.js";
+export declare const sdlAdapter: DisplayAdapterGenerator;