Class Canvas
Version
1.1.
Defined in: canvas-1.2.dev.js.
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
Canvas(canvas, fps, renderCallback, autostart, layerParent, drawOnly)
The canvas library class.
|
| Field Attributes | Field Name and Description |
|---|---|
|
Is this the first frame of the animation, a public attribute.
|
|
|
Number of frames rendered
|
|
|
The height of the canvas, a public attribute.
|
|
|
The keyboard events storage object, use to get keyboard state.
|
|
|
Last frame duration
|
|
|
The mouse events storage object, use to get mouse state.
|
|
|
The scene object.
|
|
|
The start time of the animation rendering
|
|
|
Total rendering duration
|
|
|
Library version
|
|
|
The width of the canvas, a public attribute.
|
| Method Attributes | Method Name and Description |
|---|---|
|
Applies default styles.
|
|
|
arc(x, y, radius, startAngle, endAngle, anticlockwise, align, rotation)
Draws an arc with given parameters and add it to current path.
|
|
|
beginComposite(operationName)
Begins composition.
|
|
|
beginLinearGradient(startX, startY, endX, endY, stops)
Begins linear gradient for both fill and stroke operations.
|
|
|
beginLinearGradientFill(startX, startY, endX, endY, stops)
Begins linear gradient for fill operations.
|
|
|
beginLinearGradientStroke(startX, startY, endX, endY, stops)
Begins linear gradient for stroke operations.
|
|
|
Starts a new path, emptying the list of current subpaths.
|
|
|
beginRadialGradient(x1, y1, radius1, x2, y2, radius2, stops)
Begins using radial gradient for following fill and stoke operations.
|
|
|
beginRadialGradientFill(x1, y1, radius1, x2, y2, radius2, stops)
Begins using radial gradient for following fill operations.
|
|
|
beginRadialGradientStroke(x1, y1, radius1, x2, y2, radius2, stops)
Begins using radial gradient for following stroke operations.
|
|
|
beginShadow(offsetX, offsetY, blurRadius, color)
Begins using given shadow style.
|
|
|
bezierCurveTo(fistControlPointX, firstControlPointY, secondControlPointX, secondControlPointY, x, y)
Adds a bezier curve to the path.
|
|
|
circle(x, y, radius, align)
Adds a circle subpath.
|
|
|
clear()
Clears the whole canvas.
|
|
|
clearRect(x, y, width, height, align, rotation)
Clears the pixels in specified rectangle that also intersects the current clipping
region to fully transparent black, erasing any previous image.
|
|
|
Closes the last subpath and creates a new subpath whose first point is the same as the
previous subpath's first point and adds it to the path.
|
|
|
color(fillColor, strokeColor)
Sets both the fill and the stroke color.
|
|
|
createLayer(name, fps, renderCallback, zIndex, autostart)
Creates a new layer at top-left corner with the same width, height of the parent canvas.
|
|
|
createLayerAt(name, x, y, width, height, fps, renderCallback, zIndex, autostart)
Creates a new layer at given position using given size.
|
|
|
createLinearGradient(startX, startY, endX, endY, stops)
Creates linear gradient style and returns it.
|
|
|
createRadialGradient(x1, y1, radius1, x2, y2, radius2, stops)
Creates radial gradient style and returns it.
|
|
|
drawImage(image, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10)
This function can be called with three possible argument sets:
- drawImage(image, destinationX, destinationY, align, rotation)
- drawImage(image, destinationX, destinationY, destinationWidth, destinationHeight, align, rotation)
- drawImage(image, sourceX, sourceY, sourceWidth, sourceHeight, destinationX, destinationY, destinationWidth, destinationHeight, align, rotation)
The align and rotation are optional in any case.
|
|
|
ellipse(x, y, width, height, align, rotation)
Adds an ellipse subpath.
|
|
|
Ends composition.
|
|
|
Ends using a gradient style created with any of the begin gradient methods.
|
|
|
Stops using given shadow style.
|
|
|
errorHandler(message)
Default error handler, just alerts the error.
|
|
|
fill()
Fills all the subpaths of current path using current fill style.
|
|
|
fillArc(x, y, radius, startAngle, endAngle, anticlockwise, align, rotation)
Fills an arc onto the canvas.
|
|
|
fillCircle(x, y, radius, align)
Fills a circle onto the canvas.
|
|
|
fillColor(color)
Sets the fill color.
|
|
|
fillEllipse(x, y, width, height, align, rotation)
Fills an ellipse onto the canvas.
|
|
|
fillRect(x, y, width, height, align, rotation)
Fills a rectangle onto the canvas.
|
|
|
fillRoundedRect(x, y, width, height, radius, align, rotation)
Fills a new rounded rectangle onto the canvas.
|
|
|
fillStyle(style)
Sets the fill style.
|
|
|
fillText(text, x, y, align, rotation)
Fills given text at given coordinates using the optional align and rotation settings.
|
|
|
font(definition)
Sets font style to use for the following text operations.
|
|
|
getFPS()
Returs actual current framerate (average number of frames rendered per second).
|
|
|
Returns the height of the canvas.
|
|
|
getLayer(name)
Returns a layer by name.
|
|
|
Returns the parent canvas object of a layer.
|
|
|
Returs current target framerate.
|
|
|
Returns library version
|
|
|
getWidth()
Returns the width of the canvas.
|
|
|
grid(xStep, yStep, x, y, width, height, rotation)
Draws a grid.
|
|
|
line(x1, y1, x2, y2)
Adds a line subpath to current path.
|
|
|
lineCap(lineCap)
Sets line cap style of following stroke operations.
|
|
|
lineJoin(lineJoin)
Sets line join style of following stroke operations.
|
|
|
lineTo(x, y)
Adds a line to given coordinates to the active path.
|
|
|
lineWidth(width)
Sets line width of following stroke operations.
|
|
|
loadImage(url, loadedCallback, errorCallback)
Load an image from url and calls the callbacks when read or something went wrong.
|
|
|
millis()
Returns the milliseconds, useful for timing.
|
|
|
moveTo(x, y)
Creates a new subpath with the specified point as the first and only point.
|
|
|
onContextMenu(event)
Called when context menu is requested on the canvas element.
|
|
|
onKeyDown(keyCode, character, isCtrlPressed, isShiftPressed, isAltPressed)
Called when a keyboard key is pressed down.
|
|
|
onKeyPress(keyCode, character, isCtrlPressed, isShiftPressed, isAltPressed)
Called when a keyboard key is pressed (both down and released back up)
This does nothing by default and is meant for overriding to implement
your own functionality.
|
|
|
onKeyUp(keyCode, character, isCtrlPressed, isShiftPressed, isAltPressed)
Called when a keyboard key is released.
|
|
|
onMouseDown(x, y, button)
Called when a mouse button is pressed down.
|
|
|
onMouseMove(x, y)
Called when the mouse is moved.
|
|
|
onMouseScroll(delta, absolute)
Called when the mouse wheel is scrolled.
|
|
|
onMouseUp(x, y, button)
Called when a mouse button is released.
|
|
|
onMultiTouchEnd(touches, event)
Called at the end of a multi-touch event (atleast two touches)
The touches array contains the following info about every touch
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
|
|
|
onMultiTouchMove(touches, previousTouches, event)
Called at touch move events (atleast two touches)
The touches array contains the following info about every touch
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
|
|
|
onMultiTouchStart(touches, event)
Called at the start of a multi-touch event (atleast two touches)
The touches array contains the following info about every touch
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
|
|
|
onTouchEnd(info, index, count, event)
Called at the end of every touch start (including when multiple touches occured)
The info object contains the folloring info:
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
|
|
|
onTouchMove(info, index, count, previousInfo, event)
Called when a touch move event occurs (including when multiple touches occured)
The info object contains the folloring info:
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
|
|
|
onTouchStart(info, index, count, event)
Called at the start of every touch start (including when multiple touches occured)
The info object contains the folloring info:
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
|
|
|
Called when window is resized.
|
|
|
quadraticCurveTo(controlPointX, controlPointY, x, y)
Adds a quadratic curve to the path.
|
|
|
rect(x, y, width, height, align, rotation)
Adds a new rectangle subpath to current path.
|
|
|
Renders one frame.
|
|
|
renderToCanvas(width, height, fps, renderFunction)
Render something offscreen into an image that you can later draw on the canvas.
|
|
|
restore()
Restores the current drawing state of the canvas.
|
|
|
rotate(angle)
Sets the rotation of following operations.
|
|
|
roundedRect(x, y, width, height, radius, align, rotation)
Adds a new rounded rectangle subpath to current path.
|
|
|
save()
Saves the current drawing state of the canvas.
|
|
|
scale(x, y)
Sets the scaling factor of following operations.
|
|
|
setAutoResize(useAutoResize)
Sets wheter automatic resizing of the canvas element is used when
window is resized.
|
|
|
setCompositeOperation(operationName)
Sets how shapes and images are drawn onto the existing bitmap, once they have had globalAlpha
and the current transformation matrix applied.
|
|
|
setErrorHandler(errorHandler)
Sets the new error handler to use.
|
|
|
setGlobalAlpha(alpha)
Sets the global alpha transparency level.
|
|
|
setRenderCallback(callback)
Sets/changes the render callback.
|
|
|
setTargetFramerate(fps)
Sets target frames-per-second to given value.
|
|
|
setTouchEmulatesMouse(doesTouchEmulateMouse)
Sets whether touch events emulate mouse events.
|
|
|
setTransform(a, b, c, d, e, f)
Sets the transformation matrix.
|
|
|
setZIndex(zIndex)
Sets the z-index of the layer (only when canvas was created as a layer).
|
|
|
shadowStyle(offsetX, offsetY, blurRadius, color)
Sets the shadow style.
|
|
|
start()
Starts the animation.
|
|
|
stop()
Stops the animation.
|
|
|
stroke()
Strokes all the strokess of current path using current stroke style.
|
|
|
strokeArc(x, y, radius, startAngle, endAngle, anticlockwise, close, align, rotation)
Strokes an arc onto the canvas.
|
|
|
strokeCircle(x, y, radius, align)
Strokes a circle onto the canvas.
|
|
|
strokeColor(color)
Sets the stroke color.
|
|
|
strokeEllipse(x, y, width, height, align, rotation)
Strokes an ellipse onto the canvas.
|
|
|
strokeLine(x1, y1, x2, y2)
Strokes a line.
|
|
|
strokeRect(x, y, width, height, align, rotation)
Strokes a rectangle onto the canvas.
|
|
|
strokeRoundedRect(x, y, width, height, radius, align, rotation)
Strokes a new rounded rectangle onto the canvas.
|
|
|
strokeStyle(style, lineWidth, lineCap)
Sets the stroke style.
|
|
|
strokeText(text, x, y, align, rotation)
Strokes given text at given coordinates using the optional align and rotation settings.
|
|
|
text(text, x, y, align, rotation)
Adds text to subpath given text at given coordinates using the optional align and rotation settings.
|
|
|
textAlign(align)
Sets the text align to use for the following text operations.
|
|
|
textBaseline(baseline)
Sets text baseline to use for the following text operations.
|
|
|
transform(a, b, c, d, e, f)
Transforms the transformation matrix by given values.
|
|
|
translate(x, y)
Moves the drawing orign by given amount.
|
Class Detail
Canvas(canvas, fps, renderCallback, autostart, layerParent, drawOnly)
The canvas library class.
HTML canvas library is a full-featured lightweight wrapper library of the
native html canvas element written in Javascript, aimed to make visualization
and animation using canvas simpler. Features animation support, layers, event
capture, multitouch and many examples.
This is the main constructor.
The parameters layerParent and drawOnly are used by layers, you dont have to
define these yourself.
The fps parameter can have three kind of values
> 0: static image, the render function is called only once
> -1: animation without framerate limit, runs as fast as possible
> positive: for example 60, use to try to maintain given framerate
- Parameters:
- {string|object} canvas
- Canvas element id or the actual dom-element
- {integer} fps Optional, Default: 0
- Requested frames-per-second, use for animations, optional, defaults to 0
- {function} renderCallback Optional, Default: null
- The function to call to render each frame, gets the canvas as "this", optional, can set later with setRenderCallback()
- {boolean} autostart Optional, Default: true
- Should the rendering be started at once or manually later by calling start(), optional, defaults to true
- {Canvas} layerParent Optional, Default: null
- The parent canvas element of given layer, used by layers system, no need to define
- {boolean} drawOnly Optional, Default: false
- Is this a render-to-canvas operation canvas, does not intercept any events, no need to define
Field Detail
{boolean}
firstFrame
Is this the first frame of the animation, a public attribute.
This can be used in your render callback to do some setting up of the
scene that should only happen once.
- Since:
- 1.0
{integer}
frameCount
Number of frames rendered
- Since:
- 1.0
{integer}
height
The height of the canvas, a public attribute.
This can be used in calculations to position elements on the canvas.
- Since:
- 1.0
{object}
kb
The keyboard events storage object, use to get keyboard state.
This stores the keys that are currently pressed, including the modifier
keys ctrl, shift and alt. Use the kb.isDown(keyCode) method to check
whether given key is currently pressed. To get individual keyboard events,
register for the onKeyDown, onKeyUp and onKeyPress events. The keycodes
can be compared to KC.SOMEKEY constants.
Has keys:
> down: array of keycodes of buttons that are pressed
> ctrl: is the CTRL button pressed
> shift: is the SHIFT button pressed
> alt: is the ALT button pressed
And the method:
> isDown: return whether a button by given keycode is currently pressed
- Since:
- 1.0
{long}
lastFrameDuration
Last frame duration
- Since:
- 1.0
{object}
mouse
The mouse events storage object, use to get mouse state.
Stores the pressed mouse buttons, mouse coordinates and scroll offset.
Includes keys:
> left: is the left button pressed
> right: is the right button pressed
> middle: is the middle button pressed
> x: the x-coordinate of the mouse, relative to canvas location
> y: the y-coordinate of the mouse, relative to canvas location
> scroll: the scroll offset as changed by mouse wheel
- Since:
- 1.0
{object}
scene
The scene object.
This can be used as a namespace for scene variables and methods, includes "canvas" key
that points to the canvas that created it for drawing.
- Since:
- 1.0
{long}
startTime
The start time of the animation rendering
- Since:
- 1.0
{long}
totalDuration
Total rendering duration
- Since:
- 1.0
{string}
version
Library version
- Since:
- 1.0
{integer}
width
The width of the canvas, a public attribute.
This can be used in calculations to position elements on the canvas.
- Since:
- 1.0
Method Detail
{Canvas}
applyDefaultStyles()
Applies default styles.
This includes:
> setting fill color to red
> setting stroke color to green
> translating to 0.5x0.5 to get crisp shapes
> setting the font to 12px Courier
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
arc(x, y, radius, startAngle, endAngle, anticlockwise, align, rotation)
Draws an arc with given parameters and add it to current path.
If the context has any subpaths, then the method must add a straight line from the last point
in the subpath to the start point of the arc. In any case, it must draw the arc between the
start point of the arc and the end point of the arc, and add the start and end points of the
arc to the subpath. The arc and its start and end points are defined as follows:
Consider a circle that has its origin at (x, y) and that has radius radius. The points at
startAngle and endAngle along this circle's circumference, measured in radians clockwise
from the positive x-axis, are the start and end points respectively.
If the anticlockwise argument is omitted or false and endAngle-startAngle is equal to or
greater than 2π, or, if the anticlockwise argument is true and startAngle-endAngle is equal
to or greater than 2π, then the arc is the whole circumference of this circle.
Otherwise, the arc is the path along the circumference of this circle from the start point
to the end point, going anti-clockwise if the anticlockwise argument is true, and clockwise
otherwise. Since the points are on the circle, as opposed to being simply angles from zero,
the arc can never cover an angle greater than 2π radians. If the two points are the same,
or if the radius is zero, then the arc is defined as being of zero length in both directions.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} radius
- Arc radius
- {float} startAngle
- Arc start angle in degrees, use rad() to convert from radians
- {float} endAngle
- Arc end angle in degrees, use rad() to convert from radians
- {boolean} anticlockwise Optional
- Should the arc be drawn counter-clockwise
- {string} align Optional
- The align definition, see ALIGN
- {float} rotation Optional
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
beginComposite(operationName)
Begins composition.
Starts the composite drawing for following calls, use endComposite() to return to normal.
See setCompositeOperation() for explanation of the possible operations.
- Parameters:
- {string} operationName
- The name of the operation, use the OP. shortcuts
- Since:
- 1.0
- Returns:
- {Canvas} Self
{CanvasGradient}
beginLinearGradient(startX, startY, endX, endY, stops)
Begins linear gradient for both fill and stroke operations.
Use endGradient() to stop using this style.
The optional stops object is expected to contain the positions and colors of
the gradient. For example:
{
0.0: 'rgba(255, 0, 0, 1)',
0.5: 'rgba(0, 255, 0, 0.5)',
1.0: 'rgba(0, 0, 255, 0)'
}
defines that the gradient should begin with solid red, then change to half-transparent
green in the middle and end with transparent blue.
You can also add the stops using addColorStop() method of the returned gradient.
- Parameters:
- {float} startX
- Gradient start horizontal position
- {float} startY
- Gradient start vertical position
- {float} endX
- Gradient end horizontal position
- {float} endY
- Gradient end vertical position
- {object} stops Optional
- Object of color stops
- Since:
- 1.0
- Returns:
- {CanvasGradient} The gradient object
{CanvasGradient}
beginLinearGradientFill(startX, startY, endX, endY, stops)
Begins linear gradient for fill operations.
Use endGradient() to stop using this style.
The optional stops object is expected to contain the positions and colors of
the gradient. For example:
{
0.0: 'rgba(255, 0, 0, 1)',
0.5: 'rgba(0, 255, 0, 0.5)',
1.0: 'rgba(0, 0, 255, 0)'
}
defines that the gradient should begin with solid red, then change to half-transparent
green in the middle and end with transparent blue.
You can also add the stops using addColorStop() method of the returned gradient.
- Parameters:
- {float} startX
- Gradient start horizontal position
- {float} startY
- Gradient start vertical position
- {float} endX
- Gradient end horizontal position
- {float} endY
- Gradient end vertical position
- {object} stops Optional
- Object of color stops
- Since:
- 1.0
- Returns:
- {CanvasGradient} The gradient object
{CanvasGradient}
beginLinearGradientStroke(startX, startY, endX, endY, stops)
Begins linear gradient for stroke operations.
Use endGradient() to stop using this style.
The optional stops object is expected to contain the positions and colors of
the gradient. For example:
{
0.0: 'rgba(255, 0, 0, 1)',
0.5: 'rgba(0, 255, 0, 0.5)',
1.0: 'rgba(0, 0, 255, 0)'
}
defines that the gradient should begin with solid red, then change to half-transparent
green in the middle and end with transparent blue.
You can also add the stops using addColorStop() method of the returned gradient.
- Parameters:
- {float} startX
- Gradient start horizontal position
- {float} startY
- Gradient start vertical position
- {float} endX
- Gradient end horizontal position
- {float} endY
- Gradient end vertical position
- {object} stops Optional
- Object of color stops
- Since:
- 1.0
- Returns:
- {CanvasGradient} The gradient object
{Canvas}
beginPath()
Starts a new path, emptying the list of current subpaths.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{CanvasGradient}
beginRadialGradient(x1, y1, radius1, x2, y2, radius2, stops)
Begins using radial gradient for following fill and stoke operations.
Use endGradient() to stop using this style.
The optional stops object is expected to contain the positions and colors of
the gradient. For example:
{
0.0: 'rgba(255, 0, 0, 1)',
0.5: 'rgba(0, 255, 0, 0.5)',
1.0: 'rgba(0, 0, 255, 0)'
}
defines that the gradient should begin with solid red, then change to half-transparent
green in the middle and end with transparent blue.
You can also add the stops using addColorStop() method of the returned gradient.
- Parameters:
- {float} x1
- Inner circle horizontal offset
- {float} y1
- Inner circle vertical offset
- {float} radius1
- Inner circle radius
- {float} x2
- Outer circle horizontal offset
- {float} y2
- Outer circle vertical offset
- {float} radius2
- Outer circle radius
- {object} stops Optional
- Object of color stops
- Since:
- 1.0
- Returns:
- {CanvasGradient} The gradient object
{CanvasGradient}
beginRadialGradientFill(x1, y1, radius1, x2, y2, radius2, stops)
Begins using radial gradient for following fill operations.
Use endGradient() to stop using this style.
The optional stops object is expected to contain the positions and colors of
the gradient. For example:
{
0.0: 'rgba(255, 0, 0, 1)',
0.5: 'rgba(0, 255, 0, 0.5)',
1.0: 'rgba(0, 0, 255, 0)'
}
defines that the gradient should begin with solid red, then change to half-transparent
green in the middle and end with transparent blue.
You can also add the stops using addColorStop() method of the returned gradient.
- Parameters:
- {float} x1
- Inner circle horizontal offset
- {float} y1
- Inner circle vertical offset
- {float} radius1
- Inner circle radius
- {float} x2
- Outer circle horizontal offset
- {float} y2
- Outer circle vertical offset
- {float} radius2
- Outer circle radius
- {object} stops Optional
- Object of color stops
- Since:
- 1.0
- Returns:
- {CanvasGradient} The gradient object
{CanvasGradient}
beginRadialGradientStroke(x1, y1, radius1, x2, y2, radius2, stops)
Begins using radial gradient for following stroke operations.
Use endGradient() to stop using this style.
The optional stops object is expected to contain the positions and colors of
the gradient. For example:
{
0.0: 'rgba(255, 0, 0, 1)',
0.5: 'rgba(0, 255, 0, 0.5)',
1.0: 'rgba(0, 0, 255, 0)'
}
defines that the gradient should begin with solid red, then change to half-transparent
green in the middle and end with transparent blue.
You can also add the stops using addColorStop() method of the returned gradient.
- Parameters:
- {float} x1
- Inner circle horizontal offset
- {float} y1
- Inner circle vertical offset
- {float} radius1
- Inner circle radius
- {float} x2
- Outer circle horizontal offset
- {float} y2
- Outer circle vertical offset
- {float} radius2
- Outer circle radius
- {object} stops Optional
- Object of color stops
- Since:
- 1.0
- Returns:
- {CanvasGradient} The gradient object
{Canvas}
beginShadow(offsetX, offsetY, blurRadius, color)
Begins using given shadow style.
Use endShadow() to stop using this style.
- Parameters:
- {float} offsetX
- Shadow horizontal offset
- {float} offsetY
- Shadow vertical offset
- {float} blurRadius Optional
- The softness of the shadow
- {string} color Optional
- Shadow color, must be a css-style color declaration (hex or rgba)
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
bezierCurveTo(fistControlPointX, firstControlPointY, secondControlPointX, secondControlPointY, x, y)
Adds a bezier curve to the path.
Adds a curve between point (x, y), controlled by the two control points.
For simpler method using one control point, use quadraticCurveTo().
- Parameters:
- {float} fistControlPointX
- First control point x-coordinate
- {float} firstControlPointY
- First control point y-coordinate
- {float} secondControlPointX
- Second control point x-coordinate
- {float} secondControlPointY
- Second control point y-coordinate
- {float} x
- target x-coordinate
- {float} y
- target y-coordinate
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
circle(x, y, radius, align)
Adds a circle subpath.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} radius
- Circle radius
- {string} align Optional
- The align definition, see ALIGN
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
clear()
Clears the whole canvas.
Useful to clear the canvas before every new frame.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
clearRect(x, y, width, height, align, rotation)
Clears the pixels in specified rectangle that also intersects the current clipping
region to fully transparent black, erasing any previous image.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} width
- The width
- {float} height
- The height
- {string} align
- The align definition, see ALIGN
- {float} rotation
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
closePath()
Closes the last subpath and creates a new subpath whose first point is the same as the
previous subpath's first point and adds it to the path.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
color(fillColor, strokeColor)
Sets both the fill and the stroke color.
Colors can be either in hex (#FF0000 etc) or rgba format (rgba(255, 0, 0, 1) etc).
- Parameters:
- {string|object} fillColor
- New fill color
- {string|object} strokeColor
- New stroke color
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
createLayer(name, fps, renderCallback, zIndex, autostart)
Creates a new layer at top-left corner with the same width, height of the parent canvas.
Layers are useful for drawing dynamic parts of the animation every frame while there can be complex static parent layers
that are drawn only once.
Use the createLayerAt() function to create a layer that can be placed anywhere and of custom size different than the parent.
- Parameters:
- {string} name
- The name of the layar, can later be used to fetch its reference from parent
- {integer} fps
- Target framerate, see the Canvas constructor for explanation
- {function} renderCallback
- The render callback to use for drawing this layer
- {integer} zIndex Optional
- Optional z-index, use to control which layer appears of top of others
- {boolean} autostart Optional
- Should rendering of this layer be started at once or later by calling start() yourself
- Since:
- 1.0
- Returns:
- {Canvas} The canvas element of the created layer, use the same way as parent
{Canvas}
createLayerAt(name, x, y, width, height, fps, renderCallback, zIndex, autostart)
Creates a new layer at given position using given size.
Layers are useful for drawing dynamic parts of the animation every frame while there can be complex static parent layers
that are drawn only once.
Use the simpler createLayer() function to create a layer is the same size as the parent layer.
- Parameters:
- {string} name
- The name of the layar, can later be used to fetch its reference from parent
- {integer} x
- The x-coordinate of the layer, relative to the parent
- {integer} y
- The y-coordinate of the layer, relative to the parent
- {integer} width
- The width of the layer
- {integer} height
- The height of the layer
- {integer} fps
- Target framerate, see the Canvas constructor for explanation
- {function} renderCallback
- The render callback to use for drawing this layer
- {integer} zIndex Optional
- Optional z-index, use to control which layer appears of top of others
- {boolean} autostart Optional
- Should rendering of this layer be started at once or later by calling start() yourself
- Since:
- 1.0
- Returns:
- {Canvas} The canvas element of the created layer, use the same way as parent
{CanvasGradient}
createLinearGradient(startX, startY, endX, endY, stops)
Creates linear gradient style and returns it.
The returned value can be used as argument for stroke/fill style but you can
use the beginLinearGradientFill/beginLinearGradientStroke/beginLinearGradient and
endGradient() pairs to use the gradient for fill operations in-between the calls.
The optional stops object is expected to contain the positions and colors of
the gradient. For example:
{
0.0: 'rgba(255, 0, 0, 1)',
0.5: 'rgba(0, 255, 0, 0.5)',
1.0: 'rgba(0, 0, 255, 0)'
}
defines that the gradient should begin with solid red, then change to half-transparent
green in the middle and end with transparent blue.
You can also add the stops using addColorStop() method of the returned gradient.
- Parameters:
- {float} startX
- Gradient start horizontal position
- {float} startY
- Gradient start vertical position
- {float} endX
- Gradient end horizontal position
- {float} endY
- Gradient end vertical position
- {object} stops Optional
- Object of color stops
- Since:
- 1.0
- Returns:
- {CanvasGradient} The gradient object
{CanvasGradient}
createRadialGradient(x1, y1, radius1, x2, y2, radius2, stops)
Creates radial gradient style and returns it.
The returned value can be used as argument for stroke/fill style but you can
use the beginRadialGradientFill/beginRadialGradientStroke/beginRadialGradient and
endGradient() pairs to use the gradient for fill operations in-between the calls.
The optional stops object is expected to contain the positions and colors of
the gradient. For example:
{
0.0: 'rgba(255, 0, 0, 1)',
0.5: 'rgba(0, 255, 0, 0.5)',
1.0: 'rgba(0, 0, 255, 0)'
}
defines that the gradient should begin with solid red, then change to half-transparent
green in the middle and end with transparent blue.
You can also add the stops using addColorStop() method of the returned gradient.
- Parameters:
- {float} x1
- Inner circle horizontal offset
- {float} y1
- Inner circle vertical offset
- {float} radius1
- Inner circle radius
- {float} x2
- Outer circle horizontal offset
- {float} y2
- Outer circle vertical offset
- {float} radius2
- Outer circle radius
- {object} stops Optional
- Object of color stops
- Since:
- 1.0
- Returns:
- {CanvasGradient} The gradient object
{Canvas}
drawImage(image, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10)
This function can be called with three possible argument sets:
- drawImage(image, destinationX, destinationY, align, rotation)
- drawImage(image, destinationX, destinationY, destinationWidth, destinationHeight, align, rotation)
- drawImage(image, sourceX, sourceY, sourceWidth, sourceHeight, destinationX, destinationY, destinationWidth, destinationHeight, align, rotation)
The align and rotation are optional in any case.
- Parameters:
- image
- p1
- p2
- p3
- p4
- p5
- p6
- p7
- p8
- p9
- p10
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
ellipse(x, y, width, height, align, rotation)
Adds an ellipse subpath.
Based on: http://webreflection.blogspot.com/2009/01/ellipse-and-circle-for-canvas-2d.html
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} width
- Ellipse width
- {float} height
- Ellipse height
- {string} align Optional
- The align definition, see ALIGN
- {float} rotation Optional
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
endComposite()
Ends composition.
Starts the composite drawing for following calls, use endComposite() to return to normal.
See setCompositeOperation() for explanation of the possible operations.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
endGradient()
Ends using a gradient style created with any of the begin gradient methods.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
endShadow()
Stops using given shadow style.
Use beginShadow() to start using a style.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{void}
errorHandler(message)
Default error handler, just alerts the error.
Replace this with your own for better error handling, use setErrorHandler() for that.
Note that the error handling is quite lean, the parameters passed to various drawing methods
are not verified.
- Parameters:
- {string} message
- The message of the error
- Since:
- 1.0
- Returns:
- {void}
{Canvas}
fill()
Fills all the subpaths of current path using current fill style.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
fillArc(x, y, radius, startAngle, endAngle, anticlockwise, align, rotation)
Fills an arc onto the canvas.
If the context has any subpaths, then the method must add a straight line from the last point
in the subpath to the start point of the arc. In any case, it must draw the arc between the
start point of the arc and the end point of the arc, and add the start and end points of the
arc to the subpath. The arc and its start and end points are defined as follows:
Consider a circle that has its origin at (x, y) and that has radius radius. The points at
startAngle and endAngle along this circle's circumference, measured in radians clockwise
from the positive x-axis, are the start and end points respectively.
If the anticlockwise argument is omitted or false and endAngle-startAngle is equal to or
greater than 2π, or, if the anticlockwise argument is true and startAngle-endAngle is equal
to or greater than 2π, then the arc is the whole circumference of this circle.
Otherwise, the arc is the path along the circumference of this circle from the start point
to the end point, going anti-clockwise if the anticlockwise argument is true, and clockwise
otherwise. Since the points are on the circle, as opposed to being simply angles from zero,
the arc can never cover an angle greater than 2π radians. If the two points are the same,
or if the radius is zero, then the arc is defined as being of zero length in both directions.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} radius
- Arc radius
- {float} startAngle
- Arc start angle in degrees, use rad() to convert from radians
- {float} endAngle
- Arc end angle in degrees, use rad() to convert from radians
- {boolean} anticlockwise Optional
- Should the arc be drawn counter-clockwise
- {string} align Optional
- The align definition, see ALIGN
- {float} rotation Optional
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
fillCircle(x, y, radius, align)
Fills a circle onto the canvas.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} radius
- Circle radius
- {string} align Optional
- The align definition, see ALIGN
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
fillColor(color)
Sets the fill color.
This color is used when filling shapes.
Fill color can be either in hex (#FF0000 etc) or rgba format (rgba(255, 0, 0, 1) etc).
- Parameters:
- {string} color
- New fill color
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
fillEllipse(x, y, width, height, align, rotation)
Fills an ellipse onto the canvas.
Based on: http://webreflection.blogspot.com/2009/01/ellipse-and-circle-for-canvas-2d.html
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} width
- Ellipse width
- {float} height
- Ellipse height
- {string} align Optional
- The align definition, see ALIGN
- {float} rotation Optional
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
fillRect(x, y, width, height, align, rotation)
Fills a rectangle onto the canvas.
Creates a new subpath containing just the four points (x, y), (x+w, y), (x+w, y+h),
(x, y+h), with those four points connected by straight lines, and then marks the subpath
as closed. It then creates a new subpath with the point (x, y) as the only point
in the subpath. Then fills it.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} width
- The width
- {float} height
- The height
- {string} align
- The align definition, see ALIGN
- {float} rotation
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
fillRoundedRect(x, y, width, height, radius, align, rotation)
Fills a new rounded rectangle onto the canvas.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} width
- The width
- {float} height
- The height
- {float} radius
- The radius of the corners
- {string} align
- The align definition, see ALIGN
- {float} rotation
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
fillStyle(style)
Sets the fill style.
This style is used when filling shapes.
A fill style can be a color (hex or rgba), a CanvasGradient or a CanvasPattern. For clarity,
using fillColor when meaning to change color is advisid.
- Parameters:
- {string|object} style
- New fill style
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
fillText(text, x, y, align, rotation)
Fills given text at given coordinates using the optional align and rotation settings.
The text is rotated about the point defined by align.
- Parameters:
- {string} text
- Text to draw
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {string} align
- The align definition, see ALIGN
- {float} rotation
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
font(definition)
Sets font style to use for the following text operations.
The syntax is the same as css 'font' property, for example "10px sans-serif".
- Parameters:
- {string} definition
- The font definition
- Since:
- 1.0
- Returns:
- {Canvas} Self
{float}
getFPS()
Returs actual current framerate (average number of frames rendered per second).
- Since:
- 1.0
- Returns:
- {float} Current target framerate
{integer}
getHeight()
Returns the height of the canvas. Returns layer height when used as layer.
You can use the public height field of the Canvas object to type less.
- Since:
- 1.0
- Returns:
- {integer} The height
{Canvas|null}
getLayer(name)
Returns a layer by name.
If there is no such layer, returns null
- Parameters:
- {string} name
- The name of the layer
- Since:
- 1.0
- Returns:
- {Canvas|null} The layer canvas object or null if not found
{Canvas}
getParent()
Returns the parent canvas object of a layer.
This is only set when the canvas element was created as a layer.
- Since:
- 1.0
- Returns:
- {Canvas} The parent canvas element
{float}
getTargetFramerate()
Returs current target framerate.
The fps parameter can have three kind of values
> 0: static image, the render function is called only once
> -1: animation without framerate limit, runs as fast as possible
> positive: for example 60, use to try to maintain given framerate
- Since:
- 1.0
- Returns:
- {float} Current target framerate
{string}
getVersion()
Returns library version
- Since:
- 1.0
{integer}
getWidth()
Returns the width of the canvas. Returns layer width when used as layer.
You can use the public width field of the Canvas object to type less.
- Since:
- 1.0
- Returns:
- {integer} The width
{Canvas}
grid(xStep, yStep, x, y, width, height, rotation)
Draws a grid.
High-level operation to draw a grid onto the canvas using current stroke style.
- Parameters:
- {float} xStep Optional
- Grid horizontal step, defaults to 50
- {float} yStep Optional
- Grid vertical step, defaults to 50
- {float} x Optional
- Grid start x-coordinate, default to 0
- {float} y Optional
- Grid start y-coordinate, default to 0
- {float} width Optional
- Grid width, defaults to canvas full width
- {float} height Optional
- Grid height, defaults to canvas full height
- {float} rotation Optional
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
line(x1, y1, x2, y2)
Adds a line subpath to current path.
- Parameters:
- {float} x1
- The start x-coordinate
- {float} y1
- The start y-coordinate
- {float} x2
- The end x-coordinate
- {float} y2
- The end y-coordinate
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
lineCap(lineCap)
Sets line cap style of following stroke operations.
Use one of the following:
CAP.ROUND : 'round' - round edges
CAP.SQUARE : 'square' - square edges, over the start/end coords by half width
CAP.BUTT : 'butt' - square ending at start/end coords
- Parameters:
- {string} lineCap
- Line cap style
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
lineJoin(lineJoin)
Sets line join style of following stroke operations.
Use one of the following:
JOIN.BEVEL : 'bevel' - beveled line joins (straight connection)
JOIN.ROUND : 'round' - round joins
JOIN.MITER : 'miter' - mitered joins (square)
- Parameters:
- {string} lineJoin
- Line join style
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
lineTo(x, y)
Adds a line to given coordinates to the active path. Ensures that there is a subpath
for (x, y) if the context has no subpaths. Otherwise it connects the last point in the
subpath to given point using a straight line, adds the given point to the subpath.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
lineWidth(width)
Sets line width of following stroke operations.
- Parameters:
- {float} width
- Stroke weight
- Since:
- 1.0
- Returns:
- {Canvas} Self
{void}
loadImage(url, loadedCallback, errorCallback)
Load an image from url and calls the callbacks when read or something went wrong.
This is a convienent way to load and use a picture in your image. Just provide the
loadedCallback function that gets the loaded image as first argument. You can
optionally provide the errorCallback that is called when something goes wrong.
The callbacks get the canvas object as this-context so it's easy to use the image
to draw it on the canvas. See drawImage() for that.
- Parameters:
- {string} url
- The url of the image
- {function} loadedCallback
- Called when the image has finished loading, gets the image as first argument
- {function} errorCallback
- Called when loading the image has failed
- Since:
- 1.0
- Returns:
- {void}
{long}
millis()
Returns the milliseconds, useful for timing.
Also used internally.
- Since:
- 1.0
- Returns:
- {long} The milliseconds
{Canvas}
moveTo(x, y)
Creates a new subpath with the specified point as the first and only point.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- Since:
- 1.0
- Returns:
- {Canvas} Self
onContextMenu(event)
Called when context menu is requested on the canvas element. Return false
to disable showing browser context menu.
This does nothing by default and is meant for overriding to implement
your own functionality.
- Parameters:
- {object} event
- The triggered event
- Since:
- 1.0
onKeyDown(keyCode, character, isCtrlPressed, isShiftPressed, isAltPressed)
Called when a keyboard key is pressed down.
This does nothing by default and is meant for overriding to implement
your own functionality.
- Parameters:
- {integer} keyCode
- The keycode of the key, match using the KC constants
- {string} character
- Character of the key as it would appear in a text field
- {boolean} isCtrlPressed
- Is CTRL also pressed
- {boolean} isShiftPressed
- Is SHIFT also pressed
- {boolean} isAltPressed
- Is ALT also pressed
- Since:
- 1.0
onKeyPress(keyCode, character, isCtrlPressed, isShiftPressed, isAltPressed)
Called when a keyboard key is pressed (both down and released back up)
This does nothing by default and is meant for overriding to implement
your own functionality.
- Parameters:
- {integer} keyCode
- The keycode of the key, match using the KC constants
- {string} character
- Character of the key as it would appear in a text field
- {boolean} isCtrlPressed
- Is CTRL also pressed
- {boolean} isShiftPressed
- Is SHIFT also pressed
- {boolean} isAltPressed
- Is ALT also pressed
- Since:
- 1.0
onKeyUp(keyCode, character, isCtrlPressed, isShiftPressed, isAltPressed)
Called when a keyboard key is released.
This does nothing by default and is meant for overriding to implement
your own functionality.
- Parameters:
- {integer} keyCode
- The keycode of the key, match using the KC constants
- {string} character
- Character of the key as it would appear in a text field
- {boolean} isCtrlPressed
- Is CTRL also pressed
- {boolean} isShiftPressed
- Is SHIFT also pressed
- {boolean} isAltPressed
- Is ALT also pressed
- Since:
- 1.0
onMouseDown(x, y, button)
Called when a mouse button is pressed down.
This does nothing by default and is meant for overriding to implement
your own functionality.
- Parameters:
- {integer} x
- The x-position
- {integer} y
- The y-position
- {integer} button
- The index of the button pressed
- Since:
- 1.0
onMouseMove(x, y)
Called when the mouse is moved.
This does nothing by default and is meant for overriding to implement
your own functionality.
- Parameters:
- {integer} x
- The x-position
- {integer} y
- The y-position
- Since:
- 1.0
onMouseScroll(delta, absolute)
Called when the mouse wheel is scrolled.
This does nothing by default and is meant for overriding to implement
your own functionality.
- Parameters:
- {integer} delta
- How much the scroll changed since last time
- {integer} absolute
- The absolute value since the start of the animation
- Since:
- 1.0
onMouseUp(x, y, button)
Called when a mouse button is released.
This does nothing by default and is meant for overriding to implement
your own functionality.
- Parameters:
- {integer} x
- The x-position
- {integer} y
- The y-position
- {integer} button
- The index of the button released
- Since:
- 1.0
onMultiTouchEnd(touches, event)
Called at the end of a multi-touch event (atleast two touches)
The touches array contains the following info about every touch
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
- Parameters:
- {array} touches
- Array of touches info
- {object} event
- The actual touch event
onMultiTouchMove(touches, previousTouches, event)
Called at touch move events (atleast two touches)
The touches array contains the following info about every touch
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
- Parameters:
- {array} touches
- Array of touches info
- {array} previousTouches
- Array of previous touch states
- {object} event
- The actual touch event
onMultiTouchStart(touches, event)
Called at the start of a multi-touch event (atleast two touches)
The touches array contains the following info about every touch
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
- Parameters:
- {array} touches
- Array of touches info
- {object} event
- The actual touch event
onTouchEnd(info, index, count, event)
Called at the end of every touch start (including when multiple touches occured)
The info object contains the folloring info:
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
- Parameters:
- {object} info
- Touch info
- {integer} index
- Touch index
- {integer} count
- The total number of active touches
- {object} event
- The actual touch event
onTouchMove(info, index, count, previousInfo, event)
Called when a touch move event occurs (including when multiple touches occured)
The info object contains the folloring info:
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
- Parameters:
- {object} info
- Touch info
- {integer} index
- Touch index
- {integer} count
- The total number of active touches
- {object} previousInfo
- Touch info of the previous state of this touch
- {object} event
- The actual touch event
onTouchStart(info, index, count, event)
Called at the start of every touch start (including when multiple touches occured)
The info object contains the folloring info:
- pageX - X coordinate relative to the full page (includes scrolling)
- pageY - Y coordinate relative to the full page (includes scrolling)
- clientX - X coordinate of touch relative to the viewport (excludes scroll offset)
- clientY - Y coordinate of touch relative to the viewport (excludes scroll offset)
- screenX - X coordinate relative to the screen
- screenY - Y coordinate relative to the screen
- Parameters:
- {object} info
- Touch info
- {integer} index
- Touch index
- {integer} count
- The total number of active touches
- {object} event
- The actual touch event
onWindowResize()
Called when window is resized. Override this when needed.
This does nothing by default and is meant for overriding to implement
your own functionality.
Return false to disable default actions (resizing canvas when autoResize
is set true).
- Since:
- 1.0
{Canvas}
quadraticCurveTo(controlPointX, controlPointY, x, y)
Adds a quadratic curve to the path.
Adds a curve between point (x, y), controlled by the control point
at (controlPointX, controlPointY).
For more control with two control points, use bezierCurveTo().
- Parameters:
- {float} controlPointX
- Control point x-coordinate
- {float} controlPointY
- Control point y-coordinate
- {float} x
- target x-coordinate
- {float} y
- target y-coordinate
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
rect(x, y, width, height, align, rotation)
Adds a new rectangle subpath to current path.
Creates a new subpath containing just the four points (x, y), (x+w, y), (x+w, y+h),
(x, y+h), with those four points connected by straight lines, and then marks the subpath
as closed. It then creates a new subpath with the point (x, y) as the only point
in the subpath.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} width
- The width
- {float} height
- The height
- {string} align
- The align definition, see ALIGN
- {float} rotation
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
renderSingleFrame()
Renders one frame.
Call this to render frames when not using the automatic animation system.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{object}
renderToCanvas(width, height, fps, renderFunction)
Render something offscreen into an image that you can later draw on the canvas.
Similar to using layers except the result are not automatically painted but rather an image
is returned that you can paint on the canvas yourself in any way needed.
- Parameters:
- {integer} width
- The width of the buffer to create
- {integer} height
- The height of the drawing buffer
- {integer} fps
- Target framerate, see Canvas constructor for explanation
- {function} renderFunction
- The render callback to call to paint to this image
- Since:
- 1.0
- Returns:
- {object} The canvas element, can be drawn to canvas with drawImage()
{Canvas}
restore()
Restores the current drawing state of the canvas.
Saving the drawing state before changing it is useful so after doing some operations with certain settings, you can
easily restore the state with a single call instead of having to remember and reset all the changed attributes.
The drawing state includes:
- The current transformation matrix.
- The current clipping region.
- The current values of the following attributes: strokeStyle, fillStyle, globalAlpha, lineWidth, lineCap, lineJoin, miterLimit, shadowOffsetX, shadowOffsetY, shadowBlur, shadowColor, globalCompositeOperation, font, textAlign, textBaseline.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
rotate(angle)
Sets the rotation of following operations.
Note that this expects radians while other places where rotation is given as a parameter
to drawing operations, degrees are expected.
- Parameters:
- {float} angle
- The rotation in radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
roundedRect(x, y, width, height, radius, align, rotation)
Adds a new rounded rectangle subpath to current path.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} width
- The width
- {float} height
- The height
- {float} radius
- The radius of the corners
- {string} align
- The align definition, see ALIGN
- {float} rotation
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
save()
Saves the current drawing state of the canvas.
Saving the drawing state before changing it is useful so after doing some operations with certain settings, you can
easily restore the state with a single call instead of having to remember and reset all the changed attributes.
The drawing state includes:
- The current transformation matrix.
- The current clipping region.
- The current values of the following attributes: strokeStyle, fillStyle, globalAlpha, lineWidth, lineCap, lineJoin, miterLimit, shadowOffsetX, shadowOffsetY, shadowBlur, shadowColor, globalCompositeOperation, font, textAlign, textBaseline.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
scale(x, y)
Sets the scaling factor of following operations.
The x argument represents the scale factor in the horizontal direction and the y argument
represents the scale factor in the vertical direction. The factors are multiples.
- Parameters:
- {float} x
- The x-scale factor
- {float} y
- The y-scale factor
- Since:
- 1.0
- Returns:
- {Canvas} Self
setAutoResize(useAutoResize)
Sets wheter automatic resizing of the canvas element is used when
window is resized.
- Parameters:
- {boolean} useAutoResize
- Should automatic resize be used
- Since:
- 1.0
- Returns:
- Canvas Self
{Canvas}
setCompositeOperation(operationName)
Sets how shapes and images are drawn onto the existing bitmap, once they have had globalAlpha
and the current transformation matrix applied.
It must be set to a value from the following list. In the descriptions below, the source image,
A, is the shape or image being rendered, and the destination image, B, is the current state of
the bitmap.
You can use the following constants:
- OP.SOURCE_OVER : 'source-over'
A over B. Display the source image wherever the source image is opaque. Display the
destination image elsewhere.
- OP.SOURCE_IN : 'source-in'
A in B. Display the source image wherever both the source image and destination image are
opaque. Display transparency elsewhere.
- OP.SOURCE_OUT : 'source-out'
A out B. Display the source image wherever the source image is opaque and the destination image
is transparent. Display transparency elsewhere.
- OP.SOURCE_ATOP : 'source-atop'
A atop B. Display the source image wherever both images are opaque. Display the destination
image wherever the destination image is opaque but the source image is transparent. Display
transparency elsewhere.
- OP.DESTINATION_OVER : 'destination-over'
B over A. Same as source-over but using the destination image instead of the source image
and vice versa.
- OP.DESTINATION_IN : 'destination-in'
B in A. Same as source-in but using the destination image instead of the source image and
vice versa.
- OP.DESTINATION_OUT : 'destination-out'
B out A. Same as source-out but using the destination image instead of the source image and
vice versa.
- OP.DESTINATION_ATOP : 'destination-atop'
B atop A. Same as source-atop but using the destination image instead of the source image
and vice versa.
- OP.LIGHTER : 'lighter'
A plus B. Display the sum of the source image and destination image, with color values
approaching 255 (100%) as a limit.
- OP.COPY : 'copy'
A (B is ignored). Display the source image instead of the destination image.
- OP.XOR : 'xor'
A xor B. Exclusive OR of the source image and destination image.
- Parameters:
- {string} operationName
- The name of the operation, use the OP. shortcuts
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
setErrorHandler(errorHandler)
Sets the new error handler to use.
The error handler will get just the error message as first argument. It's a good idea to
replace the default error handler as it will just alert the message that is not very useful
for users.
You can set it to null to ignore errors.
- Parameters:
- {function} errorHandler
- The error handler callback to use
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
setGlobalAlpha(alpha)
Sets the global alpha transparency level.
This gives an alpha value that is applied to shapes and images before they are composited onto
the canvas. The value must be in the range from 0.0 (fully transparent) to 1.0 (no additional
transparency so fully opaque).
- Parameters:
- {float} alpha
- The opacity level
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
setRenderCallback(callback)
Sets/changes the render callback.
Render callback is the function that is repeatedly called to render
each frame.
- Parameters:
- {function} callback
- The renderer callback function
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
setTargetFramerate(fps)
Sets target frames-per-second to given value.
The fps parameter can have three kind of values
> 0: static image, the render function is called only once
> -1: animation without framerate limit, runs as fast as possible
> positive: for example 60, use to try to maintain given framerate
- Parameters:
- {float} fps
- Target framerate
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
setTouchEmulatesMouse(doesTouchEmulateMouse)
Sets whether touch events emulate mouse events.
For example, touchmove events are translated to mousemove events.
- Parameters:
- {boolean} doesTouchEmulateMouse
- Should touch events be translated to mouse events
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
setTransform(a, b, c, d, e, f)
Sets the transformation matrix.
The arguments a, b, c, d, e, and f are sometimes called m11, m12, m21, m22, dx, and dy or m11,
m21, m12, m22, dx, and dy. Care should be taken in particular with the order of the second and
third arguments (b and c) as their order varies from API to API and APIs sometimes use the
notation m12/m21 and sometimes m21/m12 for those positions.
a c e
b d f
0 0 1
TODO: Explain what each one does
- Parameters:
- a
- b
- c
- d
- e
- f
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
setZIndex(zIndex)
Sets the z-index of the layer (only when canvas was created as a layer).
The bigger the z-index, the more on-top a layer is when there are several.
- Parameters:
- {integer} zIndex
- The new z-index
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
shadowStyle(offsetX, offsetY, blurRadius, color)
Sets the shadow style.
The shadow style is used for all following drawing operations. Use beginShadow()
and endShadow() to use the shadow style for operations between the calls.
- Parameters:
- {float} offsetX
- Shadow horizontal offset
- {float} offsetY
- Shadow vertical offset
- {float} blurRadius Optional
- The softness of the shadow
- {string} color Optional
- Shadow color, must be a css-style color declaration (hex or rgba)
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
start()
Starts the animation.
Call stop() to stop it.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
stop()
Stops the animation.
Call start() to (re)start it.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
stroke()
Strokes all the strokess of current path using current stroke style.
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
strokeArc(x, y, radius, startAngle, endAngle, anticlockwise, close, align, rotation)
Strokes an arc onto the canvas.
If the context has any subpaths, then the method must add a straight line from the last point
in the subpath to the start point of the arc. In any case, it must draw the arc between the
start point of the arc and the end point of the arc, and add the start and end points of the
arc to the subpath. The arc and its start and end points are defined as follows:
Consider a circle that has its origin at (x, y) and that has radius radius. The points at
startAngle and endAngle along this circle's circumference, measured in radians clockwise
from the positive x-axis, are the start and end points respectively.
If the anticlockwise argument is omitted or false and endAngle-startAngle is equal to or
greater than 2π, or, if the anticlockwise argument is true and startAngle-endAngle is equal
to or greater than 2π, then the arc is the whole circumference of this circle.
Otherwise, the arc is the path along the circumference of this circle from the start point
to the end point, going anti-clockwise if the anticlockwise argument is true, and clockwise
otherwise. Since the points are on the circle, as opposed to being simply angles from zero,
the arc can never cover an angle greater than 2π radians. If the two points are the same,
or if the radius is zero, then the arc is defined as being of zero length in both directions.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} radius
- Arc radius
- {float} startAngle
- Arc start angle in degrees, use rad() to convert from radians
- {float} endAngle
- Arc end angle in degrees, use rad() to convert from radians
- {boolean} anticlockwise Optional
- Should the arc be drawn counter-clockwise
- {boolean} close Optional
- Should the subpath be closed first
- {string} align Optional
- The align definition, see ALIGN
- {float} rotation Optional
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
strokeCircle(x, y, radius, align)
Strokes a circle onto the canvas.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} radius
- Circle radius
- {string} align Optional
- The align definition, see ALIGN
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
strokeColor(color)
Sets the stroke color.
This color is used when stroking shapes.
Stroke color can be either in hex (#FF0000 etc) or rgba format (rgba(255, 0, 0, 1) etc).
- Parameters:
- {string|object} color
- New stroke color
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
strokeEllipse(x, y, width, height, align, rotation)
Strokes an ellipse onto the canvas.
Based on: http://webreflection.blogspot.com/2009/01/ellipse-and-circle-for-canvas-2d.html
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} width
- Ellipse width
- {float} height
- Ellipse height
- {string} align Optional
- The align definition, see ALIGN
- {float} rotation Optional
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
strokeLine(x1, y1, x2, y2)
Strokes a line.
- Parameters:
- {float} x1
- The start x-coordinate
- {float} y1
- The start y-coordinate
- {float} x2
- The end x-coordinate
- {float} y2
- The end y-coordinate
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
strokeRect(x, y, width, height, align, rotation)
Strokes a rectangle onto the canvas.
Creates a new subpath containing just the four points (x, y), (x+w, y), (x+w, y+h),
(x, y+h), with those four points connected by straight lines, and then marks the subpath
as closed. It then creates a new subpath with the point (x, y) as the only point
in the subpath. Then strokes it.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} width
- The width
- {float} height
- The height
- {string} align
- The align definition, see ALIGN
- {float} rotation
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
strokeRoundedRect(x, y, width, height, radius, align, rotation)
Strokes a new rounded rectangle onto the canvas.
- Parameters:
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {float} width
- The width
- {float} height
- The height
- {float} radius
- The radius of the corners
- {string} align
- The align definition, see ALIGN
- {float} rotation
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
strokeStyle(style, lineWidth, lineCap)
Sets the stroke style.
This style is used when stroking shapes.
A stroke style can be a color (hex or rgba), a CanvasGradient or a CanvasPattern. For clarity,
using strokeColor when meaning to change color is advisid.
- Parameters:
- {string|object} style
- New stroke style
- {integer} lineWidth Optional
- Width of stroke, optional
- {integer} lineCap Optional
- Cap style of lines, see lineCap() method, optional
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
strokeText(text, x, y, align, rotation)
Strokes given text at given coordinates using the optional align and rotation settings.
The text is rotated about the point defined by align.
- Parameters:
- {string} text
- Text to draw
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {string} align
- The align definition, see ALIGN
- {float} rotation
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
text(text, x, y, align, rotation)
Adds text to subpath given text at given coordinates using the optional align and rotation settings.
The text is rotated about the point defined by align.
- Parameters:
- {string} text
- Text to draw
- {float} x
- The x-coordinate
- {float} y
- The y-coordinate
- {string} align
- The align definition, see ALIGN
- {float} rotation
- Rotation in degrees, use rad() to convert from radians
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
textAlign(align)
Sets the text align to use for the following text operations.
Use the ALIGN constants, for example ALIGN.RIGHT.BOTTOM to align to right-bottom.
- Parameters:
- {string} align
- The align definition
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
textBaseline(baseline)
Sets text baseline to use for the following text operations.
- Parameters:
- {string} baseline
- The baseline setting
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
transform(a, b, c, d, e, f)
Transforms the transformation matrix by given values.
The arguments a, b, c, d, e, and f are sometimes called m11, m12, m21, m22, dx, and dy or m11,
m21, m12, m22, dx, and dy. Care should be taken in particular with the order of the second and
third arguments (b and c) as their order varies from API to API and APIs sometimes use the
notation m12/m21 and sometimes m21/m12 for those positions.
a c e
b d f
0 0 1
TODO: Explain what each one does
- Parameters:
- a
- b
- c
- d
- e
- f
- Since:
- 1.0
- Returns:
- {Canvas} Self
{Canvas}
translate(x, y)
Moves the drawing orign by given amount. The x argument represents the translation distance
in the horizontal direction and the y argument represents the translation distance in the
vertical direction. The arguments are in coordinate space units.
- Parameters:
- {float} x
- The x transformation hotizontally
- {float} y
- The y transformation vertically
- Since:
- 1.0
- Returns:
- {Canvas} Self