@tty-pt/lamina 0.0.0-stage → 1.1.0

package/dist/index.js

@@ -0,0 +1,263 @@
+import { loadWasmModule, loadNativeAddon, getSubstrate } from "@tty-pt/stele";
+import { createLaminaRenderer } from "./renderer.js";
+import { createLaminaBridge } from "./bridge.js";
+
+export { createLaminaRenderer } from "./renderer.js";
+export { createLaminaBridge } from "./bridge.js";
+
+const nativeBinding = loadNativeAddon(import.meta.url, "lamina");
+let wasmInstance = null;
+
+export function getLaminaWasm() {
+  if (wasmInstance) return wasmInstance;
+  wasmInstance = loadWasmModule(new URL("./lamina.wasm", import.meta.url));
+  return wasmInstance;
+}
+
+/**
+ * Color packing helpers
+ */
+export function rgba(r, g, b, a = 255) {
+  return (((a & 0xff) << 24) | ((b & 0xff) << 16) | ((g & 0xff) << 8) | (r & 0xff)) >>> 0;
+}
+
+export function rgb(r, g, b) {
+  return rgba(r, g, b, 255);
+}
+
+export function colorR(c) {
+  return c & 0xff;
+}
+
+export function colorG(c) {
+  return (c >> 8) & 0xff;
+}
+
+export function colorB(c) {
+  return (c >> 16) & 0xff;
+}
+
+export function colorA(c) {
+  return (c >>> 24) & 0xff;
+}
+
+/**
+ * attachCanvas: Creates an automatic hardware-accelerated WebGL / 2D renderer target for a canvas.
+ */
+export function attachCanvas(canvasEl) {
+  const renderer = createLaminaRenderer(canvasEl);
+  return {
+    isWebGL: () => renderer.isWebGL(),
+    present: (surface) => {
+      renderer.render(surface.getClampedPixels(), surface.width, surface.height);
+    },
+    destroy: () => renderer.destroy()
+  };
+}
+
+/**
+ * LaminaSurface: Pure-C immediate-mode 2D software framebuffer
+ */
+export class LaminaSurface {
+  constructor(width, height, options = {}) {
+    this.width = width;
+    this.height = height;
+    this.canvas = options.canvas || null;
+    this._renderer = null;
+
+    const wasm = getLaminaWasm();
+    this.wasmHandle = wasm.exports.lamina_surface_new(width, height);
+    if (!this.wasmHandle) {
+      throw new Error(`Failed to allocate LaminaSurface(${width}x${height})`);
+    }
+
+    if (this.canvas) {
+      this._renderer = createLaminaRenderer(this.canvas);
+    }
+  }
+
+  free() {
+    if (this._renderer) {
+      this._renderer.destroy();
+      this._renderer = null;
+    }
+    if (this.wasmHandle) {
+      const wasm = getLaminaWasm();
+      wasm.exports.lamina_surface_free(this.wasmHandle);
+      this.wasmHandle = 0;
+    }
+  }
+
+  clear(color = 0x00000000) {
+    const wasm = getLaminaWasm();
+    wasm.exports.lamina_surface_clear(this.wasmHandle, color >>> 0);
+    return this;
+  }
+
+  fill(x, y, w, h, color) {
+    const wasm = getLaminaWasm();
+    wasm.exports.lamina_surface_fill(this.wasmHandle, x, y, w, h, color >>> 0);
+    return this;
+  }
+
+  rect(x, y, w, h, color, thickness = 1) {
+    const wasm = getLaminaWasm();
+    wasm.exports.lamina_surface_rect(this.wasmHandle, x, y, w, h, color >>> 0, thickness);
+    return this;
+  }
+
+  line(x0, y0, x1, y1, color, thickness = 1) {
+    const wasm = getLaminaWasm();
+    wasm.exports.lamina_surface_line(this.wasmHandle, x0, y0, x1, y1, color >>> 0, thickness);
+    return this;
+  }
+
+  paint(x, y, color) {
+    const wasm = getLaminaWasm();
+    wasm.exports.lamina_surface_paint(this.wasmHandle, x, y, color >>> 0);
+    return this;
+  }
+
+  pick(x, y) {
+    const wasm = getLaminaWasm();
+    return wasm.exports.lamina_surface_pick(this.wasmHandle, x, y) >>> 0;
+  }
+
+  getPixels() {
+    const wasm = getLaminaWasm();
+    const ptr = wasm.exports.lamina_surface_get_pixels(this.wasmHandle);
+    const mem = (wasm.exports.memory || getSubstrate().memory).buffer;
+    return new Uint32Array(mem, ptr, this.width * this.height);
+  }
+
+  getClampedPixels() {
+    const wasm = getLaminaWasm();
+    const ptr = wasm.exports.lamina_surface_get_pixels(this.wasmHandle);
+    const mem = (wasm.exports.memory || getSubstrate().memory).buffer;
+    return new Uint8ClampedArray(mem, ptr, this.width * this.height * 4);
+  }
+
+  flush(targetCanvas = this.canvas) {
+    if (!targetCanvas) {
+      throw new Error("No canvas element specified for LaminaSurface.flush()");
+    }
+    if (!this._renderer || this.canvas !== targetCanvas) {
+      if (this._renderer) this._renderer.destroy();
+      this.canvas = targetCanvas;
+      this._renderer = createLaminaRenderer(targetCanvas);
+    }
+    this._renderer.render(this.getClampedPixels(), this.width, this.height);
+    return this;
+  }
+}
+
+/**
+ * ViewportController: Manages canvas / tilemap viewport transformations
+ */
+export class ViewportController {
+  constructor(width = 640, height = 480) {
+    this.width = width;
+    this.height = height;
+    this.cameraX = 0;
+    this.cameraY = 0;
+    this.zoom = 1.0;
+  }
+
+  setCamera(x, y, zoom = this.zoom) {
+    this.cameraX = x;
+    this.cameraY = y;
+    this.zoom = zoom;
+  }
+
+  worldToScreen(worldX, worldY) {
+    if (nativeBinding && nativeBinding.worldToScreen) {
+      return nativeBinding.worldToScreen(worldX, worldY, this.cameraX, this.cameraY, this.zoom, this.width, this.height);
+    }
+    const wasm = getLaminaWasm();
+    const outPtr = wasm.exports.malloc(16);
+    wasm.exports.lamina_wasm_world_to_screen(worldX, worldY, this.cameraX, this.cameraY, this.zoom, this.width, this.height, outPtr);
+    const mem = (wasm.exports.memory || getSubstrate().memory).buffer;
+    const arr = new Float64Array(mem, outPtr, 2);
+    const res = { x: Math.round(arr[0]), y: Math.round(arr[1]) };
+    wasm.exports.free(outPtr);
+    return res;
+  }
+
+  screenToWorld(screenX, screenY) {
+    if (nativeBinding && nativeBinding.screenToWorld) {
+      return nativeBinding.screenToWorld(screenX, screenY, this.cameraX, this.cameraY, this.zoom, this.width, this.height);
+    }
+    const wasm = getLaminaWasm();
+    const outPtr = wasm.exports.malloc(16);
+    wasm.exports.lamina_wasm_screen_to_world(screenX, screenY, this.cameraX, this.cameraY, this.zoom, this.width, this.height, outPtr);
+    const mem = (wasm.exports.memory || getSubstrate().memory).buffer;
+    const arr = new Float64Array(mem, outPtr, 2);
+    const res = { x: Math.round(arr[0]), y: Math.round(arr[1]) };
+    wasm.exports.free(outPtr);
+    return res;
+  }
+}
+
+/**
+ * FlexNode: CSS-like flexbox UI element tree layout engine
+ */
+export class FlexNode {
+  constructor(direction = "column") {
+    const wasm = getLaminaWasm();
+    const dir = direction === "row" ? 0 : 1;
+    this.wasmHandle = wasm.exports.lamina_node_new(dir);
+  }
+
+  setSize(w, h) {
+    const wasm = getLaminaWasm();
+    wasm.exports.lamina_node_set_size(this.wasmHandle, w, h);
+    return this;
+  }
+
+  setPadding(l, t, r, b) {
+    const wasm = getLaminaWasm();
+    wasm.exports.lamina_node_set_padding(this.wasmHandle, l, t, r, b);
+    return this;
+  }
+
+  setFlex(grow = 0, shrink = 1) {
+    const wasm = getLaminaWasm();
+    wasm.exports.lamina_node_set_flex(this.wasmHandle, grow, shrink);
+    return this;
+  }
+
+  addChild(child) {
+    const wasm = getLaminaWasm();
+    wasm.exports.lamina_node_add_child(this.wasmHandle, child.wasmHandle);
+    return this;
+  }
+
+  computeLayout(availableWidth, availableHeight, startX = 0, startY = 0) {
+    const wasm = getLaminaWasm();
+    wasm.exports.lamina_node_compute_layout(this.wasmHandle, startX, startY, availableWidth, availableHeight);
+    return this;
+  }
+
+  getBounds() {
+    const wasm = getLaminaWasm();
+    const outPtr = wasm.exports.malloc(32);
+    wasm.exports.lamina_node_get_bounds(this.wasmHandle, outPtr);
+    const mem = (wasm.exports.memory || getSubstrate().memory).buffer;
+    const arr = new Float64Array(mem, outPtr, 4);
+    const bounds = { x: arr[0], y: arr[1], width: arr[2], height: arr[3] };
+    wasm.exports.free(outPtr);
+    return bounds;
+  }
+
+  free() {
+    if (this.wasmHandle) {
+      const wasm = getLaminaWasm();
+      wasm.exports.lamina_node_free(this.wasmHandle);
+      this.wasmHandle = 0;
+    }
+  }
+}
+
+export function version() {
+  return "1.1.0";
+}

package/dist/renderer.js

@@ -0,0 +1,143 @@
+const VS_QUAD = `attribute vec2 a_pos;
+attribute vec2 a_uv;
+varying vec2 v_uv;
+void main() {
+	v_uv = a_uv;
+	gl_Position = vec4(a_pos, 0.0, 1.0);
+}`;
+
+const FS_QUAD = `precision mediump float;
+varying vec2 v_uv;
+uniform sampler2D u_tex;
+void main() {
+	gl_FragColor = texture2D(u_tex, v_uv);
+}`;
+
+function initGlPipeline(gl) {
+  try {
+    const vs = gl.createShader(gl.VERTEX_SHADER);
+    gl.shaderSource(vs, VS_QUAD);
+    gl.compileShader(vs);
+
+    const fs = gl.createShader(gl.FRAGMENT_SHADER);
+    gl.shaderSource(fs, FS_QUAD);
+    gl.compileShader(fs);
+
+    const prog = gl.createProgram();
+    gl.attachShader(prog, vs);
+    gl.attachShader(prog, fs);
+    gl.linkProgram(prog);
+
+    if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) {
+      return null;
+    }
+
+    gl.useProgram(prog);
+
+    const verts = new Float32Array([
+      -1.0, -1.0, 0.0, 1.0,
+       1.0, -1.0, 1.0, 1.0,
+      -1.0,  1.0, 0.0, 0.0,
+      -1.0,  1.0, 0.0, 0.0,
+       1.0, -1.0, 1.0, 1.0,
+       1.0,  1.0, 1.0, 0.0
+    ]);
+
+    const vbo = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
+    gl.bufferData(gl.ARRAY_BUFFER, verts, gl.STATIC_DRAW);
+
+    const aPos = gl.getAttribLocation(prog, "a_pos");
+    const aUv = gl.getAttribLocation(prog, "a_uv");
+    gl.enableVertexAttribArray(aPos);
+    gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 16, 0);
+    gl.enableVertexAttribArray(aUv);
+    gl.vertexAttribPointer(aUv, 2, gl.FLOAT, false, 16, 8);
+
+    const tex = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+    return { prog, vbo, tex };
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * createLaminaRenderer: Shared hardware-accelerated WebGL textured quad presentation engine
+ * with automatic fallback to HTML5 2D canvas putImageData.
+ */
+export function createLaminaRenderer(canvasEl) {
+  let gl = null;
+  let glPipe = null;
+  let canvas2d = null;
+
+  if (canvasEl && typeof canvasEl.getContext === "function") {
+    try {
+      const opts = { preserveDrawingBuffer: true, alpha: true, antialias: true };
+      gl = canvasEl.getContext("webgl2", opts) || canvasEl.getContext("webgl", opts);
+      if (gl) {
+        glPipe = initGlPipeline(gl);
+      }
+    } catch (e) {
+      gl = null;
+      glPipe = null;
+    }
+
+    if (!gl || !glPipe) {
+      gl = null;
+      glPipe = null;
+      try {
+        canvas2d = canvasEl.getContext("2d");
+      } catch (e) {
+        canvas2d = null;
+      }
+    }
+  }
+
+  return {
+    isWebGL() {
+      return Boolean(gl && glPipe);
+    },
+
+    render(rgbaBytes, width, height) {
+      if (!canvasEl) return;
+
+      if (gl && glPipe) {
+        gl.viewport(0, 0, canvasEl.width || width, canvasEl.height || height);
+        gl.useProgram(glPipe.prog);
+        gl.bindTexture(gl.TEXTURE_2D, glPipe.tex);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, rgbaBytes);
+        gl.drawArrays(gl.TRIANGLES, 0, 6);
+        return;
+      }
+
+      if (canvas2d) {
+        const clamped = rgbaBytes instanceof Uint8ClampedArray
+          ? rgbaBytes
+          : new Uint8ClampedArray(rgbaBytes.buffer, rgbaBytes.byteOffset, rgbaBytes.byteLength);
+        const imgData = typeof ImageData !== "undefined"
+          ? new ImageData(clamped, width, height)
+          : { data: clamped, width, height };
+        canvas2d.putImageData(imgData, 0, 0);
+      }
+    },
+
+    destroy() {
+      if (gl && glPipe) {
+        try {
+          gl.deleteTexture(glPipe.tex);
+          gl.deleteBuffer(glPipe.vbo);
+          gl.deleteProgram(glPipe.prog);
+        } catch (e) {}
+      }
+      gl = null;
+      glPipe = null;
+      canvas2d = null;
+    }
+  };
+}

package/include/ttypt/lam-cam.h

@@ -0,0 +1,150 @@
+/**
+ * @file lam-cam.h
+ * @brief 3D Camera, matrix math, and perspective projection for liblamina.
+ *
+ * Provides a lightweight 3D pipeline for 2.5D tilted-camera and full 3D views,
+ * including 4x4 matrix operations, camera setup, ray-plane unprojecting,
+ * ground tiles, and billboard sprites.
+ */
+
+#ifndef LAM_CAM_H
+#define LAM_CAM_H
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* 4x4 matrix in column-major order (OpenGL compatible) */
+typedef float lam_mat4_t[16];
+
+/**
+ * @brief Initialize matrix to 4x4 identity.
+ */
+void lam_mat4_identity(float m[16]);
+
+/**
+ * @brief Multiply two 4x4 matrices: out = a * b.
+ */
+void lam_mat4_mul(float out[16], const float a[16], const float b[16]);
+
+/**
+ * @brief Apply translation to matrix m.
+ */
+void lam_mat4_translate(float m[16], float x, float y, float z);
+
+/**
+ * @brief Apply scaling to matrix m.
+ */
+void lam_mat4_scale(float m[16], float sx, float sy, float sz);
+
+/**
+ * @brief Rotate matrix m around X axis by angle in radians.
+ */
+void lam_mat4_rotate_x(float m[16], float rad);
+
+/**
+ * @brief Rotate matrix m around Y axis by angle in radians.
+ */
+void lam_mat4_rotate_y(float m[16], float rad);
+
+/**
+ * @brief Rotate matrix m around Z axis by angle in radians.
+ */
+void lam_mat4_rotate_z(float m[16], float rad);
+
+/**
+ * @brief Construct standard perspective projection matrix.
+ */
+void lam_mat4_perspective(float m[16], float fov_rad, float aspect, float near_z, float far_z);
+
+/**
+ * @brief Construct standard orthographic projection matrix.
+ */
+void lam_mat4_ortho(float m[16], float l, float r, float b, float t, float n, float f);
+
+/**
+ * @brief Construct view matrix looking from eye towards target with given up vector.
+ */
+void lam_mat4_look_at(float m[16], const float eye[3], const float target[3], const float up[3]);
+
+/**
+ * @brief Invert a 4x4 matrix. Returns true on success, false if singular.
+ */
+bool lam_mat4_invert(float out[16], const float in[16]);
+
+/* Camera state descriptor */
+typedef struct {
+	float target[3];   /* Focus point in world coordinates (X, Y, Z) */
+	float distance;    /* Distance from target */
+	float pitch_deg;   /* Tilt pitch angle (degrees, e.g. 50.0) */
+	float yaw_deg;     /* Rotation yaw angle (degrees, 0 = facing north) */
+	float fov_deg;     /* Vertical FOV (degrees, e.g. 45.0) */
+	float near_z;      /* Near clipping plane (e.g. 0.1) */
+	float far_z;       /* Far clipping plane (e.g. 1000.0) */
+	int active;        /* 1 if 3D camera is currently enabled, 0 for 2D */
+
+	/* Computed matrices and vectors */
+	lam_mat4_t view;
+	lam_mat4_t proj;
+	lam_mat4_t vp;
+	lam_mat4_t inv_vp;
+	float eye[3];
+	float right[3];
+	float up[3];
+} lam_cam_t;
+
+/**
+ * @brief Configure and activate the 3D camera.
+ *
+ * @param target_x, target_y Target world coordinates on the ground plane
+ * @param distance           Camera distance / zoom
+ * @param pitch_deg          Camera tilt angle in degrees (e.g. 45..60)
+ * @param yaw_deg            Camera yaw rotation angle in degrees
+ * @param fov_deg            Field of view in degrees (e.g. 45.0)
+ */
+void (lam_cam_set_3d)(float target_x, float target_y, float distance,
+                      float pitch_deg, float yaw_deg, float fov_deg);
+
+/**
+ * @brief Restore classic 2D orthographic rendering mode.
+ */
+#undef lam_cam_set_2d
+void lam_cam_set_2d(void);
+
+/**
+ * @brief Check if 3D camera mode is currently active.
+ */
+int lam_cam_is_3d(void);
+
+/**
+ * @brief Get pointer to active camera state.
+ */
+const lam_cam_t *lam_cam_get(void);
+
+/**
+ * @brief Copy the current View-Projection matrix into out.
+ */
+void lam_cam_get_vp(float out[16]);
+
+/**
+ * @brief Get the camera right vector in world coordinates.
+ */
+void lam_cam_get_right(float r[3]);
+
+/**
+ * @brief Cast a ray from screen coordinates and find intersection with ground plane Z=0.
+ *
+ * @param screen_x, screen_y Screen pixel coordinates
+ * @param out_x, out_y       Output world coordinates on the ground plane
+ * @return 1 on intersection, 0 if parallel or pointing away
+ */
+int lam_unproject_ground(int32_t screen_x, int32_t screen_y, float *out_x, float *out_y);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LAM_CAM_H */

package/include/ttypt/lam-font.h

@@ -0,0 +1,119 @@
+#ifndef LAM_FONT_H
+#define LAM_FONT_H
+
+/**
+ * @file lam-font.h
+ * @brief Public header for the liblamina bitmap font system.
+ *
+ * Declares the API for loading, measuring and rendering
+ * bitmap-based fonts used by the liblamina rendering layer.
+ */
+
+#include <stdint.h>
+#include "./lam-ui.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @defgroup lam_font_core liblamina font management
+ *  @brief Font loading and lifecycle functions.
+ *  @{
+ */
+
+/**
+ * @brief Load a bitmap font from an image file.
+ *
+ * Loads a pre-rendered font atlas (e.g. generated from BDF)
+ * and registers it in liblamina’s internal font table.
+ *
+ * @param[in] png_path Path to the font atlas (PNG).
+ * @param[in] cell_w   Width of each glyph cell.
+ * @param[in] cell_h   Height of each glyph cell.
+ * @param[in] first    First character code in the atlas.
+ * @param[in] last     Last character code in the atlas.
+ * @return Font handle (font_ref) or CM_MISS on error.
+ */
+uint32_t lam_font_open(const char *png_path,
+		       unsigned cell_w,
+		       unsigned cell_h,
+		       uint8_t first,
+		       uint8_t last);
+
+/**
+ * @brief Unload a font and free its resources.
+ *
+ * @param[in] font_ref Font handle returned by lam_font_open().
+ */
+void lam_font_close(uint32_t font_ref);
+
+/** @} */
+
+/** @defgroup lam_font_render liblamina font rendering and measurement
+ *  @brief Functions for drawing and measuring text.
+ *  @{
+ */
+
+/**
+ * @brief Draw text using a loaded bitmap font.
+ *
+ * Renders text within the given rectangle, obeying wrapping
+ * and breaking rules. Returns a pointer to the first
+ * unrendered character if overflow occurred.
+ *
+ * @param[in] font_ref    Font handle.
+ * @param[in] text        UTF-8 text to render.
+ * @param[in] x0,y0       Top-left position (pixels).
+ * @param[in] x1,y1       Bottom-right boundary (pixels).
+ * @param[in] scale       Font scale factor.
+ * @param[in] white_space White-space handling mode (see lam_ui_white_space_t).
+ * @param[in] word_break  Word-break behavior (see lam_ui_word_break_t).
+ * @return NULL if fully rendered, or pointer to remaining text.
+ */
+const char *lam_font_draw(uint32_t font_ref,
+			  const char *text,
+			  uint32_t x0,
+			  uint32_t y0,
+			  uint32_t x1,
+			  uint32_t y1,
+			  uint32_t scale,
+			  lam_ui_white_space_t white_space,
+			  lam_ui_word_break_t word_break);
+
+/**
+ * @brief Measure text layout and overflow.
+ *
+ * Computes how text fits within the specified rectangle
+ * and returns a pointer to the first unrendered character
+ * if overflow occurred.
+ *
+ * @param[out] out_w       Optional: resulting text width in pixels.
+ * @param[out] out_h       Optional: resulting text height in pixels.
+ * @param[in]  font_ref    Font handle.
+ * @param[in]  text        UTF-8 text to measure.
+ * @param[in]  x0,y0       Top-left position (pixels).
+ * @param[in]  x1,y1       Bottom-right boundary (pixels).
+ * @param[in]  scale       Font scale factor.
+ * @param[in]  white_space White-space handling mode (see lam_ui_white_space_t).
+ * @param[in]  word_break  Word-break behavior (see lam_ui_word_break_t).
+ * @return NULL if text fully fits, or pointer to remaining text.
+ */
+const char *lam_font_measure(uint32_t *out_w,
+			     uint32_t *out_h,
+			     uint32_t font_ref,
+			     const char *text,
+			     uint32_t x0,
+			     uint32_t y0,
+			     uint32_t x1,
+			     uint32_t y1,
+			     uint32_t scale,
+			     lam_ui_white_space_t white_space,
+			     lam_ui_word_break_t word_break);
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LAM_FONT_H */