@pirireis/webglobeplugins 1.0.2 → 1.0.4

package/{util/webglobjectbuilders.ts → webglobeplugins/util/webglobjectbuilders.js}

@@ -1,446 +1,358 @@
-/**
- * Creates and compiles a WebGL shader.
- * @param gl The WebGL2RenderingContext.
- * @param type The type of shader (e.g., gl.VERTEX_SHADER or gl.FRAGMENT_SHADER).
- * @param source The GLSL source code for the shader.
- * @returns The compiled WebGLShader.
- * @throws An error if shader compilation fails.
- */
-export function createShader(gl: WebGL2RenderingContext, type: GLenum, source: string): WebGLShader {
-    const shader = gl.createShader(type);
-    if (!shader) {
-        throw new Error("Failed to create WebGLShader.");
-    }
-
-    gl.shaderSource(shader, source);
-    gl.compileShader(shader);
-
-    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
-        const errorLog = gl.getShaderInfoLog(shader);
-        const shaderType = type === gl.VERTEX_SHADER ? 'VERTEX_SHADER' : 'FRAGMENT_SHADER';
-        const sourceWithLineNumbers = source.split('\n').map((line, i) => `${i + 1}: ${line}`).join('\n');
-        gl.deleteShader(shader); // Clean up the failed shader
-        throw new Error(`Error compiling ${shaderType}:\n${errorLog}\nSource:\n${sourceWithLineNumbers}`);
-    }
-
-    return shader;
-}
-
-
-/**
- * Creates, compiles, and links a WebGL program from vertex and fragment shader sources.
- * Note: This function logs errors to the console and returns `undefined` on failure.
- * Consider using `createProgramWrapper` for more robust error handling.
- * @param gl The WebGL2RenderingContext.
- * @param vertexSource The GLSL source code for the vertex shader.
- * @param fragmentSource The GLSL source code for the fragment shader.
- * @returns The linked WebGLProgram, or `undefined` if compilation or linking fails.
- */
-export function createProgram(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string): WebGLProgram {
-    const program = gl.createProgram();
-    if (!program) {
-        throw new Error("Failed to create WebGLProgram.");
-    }
-
-    let vertexShader: WebGLShader | undefined;
-    let fragmentShader: WebGLShader | undefined;
-
-    try {
-        vertexShader = createShader(gl, gl.VERTEX_SHADER, vertexSource);
-        fragmentShader = createShader(gl, gl.FRAGMENT_SHADER, fragmentSource);
-    } catch (e: any) { // Catching errors from createShader
-        console.error(e.message);
-        throw new Error(`Shader creation failed: ${e.message}`);
-    }
-
-    gl.attachShader(program, vertexShader);
-    gl.attachShader(program, fragmentShader);
-    gl.linkProgram(program);
-
-    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
-        // console.error("Failed to link WebGL program:", gl.getProgramInfoLog(program));
-        throw new Error(`Error linking program:\n${gl.getProgramInfoLog(program)}`);
-    }
-
-    // Detach and delete shaders after linking to free up resources
-    gl.detachShader(program, vertexShader);
-    gl.detachShader(program, fragmentShader);
-    gl.deleteShader(vertexShader);
-    gl.deleteShader(fragmentShader);
-
-    return program;
-}
-
-
-/**
- * Interface for the program wrapper object returned by `createProgramWrapper`.
- * It includes the `program` itself, and dynamically added properties for attribute and uniform locations.
- */
-export interface ProgramWrapper extends WebGLProgram {
-    program: WebGLProgram;
-    [key: string]: WebGLProgram | number | WebGLUniformLocation | null; // Allow dynamic properties for attributes/uniforms
-}
-
-/**
- * Creates, links a WebGL program, and wraps it with convenience properties
- * for attribute and uniform locations.
- * @param gl The WebGL2RenderingContext.
- * @param vertexSource The GLSL source code for the vertex shader.
- * @param fragmentSource The GLSL source code for the fragment shader.
- * @returns A ProgramWrapper object containing the WebGLProgram and its active attribute/uniform locations.
- * @throws An error if shader compilation or program linking fails.
- */
-export function createProgramWrapper(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string): ProgramWrapper {
-    const program = gl.createProgram();
-    if (!program) {
-        throw new Error("Failed to create WebGLProgram.");
-    }
-
-    const vertexShader = createShader(gl, gl.VERTEX_SHADER, vertexSource);
-    const fragmentShader = createShader(gl, gl.FRAGMENT_SHADER, fragmentSource);
-
-    gl.attachShader(program, vertexShader);
-    gl.attachShader(program, fragmentShader);
-
-    gl.linkProgram(program);
-    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
-        const errorLog = gl.getProgramInfoLog(program);
-        gl.deleteProgram(program);
-        gl.deleteShader(vertexShader);
-        gl.deleteShader(fragmentShader);
-        throw new Error(`Error linking program:\n${errorLog}`);
-    }
-
-    // Detach and delete shaders after linking
-    gl.detachShader(program, vertexShader);
-    gl.detachShader(program, fragmentShader);
-    gl.deleteShader(vertexShader);
-    gl.deleteShader(fragmentShader);
-
-    // Using an object literal for dynamic properties
-    const wrapper: ProgramWrapper = { program: program };
-
-    const numAttributes = gl.getProgramParameter(program, gl.ACTIVE_ATTRIBUTES);
-    for (let i = 0; i < numAttributes; i++) {
-        const attribute = gl.getActiveAttrib(program, i);
-        if (attribute) {
-            wrapper[attribute.name] = gl.getAttribLocation(program, attribute.name);
-        }
-    }
-
-    const numUniforms = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);
-    for (let i = 0; i < numUniforms; i++) {
-        const uniform = gl.getActiveUniform(program, i);
-        if (uniform) {
-            wrapper[uniform.name] = gl.getUniformLocation(program, uniform.name);
-        }
-    }
-
-    return wrapper;
-}
-
-
-/**
- * Creates and configures a WebGL texture.
- * @param gl The WebGL2RenderingContext.
- * @param filter The texture filter (e.g., gl.LINEAR, gl.NEAREST).
- * @param data The image data (e.g., ImageData, HTMLImageElement, HTMLCanvasElement, HTMLVideoElement, ImageBitmap, or Uint8Array).
- * @param width The width of the texture (required if data is Uint8Array).
- * @param height The height of the texture (required if data is Uint8Array).
- * @returns The created WebGLTexture.
- * @throws An error if texture creation fails.
- */
-export function createTexture(
-    gl: WebGL2RenderingContext,
-    filter: GLenum,
-    data: TexImageSource | Uint8Array | null | any,
-    width?: number,
-    height?: number
-): WebGLTexture {
-    const texture = gl.createTexture();
-    if (!texture) {
-        throw new Error("Failed to create WebGLTexture.");
-    }
-    gl.bindTexture(gl.TEXTURE_2D, texture);
-
-    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);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
-
-    if (data instanceof Uint8Array) {
-        if (width === undefined || height === undefined) {
-            throw new Error("Width and height must be provided when data is Uint8Array.");
-        }
-        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, data);
-    } else {
-        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, data);
-    }
-    gl.bindTexture(gl.TEXTURE_2D, null);
-    return texture;
-}
-
-
-/**
- * Binds a WebGL texture to a specific texture unit.
- * @param gl The WebGL2RenderingContext.
- * @param texture The WebGLTexture to bind.
- * @param unit The texture unit to activate (e.g., 0 for TEXTURE0, 1 for TEXTURE1).
- */
-export function bindTexture(gl: WebGL2RenderingContext, texture: WebGLTexture | null, unit: number): void {
-    gl.activeTexture(gl.TEXTURE0 + unit);
-    gl.bindTexture(gl.TEXTURE_2D, texture);
-}
-
-
-/**
- * Creates a WebGL buffer and uploads data to it.
- * @param gl The WebGL2RenderingContext.
- * @param data The data to upload to the buffer (e.g., Float32Array, Uint16Array).
- * @returns The created WebGLBuffer.
- * @throws An error if buffer creation fails.
- */
-export function createBuffer(gl: WebGL2RenderingContext, data: BufferSource): WebGLBuffer {
-    const buffer = gl.createBuffer();
-    if (!buffer) {
-        throw new Error("Failed to create WebGLBuffer.");
-    }
-    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
-    gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
-    return buffer;
-}
-
-
-
-/**
- * Binds a buffer to a specific attribute location and configures the vertex attribute pointer.
- * @param gl The WebGL2RenderingContext.
- * @param buffer The WebGLBuffer to bind.
- * @param attribute The attribute location (e.g., from `gl.getAttribLocation`).
- * @param numComponents The number of components per vertex attribute (e.g., 2 for vec2, 3 for vec3).
- */
-export function bindAttribute(gl: WebGL2RenderingContext, buffer: WebGLBuffer | null, attribute: GLint, numComponents: GLint): void {
-    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
-    gl.enableVertexAttribArray(attribute);
-    gl.vertexAttribPointer(attribute, numComponents, gl.FLOAT, false, 0, 0);
-}
-
-
-/**
- * Binds a WebGL framebuffer and optionally attaches a texture to it.
- * @param gl The WebGL2RenderingContext.
- * @param framebuffer The WebGLFramebuffer to bind.
- * @param texture The WebGLTexture to attach to the framebuffer's COLOR_ATTACHMENT0, or `null` to unbind.
- */
-export function bindFramebuffer(gl: WebGL2RenderingContext, framebuffer: WebGLFramebuffer | null, texture: WebGLTexture | null): void {
-    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
-    if (texture) {
-        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
-    }
-}
-
-
-/**
- * Decodes a base64 encoded string into a Uint8Array.
- * @param data The base64 encoded string.
- * @returns A Uint8Array containing the decoded bytes.
- */
-export function decodeBase64(data: string): Uint8Array {
-    const binary_string = atob(data);
-    const len = binary_string.length;
-    const bytes = new Uint8Array(len);
-    for (let i = 0; i < len; i++) {
-        bytes[i] = binary_string.charCodeAt(i);
-    }
-    return bytes;
-}
-
-
-/**
- * Creates an HTMLImageElement from a base64 encoded image string.
- * @param encodedData The base64 encoded image data (e.g., "iVBORw0KGgo...").
- * @returns An HTMLImageElement with the image data loaded.
- */
-export function createImageFromBase64(encodedData: string): HTMLImageElement {
-    const source = decodeBase64(encodedData).buffer as BufferSource;
-    const blob = new Blob([source], { type: "image/png" });
-    const urlCreator = window.URL || window.webkitURL;
-    const imageUrl = urlCreator.createObjectURL(blob);
-    const image = new Image();
-    image.src = imageUrl;
-    // Revoke the object URL after the image has loaded to free up memory
-    image.onload = () => urlCreator.revokeObjectURL(imageUrl);
-    return image;
-}
-
-
-/**
- * Creates a 1x256 pixel color ramp (gradient) as a Uint8Array.
- * @param colors An object where keys are stop positions (0.0-1.0) and values are CSS color strings (e.g., { "0.0": "#RRGGBB", "0.5": "rgba(R,G,B,A)" }).
- * @returns A Uint8Array representing the RGBA pixel data of the 1x256 color ramp.
- */
-export function getColorRamp(colors: Array<[number, string]>): Uint8Array {
-    const canvas = document.createElement('canvas');
-    const ctx = canvas.getContext('2d');
-
-    if (!ctx) {
-        throw new Error("Failed to get 2D rendering context for canvas.");
-    }
-
-    canvas.width = 256;
-    canvas.height = 1;
-
-    const gradient = ctx.createLinearGradient(0, 0, 256, 0);
-
-    for (const stop in colors) {
-
-
-        gradient.addColorStop(colors[stop][0], colors[stop][1]);
-    }
-
-    ctx.fillStyle = gradient;
-    ctx.fillRect(0, 0, 256, 1);
-
-    return new Uint8Array(ctx.getImageData(0, 0, 256, 1).data);
-}
-
-
-/**
- * Creates a 1x256 pixel discrete color ramp as a Uint8Array.
- * This ramp features sharp transitions between colors at specified thresholds.
- * @param values An array of CSS color strings.
- * @param thresholds An array of stop positions (0.0-1.0) for the colors.
- * @returns A Uint8Array representing the RGBA pixel data of the 1x256 discrete color ramp.
- */
-export function getColorRampDiscrate(values: string[], thresholds: number[]): Uint8Array {
-    const canvas = document.createElement('canvas');
-    const ctx = canvas.getContext('2d');
-
-    if (!ctx) {
-        throw new Error("Failed to get 2D rendering context for canvas.");
-    }
-
-    canvas.width = 256;
-    canvas.height = 1;
-
-    const gap = 1.0 / 256; // Represents one pixel width in normalized coordinates
-
-    const gradient = ctx.createLinearGradient(0, 0, 256, 0);
-
-    for (let i = 0; i < thresholds.length - 1; i++) {
-        gradient.addColorStop(thresholds[i], values[i]);
-        // Create a sharp transition by setting the next stop just before the next threshold
-        gradient.addColorStop(Math.max(0, thresholds[i + 1] - gap), values[i]);
-    }
-    // Add the final color for the last segment
-    gradient.addColorStop(thresholds[thresholds.length - 1], values[values.length - 1]);
-
-    ctx.fillStyle = gradient;
-    ctx.fillRect(0, 0, 256, 1);
-
-    return new Uint8Array(ctx.getImageData(0, 0, 256, 1).data);
-}
-
-
-/**
- * Creates a 1x256 pixel interpolated color ramp (smooth gradient) as a Uint8Array.
- * @param values An array of CSS color strings.
- * @param thresholds An array of stop positions (0.0-1.0) for the colors.
- * @returns A Uint8Array representing the RGBA pixel data of the 1x256 interpolated color ramp.
- */
-export function getColorRampInterpolated(values: string[], thresholds: number[]): Uint8Array {
-    const canvas = document.createElement('canvas');
-    const ctx = canvas.getContext('2d');
-
-    if (!ctx) {
-        throw new Error("Failed to get 2D rendering context for canvas.");
-    }
-
-    canvas.width = 256;
-    canvas.height = 1;
-
-    const gradient = ctx.createLinearGradient(0, 0, 256, 0);
-
-    for (let i = 0; i < thresholds.length; i++) {
-        gradient.addColorStop(thresholds[i], values[i]);
-    }
-
-    ctx.fillStyle = gradient;
-    ctx.fillRect(0, 0, 256, 1);
-
-    return new Uint8Array(ctx.getImageData(0, 0, 256, 1).data);
-}
-
-
-/**
- * Creates a 1x256 pixel color ramp based on the specified mode (discrete or interpolated).
- * @param values An array of color hex values (e.g., ["#ff0000", "#00ff00", "#0000ff"]).
- * @param thresholds An array of thresholds (0.0-1.0) for the colors.
- * @param mode The ramp mode: "discrete" for sharp transitions, "interpolated" for smooth transitions (default).
- * @returns A Uint8Array representing the RGBA pixel data of the 1x256 color ramp.
- * @throws An error if an invalid mode is provided.
- */
-export function getColorRampModed(values: string[], thresholds: number[], mode: "discrete" | "interpolated" = "interpolated"): Uint8Array {
-    if (mode === "discrete") {
-        return getColorRampDiscrate(values, thresholds);
-    } else if (mode === "interpolated") {
-        return getColorRampInterpolated(values, thresholds);
-    } else {
-        throw new Error("mode is not valid. Expected 'discrete' or 'interpolated'.");
-    }
-}
-
-
-
-/**
- * Returns a default interpolated color ramp commonly used for visualizations.
- * @returns A Uint8Array representing the RGBA pixel data of the default 1x256 color ramp.
- */
-export function defaultColorRamp(): Uint8Array {
-    const defaultRampColors = [
-        [0.0, '#5e4fa2'],
-        [0.15, '#3288bd'],
-        [0.20, '#66c2a5'],
-        [0.25, '#66c2a5'],
-        [0.3, '#abdda4'],
-        [0.4, '#e6f598'],
-        [0.5, '#fee08b'],
-        [0.6, '#fdae61'],
-        [0.7, '#f46d43'],
-        [1.0, '#ff1e13']
-    ] as Array<[number, string]>;
-    return getColorRamp(defaultRampColors);
-}
-
-
-
-/**
- * A method decorator that reloads the current WebGL program after the decorated method executes.
- * This is useful for ensuring the correct program is active after a method might change it.
- * @returns A method decorator function.
- */
-export function reloadCurrentGLProgram() {
-    return function (target: any, key: string, descriptor: PropertyDescriptor) {
-        const originalMethod = descriptor.value;
-
-        // Ensure the target has a 'gl' property of type WebGL2RenderingContext
-        if (!('gl' in target) || !(target.gl instanceof WebGL2RenderingContext)) {
-            console.warn(`Decorator 'reloadCurrentGLProgram' applied to a method where 'this.gl' is not a WebGL2RenderingContext. This may not function as expected.`);
-            // Optionally, throw an error here if strictness is desired
-        }
-
-        descriptor.value = function (this: { gl: WebGL2RenderingContext } & any, ...args: any[]) {
-            const gl = this.gl;
-            if (!gl) {
-                console.error("reloadCurrentGLProgram decorator: 'gl' context not found on 'this'.");
-                return originalMethod.apply(this, args);
-            }
-
-            const currentProgram = gl.getParameter(gl.CURRENT_PROGRAM);
-            originalMethod.apply(this, args);
-            gl.useProgram(currentProgram);
-        };
-
-        return descriptor;
-    };
-}
+/**
+ * Creates and compiles a WebGL shader.
+ * @param gl The WebGL2RenderingContext.
+ * @param type The type of shader (e.g., gl.VERTEX_SHADER or gl.FRAGMENT_SHADER).
+ * @param source The GLSL source code for the shader.
+ * @returns The compiled WebGLShader.
+ * @throws An error if shader compilation fails.
+ */
+export function createShader(gl, type, source) {
+    const shader = gl.createShader(type);
+    if (!shader) {
+        throw new Error("Failed to create WebGLShader.");
+    }
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        const errorLog = gl.getShaderInfoLog(shader);
+        const shaderType = type === gl.VERTEX_SHADER ? 'VERTEX_SHADER' : 'FRAGMENT_SHADER';
+        const sourceWithLineNumbers = source.split('\n').map((line, i) => `${i + 1}: ${line}`).join('\n');
+        gl.deleteShader(shader); // Clean up the failed shader
+        throw new Error(`Error compiling ${shaderType}:\n${errorLog}\nSource:\n${sourceWithLineNumbers}`);
+    }
+    return shader;
+}
+/**
+ * Creates, compiles, and links a WebGL program from vertex and fragment shader sources.
+ * Note: This function logs errors to the console and returns `undefined` on failure.
+ * Consider using `createProgramWrapper` for more robust error handling.
+ * @param gl The WebGL2RenderingContext.
+ * @param vertexSource The GLSL source code for the vertex shader.
+ * @param fragmentSource The GLSL source code for the fragment shader.
+ * @returns The linked WebGLProgram, or `undefined` if compilation or linking fails.
+ */
+export function createProgram(gl, vertexSource, fragmentSource) {
+    const program = gl.createProgram();
+    if (!program) {
+        throw new Error("Failed to create WebGLProgram.");
+    }
+    let vertexShader;
+    let fragmentShader;
+    try {
+        vertexShader = createShader(gl, gl.VERTEX_SHADER, vertexSource);
+        fragmentShader = createShader(gl, gl.FRAGMENT_SHADER, fragmentSource);
+    }
+    catch (e) { // Catching errors from createShader
+        console.error(e.message);
+        throw new Error(`Shader creation failed: ${e.message}`);
+    }
+    gl.attachShader(program, vertexShader);
+    gl.attachShader(program, fragmentShader);
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+        // console.error("Failed to link WebGL program:", gl.getProgramInfoLog(program));
+        throw new Error(`Error linking program:\n${gl.getProgramInfoLog(program)}`);
+    }
+    // Detach and delete shaders after linking to free up resources
+    gl.detachShader(program, vertexShader);
+    gl.detachShader(program, fragmentShader);
+    gl.deleteShader(vertexShader);
+    gl.deleteShader(fragmentShader);
+    return program;
+}
+/**
+ * Creates, links a WebGL program, and wraps it with convenience properties
+ * for attribute and uniform locations.
+ * @param gl The WebGL2RenderingContext.
+ * @param vertexSource The GLSL source code for the vertex shader.
+ * @param fragmentSource The GLSL source code for the fragment shader.
+ * @returns A ProgramWrapper object containing the WebGLProgram and its active attribute/uniform locations.
+ * @throws An error if shader compilation or program linking fails.
+ */
+export function createProgramWrapper(gl, vertexSource, fragmentSource) {
+    const program = gl.createProgram();
+    if (!program) {
+        throw new Error("Failed to create WebGLProgram.");
+    }
+    const vertexShader = createShader(gl, gl.VERTEX_SHADER, vertexSource);
+    const fragmentShader = createShader(gl, gl.FRAGMENT_SHADER, fragmentSource);
+    gl.attachShader(program, vertexShader);
+    gl.attachShader(program, fragmentShader);
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+        const errorLog = gl.getProgramInfoLog(program);
+        gl.deleteProgram(program);
+        gl.deleteShader(vertexShader);
+        gl.deleteShader(fragmentShader);
+        throw new Error(`Error linking program:\n${errorLog}`);
+    }
+    // Detach and delete shaders after linking
+    gl.detachShader(program, vertexShader);
+    gl.detachShader(program, fragmentShader);
+    gl.deleteShader(vertexShader);
+    gl.deleteShader(fragmentShader);
+    // Using an object literal for dynamic properties
+    const wrapper = { program: program };
+    const numAttributes = gl.getProgramParameter(program, gl.ACTIVE_ATTRIBUTES);
+    for (let i = 0; i < numAttributes; i++) {
+        const attribute = gl.getActiveAttrib(program, i);
+        if (attribute) {
+            wrapper[attribute.name] = gl.getAttribLocation(program, attribute.name);
+        }
+    }
+    const numUniforms = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);
+    for (let i = 0; i < numUniforms; i++) {
+        const uniform = gl.getActiveUniform(program, i);
+        if (uniform) {
+            wrapper[uniform.name] = gl.getUniformLocation(program, uniform.name);
+        }
+    }
+    return wrapper;
+}
+/**
+ * Creates and configures a WebGL texture.
+ * @param gl The WebGL2RenderingContext.
+ * @param filter The texture filter (e.g., gl.LINEAR, gl.NEAREST).
+ * @param data The image data (e.g., ImageData, HTMLImageElement, HTMLCanvasElement, HTMLVideoElement, ImageBitmap, or Uint8Array).
+ * @param width The width of the texture (required if data is Uint8Array).
+ * @param height The height of the texture (required if data is Uint8Array).
+ * @returns The created WebGLTexture.
+ * @throws An error if texture creation fails.
+ */
+export function createTexture(gl, filter, data, width, height) {
+    const texture = gl.createTexture();
+    if (!texture) {
+        throw new Error("Failed to create WebGLTexture.");
+    }
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    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);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+    if (data instanceof Uint8Array) {
+        if (width === undefined || height === undefined) {
+            throw new Error("Width and height must be provided when data is Uint8Array.");
+        }
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, data);
+    }
+    else {
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, data);
+    }
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    return texture;
+}
+/**
+ * Binds a WebGL texture to a specific texture unit.
+ * @param gl The WebGL2RenderingContext.
+ * @param texture The WebGLTexture to bind.
+ * @param unit The texture unit to activate (e.g., 0 for TEXTURE0, 1 for TEXTURE1).
+ */
+export function bindTexture(gl, texture, unit) {
+    gl.activeTexture(gl.TEXTURE0 + unit);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+}
+/**
+ * Creates a WebGL buffer and uploads data to it.
+ * @param gl The WebGL2RenderingContext.
+ * @param data The data to upload to the buffer (e.g., Float32Array, Uint16Array).
+ * @returns The created WebGLBuffer.
+ * @throws An error if buffer creation fails.
+ */
+export function createBuffer(gl, data) {
+    const buffer = gl.createBuffer();
+    if (!buffer) {
+        throw new Error("Failed to create WebGLBuffer.");
+    }
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
+    return buffer;
+}
+/**
+ * Binds a buffer to a specific attribute location and configures the vertex attribute pointer.
+ * @param gl The WebGL2RenderingContext.
+ * @param buffer The WebGLBuffer to bind.
+ * @param attribute The attribute location (e.g., from `gl.getAttribLocation`).
+ * @param numComponents The number of components per vertex attribute (e.g., 2 for vec2, 3 for vec3).
+ */
+export function bindAttribute(gl, buffer, attribute, numComponents) {
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.enableVertexAttribArray(attribute);
+    gl.vertexAttribPointer(attribute, numComponents, gl.FLOAT, false, 0, 0);
+}
+/**
+ * Binds a WebGL framebuffer and optionally attaches a texture to it.
+ * @param gl The WebGL2RenderingContext.
+ * @param framebuffer The WebGLFramebuffer to bind.
+ * @param texture The WebGLTexture to attach to the framebuffer's COLOR_ATTACHMENT0, or `null` to unbind.
+ */
+export function bindFramebuffer(gl, framebuffer, texture) {
+    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+    if (texture) {
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+    }
+}
+/**
+ * Decodes a base64 encoded string into a Uint8Array.
+ * @param data The base64 encoded string.
+ * @returns A Uint8Array containing the decoded bytes.
+ */
+export function decodeBase64(data) {
+    const binary_string = atob(data);
+    const len = binary_string.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        bytes[i] = binary_string.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * Creates an HTMLImageElement from a base64 encoded image string.
+ * @param encodedData The base64 encoded image data (e.g., "iVBORw0KGgo...").
+ * @returns An HTMLImageElement with the image data loaded.
+ */
+export function createImageFromBase64(encodedData) {
+    const source = decodeBase64(encodedData).buffer;
+    const blob = new Blob([source], { type: "image/png" });
+    const urlCreator = window.URL || window.webkitURL;
+    const imageUrl = urlCreator.createObjectURL(blob);
+    const image = new Image();
+    image.src = imageUrl;
+    // Revoke the object URL after the image has loaded to free up memory
+    image.onload = () => urlCreator.revokeObjectURL(imageUrl);
+    return image;
+}
+/**
+ * Creates a 1x256 pixel color ramp (gradient) as a Uint8Array.
+ * @param colors An object where keys are stop positions (0.0-1.0) and values are CSS color strings (e.g., { "0.0": "#RRGGBB", "0.5": "rgba(R,G,B,A)" }).
+ * @returns A Uint8Array representing the RGBA pixel data of the 1x256 color ramp.
+ */
+export function getColorRamp(colors) {
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        throw new Error("Failed to get 2D rendering context for canvas.");
+    }
+    canvas.width = 256;
+    canvas.height = 1;
+    const gradient = ctx.createLinearGradient(0, 0, 256, 0);
+    for (const stop in colors) {
+        gradient.addColorStop(colors[stop][0], colors[stop][1]);
+    }
+    ctx.fillStyle = gradient;
+    ctx.fillRect(0, 0, 256, 1);
+    return new Uint8Array(ctx.getImageData(0, 0, 256, 1).data);
+}
+/**
+ * Creates a 1x256 pixel discrete color ramp as a Uint8Array.
+ * This ramp features sharp transitions between colors at specified thresholds.
+ * @param values An array of CSS color strings.
+ * @param thresholds An array of stop positions (0.0-1.0) for the colors.
+ * @returns A Uint8Array representing the RGBA pixel data of the 1x256 discrete color ramp.
+ */
+export function getColorRampDiscrate(values, thresholds) {
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        throw new Error("Failed to get 2D rendering context for canvas.");
+    }
+    canvas.width = 256;
+    canvas.height = 1;
+    const gap = 1.0 / 256; // Represents one pixel width in normalized coordinates
+    const gradient = ctx.createLinearGradient(0, 0, 256, 0);
+    for (let i = 0; i < thresholds.length - 1; i++) {
+        gradient.addColorStop(thresholds[i], values[i]);
+        // Create a sharp transition by setting the next stop just before the next threshold
+        gradient.addColorStop(Math.max(0, thresholds[i + 1] - gap), values[i]);
+    }
+    // Add the final color for the last segment
+    gradient.addColorStop(thresholds[thresholds.length - 1], values[values.length - 1]);
+    ctx.fillStyle = gradient;
+    ctx.fillRect(0, 0, 256, 1);
+    return new Uint8Array(ctx.getImageData(0, 0, 256, 1).data);
+}
+/**
+ * Creates a 1x256 pixel interpolated color ramp (smooth gradient) as a Uint8Array.
+ * @param values An array of CSS color strings.
+ * @param thresholds An array of stop positions (0.0-1.0) for the colors.
+ * @returns A Uint8Array representing the RGBA pixel data of the 1x256 interpolated color ramp.
+ */
+export function getColorRampInterpolated(values, thresholds) {
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        throw new Error("Failed to get 2D rendering context for canvas.");
+    }
+    canvas.width = 256;
+    canvas.height = 1;
+    const gradient = ctx.createLinearGradient(0, 0, 256, 0);
+    for (let i = 0; i < thresholds.length; i++) {
+        gradient.addColorStop(thresholds[i], values[i]);
+    }
+    ctx.fillStyle = gradient;
+    ctx.fillRect(0, 0, 256, 1);
+    return new Uint8Array(ctx.getImageData(0, 0, 256, 1).data);
+}
+/**
+ * Creates a 1x256 pixel color ramp based on the specified mode (discrete or interpolated).
+ * @param values An array of color hex values (e.g., ["#ff0000", "#00ff00", "#0000ff"]).
+ * @param thresholds An array of thresholds (0.0-1.0) for the colors.
+ * @param mode The ramp mode: "discrete" for sharp transitions, "interpolated" for smooth transitions (default).
+ * @returns A Uint8Array representing the RGBA pixel data of the 1x256 color ramp.
+ * @throws An error if an invalid mode is provided.
+ */
+export function getColorRampModed(values, thresholds, mode = "interpolated") {
+    if (mode === "discrete") {
+        return getColorRampDiscrate(values, thresholds);
+    }
+    else if (mode === "interpolated") {
+        return getColorRampInterpolated(values, thresholds);
+    }
+    else {
+        throw new Error("mode is not valid. Expected 'discrete' or 'interpolated'.");
+    }
+}
+/**
+ * Returns a default interpolated color ramp commonly used for visualizations.
+ * @returns A Uint8Array representing the RGBA pixel data of the default 1x256 color ramp.
+ */
+export function defaultColorRamp() {
+    const defaultRampColors = [
+        [0.0, '#5e4fa2'],
+        [0.15, '#3288bd'],
+        [0.20, '#66c2a5'],
+        [0.25, '#66c2a5'],
+        [0.3, '#abdda4'],
+        [0.4, '#e6f598'],
+        [0.5, '#fee08b'],
+        [0.6, '#fdae61'],
+        [0.7, '#f46d43'],
+        [1.0, '#ff1e13']
+    ];
+    return getColorRamp(defaultRampColors);
+}
+/**
+ * A method decorator that reloads the current WebGL program after the decorated method executes.
+ * This is useful for ensuring the correct program is active after a method might change it.
+ * @returns A method decorator function.
+ */
+export function reloadCurrentGLProgram() {
+    return function (target, key, descriptor) {
+        const originalMethod = descriptor.value;
+        // Ensure the target has a 'gl' property of type WebGL2RenderingContext
+        if (!('gl' in target) || !(target.gl instanceof WebGL2RenderingContext)) {
+            console.warn(`Decorator 'reloadCurrentGLProgram' applied to a method where 'this.gl' is not a WebGL2RenderingContext. This may not function as expected.`);
+            // Optionally, throw an error here if strictness is desired
+        }
+        descriptor.value = function (...args) {
+            const gl = this.gl;
+            if (!gl) {
+                console.error("reloadCurrentGLProgram decorator: 'gl' context not found on 'this'.");
+                return originalMethod.apply(this, args);
+            }
+            const currentProgram = gl.getParameter(gl.CURRENT_PROGRAM);
+            originalMethod.apply(this, args);
+            gl.useProgram(currentProgram);
+        };
+        return descriptor;
+    };
+}