canvas2gl 1.0.0

package/README_zh.md

@@ -0,0 +1,375 @@
+# Canvas2GL
+
+将 Canvas 2D API 映射为 WebGL 渲染的高性能 2D 图形库。使用标准的 Canvas 2D API，底层通过 WebGL 加速渲染，无需学习新的 API。
+
+## 快速开始
+
+```html
+<canvas id="c" width="800" height="600"></canvas>
+
+<script type="module">
+  import Canvas2gl from 'canvas2gl';
+
+  const ctx = new Canvas2gl(document.getElementById('c'));
+
+  ctx.fillStyle = '#e94560';
+  ctx.fillRect(50, 50, 200, 100);
+
+  ctx.fillStyle = 'white';
+  ctx.font = '18px sans-serif';
+  ctx.fillText('Hello Canvas2GL', 80, 110);
+</script>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `fillStyle` | `string \| Gradient` | `'#000000'` | 填充颜色或渐变 |
+| `strokeStyle` | `string \| Gradient` | `'#000000'` | 描边颜色或渐变 |
+| `lineWidth` | `number` | `1` | 线条宽度（像素） |
+| `globalAlpha` | `number` | `1` | 全局透明度（0~1） |
+| `globalCompositeOperation` | `string` | `'source-over'` | 合成操作模式 |
+| `font` | `string` | `'10px sans-serif'` | 文本字体，与 CSS font 规范相同 |
+| `textAlign` | `string` | `'start'` | 文本水平对齐方式 |
+| `textBaseline` | `string` | `'alphabetic'` | 文本基线对齐方式 |
+| `direction` | `string` | `'inherit'` | 文本方向（`'ltr'` / `'rtl'` / `'inherit'`） |
+| `letterSpacing` | `string` | `'0px'` | 字符间距 |
+
+### globalCompositeOperation 支持的值
+
+| 值 | 说明 |
+|----|------|
+| `'source-over'` | 默认，新图形绘制在已有内容上方 |
+| `'lighter'` | 颜色相加 |
+| `'copy'` | 只显示新图形，清除已有内容 |
+| `'source-in'` | 仅在重叠区域保留新图形 |
+| `'source-out'` | 仅在非重叠区域保留新图形 |
+| `'source-atop'` | 新图形在上，仅在重叠区域显示 |
+| `'destination-in'` | 仅在重叠区域保留已有内容 |
+| `'destination-out'` | 仅在非重叠区域保留已有内容 |
+| `'destination-atop'` | 已有内容在上，仅在重叠区域显示 |
+| `'xor'` | 异或模式，重叠区域透明 |
+| `'multiply'` | 颜色相乘（正片叠底） |
+
+### textAlign 支持的值
+
+| 值 | 说明 |
+|----|------|
+| `'left'` | 文本左对齐 |
+| `'center'` | 文本居中对齐 |
+| `'right'` | 文本右对齐 |
+| `'start'` | 根据文字方向对齐（默认） |
+| `'end'` | 根据文字方向对齐 |
+
+### textBaseline 支持的值
+
+| 值 | 说明 |
+|----|------|
+| `'top'` | 文本顶部对齐 |
+| `'hanging'` | 悬挂基线对齐 |
+| `'middle'` | 文本中间对齐 |
+| `'alphabetic'` | 字母基线对齐（默认） |
+| `'ideographic'` | 表意基线对齐 |
+| `'bottom'` | 文本底部对齐 |
+
+## 路径方法
+
+### beginPath()
+开始一条新路径，清除之前的路径命令。
+
+```js
+ctx.beginPath();
+```
+
+### moveTo(x, y)
+将画笔移动到指定坐标，开始一个新的子路径。
+
+```js
+ctx.moveTo(100, 100);
+```
+
+### lineTo(x, y)
+从当前位置画一条直线到指定坐标。
+
+```js
+ctx.lineTo(200, 100);
+```
+
+### arc(cx, cy, radius, startAngle, endAngle, anticlockwise?)
+绘制圆弧。角度以弧度为单位。
+
+```js
+// 绘制一个完整的圆
+ctx.arc(150, 150, 50, 0, Math.PI * 2);
+
+// 逆时针绘制半圆
+ctx.arc(150, 150, 50, 0, Math.PI, true);
+```
+
+### rect(x, y, w, h)
+添加一个矩形子路径。
+
+```js
+ctx.rect(10, 10, 100, 50);
+```
+
+### bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)
+添加一条三次贝塞尔曲线到当前路径。曲线从当前点开始，以 `(cp1x, cp1y)` 和 `(cp2x, cp2y)` 为控制点，到 `(x, y)` 结束。
+
+```js
+ctx.beginPath();
+ctx.moveTo(50, 100);
+ctx.bezierCurveTo(100, 20, 200, 180, 300, 100);
+ctx.stroke();
+```
+
+### quadraticCurveTo(cpx, cpy, x, y)
+添加一条二次贝塞尔曲线到当前路径。曲线从当前点开始，以 `(cpx, cpy)` 为控制点，到 `(x, y)` 结束。
+
+```js
+ctx.beginPath();
+ctx.moveTo(50, 100);
+ctx.quadraticCurveTo(200, 20, 350, 100);
+ctx.stroke();
+```
+
+### closePath()
+闭合当前路径，连接终点与起点。
+
+```js
+ctx.closePath();
+```
+
+### fill()
+填充当前路径。调用后会自动调用 `beginPath()`。
+
+```js
+ctx.beginPath();
+ctx.arc(100, 100, 40, 0, Math.PI * 2);
+ctx.fill();
+```
+
+### stroke()
+描边当前路径。调用后会自动调用 `beginPath()`。
+
+```js
+ctx.beginPath();
+ctx.moveTo(50, 50);
+ctx.lineTo(150, 100);
+ctx.stroke();
+```
+
+## 矩形方法
+
+### fillRect(x, y, w, h)
+绘制填充矩形。
+
+```js
+ctx.fillStyle = '#e94560';
+ctx.fillRect(50, 50, 200, 100);
+```
+
+### strokeRect(x, y, w, h)
+绘制描边矩形。
+
+```js
+ctx.strokeStyle = '#00d4ff';
+ctx.lineWidth = 3;
+ctx.strokeRect(50, 50, 200, 100);
+```
+
+### clearRect(x, y, w, h)
+清除指定矩形区域，将其变为透明。
+
+```js
+ctx.clearRect(0, 0, 400, 200);
+```
+
+## 渐变方法
+
+### createLinearGradient(x0, y0, x1, y1)
+创建一个从 `(x0, y0)` 到 `(x1, y1)` 的线性渐变。返回一个 `Gradient` 对象，可赋值给 `fillStyle` 或 `strokeStyle`。
+
+```js
+const grad = ctx.createLinearGradient(0, 0, 400, 0);
+grad.addColorStop(0, '#e94560');
+grad.addColorStop(0.5, '#ffd700');
+grad.addColorStop(1, '#00d4ff');
+ctx.fillStyle = grad;
+ctx.fillRect(0, 0, 400, 200);
+```
+
+### Gradient.addColorStop(offset, color)
+向渐变添加一个色标。`offset` 是 0 到 1 之间的值，`color` 是任意有效的 CSS 颜色字符串。
+
+```js
+grad.addColorStop(0, '#e94560');          // 起始为红色
+grad.addColorStop(0.5, 'rgba(0,255,100,0.5)');  // 中间为半透明绿色
+grad.addColorStop(1, 'blue');             // 结束为蓝色
+```
+
+## 文本方法
+
+### fillText(text, x, y, maxWidth?)
+绘制填充文本。
+
+```js
+ctx.font = '24px sans-serif';
+ctx.fillStyle = 'white';
+ctx.fillText('Hello World', 100, 100);
+
+// 带最大宽度限制
+ctx.fillText('Hello World', 100, 100, 200);
+```
+
+### strokeText(text, x, y, maxWidth?)
+绘制描边文本。
+
+```js
+ctx.font = 'bold 18px sans-serif';
+ctx.strokeStyle = '#00d4ff';
+ctx.strokeText('Stroke Text', 50, 80);
+```
+
+### measureText(text)
+测量文本尺寸，返回 `TextMetrics` 对象。
+
+```js
+const metrics = ctx.measureText('Hello');
+console.log(metrics.width); // 文本宽度
+```
+
+## 图像方法
+
+### drawImage(source, ...args)
+绘制图像到画布上，支持三种调用形式：
+
+**形式 1：按原始尺寸绘制**
+```js
+ctx.drawImage(image, dx, dy);
+```
+
+**形式 2：缩放绘制**
+```js
+ctx.drawImage(image, dx, dy, dw, dh);
+```
+
+**形式 3：裁剪并缩放绘制**
+```js
+ctx.drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh);
+```
+
+参数说明：
+- `source`：`HTMLImageElement` / `HTMLCanvasElement` / `HTMLVideoElement`
+- `sx`, `sy`：源图像裁剪起始坐标
+- `sw`, `sh`：源图像裁剪尺寸
+- `dx`, `dy`：目标画布绘制坐标
+- `dw`, `dh`：目标画布绘制尺寸
+
+```js
+const img = new Image();
+img.src = 'texture.png';
+img.onload = () => {
+  // 在 (50, 50) 绘制原始尺寸
+  ctx.drawImage(img, 50, 50);
+
+  // 在 (200, 50) 缩放为 100x100
+  ctx.drawImage(img, 200, 50, 100, 100);
+
+  // 裁剪 (10,10,50,50) 区域，绘制到 (300,50,80,80)
+  ctx.drawImage(img, 10, 10, 50, 50, 300, 50, 80, 80);
+};
+```
+
+## 像素方法
+
+### getImageData(sx, sy, sw, sh)
+读取画布指定矩形区域的像素数据，返回 `ImageData` 对象。
+
+```js
+const imageData = ctx.getImageData(0, 0, 400, 200);
+// imageData.data 是 Uint8ClampedArray，包含 RGBA 像素数据
+// imageData.width 和 imageData.height 为请求的尺寸
+const r = imageData.data[0]; // 第一个像素的红色分量
+const g = imageData.data[1];
+const b = imageData.data[2];
+const a = imageData.data[3]; // alpha 分量
+```
+
+## 变换方法
+
+### translate(x, y)
+平移变换，将原点移动到指定位置。
+
+```js
+ctx.translate(200, 100);
+```
+
+### rotate(angle)
+旋转变换，angle 以弧度为单位。
+
+```js
+ctx.rotate(Math.PI / 4); // 旋转 45 度
+```
+
+### scale(x, y)
+缩放变换。
+
+```js
+ctx.scale(2, 1); // 水平方向放大 2 倍
+```
+
+### transform(a, b, c, d, e, f)
+累积应用变换矩阵 `[a, b, c, d, e, f]`。
+
+```js
+ctx.transform(1, 0.5, 0, 1, 10, 0);
+```
+
+### setTransform(a, b, c, d, e, f)
+重置并设置变换矩阵。
+
+```js
+ctx.setTransform(2, 0, 0, 2, 50, 50);
+```
+
+### resetTransform()
+将变换矩阵重置为单位矩阵。
+
+```js
+ctx.resetTransform();
+```
+
+## 状态方法
+
+### save()
+保存当前绘图状态到栈中，包括：变换矩阵、`fillStyle`、`strokeStyle`、`lineWidth`、`globalAlpha`、`globalCompositeOperation`。
+
+```js
+ctx.save();
+ctx.translate(100, 50);
+// ... 绘制操作 ...
+ctx.restore(); // 恢复保存前的状态
+```
+
+### restore()
+从栈中恢复最近保存的绘图状态。
+
+## 画布方法
+
+### clear()
+清除整个画布，重置为透明。
+
+```js
+ctx.clear();
+```
+
+### resize()
+根据画布元素的 CSS 尺寸重新调整 WebGL 视口。在画布大小改变时调用。
+
+```js
+window.addEventListener('resize', () => {
+  ctx.resize();
+});
+```

package/dist/gradient.d.ts

@@ -0,0 +1,21 @@
+export declare class Gradient {
+    private stops;
+    private x0;
+    private y0;
+    private x1;
+    private y1;
+    private _texture;
+    private _gl;
+    constructor(x0: number, y0: number, x1: number, y1: number);
+    addColorStop(offset: number, color: string): void;
+    getTexture(gl: WebGLRenderingContext): WebGLTexture;
+    getParams(): {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+    toCanvasGradient(ctx: CanvasRenderingContext2D): CanvasGradient;
+    private _sample;
+}
+export declare function parseColorString(color: string): [number, number, number, number];

package/dist/gradient.js

@@ -0,0 +1,137 @@
+export class Gradient {
+    stops = [];
+    x0;
+    y0;
+    x1;
+    y1;
+    _texture = null;
+    _gl = null;
+    constructor(x0, y0, x1, y1) {
+        this.x0 = x0;
+        this.y0 = y0;
+        this.x1 = x1;
+        this.y1 = y1;
+    }
+    addColorStop(offset, color) {
+        this.stops.push({ offset, color: parseColorString(color) });
+        this.stops.sort((a, b) => a.offset - b.offset);
+        this._texture = null;
+    }
+    getTexture(gl) {
+        if (this._texture && this._gl === gl)
+            return this._texture;
+        const size = 256;
+        const data = new Uint8Array(size * 4);
+        for (let i = 0; i < size; i++) {
+            const t = i / (size - 1);
+            const color = this._sample(t);
+            const idx = i * 4;
+            data[idx] = Math.round(color[0] * 255);
+            data[idx + 1] = Math.round(color[1] * 255);
+            data[idx + 2] = Math.round(color[2] * 255);
+            data[idx + 3] = Math.round(color[3] * 255);
+        }
+        const tex = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, tex);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, size, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, data);
+        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, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        this._texture = tex;
+        this._gl = gl;
+        return tex;
+    }
+    getParams() {
+        return { x0: this.x0, y0: this.y0, x1: this.x1, y1: this.y1 };
+    }
+    toCanvasGradient(ctx) {
+        const g = ctx.createLinearGradient(this.x0, this.y0, this.x1, this.y1);
+        for (const stop of this.stops) {
+            const [r, gv, b, a] = stop.color;
+            g.addColorStop(stop.offset, `rgba(${Math.round(r * 255)},${Math.round(gv * 255)},${Math.round(b * 255)},${a})`);
+        }
+        return g;
+    }
+    _sample(t) {
+        if (this.stops.length === 0)
+            return [0, 0, 0, 0];
+        if (t <= this.stops[0].offset)
+            return this.stops[0].color;
+        for (let i = 0; i < this.stops.length - 1; i++) {
+            const s0 = this.stops[i];
+            const s1 = this.stops[i + 1];
+            if (t < s1.offset) {
+                const f = (t - s0.offset) / (s1.offset - s0.offset);
+                return [
+                    s0.color[0] + (s1.color[0] - s0.color[0]) * f,
+                    s0.color[1] + (s1.color[1] - s0.color[1]) * f,
+                    s0.color[2] + (s1.color[2] - s0.color[2]) * f,
+                    s0.color[3] + (s1.color[3] - s0.color[3]) * f,
+                ];
+            }
+        }
+        return this.stops[this.stops.length - 1].color;
+    }
+}
+export function parseColorString(color) {
+    const named = {
+        black: [0, 0, 0, 1], white: [1, 1, 1, 1], red: [1, 0, 0, 1],
+        green: [0, 0.502, 0, 1], blue: [0, 0, 1, 1], yellow: [1, 1, 0, 1],
+        cyan: [0, 1, 1, 1], magenta: [1, 0, 1, 1], orange: [1, 0.647, 0, 1],
+        gray: [0.502, 0.502, 0.502, 1], grey: [0.502, 0.502, 0.502, 1],
+        transparent: [0, 0, 0, 0],
+    };
+    color = color.trim().toLowerCase();
+    if (named[color])
+        return [...named[color]];
+    let match;
+    match = color.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/);
+    if (match) {
+        return [
+            parseInt(match[1], 16) / 255,
+            parseInt(match[2], 16) / 255,
+            parseInt(match[3], 16) / 255,
+            parseInt(match[4], 16) / 255,
+        ];
+    }
+    match = color.match(/^#([0-9a-f])([0-9a-f])([0-9a-f])([0-9a-f])$/);
+    if (match) {
+        return [
+            parseInt(match[1] + match[1], 16) / 255,
+            parseInt(match[2] + match[2], 16) / 255,
+            parseInt(match[3] + match[3], 16) / 255,
+            parseInt(match[4] + match[4], 16) / 255,
+        ];
+    }
+    match = color.match(/^#([0-9a-f]{6})$/);
+    if (match) {
+        return [
+            parseInt(match[1].substring(0, 2), 16) / 255,
+            parseInt(match[1].substring(2, 4), 16) / 255,
+            parseInt(match[1].substring(4, 6), 16) / 255,
+            1,
+        ];
+    }
+    match = color.match(/^#([0-9a-f]{3})$/);
+    if (match) {
+        const c = match[1];
+        return [
+            parseInt(c[0] + c[0], 16) / 255,
+            parseInt(c[1] + c[1], 16) / 255,
+            parseInt(c[2] + c[2], 16) / 255,
+            1,
+        ];
+    }
+    match = color.match(/^rgba?\(\s*(\d+%?)\s*,\s*(\d+%?)\s*,\s*(\d+%?)\s*(?:,\s*([\d.]+%?)\s*)?\)$/);
+    if (match) {
+        const toVal = (v) => v.endsWith('%') ? parseFloat(v) / 100 * 255 : parseInt(v, 10);
+        return [
+            toVal(match[1]) / 255,
+            toVal(match[2]) / 255,
+            toVal(match[3]) / 255,
+            match[4] !== undefined ? parseFloat(match[4]) : 1,
+        ];
+    }
+    return [0, 0, 0, 1];
+}

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { Gradient } from './gradient.js';
+export default class Canvas2gl {
+    private renderer;
+    private pathCommands;
+    private pathPoints;
+    private pathSubpaths;
+    private pathClosed;
+    private texCache;
+    private _offscreen;
+    private _offCtx;
+    private _transform;
+    private _stateStack;
+    fillStyle: string | Gradient;
+    strokeStyle: string | Gradient;
+    lineWidth: number;
+    globalAlpha: number;
+    globalCompositeOperation: string;
+    font: string;
+    textAlign: CanvasTextAlign;
+    textBaseline: CanvasTextBaseline;
+    direction: CanvasDirection;
+    letterSpacing: string;
+    private currentX;
+    private currentY;
+    private subStartIdx;
+    constructor(canvas: HTMLCanvasElement);
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    arc(cx: number, cy: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    fillRect(x: number, y: number, w: number, h: number): void;
+    strokeRect(x: number, y: number, w: number, h: number): void;
+    closePath(): void;
+    fill(): void;
+    stroke(): void;
+    clearRect(x: number, y: number, w: number, h: number): void;
+    clear(): void;
+    getImageData(sx: number, sy: number, sw: number, sh: number): ImageData;
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): Gradient;
+    resize(): void;
+    drawImage(source: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, dx: number, dy: number): void;
+    drawImage(source: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, dx: number, dy: number, dw: number, dh: number): void;
+    drawImage(source: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
+    fillText(text: string, x: number, y: number, maxWidth?: number): void;
+    strokeText(text: string, x: number, y: number, maxWidth?: number): void;
+    measureText(text: string): TextMetrics;
+    save(): void;
+    restore(): void;
+    translate(x: number, y: number): void;
+    rotate(angle: number): void;
+    scale(x: number, y: number): void;
+    transform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    resetTransform(): void;
+    private _multiplyTransform;
+    private _drawShape;
+    private _renderText;
+    private _syncToOffscreen;
+    private _applyTextAlignX;
+    private parseColor;
+}