Instruction set reference
HIPE_OP_CANVAS_ACTION
Calls a drawing method on the canvas that was selected with HIPE_OP_USE_CANVAS. The methods are those of the HTML Canvas 2D Context.
- location: not used. The instruction applies to the selected canvas.
- arg[0]: the name of the method, e.g. "fillRect".
- arg[1]: the method's parameters, separated by commas, in the order the method takes them, e.g. "0,0,150,75" for fillRect's x, y, width and height.
An unknown method name, the wrong number of parameters, or a parameter that can't be used (such as text where a number is expected) causes the instruction to be ignored. No error is reported.
The methods are those listed below. Most are methods of the HTML Canvas 2D Context; those dealing with ids, and setSrcRegion, are Hipe's own.
Writing the parameters
- Spaces around a comma are ignored: "0, 0, 150, 75" is the same as "0,0,150,75".
- A comma inside round or square brackets doesn't separate parameters, so rgba(0,0,0,0.5) and [4,2] are each one parameter.
- Put a parameter in double quotes if it contains a comma or spaces that matter, such as the text for fillText: "Score: 1, 2, 3", 10, 20. Inside the quotes, write a double quote as \".
Methods
| Method | Arguments |
|---|---|
| save | — |
| restore | — |
| scale | sx, sy |
| rotate | angle (radians) |
| translate | tx, ty |
| transform | m11, m12, m21, m22, dx, dy |
| setTransform | m11, m12, m21, m22, dx, dy |
| beginPath | — |
| closePath | — |
| moveTo | x, y |
| lineTo | x, y |
| quadraticCurveTo | cpx, cpy, x, y |
| bezierCurveTo | cp1x, cp1y, cp2x, cp2y, x, y |
| arcTo | x0, y0, x1, y1, radius |
| arc | x, y, radius, startAngle, endAngle, anticlockwise ("true"/"false") |
| ellipse | x, y, radiusX, radiusY, rotation, startAngle, endAngle, anticlockwise ("true"/"false") |
| rect | x, y, width, height |
| fill | 0 args (implicit path, default winding); 1 arg (implicit path, winding rule "nonzero"/"evenodd"); or 2 args (path id, winding rule) |
| stroke | 0 args (implicit path) or 1 arg (path id) |
| clip | same shape as fill above |
| clearRect | x, y, width, height |
| fillRect | x, y, width, height |
| strokeRect | x, y, width, height |
| fillText | text, x, y, optional maxWidth |
| strokeText | text, x, y, optional maxWidth |
| setLineDash | a single bracketed list of numbers, e.g. [4,2] ([] clears the dash pattern) |
| drawImage | source element id, then either (dx, dy), (dx, dy, dw, dh), or (sx, sy, sw, sh, dx, dy, dw, dh) (see Notes) |
| setSrcRegion | dx, dy, width, height (see Notes) |
| createLinearGradient | id, x0, y0, x1, y1 |
| createRadialGradient | id, x0, y0, r0, x1, y1, r1 |
| addColorStop | gradientId, offset, color |
| createPattern | id, sourceElementId, repetition ("repeat"/"repeat-x"/"repeat-y"/"no-repeat") |
| deleteGradient | gradientId |
| deletePattern | patternId |
| createPath2D | id |
| deletePath2D | id |
| selectPath2D | id (empty string reselects this canvas's own implicit path) |
Gradients, patterns and paths
In HTML a gradient, pattern or path is an object that a script keeps hold of. Here each one is given an id by the client when it is created, and is referred to by that id afterwards. Ids belong to the canvas they were created on: the same id on another canvas is a different object.
- Gradients and patterns are created with createLinearGradient, createRadialGradient and createPattern. To draw with one, set fillStyle or strokeStyle to url(#id) with HIPE_OP_CANVAS_SET_PROPERTY.
- A path is created with createPath2D. Call selectPath2D with its id, and the path-building methods (moveTo, lineTo, arc, rect and so on) add to that path instead of the canvas's own, until selectPath2D is called with a different id or an empty one. fill, stroke and clip can be given a path's id directly, without selecting it, and so can the tests of HIPE_OP_CANVAS_QUERY.
- These objects are kept until they are deleted with deleteGradient, deletePattern or deletePath2D. A client that creates many should delete those it no longer needs.
Notes
beginPath always starts the canvas's own path afresh, whichever path is selected. To start a new named path, create one under a new id.
drawImage's first parameter is the id attribute of an img, canvas or video element in the document. The rest are numbers, in one of three forms: the destination position (dx, dy); the destination rectangle (dx, dy, dw, dh); or a source rectangle followed by the destination rectangle (sx, sy, sw, sh, dx, dy, dw, dh).
setSrcRegion is not a method of the HTML canvas. It sets the area of the canvas that raw pixels sent with HIPE_OP_SET_SRC will be written to: the top-left position (dx, dy) and the width and height of the pixel data. The area is in canvas pixels and is not affected by scale, translate or the other transformations. It stays in effect until it is set again. If it is never set, raw pixels fill the whole canvas. See HIPE_OP_SET_SRC.
Only the 2D context is available. To read a canvas back as an image, use HIPE_OP_GET_SRC.