@pirireis/webglobeplugins 0.15.35 → 0.16.0

package/util/webglobjectbuilders.ts

@@ -0,0 +1,446 @@
+/**
+ * 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;
+    };
+}

package/waveparticles/adaptor.js

@@ -1,15 +1,16 @@
-function centigradePlus90ToVectorArray(centigradeArray, noDataValue = -9999) {
-    const vectorArray = new Float32Array(centigradeArray.length * 2);
-    for (let i = 0; i < centigradeArray.length; i++) {
-        if (centigradeArray[i] === noDataValue) {
-            vectorArray.set([0, 0], i * 2);
-            continue;
-        }
-        const rad = (centigradeArray[i] + 90.0) * Math.PI / 180;
-        const x = Math.cos(rad);
-        const y = Math.sin(rad);
-        vectorArray.set([x, y], i * 2);
-    }
-    return vectorArray;
-}
-export { centigradePlus90ToVectorArray };
+function centigradePlus90ToVectorArray(centigradeArray, noDataValue = -9999) {
+    const vectorArray = new Float32Array(centigradeArray.length * 2);
+    for (let i = 0; i < centigradeArray.length; i++) {
+        if (centigradeArray[i] === noDataValue) {
+            vectorArray.set([0, 0], i * 2);
+            continue;
+        }
+        const rad = (centigradeArray[i] + 90.0) * Math.PI / 180;
+        const x = Math.cos(rad);
+        const y = Math.sin(rad);
+        vectorArray.set([x, y], i * 2);
+    }
+    return vectorArray;
+}
+
+export { centigradePlus90ToVectorArray }

package/waveparticles/index.js

@@ -1,3 +1,3 @@
-import VectorFieldWaveParticle from "./plugin";
-import { centigradePlus90ToVectorArray } from "./adaptor";
-export { centigradePlus90ToVectorArray, VectorFieldWaveParticle };
+import VectorFieldWaveParticle from "./plugin";
+import { centigradePlus90ToVectorArray } from "./adaptor";
+export { centigradePlus90ToVectorArray, VectorFieldWaveParticle };