docs(hdom-canvas): update readme

thi-ng · Sep 13, 2018 · 99020ca · 99020ca
1 parent 5aa9d46
commit 99020ca
Show file tree

Hide file tree

Showing 2 changed files with 175 additions and 0 deletions.
diff --git a/examples/hdom-canvas-shapes/README.md b/examples/hdom-canvas-shapes/README.md
@@ -13,6 +13,8 @@ are translated into canvas API draw calls. Shapes can be grouped and any
 attributes defined on group nodes will be inherited by all children
 (same as in SVG).
 
+See the [@thi.ng/hdom-canvas readme](https://github.com/thi-ng/umbrella/tree/feature/hdom-canvas/packages/hdom-canvas) for further details.
+
 Related examples:
 
 - [hdom-canvas-clock](https://github.com/thi-ng/umbrella/tree/feature/hdom-canvas/examples/hdom-canvas-clock)

diff --git a/packages/hdom-canvas/README.md b/packages/hdom-canvas/README.md
@@ -12,6 +12,22 @@ This project is part of the
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [Usage examples](#usage-examples)
+- [Supported shape types](#supported-shape-types)
+    - [Group](#group)
+    - [Circle](#circle)
+    - [Rect](#rect)
+    - [Line](#line)
+    - [Polyline / Polygon](#polyline--polygon)
+    - [Path](#path)
+    - [Points](#points)
+    - [Text](#text)
+    - [Gradients](#gradients)
+- [Attributes](#attributes)
+- [Coordinate transformations](#coordinate-transformations)
+    - [Transform matrix](#transform-matrix)
+    - [Translation](#translation)
+    - [Scaling](#scaling)
+    - [Rotation](#rotation)
 - [Authors](#authors)
 - [License](#license)
 
@@ -53,6 +69,163 @@ start(() => {
 });
 ```
 
+## Supported shape types
+
+### Group
+
+```ts
+["g", attribs, child1, child2, ...]
+```
+
+Attributes defined at group level are inherited by child elements.
+
+### Circle
+
+```ts
+["circle", attribs, [x, y], r]
+```
+
+### Rect
+
+```ts
+["rect", attribs, [x, y], w, h, r?]
+```
+
+If `r` is given, creates a rounded rectangle. `r` will be clamped to `Math.min(w, h)/2`.
+
+### Line
+
+```ts
+["line", attribs, [x1, y1], [x2, y2]]
+```
+
+### Polyline / Polygon
+
+```ts
+["polyline", attribs, [[x1, y1], [x2, y2], [x3, y3]...]]
+```
+
+Always non-filled (even if `fill` attrib given or inherited)
+
+```ts
+["polygon", attribs, [[x1, y1], [x2, y2], [x3, y3]...]]
+```
+
+Always closed, filled and/or stroked.
+
+### Path
+
+```ts
+["path", attribs, [seg1, seg2, ...]]
+```
+
+Path segments are tuples of `[type, [x,y]...]`. The following segment types are supported and (as with SVG), absolute and relative versions can be used. Relative versions use lowercase letters.
+
+| Format                               | Description          |
+|--------------------------------------|----------------------|
+| `["M", [x, y]]`                      | Move                 |
+| `["L", [x, y]]`                      | Line                 |
+| `["H", x]`                           | Horizontal line      |
+| `["V", y]`                           | Vertical line        |
+| `["C", [x1,y1], [x2, y2], [x3, y3]]` | Cubic / bezier curve |
+| `["Q", [x1,y1], [x2, y2]]`           | Quadratic curve      |
+| `["A", [x1,y1], [x2, y2], r]`        | Arc                  |
+| `["Z"]`                              | Close (sub)path      |
+
+### Points
+
+```ts
+["points", attribs, [[x1,y1], [x2,y2],...]]
+```
+
+### Text
+
+```ts
+["text", attribs, [x,y], "body..."]
+```
+
+### Gradients
+
+Gradients MUST be defined at the root level of the scene tree and prior to shapes using them. Use the `$` prefix to refer to a gradient in a `fill` or `stroke` attribute, e.g. `{stroke: "$foo" }`
+
+```ts
+["linearGradient",
+    {id: "foo", from: [x1,y1], to: [x2, y2]},
+    [offset1, color1],
+    [offset2, color2],
+    ...
+]
+```
+
+```ts
+["radialGradient",
+    {id: "foo", from: [x1,y1], to: [x2, y2], r1: r1, r2: r2 },
+    [offset1, color1],
+    [offset2, color2],
+    ...
+]
+```
+
+## Attributes
+
+Some attributes use different names than their actual names in the
+`CanvasRenderingContext2D`:
+
+| Attribute   | Context 2D property      |
+|-------------|--------------------------|
+| align       | textAlign                |
+| alpha       | globalAlpha              |
+| baseLine    | textBaseline             |
+| compose     | globalCompositeOperation |
+| dash        | setLineDash              |
+| dashOffset  | lineDashOffset           |
+| direction   | direction                |
+| fill        | fillStyle                |
+| filter      | filter                   |
+| font        | font                     |
+| lineCap     | lineCap                  |
+| lineJoin    | lineJoin                 |
+| miterLimit  | miterLimit               |
+| shadowBlur  | shadowBlur               |
+| shadowColor | shadowColor              |
+| shadowX     | shadowOffsetX            |
+| shadowY     | shadowOffsetY            |
+| smooth      | imageSmoothingEnabled    |
+| stroke      | strokeStyle              |
+| weight      | lineWidth                |
+
+## Coordinate transformations
+
+Coordinate system transformations can be achieved via the following attributes. Nested transformations are supported.
+
+If using a combination of `translate`, `scale` and/or `rotate` attribs,
+the order of application is always TRS.
+
+### Transform matrix
+
+```ts
+{ transform: [xx, xy, yx, yy, ox, oy] }
+```
+
+### Translation
+
+```ts
+{ translate: [x, y] }
+```
+
+### Scaling
+
+```ts
+{ scale: [x, y] } // non-uniform
+{ scale: x } // uniform
+```
+
+### Rotation
+
+```ts
+{ rotate: theta } // in radians
+```
+
 ## Authors
 
 - Karsten Schmidt