Drawing graphics with canvas

  • Revision slug: HTML/Canvas/Drawing_Graphics_with_Canvas
  • Revision title: Drawing Graphics with Canvas
  • Revision id: 343111
  • Created:
  • Creator: trevorh
  • Is current revision? No
  • Comment Moving to Live samples

Revision Content

Most of this content (but not the documentation on drawWindow) has been rolled into the more expansive Canvas tutorial, this page should probably be redirected there as it's now redundant.

Introduction

With Firefox 1.5, Firefox includes a new HTML element for programmable graphics. <canvas> is based on the WHATWG canvas specification, which itself is based on Apple's <canvas> implemented in Safari. It can be used for rendering graphs, UI elements, and other custom graphics on the client.

<canvas> creates a fixed size drawing surface that exposes one or more rendering contexts. We'll focus on the 2D rendering context. For 3D graphics, you should use the WebGL rendering context.

The 2D Rendering Context

A Simple Example

To start off, here's a simple example that draws two intersecting rectangles, one of which has alpha transparency:

function draw() {
  var ctx = document.getElementById('canvas').getContext('2d');

  ctx.fillStyle = "rgb(200,0,0)";
  ctx.fillRect (10, 10, 55, 50);

  ctx.fillStyle = "rgba(0, 0, 200, 0.5)";
  ctx.fillRect (30, 30, 55, 50);
}

{{ EmbedLiveSample('A_Simple_Example','150','150','/@api/deki/files/602/=Canvas_ex1.png') }}

The draw function gets the canvas element, then obtains the 2d context. The ctx object can then be used to actually render to the canvas. The example simply fills two rectangles, by setting fillStyle to two different colors using CSS color specifications and calling fillRect. The second fillStyle uses rgba() to specify an alpha value along with the color.

The fillRect, strokeRect, and clearRect calls render a filled, outlined, or clear rectangle. To render more complex shapes, paths are used.

Using Paths

The beginPath function starts a new path, and moveTo, lineTo, arcTo, arc, and similar methods are used to add segments to the path. The path can be closed using closePath. Once a path is created, you can use fill or stroke to render the path to the canvas.

function draw() {
  var ctx = document.getElementById('canvas').getContext('2d');

  ctx.fillStyle = "red";

  ctx.beginPath();
  ctx.moveTo(30, 30);
  ctx.lineTo(150, 150);
  // was: ctx.quadraticCurveTo(60, 70, 70, 150); which is wrong.
  ctx.bezierCurveTo(60, 70, 60, 70, 70, 150); // <- this is right formula for the image on the right ->
  ctx.lineTo(30, 30);
  ctx.fill();
}

{{ EmbedLiveSample('Using_Paths','190','190','/@api/deki/files/603/=Canvas_ex2.png') }}

Calling fill() or stroke() causes the current path to be used. To be filled or stroked again, the path must be recreated.

Graphics State

Attributes of the context such as fillStyle, strokeStyle, lineWidth, and lineJoin are part of the current graphics state. The context provides two methods, save() and restore(), that can be used to move the current state to and from the state stack.

A More Complicated Example

Here's a little more complicated example, that uses paths, state, and also introduces the current transformation matrix. The context methods translate(), scale(), and rotate() all transform the current matrix. All rendered points are first transformed by this matrix.

function drawBowtie(ctx, fillStyle) {
 
  ctx.fillStyle = "rgba(200,200,200,0.3)";
  ctx.fillRect(-30, -30, 60, 60);
 
  ctx.fillStyle = fillStyle;
  ctx.globalAlpha = 1.0;
  ctx.beginPath();
  ctx.moveTo(25, 25);
  ctx.lineTo(-25, -25);
  ctx.lineTo(25, -25);
  ctx.lineTo(-25, 25);
  ctx.closePath();
  ctx.fill();
}
 
function dot(ctx) {
  ctx.save();
  ctx.fillStyle = "black";
  ctx.fillRect(-2, -2, 4, 4);
  ctx.restore();
}
 
function draw() {
  var ctx = document.getElementById('canvas').getContext('2d');

  // note that all other translates are relative to this one
  ctx.translate(45, 45);

  ctx.save();
  //ctx.translate(0, 0); // unnecessary
  drawBowtie(ctx, "red");
  dot(ctx);
  ctx.restore();
 
  ctx.save();
  ctx.translate(85, 0);
  ctx.rotate(45 * Math.PI / 180);
  drawBowtie(ctx, "green");
  dot(ctx);
  ctx.restore();
 
  ctx.save();
  ctx.translate(0, 85);
  ctx.rotate(135 * Math.PI / 180);
  drawBowtie(ctx, "blue");
  dot(ctx);
  ctx.restore();
 
  ctx.save();
  ctx.translate(85, 85);
  ctx.rotate(90 * Math.PI / 180);
  drawBowtie(ctx, "yellow");
  dot(ctx);
  ctx.restore();
}

{{ EmbedLiveSample('A_More_Complicated_Example','215','215','/@api/deki/files/604/=Canvas_ex3.png') }}

This defines two methods, drawBowtie and dot, that are called 4 times. Before each call, translate() and rotate() are used to set up the current transformation matrix, which in turn positions the dot and the bowtie. dot renders a small black square centered at (0, 0). That dot is moved around by the transformation matrix. drawBowtie renders a simple bowtie path using the passed-in fill style.

As matrix operations are cumulative, save() and restore() are used around each set of calls to restore the original canvas state. One thing to watch out for is that rotation always occurs around the current origin; thus a translate() rotate() translate() sequence will yield different results than a translate() translate() rotate() series of calls.

Compatibility With Apple <canvas>

For the most part, <canvas> is compatible with Apple's and other implementations. There are, however, a few issues to be aware of, described here.

Required </canvas> tag

In the Apple Safari implementation, <canvas> is an element implemented in much the same way <img> is; it does not have an end tag. However, for <canvas> to have widespread use on the web, some facility for fallback content must be provided. Therefore, Mozilla's implementation has a required end tag.

If fallback content is not needed, a simple <canvas id="foo" ...></canvas> will be fully compatible with both Safari and Mozilla -- Safari will simply ignore the end tag.

If fallback content is desired, some CSS tricks must be employed to mask the fallback content from Safari (which should render just the canvas), and also to mask the CSS tricks themselves from IE (which should render the fallback content). Todo: get hixie to put the CSS bits in

Additional Features

Rendering Web Content Into A Canvas

This feature is only available for code running with Chrome privileges. It is not allowed in normal HTML pages. Read why.

Mozilla's canvas is extended with the drawWindow() method. This method draws a snapshot of the contents of a DOM window into the canvas. For example,

ctx.drawWindow(window, 0, 0, 100, 200, "rgb(255,255,255)");

would draw the contents of the current window, in the rectangle (0,0,100,200) in pixels relative to the top-left of the viewport, on a white background, into the canvas. By specifying "rgba(255,255,255,0)" as the color, the contents would be drawn with a transparent background (which would be slower).

It is usually a bad idea to use any background other than pure white "rgb(255,255,255)" or transparent, as this is what all browsers do, and many websites expect that transparent parts of their interface will be drawn on white background.

With this method, it is possible to fill a hidden IFRAME with arbitrary content (e.g., CSS-styled HTML text, or SVG) and draw it into a canvas. It will be scaled, rotated and so on according to the current transformation.

Ted Mielczarek's tab preview extension uses this technique in chrome to provide thumbnails of web pages, and the source is available for reference.

Note: Using canvas.drawWindow() while handling a document's onload event doesn't work.  In Firefox 3.5 or later, you can do this in a handler for the MozAfterPaint event to successfully draw HTML content into a canvas on page load.

See also

Revision Source

<div class="note">
  <p>Most of this content (but not the documentation on drawWindow) has been rolled into the more expansive <a href="/en/Canvas_tutorial" title="en/Canvas_tutorial">Canvas tutorial</a>, this page should probably be redirected there as it's now redundant.</p>
</div>
<h3 id="Introduction" name="Introduction">Introduction</h3>
<p>With <a href="/en/Firefox_1.5_for_developers" title="en/Firefox_1.5_for_developers">Firefox 1.5</a>, Firefox includes a new HTML element for programmable graphics. <code>&lt;canvas&gt;</code> is based on the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#the-canvas">WHATWG canvas specification</a>, which itself is based on Apple's <code>&lt;canvas&gt;</code> implemented in Safari. It can be used for rendering graphs, UI elements, and other custom graphics on the client.</p>
<p><code>&lt;canvas&gt;</code> creates a fixed size drawing surface that exposes one or more <em>rendering contexts</em>. We'll focus on the 2D rendering context. For 3D graphics, you should use the <a href="/en/WebGL" title="https://developer.mozilla.org/en/WebGL">WebGL rendering context</a>.</p>
<h3 id="The_2D_Rendering_Context" name="The_2D_Rendering_Context">The 2D Rendering Context</h3>
<h4 id="A_Simple_Example" name="A_Simple_Example">A Simple Example</h4>
<p>To start off, here's a simple example that draws two intersecting rectangles, one of which has alpha transparency:</p>
<pre class="brush: js">
function draw() {
  var ctx = document.getElementById('canvas').getContext('2d');

  ctx.fillStyle = "rgb(200,0,0)";
  ctx.fillRect (10, 10, 55, 50);

  ctx.fillStyle = "rgba(0, 0, 200, 0.5)";
  ctx.fillRect (30, 30, 55, 50);
}
</pre>
<div class="hidden">
  <pre class="brush: html">
&lt;canvas id="canvas" width="120" height="120"&gt;&lt;/canvas&gt;</pre>
  <pre class="brush: js">
draw();</pre>
</div>
<p>{{ EmbedLiveSample('A_Simple_Example','150','150','/@api/deki/files/602/=Canvas_ex1.png') }}</p>
<p>The <code>draw</code> function gets the <code>canvas</code> element, then obtains the <code>2d</code> context. The <code>ctx</code> object can then be used to actually render to the canvas. The example simply fills two rectangles, by setting fillStyle to two different colors using CSS color specifications and calling <code>fillRect</code>. The second fillStyle uses <code>rgba()</code> to specify an alpha value along with the color.</p>
<p>The <code>fillRect</code>, <code>strokeRect</code>, and <code>clearRect</code> calls render a filled, outlined, or clear rectangle. To render more complex shapes, paths are used.</p>
<h4 id="Using_Paths" name="Using_Paths">Using Paths</h4>
<p>The <code>beginPath</code> function starts a new path, and <code>moveTo</code>, <code>lineTo</code>, <code>arcTo</code>, <code>arc</code>, and similar methods are used to add segments to the path. The path can be closed using <code>closePath</code>. Once a path is created, you can use <code>fill</code> or <code>stroke</code> to render the path to the canvas.</p>
<pre class="brush: js">
function draw() {
  var ctx = document.getElementById('canvas').getContext('2d');

  ctx.fillStyle = "red";

  ctx.beginPath();
  ctx.moveTo(30, 30);
  ctx.lineTo(150, 150);
  // was: ctx.quadraticCurveTo(60, 70, 70, 150); which is wrong.
  ctx.bezierCurveTo(60, 70, 60, 70, 70, 150); // &lt;- this is right formula for the image on the right -&gt;
  ctx.lineTo(30, 30);
  ctx.fill();
}
</pre>
<div class="hidden">
  <pre class="brush: html">
&lt;canvas id="canvas" width="160" height="160"&gt;&lt;/canvas&gt;</pre>
  <pre class="brush: js">
draw();</pre>
</div>
<p>{{ EmbedLiveSample('Using_Paths','190','190','/@api/deki/files/603/=Canvas_ex2.png') }}</p>
<p>Calling <code>fill()</code> or <code>stroke()</code> causes the current path to be used. To be filled or stroked again, the path must be recreated.</p>
<h4 id="Graphics_State" name="Graphics_State">Graphics State</h4>
<p>Attributes of the context such as <code>fillStyle</code>, <code>strokeStyle</code>, <code>lineWidth</code>, and <code>lineJoin</code> are part of the current <em>graphics state</em>. The context provides two methods, <code>save()</code> and <code>restore()</code>, that can be used to move the current state to and from the state stack.</p>
<h4 id="A_More_Complicated_Example" name="A_More_Complicated_Example">A More Complicated Example</h4>
<p>Here's a little more complicated example, that uses paths, state, and also introduces the current transformation matrix. The context methods <code>translate()</code>, <code>scale()</code>, and <code>rotate()</code> all transform the current matrix. All rendered points are first transformed by this matrix.</p>
<pre class="brush: js">
function drawBowtie(ctx, fillStyle) {
 
  ctx.fillStyle = "rgba(200,200,200,0.3)";
  ctx.fillRect(-30, -30, 60, 60);
 
  ctx.fillStyle = fillStyle;
  ctx.globalAlpha = 1.0;
  ctx.beginPath();
  ctx.moveTo(25, 25);
  ctx.lineTo(-25, -25);
  ctx.lineTo(25, -25);
  ctx.lineTo(-25, 25);
  ctx.closePath();
  ctx.fill();
}
 
function dot(ctx) {
  ctx.save();
  ctx.fillStyle = "black";
  ctx.fillRect(-2, -2, 4, 4);
  ctx.restore();
}
 
function draw() {
  var ctx = document.getElementById('canvas').getContext('2d');

  // note that all other translates are relative to this one
  ctx.translate(45, 45);

  ctx.save();
  //ctx.translate(0, 0); // unnecessary
  drawBowtie(ctx, "red");
  dot(ctx);
  ctx.restore();
 
  ctx.save();
  ctx.translate(85, 0);
  ctx.rotate(45 * Math.PI / 180);
  drawBowtie(ctx, "green");
  dot(ctx);
  ctx.restore();
 
  ctx.save();
  ctx.translate(0, 85);
  ctx.rotate(135 * Math.PI / 180);
  drawBowtie(ctx, "blue");
  dot(ctx);
  ctx.restore();
 
  ctx.save();
  ctx.translate(85, 85);
  ctx.rotate(90 * Math.PI / 180);
  drawBowtie(ctx, "yellow");
  dot(ctx);
  ctx.restore();
}
</pre>
<div class="hidden">
  <pre class="brush: html">
&lt;canvas id="canvas" width="185" height="185"&gt;&lt;/canvas&gt;</pre>
  <pre class="brush: js">
draw();</pre>
</div>
<p>{{ EmbedLiveSample('A_More_Complicated_Example','215','215','/@api/deki/files/604/=Canvas_ex3.png') }}</p>
<p>This defines two methods, <code>drawBowtie</code> and <code>dot</code>, that are called 4 times. Before each call, <code>translate()</code> and <code>rotate()</code> are used to set up the current transformation matrix, which in turn positions the dot and the bowtie. <code>dot</code> renders a small black square centered at <code>(0, 0)</code>. That dot is moved around by the transformation matrix. <code>drawBowtie</code> renders a simple bowtie path using the passed-in fill style.</p>
<p>As matrix operations are cumulative, <code>save()</code> and <code>restore()</code> are used around each set of calls to restore the original canvas state. One thing to watch out for is that rotation always occurs around the current origin; thus a <code>translate() rotate() translate()</code> sequence will yield different results than a <code>translate() translate() rotate()</code> series of calls.</p>
<h3 id="Compatibility_With_Apple_.3Ccanvas.3E" name="Compatibility_With_Apple_.3Ccanvas.3E">Compatibility With Apple &lt;canvas&gt;</h3>
<p>For the most part, <code>&lt;canvas&gt;</code> is compatible with Apple's and other implementations. There are, however, a few issues to be aware of, described here.</p>
<h4 id="Required_.3C.2Fcanvas.3E_tag" name="Required_.3C.2Fcanvas.3E_tag">Required <code>&lt;/canvas&gt;</code> tag</h4>
<p>In the Apple Safari implementation, <code>&lt;canvas&gt;</code> is an element implemented in much the same way <code>&lt;img&gt;</code> is; it does not have an end tag. However, for <code>&lt;canvas&gt;</code> to have widespread use on the web, some facility for fallback content must be provided. Therefore, Mozilla's implementation has a <em>required</em> end tag.</p>
<p>If fallback content is not needed, a simple <code>&lt;canvas id="foo" ...&gt;&lt;/canvas&gt;</code> will be fully compatible with both Safari and Mozilla -- Safari will simply ignore the end tag.</p>
<p>If fallback content is desired, some CSS tricks must be employed to mask the fallback content from Safari (which should render just the canvas), and also to mask the CSS tricks themselves from IE (which should render the fallback content). <strong>Todo: get hixie to put the CSS bits in</strong></p>
<h3 id="Additional_Features" name="Additional_Features">Additional Features</h3>
<h4 id="Rendering_Web_Content_Into_A_Canvas" name="Rendering_Web_Content_Into_A_Canvas">Rendering Web Content Into A Canvas</h4>
<div class="note">
  This feature is only available for code running with Chrome privileges. It is not allowed in normal HTML pages. <a class="external" href="http://mxr.mozilla.org/mozilla/source/content/canvas/src/nsCanvasRenderingContext2D.cpp#2352" title="http://mxr.mozilla.org/mozilla/source/content/canvas/src/nsCanvasRenderingContext2D.cpp#2352">Read why</a>.</div>
<p>Mozilla's <code>canvas</code> is extended with the <a href="/en/DOM/CanvasRenderingContext2D#drawWindow()" title="en/DOM/CanvasRenderingContext2D#drawWindow()"><code>drawWindow()</code></a> method. This method draws a snapshot of the contents of a DOM <code>window</code> into the canvas. For example,</p>
<pre class="brush: js">
ctx.drawWindow(window, 0, 0, 100, 200, "rgb(255,255,255)");
</pre>
<p>would draw the contents of the current window, in the rectangle (0,0,100,200) in pixels relative to the top-left of the viewport, on a white background, into the canvas. By specifying "rgba(255,255,255,0)" as the color, the contents would be drawn with a transparent background (which would be slower).</p>
<p>It is usually a bad idea to use any background other than pure white "rgb(255,255,255)" or transparent, as this is what all browsers do, and many websites expect that transparent parts of their interface will be drawn on white background.</p>
<p>With this method, it is possible to fill a hidden IFRAME with arbitrary content (e.g., CSS-styled HTML text, or SVG) and draw it into a canvas. It will be scaled, rotated and so on according to the current transformation.</p>
<p>Ted Mielczarek's <a class="external" href="http://ted.mielczarek.org/code/mozilla/tabpreview/">tab preview</a> extension uses this technique in chrome to provide thumbnails of web pages, and the source is available for reference.</p>
<div class="note">
  <strong>Note:</strong> Using <code>canvas.drawWindow()</code>&nbsp;while handling a document's <code>onload</code> event doesn't work.&nbsp; In Firefox 3.5 or later, you can do this in a handler for the <a class="internal" href="/en/Gecko-Specific_DOM_Events#MozAfterPaint" title="en/Gecko-Specific DOM Events#MozAfterPaint"><code>MozAfterPaint</code></a> event to successfully draw HTML content into a canvas on page load.</div>
<h3 id="See_also" name="See_also">See also</h3>
<ul>
  <li><a href="/en/HTML/Canvas" title="en/HTML/Canvas">Canvas topic page</a></li>
  <li><a href="/en/Canvas_tutorial" title="en/Canvas_tutorial">Canvas tutorial</a></li>
  <li><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#the-canvas">WHATWG specification</a></li>
  <li><a class="external" href="http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSProgTopics/Tasks/Canvas.html" title="http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSProgTopics/Tasks/Canvas.html">Apple Canvas Documentation</a></li>
  <li><a class="external" href="http://weblogs.mozillazine.org/roc/archives/2005/05/rendering_web_p.html">Rendering Web Page Thumbnails</a></li>
  <li>Some <a href="/Special:Tags" title="Site Tags">examples</a>:
    <ul>
      <li><a class="external" href="http://azarask.in/projects/algorithm-ink">Algorithm Ink</a></li>
      <li><a class="external" href="http://www.tapper-ware.net/canvas3d/">OBJ format 3D Renderer</a></li>
      <li><a href="/en/A_Basic_RayCaster" title="en/A_Basic_RayCaster">A Basic RayCaster</a></li>
      <li><a class="external" href="http://awordlike.textdriven.com/">The Lightweight Visual Thesaurus</a></li>
      <li><a class="external" href="http://caimansys.com/painter/">Canvas Painter</a></li>
    </ul>
  </li>
  <li><a href="/Special:Tags" title="Site Tags">And more...</a></li>
</ul>
Revert to this revision