canvas2gl 1.0.0

package/README.md

@@ -0,0 +1,376 @@
+中文文档 [README.zh-CN.md](README.zh-CN.md)
+# Canvas2GL
+
+A high-performance 2D graphics library that maps the Canvas 2D API to WebGL rendering. Use standard Canvas 2D API calls — the library handles WebGL acceleration under the hood. No new APIs to learn.
+
+## Quick Start
+
+```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>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `fillStyle` | `string \| Gradient` | `'#000000'` | Fill color or gradient |
+| `strokeStyle` | `string \| Gradient` | `'#000000'` | Stroke color or gradient |
+| `lineWidth` | `number` | `1` | Line width in pixels |
+| `globalAlpha` | `number` | `1` | Global alpha transparency (0–1) |
+| `globalCompositeOperation` | `string` | `'source-over'` | Compositing operation |
+| `font` | `string` | `'10px sans-serif'` | Font style (same as CSS `font`) |
+| `textAlign` | `string` | `'start'` | Horizontal text alignment |
+| `textBaseline` | `string` | `'alphabetic'` | Text baseline alignment |
+| `direction` | `string` | `'inherit'` | Text direction (`'ltr'` / `'rtl'` / `'inherit'`) |
+| `letterSpacing` | `string` | `'0px'` | Letter spacing |
+
+### Supported `globalCompositeOperation` Values
+
+| Value | Description |
+|-------|-------------|
+| `'source-over'` | Default — draws new shapes over existing content |
+| `'lighter'` | Additive blending |
+| `'copy'` | Only shows new shapes, clears existing content |
+| `'source-in'` | Keeps new shapes only in overlapping areas |
+| `'source-out'` | Keeps new shapes only in non-overlapping areas |
+| `'source-atop'` | New shapes on top, only in overlapping areas |
+| `'destination-in'` | Keeps existing content only in overlapping areas |
+| `'destination-out'` | Keeps existing content only in non-overlapping areas |
+| `'destination-atop'` | Existing content on top, only in overlapping areas |
+| `'xor'` | XOR mode — overlapping area becomes transparent |
+| `'multiply'` | Multiply blending |
+
+### Supported `textAlign` Values
+
+| Value | Description |
+|-------|-------------|
+| `'left'` | Align text to the left |
+| `'center'` | Center text |
+| `'right'` | Align text to the right |
+| `'start'` | Align based on text direction (default) |
+| `'end'` | Align based on text direction |
+
+### Supported `textBaseline` Values
+
+| Value | Description |
+|-------|-------------|
+| `'top'` | Align to top of text |
+| `'hanging'` | Hanging baseline |
+| `'middle'` | Middle of text |
+| `'alphabetic'` | Alphabetic baseline (default) |
+| `'ideographic'` | Ideographic baseline |
+| `'bottom'` | Bottom of text |
+
+## Path Methods
+
+### beginPath()
+Starts a new path, clearing previous path commands.
+
+```js
+ctx.beginPath();
+```
+
+### moveTo(x, y)
+Moves the pen to the given coordinates, starting a new sub-path.
+
+```js
+ctx.moveTo(100, 100);
+```
+
+### lineTo(x, y)
+Draws a straight line from the current position to the given coordinates.
+
+```js
+ctx.lineTo(200, 100);
+```
+
+### arc(cx, cy, radius, startAngle, endAngle, anticlockwise?)
+Draws an arc. Angles are in radians.
+
+```js
+// Full circle
+ctx.arc(150, 150, 50, 0, Math.PI * 2);
+
+// Counter-clockwise half circle
+ctx.arc(150, 150, 50, 0, Math.PI, true);
+```
+
+### rect(x, y, w, h)
+Adds a rectangle sub-path.
+
+```js
+ctx.rect(10, 10, 100, 50);
+```
+
+### bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)
+Adds a cubic Bezier curve from the current point to `(x, y)`, with control points `(cp1x, cp1y)` and `(cp2x, cp2y)`.
+
+```js
+ctx.beginPath();
+ctx.moveTo(50, 100);
+ctx.bezierCurveTo(100, 20, 200, 180, 300, 100);
+ctx.stroke();
+```
+
+### quadraticCurveTo(cpx, cpy, x, y)
+Adds a quadratic Bezier curve from the current point to `(x, y)`, with control point `(cpx, cpy)`.
+
+```js
+ctx.beginPath();
+ctx.moveTo(50, 100);
+ctx.quadraticCurveTo(200, 20, 350, 100);
+ctx.stroke();
+```
+
+### closePath()
+Closes the current path by connecting the end point to the start point.
+
+```js
+ctx.closePath();
+```
+
+### fill()
+Fills the current path. Automatically calls `beginPath()` afterwards.
+
+```js
+ctx.beginPath();
+ctx.arc(100, 100, 40, 0, Math.PI * 2);
+ctx.fill();
+```
+
+### stroke()
+Strokes the current path. Automatically calls `beginPath()` afterwards.
+
+```js
+ctx.beginPath();
+ctx.moveTo(50, 50);
+ctx.lineTo(150, 100);
+ctx.stroke();
+```
+
+## Rectangle Methods
+
+### fillRect(x, y, w, h)
+Draws a filled rectangle.
+
+```js
+ctx.fillStyle = '#e94560';
+ctx.fillRect(50, 50, 200, 100);
+```
+
+### strokeRect(x, y, w, h)
+Draws a stroked rectangle.
+
+```js
+ctx.strokeStyle = '#00d4ff';
+ctx.lineWidth = 3;
+ctx.strokeRect(50, 50, 200, 100);
+```
+
+### clearRect(x, y, w, h)
+Clears the specified rectangular area to transparent.
+
+```js
+ctx.clearRect(0, 0, 400, 200);
+```
+
+## Gradient Methods
+
+### createLinearGradient(x0, y0, x1, y1)
+Creates a linear gradient from `(x0, y0)` to `(x1, y1)`. Returns a `Gradient` object that can be assigned to `fillStyle` or `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)
+Adds a color stop to the gradient. `offset` is a value between 0 and 1, `color` is any valid CSS color string.
+
+```js
+grad.addColorStop(0, '#e94560');      // red at start
+grad.addColorStop(0.5, 'rgba(0,255,100,0.5)');  // semi-transparent green in middle
+grad.addColorStop(1, 'blue');         // blue at end
+```
+
+## Text Methods
+
+### fillText(text, x, y, maxWidth?)
+Draws filled text.
+
+```js
+ctx.font = '24px sans-serif';
+ctx.fillStyle = 'white';
+ctx.fillText('Hello World', 100, 100);
+
+// With max width constraint
+ctx.fillText('Hello World', 100, 100, 200);
+```
+
+### strokeText(text, x, y, maxWidth?)
+Draws stroked (outlined) text.
+
+```js
+ctx.font = 'bold 18px sans-serif';
+ctx.strokeStyle = '#00d4ff';
+ctx.strokeText('Stroke Text', 50, 80);
+```
+
+### measureText(text)
+Measures text size and returns a `TextMetrics` object.
+
+```js
+const metrics = ctx.measureText('Hello');
+console.log(metrics.width); // text width
+```
+
+## Image Methods
+
+### drawImage(source, ...args)
+Draws an image onto the canvas. Supports three overloads:
+
+**Form 1: Draw at original size**
+```js
+ctx.drawImage(image, dx, dy);
+```
+
+**Form 2: Draw with scaling**
+```js
+ctx.drawImage(image, dx, dy, dw, dh);
+```
+
+**Form 3: Crop and scale**
+```js
+ctx.drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh);
+```
+
+Parameters:
+- `source`: `HTMLImageElement` / `HTMLCanvasElement` / `HTMLVideoElement`
+- `sx`, `sy`: Source crop start coordinates
+- `sw`, `sh`: Source crop size
+- `dx`, `dy`: Destination canvas coordinates
+- `dw`, `dh`: Destination canvas size
+
+```js
+const img = new Image();
+img.src = 'texture.png';
+img.onload = () => {
+  // Draw at original size at (50, 50)
+  ctx.drawImage(img, 50, 50);
+
+  // Draw scaled to 100x100 at (200, 50)
+  ctx.drawImage(img, 200, 50, 100, 100);
+
+  // Crop (10,10,50,50) and draw to (300,50,80,80)
+  ctx.drawImage(img, 10, 10, 50, 50, 300, 50, 80, 80);
+};
+```
+
+## Pixel Methods
+
+### getImageData(sx, sy, sw, sh)
+Reads pixel data from the specified rectangle and returns an `ImageData` object.
+
+```js
+const imageData = ctx.getImageData(0, 0, 400, 200);
+// imageData.data is a Uint8ClampedArray of RGBA values
+// imageData.width and imageData.height are the requested dimensions
+const r = imageData.data[0]; // red component of first pixel
+const g = imageData.data[1]; // green
+const b = imageData.data[2]; // blue
+const a = imageData.data[3]; // alpha
+```
+
+## Transform Methods
+
+### translate(x, y)
+Moves the origin to the given coordinates.
+
+```js
+ctx.translate(200, 100);
+```
+
+### rotate(angle)
+Rotates by `angle` (in radians).
+
+```js
+ctx.rotate(Math.PI / 4); // 45 degrees
+```
+
+### scale(x, y)
+Scales by `x` horizontally and `y` vertically.
+
+```js
+ctx.scale(2, 1); // double horizontal size
+```
+
+### transform(a, b, c, d, e, f)
+Applies a cumulative transform matrix `[a, b, c, d, e, f]`.
+
+```js
+ctx.transform(1, 0.5, 0, 1, 10, 0);
+```
+
+### setTransform(a, b, c, d, e, f)
+Resets and sets the transform matrix.
+
+```js
+ctx.setTransform(2, 0, 0, 2, 50, 50);
+```
+
+### resetTransform()
+Resets the transform matrix to the identity matrix.
+
+```js
+ctx.resetTransform();
+```
+
+## State Methods
+
+### save()
+Saves the current drawing state onto a stack, including: transform matrix, `fillStyle`, `strokeStyle`, `lineWidth`, `globalAlpha`, `globalCompositeOperation`.
+
+```js
+ctx.save();
+ctx.translate(100, 50);
+// ... draw operations ...
+ctx.restore(); // restores the saved state
+```
+
+### restore()
+Restores the most recently saved drawing state from the stack.
+
+## Canvas Methods
+
+### clear()
+Clears the entire canvas to transparent.
+
+```js
+ctx.clear();
+```
+
+### resize()
+Resizes the WebGL viewport to match the CSS size of the canvas element. Call this when the canvas size changes.
+
+```js
+window.addEventListener('resize', () => {
+  ctx.resize();
+});
+```