jmgraph 3.2.27 → 3.2.29

package/src/lib/webgl/core/mapType.js

@@ -1,29 +1,49 @@
 
+/**
+ * @fileoverview WebGL 类型到 GLSL 类型映射模块
+ * 
+ * 本模块提供了 WebGL 常量类型到 GLSL 类型名的映射。
+ * 
+ * @module lib/webgl/core/mapType
+ * @author jmGraph Team
+ */
+
+/** @type {Object.<number, string>|null} 缓存的类型映射表 */
 var GL_TABLE = null;
 
+/**
+ * WebGL 常量到 GLSL 类型的映射表
+ * @constant {Object.<string, string>}
+ */
 const GL_TO_GLSL_TYPES = {
-  'FLOAT':       'float',
-  'FLOAT_VEC2':  'vec2',
-  'FLOAT_VEC3':  'vec3',
-  'FLOAT_VEC4':  'vec4',
+    'FLOAT':       'float',
+    'FLOAT_VEC2':  'vec2',
+    'FLOAT_VEC3':  'vec3',
+    'FLOAT_VEC4':  'vec4',
 
-  'INT':         'int',
-  'INT_VEC2':    'ivec2',
-  'INT_VEC3':    'ivec3',
-  'INT_VEC4':    'ivec4',
-  
-  'BOOL':        'bool',
-  'BOOL_VEC2':   'bvec2',
-  'BOOL_VEC3':   'bvec3',
-  'BOOL_VEC4':   'bvec4',
-  
-  'FLOAT_MAT2':  'mat2',
-  'FLOAT_MAT3':  'mat3',
-  'FLOAT_MAT4':  'mat4',
-  
-  'SAMPLER_2D':  'sampler2D'  
+    'INT':         'int',
+    'INT_VEC2':    'ivec2',
+    'INT_VEC3':    'ivec3',
+    'INT_VEC4':    'ivec4',
+    
+    'BOOL':        'bool',
+    'BOOL_VEC2':   'bvec2',
+    'BOOL_VEC3':   'bvec3',
+    'BOOL_VEC4':   'bvec4',
+    
+    'FLOAT_MAT2':  'mat2',
+    'FLOAT_MAT3':  'mat3',
+    'FLOAT_MAT4':  'mat4',
+    
+    'SAMPLER_2D':  'sampler2D'  
 };
 
+/**
+ * 将 WebGL 类型常量映射为 GLSL 类型名
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {number} type WebGL 类型常量
+ * @returns {string} GLSL 类型名
+ */
 const mapType = function(gl, type) {
     if(!GL_TABLE) {
         const typeNames = Object.keys(GL_TO_GLSL_TYPES);
@@ -34,10 +54,9 @@ const mapType = function(gl, type) {
         }
     }
 
-  return GL_TABLE[type];
+    return GL_TABLE[type];
 };
 
-
 export {
-  mapType
+    mapType
 }

package/src/lib/webgl/core/program.js

@@ -1,32 +1,39 @@
-import {
-    createShader
-} from './shader.js';
-import {
-    mapSize
-} from './mapSize.js';
-import {
-    mapType
-} from './mapType.js';
-
-// 创建程序
+/**
+ * @fileoverview WebGL 着色器程序管理模块
+ * 
+ * 本模块提供了 WebGL 着色器程序的创建和管理功能，包括：
+ * - 创建着色器程序
+ * - 提取属性和 uniform 变量
+ * - 顶点属性绑定
+ * 
+ * @module lib/webgl/core/program
+ * @author jmGraph Team
+ */
+import { createShader } from './shader.js';
+import { mapSize } from './mapSize.js';
+import { mapType } from './mapType.js';
+
+/**
+ * 创建着色器程序
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {string} vertexSrc 顶点着色器源码
+ * @param {string} fragmentSrc 片段着色器源码
+ * @returns {Object} 程序对象 {program, attrs, uniforms}
+ */
 function createProgram(gl, vertexSrc, fragmentSrc) {
-    // 创建顶点着色器
     const vertexShader = createShader(gl, gl.VERTEX_SHADER, vertexSrc);
-    // 创建片段着色器
     const fragmentShader = createShader(gl, gl.FRAGMENT_SHADER, fragmentSrc);
 
-    const program = gl.createProgram() // 创建一个程序
-    gl.attachShader(program, vertexShader) // 添加顶点着色器
-    gl.attachShader(program, fragmentShader) // 添加片元着色器
-    gl.linkProgram(program) // 连接 program 中的着色器
+    const program = gl.createProgram();
+    gl.attachShader(program, vertexShader);
+    gl.attachShader(program, fragmentShader);
+    gl.linkProgram(program);
 
-    // 检查程序链接状态
     if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
         console.error('PError: Could not initialize shader.');
         console.error('gl.VALIDATE_STATUS', gl.getProgramParameter(program, gl.VALIDATE_STATUS));
         console.error('gl.getError()', gl.getError());
 
-        // if there is a program info log, log it
         if (gl.getProgramInfoLog(program) !== '') {
             console.warn('Warning: gl.getProgramInfoLog()', gl.getProgramInfoLog(program));
         }
@@ -36,28 +43,32 @@ function createProgram(gl, vertexSrc, fragmentSrc) {
 
     useProgram(gl, program);
 
-    // clean up some shaders
     gl.deleteShader(vertexShader);
     gl.deleteShader(fragmentShader);
 
     const attrs = extractAttributes(gl, program);
     const uniforms = extractUniforms(gl, program);
     
-    return {
-        program,
-        attrs,
-        uniforms
-    };
+    return { program, attrs, uniforms };
 }
 
-// 采用program
+/**
+ * 使用指定的着色器程序
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {WebGLProgram} program 着色器程序
+ */
 function useProgram(gl, program) {
-    return gl.useProgram(program); // 告诉 webgl 用这个 program 进行渲染
+    return gl.useProgram(program);
 }
 
+/**
+ * 提取着色器程序中的所有属性
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {WebGLProgram} program 着色器程序
+ * @returns {Object} 属性对象字典
+ */
 function extractAttributes(gl, program) {
     const attributes = {};
-
     const count = gl.getProgramParameter(program, gl.ACTIVE_ATTRIBUTES);
 
     for (let i = 0; i < count; i++){
@@ -74,55 +85,84 @@ function extractAttributes(gl, program) {
     return attributes;
 }
 
+/**
+ * 提取着色器程序中的所有 uniform 变量
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {WebGLProgram} program 着色器程序
+ * @returns {Object} uniform 变量对象字典
+ */
 function extractUniforms(gl, program) {
-	const uniforms = {};
-
+    const uniforms = {};
     const count = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);
 
     for (let i = 0; i < count; i++) {
-    	const uniformData = gl.getActiveUniform(program, i);
-    	const name = uniformData.name.replace(/\[.*?\]/, "");
-        const type = mapType(gl, uniformData.type );
+        const uniformData = gl.getActiveUniform(program, i);
+        const name = uniformData.name.replace(/\[.*?\]/, "");
+        const type = mapType(gl, uniformData.type);
 
-    	uniforms[name] = {
+        uniforms[name] = {
             uniformData,
-    		type: type,
-    		size: uniformData.size,
-    		location: gl.getUniformLocation(program, name),
-    	};
+            type: type,
+            size: uniformData.size,
+            location: gl.getUniformLocation(program, name),
+        };
     }
 
-	return uniforms;
-};
-
+    return uniforms;
+}
 
-// 把缓冲区的值写入变量
-// size: 组成数量，必须是1，2，3或4.  每个单元由多少个数组成
-// strip: 步长 数组中一行长度，0 表示数据是紧密的没有空隙，让OpenGL决定具体步长
-// offset: 字节偏移量，必须是类型的字节长度的倍数。
-// dataType: 每个元素的数据类型
+/**
+ * 将缓冲区数据写入顶点属性
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {Object} buffer 缓冲区对象
+ * @param {Object} attr 属性对象
+ * @param {number} [size=2] 每个顶点的分量数（1-4）
+ * @param {number} [strip=0] 步长，0 表示紧密排列
+ * @param {number} [offset=0] 字节偏移量
+ * @param {number} [dataType=gl.FLOAT] 数据类型
+ * @returns {Object} 缓冲区对象
+ */
 function writeVertexAttrib(gl, buffer, attr, size=2, strip=0, offset=0, dataType=gl.FLOAT) {
     gl.bindBuffer(buffer.type, buffer.buffer);
-    gl.vertexAttribPointer( // 告诉 OpenGL 如何从 Buffer 中获取数据
-            attr.location, // 顶点属性的索引
-            size, // 组成数量，必须是1，2，3或4。我们只提供了 x 和 y
-            dataType,
-            false, // 是否归一化到特定的范围，对 FLOAT 类型数据设置无效
-            strip * buffer.unitSize,
-            offset
-        );
+    gl.vertexAttribPointer(
+        attr.location,
+        size,
+        dataType,
+        false,
+        strip * buffer.unitSize,
+        offset
+    );
     gl.enableVertexAttribArray(attr.location);
     return buffer;
 }
 
+/**
+ * 禁用顶点属性数组
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {Object} attr 属性对象
+ */
 function disableVertexAttribArray(gl, attr) {
     return gl.disableVertexAttribArray(attr.location);
 }
 
+/**
+ * 获取属性位置
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {WebGLProgram} program 着色器程序
+ * @param {string} name 属性名
+ * @returns {number} 属性位置
+ */
 function getAttribLocation(gl, program, name) {
     return gl.getAttribLocation(program, name);
 }
 
+/**
+ * 获取 uniform 位置
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {WebGLProgram} program 着色器程序
+ * @param {string} name uniform 变量名
+ * @returns {WebGLUniformLocation} uniform 位置
+ */
 function getUniformLocation(gl, program, name) {
     return gl.getUniformLocation(program, name);
 }

package/src/lib/webgl/core/shader.js

@@ -1,14 +1,26 @@
-// 生成着色器
-// type: gl.VERTEX_SHADER 顶点着色器  , gl.FRAGMENT_SHADER  片段着色器
-// src: 着色器代码
-function createShader(gl, type, src) {
-    const shader = gl.createShader(type) // 创建一个顶点着色器
-    gl.shaderSource(shader, src); // 编写顶点着色器代码
-    gl.compileShader(shader); // 编译着色器
+/**
+ * @fileoverview WebGL 着色器管理模块
+ * 
+ * 本模块提供了 WebGL 着色器的创建功能。
+ * 
+ * @module lib/webgl/core/shader
+ * @author jmGraph Team
+ */
 
+/**
+ * 创建 WebGL 着色器
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {number} type 着色器类型：gl.VERTEX_SHADER 或 gl.FRAGMENT_SHADER
+ * @param {string} src 着色器源码
+ * @returns {WebGLShader} 编译后的着色器对象
+ */
+function createShader(gl, type, src) {
+    const shader = gl.createShader(type);
+    gl.shaderSource(shader, src);
+    gl.compileShader(shader);
     return shader;
 }
 
-export  {
+export {
     createShader
 }

package/src/lib/webgl/core/texture.js

@@ -1,54 +1,77 @@
 
-// 生成纹理
+/**
+ * @fileoverview WebGL 纹理管理模块
+ * 
+ * 本模块提供了 WebGL 纹理的创建和管理功能，包括：
+ * - 创建 2D 纹理
+ * - 创建图片纹理
+ * - 创建数据纹理
+ * - 删除纹理
+ * 
+ * @module lib/webgl/core/texture
+ * @author jmGraph Team
+ */
+
+/**
+ * 创建 2D 纹理
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @returns {WebGLTexture} 纹理对象
+ */
 function create2DTexture(gl) {
     const texture = gl.createTexture();
-    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 1); // 图像反转Y轴
-    gl.activeTexture(gl.TEXTURE0); // 激活纹理单元
-    gl.bindTexture(gl.TEXTURE_2D, texture); // 绑定纹理对象
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 1);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
     
-    //gl.generateMipmap(gl.TEXTURE_2D);
-    gl.texParameterf(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST); // 放大处理方式  // LINEAR  / NEAREST
-    gl.texParameterf(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST); // 缩小处理方式
-    gl.texParameterf(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); // 水平平铺方式
-    gl.texParameterf(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE); // 竖直平铺方式
-
+    gl.texParameterf(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameterf(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameterf(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameterf(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
     
     return texture;
 }
 
-// 创建图片纹理
+/**
+ * 创建图片纹理
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {Image|HTMLImageElement} img 图像对象
+ * @returns {Object} 纹理对象 {texture}
+ */
 function createImgTexture(gl, img) {
     const texture = create2DTexture(gl);
-
-    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img) // 配置纹理图像
-    return {
-        texture
-    };
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
+    return { texture };
 }
 
-// 用像素值来绘制纹理
+/**
+ * 根据像素数据创建纹理
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {ImageData|Object} pixels 像素数据 {data, width, height}
+ * @returns {Object} 纹理对象 {texture}
+ */
 function createDataTexture(gl, pixels) {
     const data = new Uint8Array(pixels.data || pixels);
-
     const texture = create2DTexture(gl);
 
     gl.texImage2D(
-        gl.TEXTURE_2D, // 纹理目标
-        0, // 细节级别,指定详细级别。0 级是基本图像等级，n 级是第 n 个金字塔简化级。
-        gl.RGBA, // 纹理内部格式
-        pixels.width || 1, // 指定纹理的宽度
-        pixels.height || 1, // 指定纹理的高度
-        0, // 指定纹理的边框宽度。必须为 0。
-        gl.RGBA, // 源图像数据格式
-        gl.UNSIGNED_BYTE, // 纹理数据类型
-        data // 数据
-      );
-    return {
-        texture
-    };
+        gl.TEXTURE_2D,
+        0,
+        gl.RGBA,
+        pixels.width || 1,
+        pixels.height || 1,
+        0,
+        gl.RGBA,
+        gl.UNSIGNED_BYTE,
+        data
+    );
+    return { texture };
 }
 
-// 删除纹理
+/**
+ * 删除纹理
+ * @param {WebGLRenderingContext} gl WebGL 渲染上下文
+ * @param {WebGLTexture} texture 纹理对象
+ */
 function deleteTexture(gl, texture) {
     return gl.deleteTexture(texture);
 }

package/src/lib/webgl/gradient.js

@@ -1,11 +1,46 @@
+/**
+ * @fileoverview WebGL 渐变对象
+ * 
+ * 本模块提供了 WebGL 渐变功能，支持 GLSL 着色器直接计算渐变色，
+ * 无需 textureCanvas，性能更优。
+ * 
+ * 支持的渐变类型：
+ * - 线性渐变 (linear)
+ * - 径向渐变 (radial)
+ * 
+ * @module lib/webgl/gradient
+ * @author jmGraph Team
+ */
+
+/** @constant {number} 最大颜色断点数量 */
 const MAX_STOPS = 16;
 
 /**
- * WebGL 渐变对象
- * 支持 GLSL 着色器直接计算渐变色，无需 textureCanvas
+ * WebGL 渐变类
+ * 支持 GLSL 着色器直接计算渐变色
+ * 
+ * @class WebglGradient
+ * @example
+ * const gradient = new WebglGradient('linear', { x1: 0, y1: 0, x2: 100, y2: 0 });
+ * gradient.addColorStop(0, '#ff0000');
+ * gradient.addColorStop(1, '#0000ff');
  */
 class WebglGradient {
+    /**
+     * 构造函数
+     * @param {string} [type='linear'] 渐变类型：'linear' 或 'radial'
+     * @param {Object} params 渐变参数
+     * @param {number} [params.x1=0] 起点/内圆中心X坐标
+     * @param {number} [params.y1=0] 起点/内圆中心Y坐标
+     * @param {number} [params.r1=0] 内圆半径（径向渐变）
+     * @param {number} [params.x2=0] 终点/外圆中心X坐标
+     * @param {number} [params.y2=0] 终点/外圆中心Y坐标
+     * @param {number} [params.r2=0] 外圆半径（径向渐变）
+     * @param {Object} [params.bounds] 渐变边界
+     * @param {Object} [params.control] 控制器对象
+     */
     constructor(type = 'linear', params = {}) {
+        /** @type {string} 渐变类型 */
         this.type = type || 'linear';
 
         this.x1 = params.x1 || 0;
@@ -15,15 +50,12 @@ class WebglGradient {
         this.y2 = params.y2 || 0;
         this.r2 = params.r2 || 0;
 
-        this.bounds = params.bounds || {
-            left: 0,
-            top: 0,
-            width: 0,
-            height: 0
-        };
+        /** @type {Object} 渐变边界 */
+        this.bounds = params.bounds || { left: 0, top: 0, width: 0, height: 0 };
 
         this.control = params.control;
 
+        /** @type {Array<{offset: number, color: string}>} 颜色断点数组 */
         this.stops = [];
         this._sortedStops = null;
         this._paramsHash = null;
@@ -31,6 +63,8 @@ class WebglGradient {
 
     /**
      * 添加颜色断点
+     * @param {number} offset 断点位置 (0-1)
+     * @param {string} color 颜色值
      */
     addColorStop(offset, color) {
         this.stops.push({
@@ -42,7 +76,9 @@ class WebglGradient {
     }
 
     /**
-     * 获取排序后的 stops（带解析后的颜色）
+     * 获取排序后的断点数组（带解析后的颜色）
+     * @private
+     * @returns {Array<{offset: number, r: number, g: number, b: number, a: number}>}
      */
     _getSortedStops() {
         if (this._sortedStops) return this._sortedStops;
@@ -55,8 +91,6 @@ class WebglGradient {
                     c = utils.hexToRGBA(c);
                 }
                 if (typeof c === 'object' && c !== null) {
-                    // hexToRGBA 返回 r/g/b 为 0~255，a 为 0~1
-                    // 但如果已经是 0~1 范围（由 rgbToDecimal 处理过），需要检测
                     const needNormalize = (c.r > 1 || c.g > 1 || c.b > 1) ? 255 : 1;
                     return {
                         offset: s.offset,
@@ -74,14 +108,13 @@ class WebglGradient {
     }
 
     /**
-     * 将渐变参数以 uniform 形式传递给着色器
-     * 返回 { type, start, end, stopCount, stops } 供着色器使用
+     * 将渐变参数转换为 uniform 格式，传递给着色器
+     * @returns {Object} uniform 参数对象
      */
     toUniformParams() {
         const stops = this._getSortedStops();
         const count = Math.min(stops.length, MAX_STOPS);
 
-        // 展平为 Float32Array: [offset, r, g, b, a, ...]
         const flatStops = new Float32Array(count * 5);
         for (let i = 0; i < count; i++) {
             const s = stops[i];
@@ -109,9 +142,7 @@ class WebglGradient {
         };
     }
 
-    /**
-     * 使缓存失效
-     */
+    /** 使缓存失效 */
     invalidateCache() {
         this._sortedStops = null;
         this._paramsHash = null;
@@ -119,6 +150,7 @@ class WebglGradient {
 
     /**
      * 转换为渐变的字符串表达
+     * @returns {string} 渐变字符串
      */
     toString() {
         let str = this.type + '-gradient(';