textmode.js 0.2.1-beta.6 → 0.2.1-beta.7

package/dist/types/textmode/TextmodeImage.d.ts

@@ -1,16 +1,38 @@
 import type { GLRenderer } from '../rendering/webgl/Renderer';
 /**
- * TextmodeImage represents an image source uploaded to a WebGL texture.
- * It can be drawn via the textmode image() API, which resizes into the MRT pipeline.
+ * Consolidated render data for TextmodeImage
+ */
+export interface TextmodeImageRenderData {
+    texture: WebGLTexture;
+    invert: number;
+    flipX: number;
+    flipY: number;
+    charRotation: [number, number];
+    charColorFixed: boolean;
+    charColor: [number, number, number];
+    cellColorFixed: boolean;
+    cellColor: [number, number, number];
+    backgroundColor: [number, number, number, number];
+    charCount: number;
+    charList: number[][];
+}
+/**
+ * Represents an image uploaded for textmode rendering via {@link Textmodifier.loadImage}.
+ *
+ * It can be drawn to the canvas via {@link Textmodifier.image}.
+ *
+ * An image uploaded currently runs through an adjustable brightness-converter that converts
+ * the original image into a textmode representation using characters.
+ * Those adjustable options are available via chainable methods on this class.
  */
 export declare class TextmodeImage {
     /**
      * Underlying WebGL texture handle.
      */
-    readonly texture: WebGLTexture;
+    private _texture;
     /** Original pixel dimensions of the source image. */
-    readonly width: number;
-    readonly height: number;
+    private _width;
+    private _height;
     private _gl;
     private _invert;
     private _flipX;
@@ -23,70 +45,117 @@ export declare class TextmodeImage {
     private _backgroundColor;
     private _glyphColors;
     private _glyphColorResolver;
+    /**
+     * Create a new TextmodeImage instance.
+     * @param gl WebGL2 rendering context
+     * @param texture WebGL texture containing the image
+     * @param width Original image width in pixels
+     * @param height Original image height in pixels
+     *
+     * @ignore
+     */
     constructor(gl: WebGL2RenderingContext, texture: WebGLTexture, width: number, height: number);
-    /** Dispose of GPU resources. */
+    /**
+     * Dispose of GPU resources.
+     * @ignore
+     */
     $dispose(): void;
     /** Normalize boolean | number to 0/1 */
     private _to01;
     /**
-     * Invert the image colors indicator flag to pass into MRT transform (stored in o_transform.r).
-     * Does not modify the source texture pixels; downstream stages can respond accordingly.
+     * Set the invert flag.
+     *
+     * Setting this flag to `true` will swap the character and cell colors when rendering the image.
+     *
+     * @param v Flag value
+     * @returns This instance for chaining.
      */
     invert(v?: boolean | number): this;
     /**
-     * Set horizontal flip indicator flag (stored in o_transform.g).
+     * Set horizontal flip indicator flag.
+     * @param v Flag value
+     * @returns This instance for chaining.
      */
     flipX(v?: boolean | number): this;
     /**
-     * Set vertical flip indicator flag (stored in o_transform.b).
+     * Set vertical flip indicator flag.
+     * @param v Flag value
+     * @returns This instance for chaining.
      */
     flipY(v?: boolean | number): this;
     /**
-     * Set character rotation in degrees, encoded into two channels as in RenderState.
+     * Set the character rotation in degrees.
+     * @param degrees Rotation in degrees *(0-360)*
+     * @returns This instance for chaining.
      */
     charRotation(degrees: number): this;
-    /** Snapshot of flags for renderer uniform binding */
-    get flags(): Readonly<{
-        invert: number;
-        flipX: number;
-        flipY: number;
-    }>;
-    /** Encoded (r,g) rotation channels */
-    get charRotationRG(): Readonly<[number, number]>;
-    /** Set character color mode: 'sampled' (from image) or 'fixed' (use charColor) */
+    /**
+     * Get all render data needed by the GLRenderer.
+     * @ignore
+     */
+    $getRenderData(): TextmodeImageRenderData;
+    /**
+     * Set character color mode: `'sampled'` *(from image)* or `'fixed'` *(use {@link charColor})*.
+     * @param mode
+     * @returns
+     */
     charColorMode(mode: 'sampled' | 'fixed'): this;
-    /** Set cell color mode: 'sampled' (from image) or 'fixed' (use cellColor) */
+    /**
+     * Set the cell color mode: `'sampled'` *(from image)* or `'fixed'` *(use {@link cellColor})*.
+     * @param mode
+     * @returns
+     */
     cellColorMode(mode: 'sampled' | 'fixed'): this;
-    /** Set fixed character color; numbers are 0..255 like other APIs */
+    /**
+     * Defines the character color used when {@link charColorMode} is `'fixed'`.
+     * @param r Red channel (0-255)
+     * @param g Green channel (0-255)
+     * @param b Blue channel (0-255)
+     * @returns This instance for chaining.
+     */
     charColor(r: number, g?: number, b?: number): this;
-    /** Set fixed cell color; numbers are 0..255 like other APIs */
+    /**
+     * Defines the cell color used when {@link cellColorMode} is `'fixed'`.
+     * @param r Red channel (0-255)
+     * @param g Green channel (0-255)
+     * @param b Blue channel (0-255)
+     * @returns This instance for chaining.
+     */
     cellColor(r: number, g?: number, b?: number): this;
-    /** Set background color for transparent pixels; numbers are 0..255 like other APIs */
+    /**
+     * Set background color for transparent pixels.
+     * @param r Red channel (0-255)
+     * @param g Green channel (0-255)
+     * @param b Blue channel (0-255)
+     * @param a Alpha channel (0-255)
+     * @returns This instance for chaining.
+     */
     background(r: number, g?: number, b?: number, a?: number): this;
     /**
-     * Define the characters to use for brightness mapping, as a string.
-     * The string will be translated to glyph shader colors externally and stored here (max 64).
-     * Note: In this core class we only accept the precomputed colors via a helper; the public method is wired through RenderingMixin.
+     * Define the characters to use for brightness mapping as a string.
+     *
+     * The maximum number of characters for brightness mapping currently is `64`; excess characters are ignored.
+     *
+     * @param chars
+     * @returns
      */
-    charactersFromColors(colors: ([number, number, number] | null)[]): this;
-    /** Convert a string to glyph colors using the resolver (from Textmodifier font) and store. */
     characters(chars: string): this;
-    /** Internal: uniforms for character list */
-    get characterListUniforms(): Readonly<{
-        count: number;
-        list: number[][];
-    }>;
-    /** Internal: snapshot of color uniforms for renderer */
-    get colorUniforms(): Readonly<{
-        charColorFixed: boolean;
-        _charColor: [number, number, number];
-        cellColorFixed: boolean;
-        cellColor: [number, number, number];
-        backgroundColor: [number, number, number, number];
-    }>;
     /**
      * Create a TextmodeImage from an HTML image/video/canvas element.
      * Texture parameters use NEAREST and CLAMP to align with grid sampling.
+     * @ignore
+     */
+    static $fromSource(renderer: GLRenderer, source: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, glyphResolver: (s: string) => ([number, number, number])[]): TextmodeImage;
+    /**
+     * WebGL texture handle containing the original source image.
+     */
+    get texture(): WebGLTexture;
+    /**
+     * Original pixel width of the source image.
+     */
+    get width(): number;
+    /**
+     * Original pixel height of the source image.
      */
-    static fromSource(renderer: GLRenderer, source: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, glyphResolver: (s: string) => ([number, number, number])[]): TextmodeImage;
+    get height(): number;
 }

package/dist/types/textmode/Textmodifier.d.ts

@@ -18,7 +18,13 @@ import type { GLFramebuffer, Shader } from '../rendering';
  * Options for creating a {@link Textmodifier} instance.
  */
 export type TextmodeOptions = {
-    /** An existing [HTMLCanvasElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) to use instead of creating a new one. */
+    /**
+     * An existing [HTMLCanvasElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) to use instead of creating a new one.
+     *
+     * **Note:**
+     * If using `overlay` mode, this should be the target canvas or video element to overlay on.
+     * `textmode.js` will create its own canvas applied on top of the target element, always matching its size and position.
+     */
     canvas?: HTMLCanvasElement;
     /** The font size to use for text rendering. Defaults to 16. */
     fontSize?: number;
@@ -38,13 +44,16 @@ export type TextmodeOptions = {
     fontSource?: string;
     /**
      * Use `textmode.js` in overlay mode,
-     * which sets up the textmode <canvas> on top of an existing HTMLCanvasElement or HTMLVideoElement,
+     * which sets up the textmode `<canvas>` on top of an existing HTMLCanvasElement or HTMLVideoElement,
      * automatically resizing and positioning it to match the target element.
      *
      * In this mode `textmode.js` fetches the content of the target element and applies it with adjustable textmode conversion
      * as a first layer to the textmode canvas.
      *
      * Useful for applying textmode conversion to p5.js sketches, YouTube videos, and sooo much more.
+     *
+     * All functionality of `textmode.js` remains available, including drawing additional content on top of the converted source.
+     *
      */
     overlay?: boolean;
 };
@@ -233,6 +242,10 @@ export declare class Textmodifier extends Textmodifier_base {
     get canvas(): HTMLCanvasElement;
     /** Check if the instance has been disposed/destroyed. */
     get isDisposed(): boolean;
+    /**
+     * If in overlay mode, returns the {@link TextmodeImage} instance capturing the target canvas/video content,
+     * allowing further configuration of the conversion parameters.
+     */
     get overlay(): TextmodeImage | undefined;
 }
 export interface Textmodifier extends RenderingCapabilities, ExportCapabilities, FontCapabilities, AnimationCapabilities, MouseCapabilities, KeyboardCapabilities {

package/dist/types/textmode/mixins/ExportMixin.d.ts

@@ -19,9 +19,6 @@ export interface ExportCapabilities {
      * // Create a Textmodifier instance
      * const textmodifier = textmode.create(canvas, {renderMode: 'manual'});
      *
-     * // Render a single frame
-     * textmodifier.render();
-     *
      * // Get the current rendering as a text string
      * const textString = textmodifier.toString({
      *   preserveTrailingSpaces: false,
@@ -45,9 +42,6 @@ export interface ExportCapabilities {
      * // Create a Textmodifier instance
      * const textmodifier = textmode.create(canvas, {renderMode: 'manual'});
      *
-     * // Render a single frame
-     * textmodifier.render();
-     *
      * // Export the current rendering to a TXT file
      * textmodifier.saveStrings({
      *   filename: 'my_textmode_rendering',
@@ -69,9 +63,6 @@ export interface ExportCapabilities {
      * // Create a Textmodifier instance
      * const textmodifier = textmode.create(canvas, {renderMode: 'manual'});
      *
-     * // Render a single frame
-     * textmodifier.render();
-     *
      * // Get the current rendering as an SVG string
      * const svgString = textmodifier.toSVG({
      *   includeBackgroundRectangles: true,
@@ -95,9 +86,6 @@ export interface ExportCapabilities {
      * // Create a Textmodifier instance
      * const textmodifier = textmode.create(canvas, {renderMode: 'manual'});
      *
-     * // Render a single frame
-     * textmodifier.render();
-     *
      * // Export the current rendering to an SVG file
      * textmodifier.saveSVG({
      *   filename: 'my_textmode_rendering',
@@ -117,14 +105,13 @@ export interface ExportCapabilities {
      * // Create a Textmodifier instance
      * const textmodifier = textmode.create(canvas, {renderMode: 'manual'});
      *
-     * // Render a single frame
-     * textmodifier.render();
-     *
-     * // Export the current rendering to a PNG file
-     * textmodifier.saveCanvas('my_textmode_rendering', 'png');
+     * // Export the current rendering to a PNG file *(default)*
+     * textmodifier.saveCanvas();
      *
      * // Export with custom options
-     * textmodifier.saveCanvas('my_textmode_rendering', 'jpg', {
+     * textmodifier.saveCanvas({
+     *   filename: 'my_textmode_rendering',
+     *   format: 'jpg',
      *   quality: 0.8,
      *   scale: 2.0,
      *   backgroundColor: 'white'

package/dist/types/textmode/mixins/RenderingMixin.d.ts

@@ -21,7 +21,6 @@ type UniformValue = number | boolean | number[] | Float32Array | Int32Array | We
 export interface RenderingCapabilities {
     /**
      * Set a custom shader for subsequent rendering operations.
-     * Pass null to return to the default shader.
      * @param shader The custom shader to use
      *
      * @example
@@ -43,9 +42,6 @@ export interface RenderingCapabilities {
      *   t.shader(customShader);
      *   t.setUniform('u_frameCount', t.frameCount);
      *   t.rect(0, 0, t.grid.cols, t.grid.rows);
-     *
-     *   // Return to default shader
-     *   t.shader(null);
      * });
      * ```
      */
@@ -89,18 +85,13 @@ export interface RenderingCapabilities {
      */
     createFramebuffer(options: TextmodeFramebufferOptions): GLFramebuffer;
     /**
-     * Render a framebuffer to the current render target.
-     *
-     * This method takes the 5 MRT attachments from the source framebuffer
-     * and renders them at the specified position.
-     * The framebuffer content will be processed through the same rendering
-     * pipeline as normal drawing operations.
-     *
-     * @param framebuffer The framebuffer to render
-     * @param x X position on the grid where to place the framebuffer content *(top-left corner)*
-     * @param y Y position on the grid where to place the framebuffer content *(top-left corner)*
-     * @param width Optional width to scale the framebuffer content *(defaults to framebuffer width)*
-     * @param height Optional height to scale the framebuffer content *(defaults to framebuffer height)*
+     * Draw a TextmodeFramebuffer or TextmodeImage to the current render target.
+     *
+     * @param source The TextmodeFramebuffer or TextmodeImage to render
+     * @param x X position on the grid where to place the content *(top-left corner)*
+     * @param y Y position on the grid where to place the content *(top-left corner)*
+     * @param width Width to scale the content
+     * @param height Height to scale the content
      *
      * @example
      * ```javascript

package/dist/types/textmode/mixins/TextmodifierMixin.d.ts

@@ -42,6 +42,10 @@ export interface TextmodifierContext {
     readonly _textmodeDrawFramebuffer: GLFramebuffer;
     /** Shader used for converting pixels to textmode grid format @ignore */
     readonly _textmodeConversionShader: Shader;
+    /** Framebuffer used for textmode conversion @ignore */
+    readonly _asciiColorFramebuffer: GLFramebuffer;
+    /** Shader used for final presentation to the screen @ignore */
+    readonly _presentShader: Shader;
     /** Main render method @ignore */
     $render(): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textmode.js",
-  "version": "0.2.1-beta.6",
+  "version": "0.2.1-beta.7",
   "description": "textmode.js is a lightweight creative coding library for creating real-time ASCII art on the web.",
   "type": "module",
   "types": "./dist/types/index.d.ts",

package/dist/types/assets/shaders-minified/frag/ascii.d.ts

@@ -1,14 +0,0 @@
-export interface ShaderData {
-    sourceCode: string;
-    originalCode?: string;
-    uniforms: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-    consts: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-}
-declare const shaderData: ShaderData;
-export default shaderData;

package/dist/types/assets/shaders-minified/frag/copy-mrt.d.ts

@@ -1,14 +0,0 @@
-export interface ShaderData {
-    sourceCode: string;
-    originalCode?: string;
-    uniforms: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-    consts: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-}
-declare const shaderData: ShaderData;
-export default shaderData;

package/dist/types/assets/shaders-minified/frag/image-to-mrt.d.ts

@@ -1,14 +0,0 @@
-export interface ShaderData {
-    sourceCode: string;
-    originalCode?: string;
-    uniforms: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-    consts: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-}
-declare const shaderData: ShaderData;
-export default shaderData;

package/dist/types/assets/shaders-minified/frag/instanced-ascii-mrt.d.ts

@@ -1,14 +0,0 @@
-export interface ShaderData {
-    sourceCode: string;
-    originalCode?: string;
-    uniforms: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-    consts: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-}
-declare const shaderData: ShaderData;
-export default shaderData;

package/dist/types/assets/shaders-minified/frag/present.d.ts

@@ -1,14 +0,0 @@
-export interface ShaderData {
-    sourceCode: string;
-    originalCode?: string;
-    uniforms: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-    consts: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-}
-declare const shaderData: ShaderData;
-export default shaderData;

package/dist/types/assets/shaders-minified/index.d.ts

@@ -1,7 +0,0 @@
-export { default as frag_ascii } from './frag/ascii.ts';
-export { default as frag_copy_mrt } from './frag/copy-mrt.ts';
-export { default as frag_image_to_mrt } from './frag/image-to-mrt.ts';
-export { default as frag_instanced_ascii_mrt } from './frag/instanced-ascii-mrt.ts';
-export { default as frag_present } from './frag/present.ts';
-export { default as vert_instanced_ascii_mrt } from './vert/instanced-ascii-mrt.ts';
-export { default as vert_shader } from './vert/shader.ts';

package/dist/types/assets/shaders-minified/vert/instanced-ascii-mrt.d.ts

@@ -1,14 +0,0 @@
-export interface ShaderData {
-    sourceCode: string;
-    originalCode?: string;
-    uniforms: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-    consts: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-}
-declare const shaderData: ShaderData;
-export default shaderData;

package/dist/types/assets/shaders-minified/vert/shader.d.ts

@@ -1,14 +0,0 @@
-export interface ShaderData {
-    sourceCode: string;
-    originalCode?: string;
-    uniforms: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-    consts: Record<string, {
-        variableName: string;
-        variableType: string;
-    }>;
-}
-declare const shaderData: ShaderData;
-export default shaderData;