@micahdb/tscon 0.0.0-stage → 0.1.0

package/dist/terminal.d.ts

@@ -0,0 +1,92 @@
+import { Canvas } from "./canvas.ts";
+import type { Glyphs } from "./glyphs.ts";
+import type { Rect } from "./rect.ts";
+/**
+ * Renders a character grid from glyphs onto a {@link Canvas}.
+ *
+ * `Terminal` owns a `rows` x `cols` framebuffer of packed 16-bit glyph
+ * cells (as produced by {@link textGlyphs}) and draws it one instanced
+ * quad per cell. A frame is typically: {@link clear}, {@link blit} one or
+ * more {@link Glyphs} blocks onto the framebuffer, then {@link draw}.
+ *
+ * If {@link detail_text} is set, it is rendered onto the last row as a
+ * status line each frame.
+ */
+export declare class Terminal {
+    private gl_program;
+    private attributes;
+    private uniforms;
+    private vao;
+    private vbo;
+    private fbcon;
+    private resized;
+    private last_detail_text;
+    private detail_glyphs;
+    /** The {@link Canvas} this terminal renders into. */
+    canvas: Canvas;
+    /**
+     * Status text shown on the bottom row, or `""` for none.
+     *
+     * When non-empty it is compiled to glyphs (with a bright-on-black
+     * style) and blitted across the last row each {@link draw}. Components
+     * use this to show hover details, link URLs, etc.
+     */
+    detail_text: string;
+    /**
+     * Whether to use {@link Canvas.user_font} for non-box glyphs when
+     * available. Set to `true` by the application after assigning a font
+     * texture to `canvas.user_font`; automatically falls back to the bitmap
+     * font if `user_font` is `null`.
+     */
+    use_user_font: boolean;
+    /**
+     * Initializes the terminal for use.
+     * Listens for `"resize"` events from the canvas.
+     *
+     * @param canvas  The canvas to render into.
+     */
+    constructor(canvas: Canvas);
+    /**
+     * Copy a region of a {@link Glyphs} block onto the console framebuffer.
+     *
+     * `src` selects the region of `glyphs` to copy and `dst` selects where
+     * on the console it goes. `src` and `dst` must be the same size;
+     * otherwise the blit is skipped. Both rectangles are clipped to their
+     * respective bounds, with negative origins handled by shifting both
+     * `src` and `dst` together, so partial off-screen copies work as
+     * expected.
+     *
+     * This only writes to the in-memory framebuffer; call {@link draw} to
+     * rasterise it.
+     *
+     * @example
+     * ```ts
+     * terminal.blit(content,
+     *   { row: 0, col: 0, rows: content.rows, cols: content.cols },
+     *   { row: 2, col: 4, rows: content.rows, cols: content.cols });
+     * ```
+     *
+     * @param glyphs  Source glyph grid.
+     * @param src     Region of `glyphs` to copy.
+     * @param dst     Destination region on the console.
+     */
+    blit(glyphs: Glyphs, src: Rect, dst: Rect): void;
+    /**
+     * Clears the framebuffer. If the canvas has been resized since the
+     * last clear, the framebuffer is reallocated to the new `rows` x
+     * `cols` size. Resets {@link detail_text} to `""`.
+     *
+     * Call at the start of each frame, before blitting content.
+     */
+    clear(): void;
+    /**
+     * Rasterise the console framebuffer to the canvas.
+     *
+     * If {@link detail_text} changed since the last draw it is recompiled
+     * to glyphs and blitted across the bottom row. Then the framebuffer
+     * is uploaded and drawn.
+     *
+     * Call this once per frame after all {@link blit} calls are done.
+     */
+    draw(): void;
+}

package/dist/terminal.js

@@ -0,0 +1,275 @@
+import { terminal_frag, terminal_vert } from "./shaders.js";
+import { Canvas } from "./canvas.js";
+import { textGlyphs } from "./glyphs.js";
+import { compileProgram, getAttribLocations, getUniformLocations, } from "./program.js";
+/**
+ * Renders a character grid from glyphs onto a {@link Canvas}.
+ *
+ * `Terminal` owns a `rows` x `cols` framebuffer of packed 16-bit glyph
+ * cells (as produced by {@link textGlyphs}) and draws it one instanced
+ * quad per cell. A frame is typically: {@link clear}, {@link blit} one or
+ * more {@link Glyphs} blocks onto the framebuffer, then {@link draw}.
+ *
+ * If {@link detail_text} is set, it is rendered onto the last row as a
+ * status line each frame.
+ */
+export class Terminal {
+    gl_program;
+    attributes;
+    uniforms;
+    vao;
+    vbo;
+    // framebuffer of console characters
+    fbcon;
+    resized;
+    last_detail_text;
+    detail_glyphs;
+    /** The {@link Canvas} this terminal renders into. */
+    canvas;
+    /**
+     * Status text shown on the bottom row, or `""` for none.
+     *
+     * When non-empty it is compiled to glyphs (with a bright-on-black
+     * style) and blitted across the last row each {@link draw}. Components
+     * use this to show hover details, link URLs, etc.
+     */
+    detail_text;
+    /**
+     * Whether to use {@link Canvas.user_font} for non-box glyphs when
+     * available. Set to `true` by the application after assigning a font
+     * texture to `canvas.user_font`; automatically falls back to the bitmap
+     * font if `user_font` is `null`.
+     */
+    use_user_font;
+    /**
+     * Initializes the terminal for use.
+     * Listens for `"resize"` events from the canvas.
+     *
+     * @param canvas  The canvas to render into.
+     */
+    constructor(canvas) {
+        this.canvas = canvas;
+        const gl = canvas.gl;
+        this.fbcon = new Uint16Array(0);
+        this.last_detail_text = "";
+        this.detail_glyphs = null;
+        this.detail_text = "";
+        this.gl_program = compileProgram(gl, terminal_vert, terminal_frag);
+        this.attributes = getAttribLocations(gl, this.gl_program, {
+            colour: "a_colour",
+            char_code: "a_char_code",
+        });
+        this.uniforms = getUniformLocations(gl, this.gl_program, {
+            rows: "u_rows",
+            cols: "u_cols",
+            mouse_row: "u_mouse_row",
+            mouse_col: "u_mouse_col",
+            palette: "u_palette",
+            bitmap_font: "u_bitmap_font",
+            user_font: "u_user_font",
+            use_user_font: "u_use_user_font",
+        });
+        const vao = gl.createVertexArray();
+        this.vao = vao;
+        if (!vao) {
+            throw new Error("Could not create vertex array object");
+        }
+        gl.bindVertexArray(vao);
+        const vbo = gl.createBuffer();
+        this.vbo = vbo;
+        if (!vbo) {
+            throw new Error("Could not create vertex buffer");
+        }
+        gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
+        // every vertex in the VBO is a 16-bit integer split like so:
+        // [ a_colour | a_char_code ]
+        // [ 8 bits   | 8 bits      ]
+        // a_colour
+        gl.vertexAttribIPointer(this.attributes.colour, 1, gl.UNSIGNED_BYTE, 2, 1);
+        gl.vertexAttribDivisor(this.attributes.colour, 1);
+        gl.enableVertexAttribArray(this.attributes.colour);
+        // a_char_code
+        gl.vertexAttribIPointer(this.attributes.char_code, 1, gl.UNSIGNED_BYTE, 2, 0);
+        gl.vertexAttribDivisor(this.attributes.char_code, 1);
+        gl.enableVertexAttribArray(this.attributes.char_code);
+        gl.bindVertexArray(null);
+        gl.useProgram(this.gl_program);
+        gl.uniform1i(this.uniforms.rows, this.canvas.rows);
+        gl.uniform1i(this.uniforms.cols, this.canvas.cols);
+        gl.uniform1i(this.uniforms.mouse_row, -1);
+        gl.uniform1i(this.uniforms.mouse_col, -1);
+        gl.uniform3fv(this.uniforms.palette, this.canvas.palette);
+        gl.uniform1i(this.uniforms.bitmap_font, 0);
+        gl.uniform1i(this.uniforms.user_font, 1);
+        gl.uniform1i(this.uniforms.use_user_font, 0);
+        this.resized = true;
+        this.use_user_font = false;
+        this.canvas.addEventListener("resize", () => {
+            this.resized = true;
+        });
+    }
+    /**
+     * Copy a region of a {@link Glyphs} block onto the console framebuffer.
+     *
+     * `src` selects the region of `glyphs` to copy and `dst` selects where
+     * on the console it goes. `src` and `dst` must be the same size;
+     * otherwise the blit is skipped. Both rectangles are clipped to their
+     * respective bounds, with negative origins handled by shifting both
+     * `src` and `dst` together, so partial off-screen copies work as
+     * expected.
+     *
+     * This only writes to the in-memory framebuffer; call {@link draw} to
+     * rasterise it.
+     *
+     * @example
+     * ```ts
+     * terminal.blit(content,
+     *   { row: 0, col: 0, rows: content.rows, cols: content.cols },
+     *   { row: 2, col: 4, rows: content.rows, cols: content.cols });
+     * ```
+     *
+     * @param glyphs  Source glyph grid.
+     * @param src     Region of `glyphs` to copy.
+     * @param dst     Destination region on the console.
+     */
+    blit(glyphs, src, dst) {
+        // validate the input rects
+        if (src.rows !== dst.rows || src.cols !== dst.cols) {
+            console.log("Terminal.blit: not blitting due to bad src or dst");
+            return;
+        }
+        // handle negatives
+        if (src.row < 0) {
+            const drow = Math.abs(src.row);
+            src.row = 0;
+            src.rows -= drow;
+            dst.row += drow;
+            dst.rows -= drow;
+        }
+        if (src.col < 0) {
+            const dcol = Math.abs(src.col);
+            src.col = 0;
+            src.cols -= dcol;
+            dst.col += dcol;
+            dst.cols -= dcol;
+        }
+        if (dst.row < 0) {
+            const drow = Math.abs(dst.row);
+            src.row += drow;
+            src.rows -= drow;
+            dst.row = 0;
+            dst.rows -= drow;
+        }
+        if (dst.col < 0) {
+            const dcol = Math.abs(dst.col);
+            src.col += dcol;
+            src.cols -= dcol;
+            dst.col = 0;
+            dst.cols -= dcol;
+        }
+        // handle overflow
+        if (dst.row + dst.rows > this.canvas.rows) {
+            const extra_rows = dst.row + dst.rows -
+                this.canvas.rows;
+            dst.rows -= extra_rows;
+            src.rows = dst.rows;
+        }
+        if (dst.col + dst.cols > this.canvas.cols) {
+            const extra_cols = dst.col + dst.cols -
+                this.canvas.cols;
+            dst.cols -= extra_cols;
+            src.cols = dst.cols;
+        }
+        for (let row = 0;; row++) {
+            const src_row = row + src.row;
+            const dst_row = row + dst.row;
+            if (src_row >= src.row + src.rows ||
+                dst_row >= dst.row + dst.rows) {
+                break;
+            }
+            const src_idx = src_row * glyphs.cols + src.col;
+            const dst_idx = dst_row * this.canvas.cols + dst.col;
+            this.fbcon.set(glyphs.data.subarray(src_idx, src_idx + src.cols), dst_idx);
+        }
+    }
+    /**
+     * Clears the framebuffer. If the canvas has been resized since the
+     * last clear, the framebuffer is reallocated to the new `rows` x
+     * `cols` size. Resets {@link detail_text} to `""`.
+     *
+     * Call at the start of each frame, before blitting content.
+     */
+    clear() {
+        const gl = this.canvas.gl;
+        if (this.resized) {
+            this.resized = false;
+            gl.useProgram(this.gl_program);
+            gl.uniform1i(this.uniforms.rows, this.canvas.rows);
+            gl.uniform1i(this.uniforms.cols, this.canvas.cols);
+            this.fbcon = new Uint16Array(this.canvas.rows * this.canvas.cols);
+        }
+        this.fbcon.fill(0);
+        this.detail_text = "";
+    }
+    /**
+     * Rasterise the console framebuffer to the canvas.
+     *
+     * If {@link detail_text} changed since the last draw it is recompiled
+     * to glyphs and blitted across the bottom row. Then the framebuffer
+     * is uploaded and drawn.
+     *
+     * Call this once per frame after all {@link blit} calls are done.
+     */
+    draw() {
+        if (this.last_detail_text !== this.detail_text) {
+            this.last_detail_text = this.detail_text;
+            if (this.detail_text.length > 0) {
+                this.detail_glyphs = textGlyphs("\\B0\\F7" + this.detail_text, this.detail_text.length, false);
+            }
+            else {
+                this.detail_glyphs = null;
+            }
+        }
+        if (this.detail_text.length > 0 &&
+            this.detail_glyphs !== null) {
+            this.blit(this.detail_glyphs, {
+                row: 0,
+                col: 0,
+                rows: 1,
+                cols: this.detail_glyphs.cols,
+            }, {
+                row: this.canvas.rows - 1,
+                col: 0,
+                rows: 1,
+                cols: this.detail_glyphs.cols,
+            });
+        }
+        const gl = this.canvas.gl;
+        gl.useProgram(this.gl_program);
+        // set mouse position uniforms
+        gl.uniform1i(this.uniforms.mouse_row, this.canvas.mouse_row ?? -1);
+        gl.uniform1i(this.uniforms.mouse_col, this.canvas.mouse_col ?? -1);
+        // upload glyph data to the GPU
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.vbo);
+        gl.bufferData(gl.ARRAY_BUFFER, this.fbcon, gl.DYNAMIC_DRAW);
+        // bind and activate the bitmap font
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.canvas.bitmap_font);
+        // user application-provided font
+        if (this.use_user_font) {
+            gl.uniform1i(this.uniforms.use_user_font, 1);
+        }
+        if (this.canvas.user_font !== null) {
+            gl.activeTexture(gl.TEXTURE1);
+            gl.bindTexture(gl.TEXTURE_2D, this.canvas.user_font);
+        }
+        else if (this.use_user_font) {
+            this.use_user_font = false;
+            gl.uniform1i(this.uniforms.use_user_font, 0);
+        }
+        // draw glyphs: generate 6 vertices (two triangles = one quad) per glyph instance
+        gl.bindVertexArray(this.vao);
+        gl.drawArraysInstanced(gl.TRIANGLES, 0, 6, this.canvas.rows * this.canvas.cols);
+        gl.bindVertexArray(null);
+    }
+}

package/dist/texture.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Load an image file from `path` into a mipmapped, linearly-filtered WebGL2
+ * texture.
+ *
+ * The image is decoded via an `Image` element, uploaded to the GL context as
+ * an `RGBA`/`UNSIGNED_BYTE` texture with premultiplied alpha, and given
+ * `LINEAR_MIPMAP_LINEAR` minification and `LINEAR` magnification filtering so
+ * it can be sampled at arbitrary sizes by a shader.
+ *
+ * The returned texture is suitable for use as the `texture` argument of
+ * {@link Renderer.draw} (e.g. a photograph, portrait or rendered scene) or
+ * as the `canvas.user_font` application-provided font texture.
+ *
+ * @example
+ * ```ts
+ * import { Canvas, loadTexture } from "@micahdb/tscon";
+ *
+ * const canvas = new Canvas(element);
+ * const texture = await loadTexture(canvas.gl, "/images/portrait.jpeg");
+ * ```
+ *
+ * @param gl    The WebGL2 context to create the texture on.
+ * @param path  URL/path of the image to load.
+ * @returns     A promise that resolves with the created `WebGLTexture` once
+ *              the image has been decoded and uploaded.
+ */
+export declare function loadTexture(gl: WebGL2RenderingContext, path: string): Promise<WebGLTexture>;
+/**
+ * Load six images into a mipmapped cube-map texture.
+ *
+ * Cube maps are used for environment/skybox rendering. The six faces must be
+ * supplied in the standard OpenGL cube-map face order:
+ *
+ * 1. positive X (right)
+ * 2. negative X (left)
+ * 3. positive Y (top)
+ * 4. negative Y (bottom)
+ * 5. positive Z (front)
+ * 6. negative Z (back)
+ *
+ * The resulting texture uses `LINEAR_MIPMAP_LINEAR` / `LINEAR` filtering and is
+ * suitable for sampling with `samplerCube` in a shader.
+ *
+ * @example
+ * ```ts
+ * import { Canvas, loadCubeMap } from "@micahdb/tscon";
+ *
+ * const canvas = new Canvas(element);
+ * const skybox = await loadCubeMap(canvas.gl, [
+ *   "/images/skybox/right.png",
+ *   "/images/skybox/left.png",
+ *   "/images/skybox/top.png",
+ *   "/images/skybox/bottom.png",
+ *   "/images/skybox/front.png",
+ *   "/images/skybox/back.png",
+ * ]);
+ * ```
+ *
+ * @param gl     The WebGL2 context to create the texture on.
+ * @param faces  Exactly six image URLs, one per cube-map face
+ *              (see order above).
+ * @returns      A promise that resolves with the created cube-map texture.
+ * @throws       If `faces` does not contain exactly six entries or the GL
+ *              texture cannot be created.
+ */
+export declare function loadCubeMap(gl: WebGL2RenderingContext, faces: string[]): Promise<WebGLTexture>;

package/dist/texture.js

@@ -0,0 +1,119 @@
+/**
+ * Load an image file from `path` into a mipmapped, linearly-filtered WebGL2
+ * texture.
+ *
+ * The image is decoded via an `Image` element, uploaded to the GL context as
+ * an `RGBA`/`UNSIGNED_BYTE` texture with premultiplied alpha, and given
+ * `LINEAR_MIPMAP_LINEAR` minification and `LINEAR` magnification filtering so
+ * it can be sampled at arbitrary sizes by a shader.
+ *
+ * The returned texture is suitable for use as the `texture` argument of
+ * {@link Renderer.draw} (e.g. a photograph, portrait or rendered scene) or
+ * as the `canvas.user_font` application-provided font texture.
+ *
+ * @example
+ * ```ts
+ * import { Canvas, loadTexture } from "@micahdb/tscon";
+ *
+ * const canvas = new Canvas(element);
+ * const texture = await loadTexture(canvas.gl, "/images/portrait.jpeg");
+ * ```
+ *
+ * @param gl    The WebGL2 context to create the texture on.
+ * @param path  URL/path of the image to load.
+ * @returns     A promise that resolves with the created `WebGLTexture` once
+ *              the image has been decoded and uploaded.
+ */
+export function loadTexture(gl, path) {
+    return new Promise((resolve, reject) => {
+        const image = new Image();
+        image.src = path;
+        image.onload = () => {
+            const tex = gl.createTexture();
+            if (!tex) {
+                reject(new Error("When creating GL texture"));
+                return;
+            }
+            gl.bindTexture(gl.TEXTURE_2D, tex);
+            // prevent texture halos/outlines from filtering
+            gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
+            gl.generateMipmap(gl.TEXTURE_2D);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+            resolve(tex);
+        };
+    });
+}
+/**
+ * Load six images into a mipmapped cube-map texture.
+ *
+ * Cube maps are used for environment/skybox rendering. The six faces must be
+ * supplied in the standard OpenGL cube-map face order:
+ *
+ * 1. positive X (right)
+ * 2. negative X (left)
+ * 3. positive Y (top)
+ * 4. negative Y (bottom)
+ * 5. positive Z (front)
+ * 6. negative Z (back)
+ *
+ * The resulting texture uses `LINEAR_MIPMAP_LINEAR` / `LINEAR` filtering and is
+ * suitable for sampling with `samplerCube` in a shader.
+ *
+ * @example
+ * ```ts
+ * import { Canvas, loadCubeMap } from "@micahdb/tscon";
+ *
+ * const canvas = new Canvas(element);
+ * const skybox = await loadCubeMap(canvas.gl, [
+ *   "/images/skybox/right.png",
+ *   "/images/skybox/left.png",
+ *   "/images/skybox/top.png",
+ *   "/images/skybox/bottom.png",
+ *   "/images/skybox/front.png",
+ *   "/images/skybox/back.png",
+ * ]);
+ * ```
+ *
+ * @param gl     The WebGL2 context to create the texture on.
+ * @param faces  Exactly six image URLs, one per cube-map face
+ *              (see order above).
+ * @returns      A promise that resolves with the created cube-map texture.
+ * @throws       If `faces` does not contain exactly six entries or the GL
+ *              texture cannot be created.
+ */
+export async function loadCubeMap(gl, faces) {
+    if (faces.length !== 6) {
+        throw new Error("Cube map requires exactly 6 faces");
+    }
+    const texture = gl.createTexture();
+    if (!texture) {
+        throw new Error("When creating cube map texture");
+    }
+    gl.bindTexture(gl.TEXTURE_CUBE_MAP, texture);
+    const targets = [
+        gl.TEXTURE_CUBE_MAP_POSITIVE_X,
+        gl.TEXTURE_CUBE_MAP_NEGATIVE_X,
+        gl.TEXTURE_CUBE_MAP_POSITIVE_Y,
+        gl.TEXTURE_CUBE_MAP_NEGATIVE_Y,
+        gl.TEXTURE_CUBE_MAP_POSITIVE_Z,
+        gl.TEXTURE_CUBE_MAP_NEGATIVE_Z,
+    ];
+    const promises = faces.map(async (path, index) => {
+        const image = new Promise((resolve, reject) => {
+            const img = new Image();
+            img.src = path;
+            img.onload = () => resolve(img);
+            img.onerror = (err) => reject(new Error(`When loading image at ${path}`, { cause: err }));
+        });
+        const img = await image;
+        gl.bindTexture(gl.TEXTURE_CUBE_MAP, texture);
+        gl.texImage2D(targets[index], 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
+    });
+    await Promise.all(promises);
+    gl.generateMipmap(gl.TEXTURE_CUBE_MAP);
+    gl.texParameteri(gl.TEXTURE_CUBE_MAP, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+    gl.texParameteri(gl.TEXTURE_CUBE_MAP, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    return texture;
+}

package/package.json

@@ -1,6 +1,45 @@
 {
-  "name": "@micahdb/tscon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@micahdb/tscon",
+	"version": "0.1.0",
+	"description": "WebGL 2.0 text-mode graphics in TypeScript.",
+	"license": "MIT",
+	"author": "Micah Baker",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/micahdbak/tscon.git"
+	},
+	"keywords": [
+		"webgl",
+		"webgl2",
+		"text-mode",
+		"terminal",
+		"console",
+		"cp437",
+		"typography",
+		"canvas"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"lint": "oxlint src scripts",
+		"shaders": "bun run scripts/shaders.ts",
+		"build": "tsc -p tsconfig.json",
+		"prepack": "bun run build"
+	},
+	"devDependencies": {
+		"oxlint": "^1.88.0",
+		"typescript": "^7.0.2"
+	}
+}