The HTML5 Canvas Handbook

The canvas element, introduced in HTML5, enables the dynamic generation of bitmap images by means of JavaScript code.

The basic setup is a little complicated, the involved objects themselves are poorly designed, which is also a result of a real decrease in the evolution of the standards. But there is also a combination of reasons that makes the canvas element worth learning and exercising: it is the future element for graphics and even video in HTML, it is extremely powerful and, in combination with its natural habitat of a full scripting language, flexible and fully adaptable to all needs.

The interfaces of the JavaScript objects are messy, actions are not properly separated and the effect of the methods depends on odd side effects and property settings. But these interfaces are small: Part 2 of the contents table already provides an entire summary and overview. This reduction to less than 20 properties and 35 methods makes the full features of the canvas element manageable and comprehesible. With a background knowledge of HTML, CSS and at least a little JavaScript, this Canvas Handbook might be able to serve as both, an introduction and a daily work companion sufficient to master the entire subject.

If you are a novice, read the first part and then browse through the second part for the things you need.

This handbook itself was written in Markdown and converted to HTML by means of the wonderful Pandoc universal document converter.³

1 Introduction

1.1 Official standards

1.2 Requirements: a browser with support for HTML5 and JavaScript

The canvas element is part of HTML5. If a browser is too old or not capable of dealing with this fairly new standard, you will not be able to use it, at all.

A detailed overview of browser support for HTML5 in general and the canvas element in particular can be found for example at caniuse.com.

Furthermore, your browser must be able and permitted to execute JavaScript code. A couple of years ago, JavaScript had the reputation of annoying the user and in many configurations it was switched off by default. But all this is a thing of the past, certainly if you don't want to miss the full features of HTML5 and the canvas element in particular.

For the understanding of this very text, make sure, that your browser is up to date and properly configured (see the first example next as a test to assure that it works properly). All the illustrations and examples are not inserted as <img> images, but with canvas elements.

1.3 A first example

Here is an example of a canvas picture, showing a "Hello" message in a red box: ⁷

This little example already comprises all the basic ingredients and steps we will repeat again and again later on. Every normal canvas picture has two parts of code:

All visual picture elements are purely generated in the canvas context, stored in the JavaScript variable arbitrarily named tricolourCanvasContext.

1.4 Basic setup

This double nature of HTML tag on one hand and JavaScript object on the other is not specific to the canvas element, it is essential to the whole design of the DOM (Document Object Model)⁹ that enables the dynamic manipulation of a document by means of JavaScript.

In some ways, the <canvas> tag is similar to the <img> tag for displaying images. For example, the source code

With width and height we set the size of the picture. (Recall, that in each case 100 is short for "100px".) With alt we provide some "alternative" or fallback text that would appear in case the image cannot be displayed for any reason. The general style attribute for HTML elements is used to set some CSS attributes. In this case it draws an orange border around the picture. And of course, we could have omitted the closing </img> tag.

Again, width and height are set, these are actually the only two own attributes of the <canvas> tag. The style attribute is a general attribute for HTML elements and again it puts an orange frame around the canvas. If we would have omitted this attribute, we wouldn't be able to properly see the canvas, at all.

Different to the alt attribute for the <img> tag, the fallback content for the <canvas> is not located in an attribute, but goes inside the <canvas>...</canvas> tags.

By the way, width and height may actually be omitted, in which case the width is set to 300px and the height to 150px, by default. For example,

The style attribute is a general option for all HTML tags to add some CSS features. But in fact, that is not the place where the actual picture content of a canvas element is drawn. That is done in the so-called canvas context.

The real graphical content and the picture elements of a canvas is neither located in attributes nor inbetween the <canvas>...</canvas> tag. It is not written in HTML or CSS at all. Instead, it is done in the so-called canvas context, and this context can only be accessed and modified in JavaScript.

There are different ways to get a canvas picture on the screen. In fact, it can even be entirely done in JavaScript, without a <canvas> tag involved at all. But we do not intend to delve into the JavaScript DOM too deeply and propagate a standard method, instead, that should suffice in most cases.

So alltogether, this is our default template for generating canvas pictures, at least for now:

We use this template throughout this text and in many examples, we only show the "... do stuff with the context ..." part, assuming that you know about the other lines. For most examples, this simple template will work and it is a sufficient starting place for the design of your own sample files and paintings.

But on a more professional level and when the generated pictures become more complex, you should change this design:

By the way, there are context types other than the 2d context with its CanvasRenderingContext2D objects. The [W3C] contains a note, saying: A future version of this specification will probably define a 3d context (probably based on the OpenGL ES API). But all this is outside the scope of this text and not widely supported by the major browers, yet.

1.5 Points (x,y) and the canvas coordinates

Each canvas has a width and a height, and by default these are 300 and 150 pixels, respectively. This means, that the canvas is divided into 300 pixels into the horizontal or x-axis, and 150 pixels into the vertical or y-axis. The x-axis runs from left 0 to right 300, the y-axis from top 0 to bottom 150. ¹¹

Inside this coordinate system, any point on the canvas is precisely defined by the number pair (x,y), with 0 ≤ x ≤ width and 0 ≤ y ≤ height.

For example, the point at (200,25) on a default size 300x150 pixel canvas is represented by the red dot ¹²

But as this location is difficult to verify for the reader, we often display a coordinate system or grid on canvas examples below. The same point is then easy to locate:

All points (x,y) that fall outside the range of 0 ≤ x ≤ width and 0 ≤ y ≤ height are not shown. For example, the points (-60,50) or (500,500) do not appear in the previous canvas.¹³ If (parts of) figures exceed the borders of the canvas, the exceeding parts are simply cut off, as for the following disk with center point (250,100) and radius 100.

Actually, we can add such a grid to the context by calling the context.addGrid() method, which may become very convenient when you write code. Once the whole canvas is drawn, you can simply eliminate that line, again. However, note that addGrid() is not a standard method of the CanvasRenderingContext2D object! If you want to use it yourself, you need to copy the implementation from the appendix into your own file.

2 Reference

2.1 HTMLCanvasElement

The canvas element is given in two forms: as HTML tag and JavaScript object. In this reference, we concentrate on the JavaScript side of things. But completeness sake, let us provide a short repetition of the basic setup

In fact, the canvas element has only two own attributes, width and height. Both are optional, and if they are omitted, the width is set to 300px and the height to 150px, by default.

The ... fallback content ... is what appears in the browser not capable of HTML5. Since we do not need to consider this situation here, we will just use this as the standard form for our examples:

The id attribute is just a general attribute for HTML element. But we add it in our examples below, because it provides a standard way to get hold of the HTMLCanvasElement object in JavaScript. Usually, we will do something like this

The canvas object is pretty simple, the actual drawings and picture elements are generated in its context. In general and in this handbook, we consider only one kind of context, namely the 2D context, which is comprehensively documented under the header CanvasRenderingContext2D in the second part of this reference.

2.1.1 width

For example, let us place a <canvas> tag of non-default width and height and attach an orange border (via its style attribute), so that this is visible. Then we add a script that takes this canvas, reads out its width and height and writes the result into the canvas. Alltogether,

2.1.2 height

In the previous example we saw that height and width are readable properties. But they are also writable and we can dynamically change these values.

For example, suppose we have a <canvas> of default size, i.e. 300 pixel wide and 150 high, and we again add an orange border to it via its style attribute to visualize its shape.

Then we add a script in which we explicitly resize the canvas by setting both width and height to only 30 pixel, like so:

2.1.3 getContext('2d')

This context, which will always be the 2D context in the sequel, is attached to the canvas and accessible by a call of canvas.getContext('2d'). This context is where all the action takes place. It provides the interface for all the drawings added to the given canvas and explaining the CanvasRenderingContext2D object below is thus the biggest part of this manual.

The [W3C] document announces that there will probably be a '3d' context in the future, based on the OpenGL ES API.

2.1.4 toDataURL()

If you copy this string and put it into the address field of your browser, you should see the picture of the red square.

You can copy all this and call it in your browser to get the little red square, again.

For a more convenient solution, we can attach these lines to the previous code: ¹⁵

If we then click on the canvas, the browser opens the data URL into the address field and thus shows the image. And then, the user can choose to save this image as a PNG file.

2.2 CanvasRenderingContext2D

2.2.1 Reference back to the canvas

2.2.1.1 canvas

which appears as a 250x50 pixel canvas (visible due to its solid 5pt orange border):

The original size of the canvas as given in the <canvas> tag is 150x100 pixel. The JavaScript variable context holds the CanvasRenderingContext2D object. With context.canvas we get hold of the HTMLCanvasElement that contains this context. So with context.canvas.width and context.canvas.height we refer to the width and height of this canvas.

But the point here was the demonstration of the ability to refer to the canvas object from its 2D context.

2.2.2 State

Note, that the drawing state does not include the current path or bitmaps. So save() and restore() do not save and restore entire canvas pictures, i.e. entire contents of the given context. For that, you should use ImageData objects and the getImageData() and putImageData() methods (see the chapter on pixel manipulation).

Suppose we draw 5 figures, each one a fillRect() rectangle with two lines of strokeText() text in it, like so:

As it is apparent from the picture, we use 3 different style settings for the 5 figures, defined as states:

But since we want to demonstrate the use of save() and restore(), we create the Figures in their presented order:

2.2.2.1 save()

2.2.2.2 restore()

2.2.3 Transformations

In general geometry, a transformation turns a given object into another object, but preserves its structure. Things may appear deformed, but they are not ruptured or destroyed. The absolute position of points may change, but the relative positions remain, neighboring points are still neighbors after the transformation.

Three special transformations can be called by special methods on the canvas context:

scale() resizes the canvas, rotate() turns it around the origin, and translate() shifts it to a new position. But actually, and different to what the three previous images suggest, not the canvas as an object in the brower window is moved by any of these operations, but rather its coordinate system is altered. Below we will demonstrate what that means in many examples.

Next to these three special tranformations, there are also the general transform() and setTransform() methods, which are more powerful, but also more difficult to comprehend and apply. ¹⁶ We also show, that any combination of transformations (e.g. first scaling, then a rotation, and finally scaling, again) is itself a transformation and can be performed with one transform() call. The other way round, this also implies, that we can decompose a complex transformation into simpler steps.

2.2.3.1 scale (x, y)

Given a 200x200 pixel canvas, shown with a red border, and with a blue coordinate system (here, on top of the red border):

If we now call say scale(0.8,1.5), the horizontal x-axis shrinks by the factor 0.8 and the vertical y-axis extends by the factor 1.5. The same blue coordinate system on the red border canvas is this:

That means that all drawn picture elements after the call of scale(0.8,1.5) are now smaller in width and bigger in height, accordingly. Note however, that the size of the canvas has not changed. The picture in the browser is still everything that lies within the red border.

Let us take the same 200x200 pixel canvas again (the red border is generated with the additional attribute style="border: solid 3pt red" in the <canvas> tag). We add a green circle to the canvas context, which is done with this code

The width is decreased by 0.8, the height of the circle is increased by the factor 1.5. The canvas has not changed in size, it still is a 200x200 pixel rectangular. As a result, the circle part that exceeds the canvas border, is cut off.

First, we draw a rectangle by calling fillRect(50,50,150,40) and we insert a message with strokeText('1. Hello',55,85). Then we scale x by 0.8 and y by 2 and call the same fillRect(50,50,150,40), again. This second rectangle is inserted at (0.8*50,2*50) = (40,100), is 0.8*150 = 120 pixel wide and 2*40 = 80 pixel high. So in effect, the second scaled rectangle is the same as a call of fillRect(40,100,120,80) in the original coordinate system. But when we add the second message by calling strokeText('2. Hello',55,85) we also obtained a scaled message. And for that we really need the scale() method.

For example, let there be a 200x200 pixel canvas (the red frame), then the (blue) coordinate system after a call of scale(-1,1)is this:

Note, that the x-coordinates of all points inside the canvas are negative now. For example, we place the text at (-160,120) and it runs from right to left.

On the other hand, if we call scale(1,-1), we obtain a picture mirrored at the x-axis:

2.2.3.2 rotate (angle)

If we call rotate(angle), all subsequently drawn objects are rotated by the given angle, according to the new blue coordination system. Note however, that the rendered canvas in the browser is still the red one, not the rotated blue one. Only the points that lie inside this blue canvas are visible.

More precisely, let us consider the default size (300x150 pixel) canvas that is rotated by 15 degree by calling rotate(15*Math.PI/180).

This is a picture of this canvas before the rotation with a yellow grid and the cross points like (50,50) written out

For example, the point (250,100) has disappeared because it now falls outside the canvas, while (250,-50) now does exist.

First, we draw the top horizontal rectangle with a "Hello" inside. We then rotate by 30 degree and draw the same rectangle and text, again. Note, that the coordinates are the same, i.e. fillRect(100,5,100,40). The second rectangle appears rotated below the first one. We then do a second rotation by 30 degree, followed by a third drawing of the rectangle and text. That generates the third rectangle, which is only half shown, because the other half is already outside the canvas.

2.2.3.3 translate (x, y)

Suppose we have a canvas of say 250x150 pixel, displayed by the red frame and its blue coordinate system on top of it

In its original state and before the translation, the left upper corner has the coordinates (x,y) = (0,0)

After the translation, the left upper corner of the canvas is located ad (-100,50)

So, anything we put at say (200,100) does appear before, but not after the translation, anymore.

First, a rectangle is drawn by calling fillRect(0,5,150,40) and text is added with strokeText('1. Hello',5,40). Then, translate(125,50) is called and the same rectangle is drawn again with fillRect(0,5,150,40). Since the origin has moved, this second rectangle is also moved 125 pixels to the right and 50 pixels downwards. Finally, translate(125,50) is called once more, causing the origin to move, again. And when the rectangle is also drawn again with fillRect(0,5,150,40), a third rectangle appears to the right and below the two previous ones. Note, that all content outside the canvas is cut off, the third rectangle is not fully displayed.

2.2.3.4 transform (a, b, c, d, e, f)

Consider a default size (i.e. 300x150 pixel) canvas, given by a red frame, with a blue coordinate grid on top:

Parameter	Effect
`a`	scales horizontally (and mirrors at the y-axis for negative `a`)
`b`	skews horizontally
`c`	skews vertically
`d`	scales vertically (and mirrors at the x-axis for negative `a`)
`e`	moves horizontally
`f`	movew vertically

And if we populate this canvas context before and after the same transformation by running this code

transform(), together with the similar setTransform(), is the general method to perform (affine) transformations. scale(), rotate() and translate() are just special versions of transform() with less parameters. The following table shows the exact implementations:

special transformation	same transformation in terms of `transform()`
`scale(x,y)`	`transform (x, 0, 0, y, 0, 0)`
`rotate(angle)`	`transform (c, s, -s, c, 0, 0)` where `c = Math.cos(angle)` and `s = Math.sin(angle)`
`translate(x,y)`	`transform (1, 0, 0, 1, x, y)`

rotation	in terms of `rotate()`	same transformation in terms of `transform()`
`90` degree	`rotate(Math.PI/2)`	`translate(0,1,-1,0,0,0)`
`180` degree	`rotate(Math.PI)`	`translate(-1,0,0,-1,0,0)`
`270` degree	`rotate(1.5*Math.PI)`	`translate(0,-1,1,0,0,0)`

Another special transformation, one that is not pre-defined in the CanvasRenderingContext2D API, is

2.2.3.5 setTransform (a, b, c, d, e, f)

Initially, every canvas context has the initial coordinate system, as described in the introduction. After every transformation, this coordinate system is changed to a new current system. With each tranform() call, this current system is transformed, again. A call of setTransform() however does not transform the current system, but starts from the initial one.

In standard jargon, we rather talk about "transformation" again instead of "coordinate system", so there is an initial transformation (namely the distinguished identity transformation) and a current transformation.

Let us start again with a broader view on how everything is connected together and implemented. It might help or hinder to explain the underlying mathematics, so we isolated this as optional information into a small digression and its footnotes.

At every point in time, right from its creation, the canvas context has property called the current transformation. It might help here to read "current coordinate sytem" instead of "current transformation". And that makes sense really: when the canvas is rendered in the browser, the picture components are placed into the canvas area according to the given current transformation or _coordinate system.

In the [WHATWG] standard, each CanvasRenderingContext2d still had this current transformation explicitly available as the currentTransform property.²⁰ But in the final standard of [W3C], this property has vanished and is no longer accessible.

The initial coordinate system, the one at the time of the context creation, is the one with the origin (0,0) at the left top corner point and the orthogonal x- and y-axis, as described in the introduction. The initial transformation is in fact the identity transformation id.

Each time, a new transformation τ' is issued in the script by a transform() call (or any of its special versions scale(), rotate() or translate()), the current transformation τ is replaced by the new current transformation τ⊗τ'. And this step is repeated after each new transformation.

And with a call of setTransform(), the current transformation is not set to τ⊗τ', but to the new transformation τ' itself (as it is defined by the six parameters of the setTransform(a,b,c,d,e,f) call).

The [WHATWG] standard also knew a resetTransform() method, that explicitly set the current transformation to the identity id. But again, this has been removed from the final [W3C] version. But of course, the same effect of a resetTransform() call can be achieved with a setTransform(1,0,0,1,0,0) call, which also sets the current transformation back to the identity id.

Suppose, we want to write "HELLO!" on a canvas, but in a vertical text box, like so

A similar problem is this: How do we turn the coordinate system of a canvas, say

The answer to the latter problem is this: First, rotate by 270 degree by calling rotate(1.5*Math.PI)

and secondly, move the coordinate grid down the x-axis so that (0,0) is located at the left lower corner, by calling translate(-h,0), with h being the height of the canvas, here 150.

So, back to the original problem of the vertical text, we have a 300x255 pixel canvas and then call

We just performed a rotation and a translation, but we can also merge the two transformation steps into a single one.

Let us continue the previous example of the vertical text box. There was some space left on the canvas and we are going to insert a mirror image there. This shall be the result:

The image is a mirror image, because in the original image, the horse is looking to the other side:

In the explanation of scale() we already mentioned that a mirror image at the y-axis can be achieved by a scale(-1,1) call. We let this be followed by translate(-w,0) call, where the width w = 300, so that the overall transformation²² is now given by this coordinate system

In this transformed canvas context, we now insert the image at (0,0) with an assigned width of 180 and height of 255 pixel. The code is this

The reason is, that the two transformations for the image are performed on the two transformations for the text box. In other words, calls of transform(), scale(), rotate() and translate() alter the current transformation, which may be different from the default initial identity transformation. What we need to do before the second part is a reset of the current transformation to the identity tranformation. As mentioned, the CanvasRenderingContext2D object used to have a resetTransform() to do just that. But in the final standard, there is only the setTransform() method left. Recall, that the identity transformation is given by the parameters (1,0,0,1,0,0), so calling setTransform(1,0,0,1,0,0) resets the current transformation parameters. The code for the whole canvas is this given by

2.2.4 Compositing

2.2.4.1 globalAlpha

Let us demonstrate the the effect on a canvas with four rectangles, generated by the following code template:

Of course, this value 1.0 is the default α value, so we could have omitted the whole line of code and would still have obtained the same result.

2.2.4.2 globalCompositeOperation

Suppose we first draw an orange square and then a cyan circle. In this composite operation we refer to the already existing square as the destination, and the new circle is called the source of the composition.

If the circle coincides with the square, it is put over the square by default, i.e. it is diplayed as "source-over-destination" or "source-over". But we might as well alter this behavior and set globalCompositeOperation to say "destination-over", in which case the circle is displayed under the square, i.e. the destination square is over the source circle.

and we generate the examples in the table below essentially by replacing "source-over" by the according alternative value.

Opposite to the lighter value, some earlier browsers also supported darker. But this value is not part of the official canvas specification.

2.2.5 Colors and styles

strokeStyle and fillStyle are context properties that hold the style value for the subsequently drawn stroke or filled objects, respectively.

There are three kinds of possible style values: CSS colors, (linear or radial) gradients, and patterns.

2.2.5.1 strokeStyle

After the strokeStyle value is set, all stroke objects (drawn with stroke(), strokeRect(), and strokeText()) are colored accordingly. The previous code snippet renders like this:

2.2.5.2 fillStyle

As in the previous example, we again set the fillStyle value to a green color value.

The filled objects (drawn in step 2-4 with fill(), fillRect() and fillText()) now appear green:

2.2.5.3 createLinearGradient (x0, y0, x1, y1) and addColorStop (pos, color)

A typical example of a "gradient" color style is a rainbow, gradually changing its color. So let us create a linear gradient, we name it rainbowGradient, add some colors, assign that to fillStyle and then draw a fillRect() over the size of the whole canvas. The resulting picture is this:

The whole process is more complicated than just assigning a color (say 'green') to fillStyle. Instead, we take the following steps:

The whole process also works for multiple objects and for strokeStyle instead of fillStyle. To demonstrate this, look at this canvas

generated by this code (steps 2.-4. are identical to the strokeStyle example code):

2.2.5.4 createRadialGradient (x0, y0, r0, x1, y1, r1) and addColorStop (pos, color)

The setup of the radial gradient is similar to the linear gradient, except that the gradient field is not linear, from a starting point (x0,y0) to an end point (x1,y1). Instead its origin is a circle (x0,y0,r0) and that moves towards an end circle (x1,y1,r1).

With a radial gradient we can create 3D effects like turning a monochrome red disk into a ball, illuminated by a light source:

If we would have drawn a filled rectangle over the size of the whole canvas instead of the circle, i.e. if this one line

If we then replace the colors 'yellow' by 'white' and 'red' by 'black', we obtain

It is probably important to exercise a lot of examples in order to handle the gradients. The following example shows variations of the start and end circle of the radial gradient. Each time, we use this code template:

and in each concrete example, the six parameters in context.createRadialGradient (x0, y0, r0, x1, y1, r1) are varied. The first picture in each column shows how the canvas is rendered. The second picture shows the location of the orange start and the cyan end circle.

2.2.5.5 createPattern (image, repetition)

Actually, in Firefox, 'repeat' is the only accepted value for repetition, at all.

as a pattern image for a CanvasPattern object and use this object as a value for the fillStyle property. Subsequently, we draw some filled objects: with fillRect(), a fill() path, and some fillText(). The full code snippet

2.2.6 Line caps and joins

Next to the general style settings there are special style properties defining the rendering of lines, their caps and joins, namely lineWidth, lineCap and lineJoin. And to limit the tips of pointed angles, there is also miterLimit.

2.2.6.1 lineWidth

The following canvas shows different lineWidth settings from 0.1 to 20.0. In each line example, we first set context.lineWidth to the according number and then draw the line.

Note, that all lines are drawn with strokeStyle set to (default) 'black', but that many lines appear more gray than black, and their edges are not very crisp. This is not a browser bug, but has to do with the fact that the canvas is decomposed into pixels. If a say black line or shape covers a white pixel only partially, the actual color of that pixel is a medium gray value.

In the following enlarged canvas example, a line from (0, 2) to (10, 2) covers 20 half pixels. These affected pixels are therefore rendered gray. The line from (0, 1.5) to (10, 1.5) on the other hand fully fits into the affected ten pixels, the line is rendered crisp and black.

2.2.6.2 lineCap

In the following example, we draw three times three lines from the top to the bottom orange line. The lineWidth is set to 5.0, 10.0, and 20.0, respectively. The lineCap is set to 'butt', 'round' and 'square', as explained in the picture. Note, that the lines with the round and square line caps exceed their ending points by half of the line width.

2.2.6.3 lineJoin

The following three canvas examples each draw the same sequence of lines, except that each time the lineJoin property is set to the according value before the lines are drawn.

2.2.6.4 miterLimit

2.2.7 Shadows

The CanvasRenderingContext2D comes with nice tools to add fancy shadows to all the objects in the canvas, even to text. There are four properties that determine the presence and appearance of shadows: shadowOffsetX, shadowOffsetY, shadowBlur and shadowColor.

It makes sense to think that all objects added to the context have shadows. Except these shadows are invisible in the default setting, because then shadowOffsetX and shadowOffsetY are set to 0, shadowBlur is 0 and the shadowColor is transparent.

The following example canvas shows three columns, each one with different shadow settings. The first column #1 shows the default case, #2 has a crisp orange shadow, and in column #3, the shadows are blurred and half transparent black.

2.2.7.1 shadowOffsetX

In #1 the shadowOffsetX is default 0: there is no shadow, as it is directly behind the text characters. In #2 the horizontal offset is set to 10 before the text is written, so it appears ten pixel to the right behind the text. In #3 and #4 the shadowOffsetX is -15 and 75, respectively. The source code for all this is

2.2.7.2 shadowOffsetY

Here is an example with four different shadowOffsetY values, set to default 0, 10, -10 and 75, respectively:

2.2.7.3 shadowBlur

The following example shows the shadow for four different blur levels, namely default 0, 2, 4 and 8, respectively:

Even if shadowOffsetX and shadowOffsetY are both 0 so that the shadow is directly behind the drawn objects, it still creates a visible effect when shadowBlur has a positive value, say 5, as in the following example

2.2.7.4 shadowColor

2.2.8 Simple shapes (rectangles)

The 2D context only knows one kind of simple shapes, "simple" in the sense that it can be drawn with a single method call, namely rectangles. Of course, it is possible to draw all kinds of shapes: circles, triangles, complex polygons, smooth Bézier curves. But all these need to be composed by building more complex paths.

There are the following methods for rectangles: fillRect(), strokeRect() and clearRect(). There is also the plain rect() method, but that only serves as part of a path definition, and is therefore explained later in the section on complex shapes.

2.2.8.1 fillRect (x, y, w, h)

In each of the three cases, we first set the fillStyle and then call fillRect() to draw a rectangle accordingly. By default, the fillStyle is set to the color 'black'. In the second example, we set it to 'red' and in the third example, it is not a simple color, but a linear gradient.

2.2.8.2 strokeRect (x, y, w, h)

Similar to the previous example canvas with filled rectangles, we now create a similar canvas by replacing all fillStyle occurrences by a strokeStyle and all the fillRect() by strokeRect() calls. Furthermore, we demonstrate the variation of the lineWidth, as this also determines the outfit of the final picture.

2.2.8.3 clearRect (x, y, w, h)

The following canvas is first filled with a green color (by means of a fillRect() call). Then a yellow rectangular box is added. And finally, a clearRect() call erases a big part of the picture again (namely everything to the right and below of (100,50)).

2.2.9 Complex shapes (paths)

With strokeRect() and fillRect() we can draw (stroke or filled) rectangles. But in most cases, we would also like to draw other and more complex shapes. This can be done in a stepwise fashion by building paths. The standard procedure of creating any complex shape is thus

Next, we demonstrate how we can reproduce the methods for drawing rectangles by building paths. We then give an overview of these building blocks for paths accompanied by a lot of examples.

Unfortunately, it is necessary to explain the path concept by a lot of examples, as it itself is not a well elaborated concept in the [W3C] standard. In the preceding [WHATWG] standard, Path objects were explicitly defined and the concept was much more comprehensive. But in [W3C] a lot of these concepts were eliminated. Paths are now handled internally behind the scences and we only have mehods to act on the CanvasRenderingContext2D object (beginPath() etc.). This reduced the size of the API, but it does not really help to grasp the path concept. Well, this is what we have to live with. And still, the original expressive power remains: it is possible to draw about anything we can possibly want to.

We can draw a filled rectangle with a single call of fillRect(). For example, this code

Instead of calling fillRect(), we could have drawn a path along the shape of the rectangle area and then fill() it. The following code snippet thus generates exactly the same picture as the previous one:

Note, that with each moveTo() step (step 1., indicated by the cyan line), the current point of the path is only moved to the new indicated position. Wheareas each lineTo() step (lines in black) actually draws a line from the previous position to the new indicated point. After the path is outlined, a call of fill() creates a filled object in fillStyle inside the given lines. In our case, this results in the filled red rectangle.

Of course, a red "stroke rectangle" is drawn with this path method, if we replace the fill() by the stroke() method, after we set the strokeStyle where the fillStyle was before. Alltogether, the code snippet

which is of course the same picture as the one generated with the strokeRect() method by

By the way, as yet another variation of the same picture: we can also create a rectangular with a call of rect(), so that

2.2.9.1 beginPath()

For common applications of beginPath() see the examples below, in the sections explaining stroke() and fill().

2.2.9.2 closePath()

For example, this code snippet (where lineWidth is set to 5.0 and strokeStyle to 'red')

Each beginPath() needs either a fill() or stroke() at some point later on to actually create a figure on the canvas. Just putting a closePath() does close that path, indeed, but does not draw it. Leaving out the stroke() call in the previous example would have resulted in an empty canvas (picture).

The stroke() command of the previous example draws the shape of the path, with fill() we draw the full shape. More precisely, when we replace stroke() by fill() and run this code (now with fillStyle set to 'red')

But as a path needs to be closed anyway before we can "fill" the shape, the fill() command closes the path by default. This makes the closePath() call superfluous. Leaving out this line of code would have created exactly the same picture.

2.2.9.3 stroke()

lines in the previous code, the paths are closed and become a triangle, each. The picture is then this

2.2.9.4 fill()

We can visualize this path (by calling stroke(), of course) and it looks like this ²⁴

Remember, that calling fill() means, that the path is closed first, i.e. the end point (250,125) is connected to the initial point (50,25) like so:

And with this view of the closed path it becomes apparent what the fill() call does: it fills all the closed regions of the created shape.

2.2.9.5 lineTo (x, y)

A typical example for the use of lineTo() is the constrution of a polygon. Let us draw a triangle, the simplest of all polygons. This code

Note, that the last call of lineTo() in the source code draws a line from the left corner to the initial top point of the triangle, again. We could have replaced this line of code by a call of context.closePath(), because closePath() does that return to the initial point for us.²⁵

lineTo() does not draw lines, the drawing is done with the stroke() call. We could also have called the fill() method to generate this picture

Note, that we neither used a lineTo() call for a line from the left corner (30,120) to the inial top corner (150,30), nor did we call closePath() at the end of the path. This would have been superfluous, because fill() does close the path automatically.

2.2.9.6 moveTo (x, y)

But if we would have replaced each of the three moveTo() calls by lineTo() calls in the code, the picture would be this:

2.2.9.7 rect (x, y, w, h)

Note, that the rectangle is not drawn with this command. Therefore a subsequent stroke() or fill() call is required.
Note also, that the two steps of first creating and then drawing the rectangle are combined in the two methods strokeRect() and fillRect().

We could construct a path of six separate lines. But we can also built it by creating one square (with rect()) and a roof (two lineTo() calls) like so

Of course, if we would have replaced the last three lines of the previous code by these new lines

The actual drawing is done with fill() instead of stroke(), and accordingly, this is not done in strokeStyle but fillStyle. And this time, fillStyle is not just an ordinary color, but a linear gradient (see createLinearGradient() and addColorStop()).

It is possible to replace the rect() methods by creating the rectangular with a couple of lines. More precisely, this one line

2.2.9.8 quadraticCurveTo (cpx, cpy, x, y)

The full proper title of what the method here calls "quadratic curve" is "quadratic Beziér curve". And the "Beziér curve" from the next method (see bezierCurveTo() below) is a "cubic Beziér curve" in proper termininology. The Wikipedia article on Bézier curves has very nice and intuitive animations on constructing Bézier curves.

With moveTo(30,120) the current point 0 is located at (30,120). By calling quadraticCurveTo(210,30,210,120), the control point cp is (210,30) and the new point 1 is (210,120).

The red curve starts in 0 and moves towards cp (geometrically speaking: the line from 0 to cp is a tangent to the curve at point 0), and then bends towards 1 (again: the line from cp to 1 is a tangent to the curve at point 1).

Suppose, we attempt to draw an ellipse, which should eventually look like this²⁶

Obviously, the two horizontal and two vertical lines on the next picture are tangents of the ellipse

and we can compose the ellipse essentially as a sequence of four quadraticCurveTo() calls.

We start at the top point 0 and call quadraticCurveTo() for the first time via control point cp1 to point 1:

i.e. we add three more quadraticCurveTo() calls and wrap the pieces between a beginPath() and stroke() call, so that the full code for the original shape is this

In theory, the quadraticCurveTo() method is just a special case of bezierCurveTo(), which has two instead of one control points. One just has to repeat the same control point again, i.e. we could just replace each

This possibility might also be interesting because there seems to be a bug in the Firefox 1.5 implementation of the quadraticCurveTo() method. This is mentioned in the Mozilla Development Network canvas tutorial, which also provides a bug workaround.

But in fact, the browser vendors don't seem to implement it that way, as you might discover in you own browser when comparing the following two pictures. Let us consider the ellipse example again, first implemented with quadraticCurveTo() calls as before. This snippet

2.2.9.9 bezierCurveTo (cp1x, cp1y, cp2x, cp2y, x, y)

The curve starts in point 0 towards cp1 and terminates in point 1 coming from cp2.

The same principle holds when we change the position of the involved points. For example

Also note, that even "pulling" cp1 away from point 0 (or cp2 away from 1) also pulls at the curve and bends it stronger:

As mentioned before, the proper title of what this method here calls "Beziér curve" is "cubic Beziér curve". And the "quadratic curve" from the previous method (see quadraticCurveTo() above) is actually a "quadratic Beziér curve" in proper maths terms. Your should really check out the intuitive animations in the according Wikipedia entry, in particular the section on constructing Bézier curves.

The whole theory on Beziér curves was developed in car factories for the practical purpose of creating smooth auto bodies. But finding the code for a given shape by hand can be a daunting task. Let us exercise a straight forward method on how this can be done. Suppose we try to find the code for say the shape of a heart: ²⁷

We start by identifying a couple of significant points 0, 1, 2, 3, 4, 5, and the tangents (displayed in green), i.e. the lines that touch the red shape at that particular point:

Then we read off the bezierCurveTo() calls from each piece in the path. Sometimes, we need to play a little with the best location of the control points on the tangent, i.e. we can do some pulling as described earlier, to get the red line into the best shape. We obtain the following six results:

We finally just gather the pieces and end up with the code for the original canvas picture

2.2.9.10 arc (x, y, r, start, end, anticlockwise)

For example, let us draw sections of five circle disks, each one with a radius of 50 pixels

And if we replace fillStyle by strokeStyle and each occurrence of fill() by stroke(), we obtain this picture of five circle arcs:

Let us add the coordinate system and a red dot for the center of each arc so that we can see their precise posititons:

Every angle a is measured from 3 o'clock position of the given circle in the clockwise direction:

Note, that the unit of each angle a is given in radian rad, i.e. the angle is a rad and the length of the arc is a * r.

The 4th arc of the initial example, drawn by arc(420,60,50,2,6,false) had a start angle of 2 rad and an end angle of 6 rad

And if we change the fifth parameter false to true, i.e. if we call arc(420,60,50,2,6,true), so that the direction on the circle is not clockwise, but anticlockwise, we obtain the 5th arc

Most users are more familiar with degree ° instead of radian rad as a unit for angles. Recall, that a full circle is 2π (about 6.283), and that π is in JavaScript given by the constant value

We convert back and forth between radian and degree using the equation 360°=2π

In the initial example, the 1st arc was a full circle, and we draw that with start angle 0 and end angle 2*Math.PI. The 2nd and 3rd were half circles from start angle 0 to end angle Math.PI, drawn clockwise and anticlockwise, respectively.

Recall from trigonometry, that a point on a circle with center (x,y), radius r and at an angle of a, has the coordinates

A call of arc() is part of the current path. It depends on the current point before it was called, and the end point of the arc becomes the new current point afterwards. For example, this code

The initial point of the path is (30,90). The call of arc() defines that arc, but also the line from the initial (30,90) to the starting point of the arc. After the call, the new current point is the end point of the arc. And the final call of lineTo() draws the line from the arc to (390,90)

If you want to prevent this behavior and the extra lines, wrap the arc() call between a beginPath() and stroke() or fill(), as we did in all our examples so far. That ensures that only the arc itself is drawn.

Recall, that we wrapped each arc() call inside a sequence beginPath(); arc(); stroke();. If we would have wrapped all five arc() calles in just one path, i.e. if this would have been our code

The start and end point of the arc become part of the path definition. The same holds in general for filled objects and with drawing methods inside the path.

If we add a point, say (30,25) before the arc, and if we draw a line afterwards, say to (30,100), i.e. if we use this code

The path itself, which is visible if we replace the fill by stroke in the code, is this

2.2.9.11 arcTo (x1, y1, x2, y2, radius)

Let context be the 2D context of a default size canvas (the lineWidth is set to 5.0, the strokeStyle is 'red'). Then the following code snippet

The shape drawn by the arcTo (x1, y1, x2, y3, radius) depends on three points:

Now imagine two half-infinite lines with point 1 as their origin, one going through point 0, the other one via point 1.

Now, the actual arcTo (x1, y1, x2, y3, radius) draws a line that has its origin in point 0, runs towards point 1, makes a turn towards point 2, so that radius is the actual radius of the arc. The ending point of the arcTo() line is the point, where the arc meets the tangent line (from point 1 towards point 2).

2.2.9.12 clip()

and suppose, we want to clip from this canvas the part that is defined by this circle

The standard method to achieve this is in three steps: 1. draw the shape of the area to be clipped, 2. call the clip() method and 3. draw the canvas content

In the previous example, both the clipped circle area and the canvas drawings where filled shapes. But we can replace either of these filled by stroke figures. For example, if we replace each occurrence of a "fill" by a "stroke" in the previous code, the picture will be this

The clip technique works for all canvas drawings, including images. To cut out a disk from an horse image, we can use this code ²⁸

2.2.9.13 isPointInPath (x, y)

2.2.10 Text

2.2.10.1 font

On the following canvas, in each line the font is set to another value, and this value is displayed with strokeText() on the left and fillText() on the right:

2.2.10.2 textAlign

In each of the following examples, context is the 2d context of the given canvas element.

The actual appearance of the text when textAlign is set to 'left' or 'right' depends on the directionality of text. This directionality is defined in the dir attribute, it is either 'ltr' (left-to-right) or 'rtl' (right-to-left), and the canvas element inherits this value.

2.2.10.3 textBaseline

2.2.10.4 fillText (text, x, y) and fillText (text, x, y, maxWidth)

2.2.10.5 strokeText (text, x, y) and strokeText (text, x, y, maxWidth)

(According to the reference on w3schools.com, the maxWidth property is not supported by the Safari browser.)

2.2.10.6 measureText(text).width

So, if context is the 2d context of the given canvas, then context.measure('Hello world!').width returns the length of the string "Hello world!" in the current settings.

The form of this call is rather awkward, and of course it is a combination of two steps: canvas.measureText(text) returns a TextMetrics object. In the [WHATWG] specification, a TextMetrics object held quite a lot of information. But all this is obscured away in the official [W3C] standard, only the width property of the TextMetrics object remains accessible. By calling canvas.measureText(text).width we obtain that information.

Recall, that the current height of text is set and stored by the font property.

In the following example, w takes the value for the width of the string "This is some text." in the current font settings (namely 30px Arial). As it turns out, w is 233.

2.2.11 Drawing images

2.2.11.1 drawImage (image, dx, dy)

For example, given the file horse.jpg, which is a 300x425 pixel image and let context be the 2d context of a given 400x500 pixel canvas. Then this code

2.2.11.2 drawImage (image, dx, dy, dw, dy)

For example, if we take our horse.jpg image again, and context is the 2d context of a 700x500 pixel canvas, then the code

2.2.11.3 drawImage (image, sx, sy, sw, sh, dx, dy, dw, dh)

For example, if we use our horse image horse.jpg again, context is the 2d context of a 350x350 canvas, then

2.2.12 Pixel manipulation

The picture of a canvas can be formalized as a structure that contains the color value for each of its pixels. This is done by an ImageData object. We will now show how to create such an object with createImageData(), how we to cut out such an object from a canvas with getImageData() and how to insert such an object into an area of a given canvas with putImageData().

2.2.12.1 ImageData

Suppose we have an image (a canvas, or section from a canvas context) with a given width w and height h. The color of each pixel (x,y) is given by the RGBA color rgba(R_(x,y),G_(x,y),B_(x,y),A_(x,y)), where each of the four components R_(x,y), G_(x,y), B_(x,y), A_(x,y) is a value from the set {0,1,2,...,255} and R stands for the amount of red, G for green, B for blue, and A for the "alpha" or transparency value. The whole image is then formally represented by a table like this one:

	`x = 0`	`x = 1`	...	`x = w-1`
`y = 0`	`rgba(R_(0,0),G_(0,0),B_(0,0),A_(0,0))`	`rgba(R_(1,0),G_(1,0),B_(1,0),A_(1,0))`	...	`rgba(R_(w-1,0),G_(w-1,0),B_(w-1,0),A_(w-1,0))`
`y = 1`	`rgba(R_(0,1),G_(0,1),B_(0,1),A_(0,1))`	`rgba(R_(1,1),G_(1,1),B_(1,1),A_(1,1))`	...	`rgba(R_(w-1,1),G_(w-1,1),B_(w-1,1),A_(w-1,1))`
`y = 2`	`rgba(R_(0,2),G_(0,2),B_(0,2),A_(0,2))`	`rgba(R_(1,2),G_(1,2),B_(1,2),A_(1,2))`	...	`rgba(R_(w-1,2),G_(w-1,2),B_(w-1,2),A_(w-1,2))`
`...`	...	...		...
`y = h-1`	`rgba(R_(0,h-1),G_(0,h-1),B_(0,h-1),A_(0,h-1))`	`rgba(R_(1,h-1),G_(1,h-1),B_(1,h-1),A_(1,h-1))`	...	`rgba(R_(w-1,h-1),G_(w-1,h-1),B_(w-1,h-1),A_(w-1,h-1))`

In an ImageData object this information is stored in this three-property object:

The data value is an array comprising all the color values in one single sequence. The length of this array is 4 * w * h.

	`x = 0`	`x = 1`	...	`x = 255`
`y = 0`	`rgba(0,0,0,255)`	`rgba(1,0,0,255)`	...	`rgba(255,0,0,255)`
`y = 1`	`rgba(0,1,0,255)`	`rgba(1,1,0,255)`	...	`rgba(255,1,0,255)`
`y = 2`	`rgba(0,2,0,255)`	`rgba(1,2,0,255)`	...	`rgba(255,2,0,255)`
`...`	...	...		...
`y = 255`	`rgba(0,255,0,255)`	`rgba(1,255,0,255)`	...	`rgba(255,255,0,255)`

where the length of the data array is 4*256*256, i.e. it contains 262144 integer components.

(For the actual generation of this ImageData object and the previous canvas picture, see Example 1 below.)

2.2.12.2 createImageData (sw,sh) and createImageData (imagedata)

The latter of the two calls createImageData(imagedata) is thus just a short version for calling createImageData(imagedata.width, imagedata.height).

Each createImageData() call thus returns a ImageData object, but one in which all array elements of the data array are set to 0. However, once the object is created, all these RGBA color components can be altered by explicit references to data[i].

2.2.12.3 getImageData (sx, sy, sw, sh)

2.2.12.4 putImageData (imagedata, dx, dy) and putImageData (imagedata, dx, dy, sx, sy, sw, sh)

2.2.12.5 Examples of pixel manipulation

First, we create an ImageData object, calling it imDat, by invoking context.createImageData(w,h) with w and h both set to 256. At this point the imDat.data array is an array of length 4*256*256, each array component being 0. Setting all these components to the required color code is done in the double for loop. When this loop is left again, imDat is as we wanted it. So in the last step, calling context.putImageData(imDat,0,0) inserts this ImageData object with its left upper corner at (0,0) into the canvas.

Let us show how we cut out a rectangular section and copy it into the same picture, again. Consider this canvas

We now cut out the 260x60 pixel rectangle at (20,20) and place its copy at (320,20). If we indicate this rectange by a red frame, the whole operation is displayed as

The actual copying is done by adding the following two lines to the previous code

With the first line, we extact an ImageData object, called imDat. With the second line, we insert that object into the picture, again.
The picture generated by the previous code is indeed this

We just made a simple copy of a canvas section in two steps: 1. get an ImageData object, named imDat and 2. put it into the canvas context, again.

We now modify the obtained object before putting it back, performing three steps:

As explained, createImageData(imDat) does not fully clone imDat, it only creates an ImageData object with the same dimensions, but with all color values in the data array set to 0. Accordingly, the previous line could be replaced by following line, which does exactly the same:

In the nested loops of step 2.b, the components of mirImDat.data are then updated to the correct values that turn mirImDat into the true mirror image of imDat.

This example of a mirror copy demonstrates, how all the transformation methods of the CanvasRenderingContext2D could be re-implemented by means of these manipulations on the pixel level.

3 Appendices

3.1 Reference summary

The following is a copy of the interface definitions of the HTMLCanvasElement, the CanvasRenderingContext2D, and a few other related objects, as given by the [W3C.org] standard. The content table of the Reference part of this Canvas Handbook resembles the first two main interfaces.

3.2 Some elements of CSS

3.2.1 CSS Colors

3.2.2 CSS Fonts

For more information, see the standard description on w3.org or the reference on w3schools.com.

Font properties in CSS
CSS property	possible values
`font-style`	`normal`, `italic`, `oblique`, `inherit` Default is `normal` and `inherit` means inherited from the parent element.
`font-variant`	`normal` (default), `small-caps`, `inherit` (Default is `normal` and `inherit` means inherited from the parent element.)
`font-weight`	`normal`, `bold`, `lighter`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `inherit` (Default is `normal`, which is the same as `400`. And `bold` is the same as `700`.)
`font-size`	`xx-small`, `x-small`, `small`, `medium`, `large`, `x-large`, `xx-large`, `smaller`, `larger`, `inherit` or some length specified as nn`px`, nn`cm`, nn`٪`,
`font-family`	There are two types of font family names: generic-family namely: `serif`, `sans-serif`, `cursive`, `fantasy` or `monospace` family-name for example `times`, `courier`, `arial`, `verdana`, `"Times New Roman"` etc. The `font-family` property can hold several values, separated by commas, as a "fallback" system. If the browser does not support the first font, it tries the next one. For example, `font-family="Verdana, cursive"` `font-family="'Times New Roman', Georgia, Serif, monospace"`
`font`	This property sets all the font properties in one declaration. The properties that can be set are (in this order) `font-style` `font-variant` `font-weight` `font-size` `font-family` For example, `"italic small-caps bold 12px arial, sans-serif"`,

3.3 HTML5 file templates

Below, we list and discuss some templates for HTML5 files that contain canvas elements. All these examples will produce the same browser view, namely this:

The difference lies underneath in the organization of the HTML and JavaScript code.

The text with a circle and square is generated by the following HTML file, say example.html

In this file we used the method from the introduction (see A first example and Basic setup): For each canvas, we place a <canvas>...</canvas> tag with a separate id attribute, followed by a <script>...</script>, in which the canvas is further developed.

This method suffices for simple pictures and small files. But when the pictures become more complex and external image or media files are involved, this will not work anymore and empty canvas pictures will appear instead. So in general, it is not a good advice to organize your files that way.

When we deal with non-trivial projects, it is a good custom to distinguish style from content and place the different codes into separate files. In our case, these are three:

The main HTML file holds the content and defines the organization of the whole page. The CSS file sets the non-default style features and is integrated via

instruction. The JavaScript finally contains the drawings for the two canvas elements and it is integrated via

However, is this fashion, it does not work! Instead of the previous picture with the circle and square, we see this

in the browser. Only the CSS border of the canvas elements appears, without the JavaScript generated picture elements.

When the browser starts to read the HTML file, it loads the CSS and JavaScript file, as demanded in the <head>...</head> section, and then continues to generate the <body>...</body> section with the two canvas elements. In this order of execution, the JavaScript code is executed before the canvas elements are present, and that fails. The canvas pictures remain empty.

i.e. we add the defer attribute to the <script> tag. That way, the execution of the JavaScript file example.js is delayed until the whole HTML file is loaded, first. With this modification we obtain the intended browser picture

The order in which different code types are executed can also be influenced by JavaScript itself. All canvas drawings in JavaScript are now enclosed in a function named draw(). And an event listener is added to the body that ensures that draw() is executed only onload, i.e. when the HTML code in the body is fully loaded, first. The three files are now given by

As a last variation to the previous template, we can also remove all JavaScript from the html file again and add the event listener in the js file. The underlying mechanism is still the same, but the encoding is different. This involves the following modifications of the previous file listings:

The last templates very much represent the commonly recommended methods on how canvas elements ought to be integrated in web pages. Each of these methods can still be refined by increasing the detection of errors. Both browsers and JavaScript are originally designed to "degrate gracefully" in the sense that they try to avoid the collapse of things, but rather tend to process as much as possible. The browser that doesn't understand <canvas> tags displays the fallback (the text ... inside the <canvas>...</canvas>) instead of printing a big error message all over the screen. And when a variable in JavaScript is undefined, the script doesn't protest in the browser window, but tries to continue with an undefined value for the variable.

The price for this forgiving design is the difficulty to locate the origin of problems, once they occurred. And the more professional the programming, the more strict and less forgiving the program flows and more and more error detections are built in.

For the HTML part this means that one usually does provide a fallback text such as

For the JavaScript part this involves the modularization of code into separate parts and thorough verification on the correctness of variables and objects.

For example, we can split the draw() function into drawCanvas1() and drawCanvas2(), for each occurring canvas element. And instead of writing say

Instead of pretty silent error messages we can also cause popup windows to alarm: just replace each

3.4 Tools and tool building

3.4.1 How to write your own functions like strokeCircle() and fillCircle()

In JavaScript it is quite easy to extend the toolset for the canvas and 2d context any way you like by writing functions. Suppose we want to write functions that create circles very similar to the way fillRect() and strokeRect() works for creating rectangles.

These functions should have two number arguments x and y for the location of the circles center point, and r for the radius.

where contextObj is a CanvasRenderingContext2D object. So in order to generate a picture with a green bullet like this

where canvasId is the value of the id attribute in the according <canvas> tag. This is implemented by

But as this version excludes the context, and the context is the object you need when you want to modify say the color.

If we want to built our functions according to the object-oriented design of the context, we would prefer to have the context not as a function argument (like in the first version), but fillCircle() should be a method on the 2d context, so that we can call it like this

For that, we would have to extend the method repertoire of the CanvasRenderingContext2D object. And in fact, that is possible in JavaScript by making use of its prototype design. The implementation would thus be like this

This third, prototype-based implementation is probably closest to the original style. ³⁰

3.4.2 addGrid(delta,color,font)

If you want to use the addGrid() method in your own scripts, copy the following implementation of the function into your own file.

[HOME] http://bucephalus.org/text/CanvasHandbook/CanvasHandbook.html↩
[FORUM] http://www-bucephalus-org.blogspot.nl/2013/09/the-html5-canvas-handbook.html↩
This final HTML file CanvasHandbook.html is generated from the following source files:
1. CanvasHandbook.markdown containing the source text for the HTML document. The conversion into HTML is done with Pandoc.
2. CanvasHandbook.js containing the tool functions (such as addGrid()) and the scripts for the canvas elements. This code is integrated into the main document according to the method described in the appendix.
  I also used the CodeDown document generator to convert the js file into a more readable document file CanvasHandbook.js.html, which was itself generated from an intermediate Markdown file CanvasHandbook.js.markdown.
3. Two CSS files: the standard CodeDown.css stylesheet and CodeDownPrint.css for printing the file with a smaller font.
4. Image files: horse.jpg, grayhorse.jpg, baselines.png, TemplateCircleAndSquare.png and TemplateCircleAndSquare2.png. All other pictures in the browser are generated by <canvas> tags and JavaScript.
↩
[W3C] http://www.w3.org/TR/2009/WD-html5-20090825/the-canvas-element.html↩
[WHATWG] http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#the-canvas-element↩
[W3C/2D] http://dev.w3.org/html5/2dcontext↩
If you do not see the "Hello" message or if you read "GO AND UPDATE YOUR BROWSER BEFORE YOU READ ON!" instead, you should really follow that advise. Otherwise, none of the pictures in this handbook will be displayed properly and the whole text does not make sense.↩
What you see inside the <script>...</script> tag is not HTML, but JavaScript code, and that has a different syntax. One important feature is the comment, a piece of information inserted into programming code, which is only meant as an aid to understand and maintain the code. A comment only serves the human reader of the code and is ignored by the computer program, in this case the JavaScript engine of the browser.
All text on a line after a double slash "//" is a comment in JavaScript. In the given example, "// identify the canvas element" is a comment and explains what the code left of the "//" is doing. We will make heavy use of comments in all our JavaScript code examples.↩
You probably know about the DOM (Document Object Model). Each web document is first of all given as a HTML file. When this HTML code is loaded, the browser translates the document into a hierarchical JavaScript tree object. Each element of the HTML code is represented as a node object in this tree. The root to that tree is accessed by the predefined document keyword. Any element node in this tree that corresponds to a tag with an id is then accessed by a call of document.getElementById('...'). Alternatively we could also get the array of all HTMLCanvasElement objects in one document by calling document.getElementsByTagName('canvas'). But we will not use this in our text here. ↩
In JavaScript, a string is enclosed in either single quotes '...' or double quotes "...". For example, 'Hello world!' and "Hello world!" both denote the same string. There are subtle differences between these two versions, but for now we can neglects these details. So document.getElementById('Example1') and document.getElementById("Example1") have the same effect and you may freely choose between these two versions.↩
Note, that the direction of the y-axis is really opposite the standard direction in cartesian coordinate systems!↩
Actually, the drawn red dot is not just 1 pixel big, but has a radius of 4 pixel. Otherwise it might be too difficult to see.↩
It is however possible, to shift the whole coordinate system on the canvas, so that e.g. the origin (0,0) no longer is the left upper corner, but moves to the center, and so that points like (-60,50) now do become part of the picture. This can be done with transformations such as translate(x,y).↩

The six lines that draw the three colored rectangles are wrapped in this code, according to our previous template:

<canvas id="GermanFlag" width=200 height=120> </canvas>
<script>
  // get the canvas object and its context
  var canvas = document.getElementById('GermanFlag');
  var context = canvas.getContext('2d');
  // add the grid with 40 pixels for each step to the next line (see the appendix on this addGrid() method
  context.addGrid(40);            // THIS IS NOT A STANDARD METHOD!!!
  // now draw the colored rectangles
  // now draw the colored rectangles
  context.fillStyle = '#000000';
  context.fillRect(0, 0,200,40);
  context.fillStyle = '#FF0000';
  context.fillRect(0,40,200,40);
  context.fillStyle = '#FFCC00';
  context.fillRect(0,80,200,40);
</script>

↩

This idea of the clickable canvas was suggested in html5doctor.com.↩
The transform() method however is not able to perform any (topological) transformation in the general geometrical sense, but only what is called an affine transformation. For example, it cannot produce a fisheye perspective, because during affine transformations, straight and parallel lines must remain straight and parallel, respectively. It is possible however, to implement topological transformations by making use of the pixel manipulations, but that is a different approach.↩
With the method described in the appendix, we can add shear() as a new method to the CanvasRenderingContext2D object like so:
```
CanvasRenderingContext2D.prototype.shear = function (x,y) {
  this.transform (1, y, x, 1, 0, 0);
};
```
I took the idea and definition of the shear() method from David Flanagan, Canvas Pocket Reference.↩
It is not important here to specify the exact data structure for this sixtuple (a,b,c,d,e,f). It might be given as an array [a,b,c,d,e,f]. In [WHATWG] this was stored as a SVGMatrix object. For the computation of transformation compositions, it is convenient to store it as a 3x2 matrix of the form

a c e

b d f

0 0 1

because the composition is then nothing but a matrix multiplication.↩

The definition of the composition ⊗ is as follows:
Given (a₁,b₁,c₁,d₁,e₁,f₁) and (a₂,b₂,c₂,d₂,e₂,f₂) then

(a₁,b₁,c₁,d₁,e₁,f₁)⊗(a₂,b₂,c₂,d₂,e₂,f₂) = (a₃,b₃,c₃,d₃,e₃,f₃)

where

a₃ = (a₂ * a₁) + (c₂ * b₁)
b₃ = (b₂ * a₁) + (d₂ * b₁)
c₃ = (a₂ * c₁) + (c₂ * d₁)
d₃ = (b₂ * c₁) + (d₂ * d₁)
e₃ = (a₂ * e₁) + (c₂ * f₁) + e₂
b₃ = (b₂ * e₁) + (d₂ * f₁) + f₂

When the parameters are stored as 3x3 matrices, then composition is nothing but a matrix multiplication, namely

a₂ c₂ e₂

b₂ d₂ f₂

0 0 1

⊗

a₁ c₁ e₁

b₁ d₁ f₁

0 0 1

=

a₃ c₃ e₃

b₃ d₃ f₃

0 0 1

Note, that τ₁⊗τ₂ meant that first τ₁ and then τ₂ is performed. In matrix multiplication, this order is reversed: the matrix of τ₂ is multiplied with the matrix of τ₁, not the other way round. (Composition and matrix multiplication is not commutative. It is associative however, i.e. (τ₁⊗τ₂)⊗τ₃ = τ₁⊗(τ₂⊗τ₃).)

We can also implement this as a JavaScript function: given two arrays arr1=[a1,b1,c1,d1,e1,f1] and arr2=[a2,b2,c2,d2,e2,f2], then composeTransform(arr1,arr2) returns their composition [a3,b3,c3,d3,e3,f3].

function composeTransform (arr1, arr2) {
  if (Array.isArray (arr1) && Array.isArray (arr2)) {
    if (arr1.length === 6 && arr2.length === 6) {
      // components of arr1
      var a1 = arr1[0]; var b1 = arr1[1]; var c1 = arr1[2]; var d1 = arr1[3]; var e1 = arr1[4]; var f1 = arr1[5];
      // components of arr2
      var a2 = arr2[0]; var b2 = arr2[1]; var c2 = arr2[2]; var d2 = arr2[3]; var e2 = arr2[4]; var f2 = arr2[5];
      // components of the resulting array
      var a3 = (a2 * a1) + (c2 * b1);
      var b3 = (b2 * a1) + (d2 * b1);
      var c3 = (a2 * c1) + (c2 * d1);
      var d3 = (b2 * c1) + (d2 * d1);
      var e3 = (a2 * e1) + (c2 * f1) + e2;
      var f3 = (b2 * e1) + (d2 * f1) + f2;
      return [a3, b3, c3, d3, e3, f3];
    } else {
      throw Error ("The two array arguments of composeTransform(arr1,arr2) must both have six components each.");
    }
  } else {
    throw Error ("The two arguments of composeTransform(arr1,arr2) must both be arrays.");
  }
};

In case the arguments arr1 and arr2 are not both arrays of length 6, an error message is thrown.↩

As mentioned before, in this standard, the parameters (a,b,c,d,e,f) of the currentTransform was an SVGMatrix object.↩