mozilla

Revision 18423 of CanvasRenderingContext2D

  • Revision slug: DOM/CanvasRenderingContext2D
  • Revision title: CanvasRenderingContext2D
  • Revision id: 18423
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment lots of CSS bugs fixed in Gecko 5.0!; 287 words added

Revision Content

The bulk of the operations available at present with {{ HTMLElement("canvas") }} are available through this interface, returned by a call to getContext on the {{ HTMLElement("canvas") }} element, with "2d" as its argument.

Note: This page needs to be turned into a properly-formatted, thorough reference, and the notes at the bottom of the page moved into the docs for the corresponding methods and attributes.

Attributes

  // back-reference to the canvas
  readonly HTMLCanvasElement canvas

  // compositing
  float globalAlpha // (default 1.0)
  DOMString globalCompositeOperation // default source-over

  // colors and styles
  any strokeStyle // default black
  any fillStyle // default black
  // line caps/joins
  float lineWidth // default 1
  DOMString lineCap // "butt", "round", "square" (default "butt")
  DOMString lineJoin // "round", "bevel", "miter" (default "miter")
  float miterLimit // default 10

  // shadows
  float shadowOffsetX // default 0
  float shadowOffsetY // default 0
  float shadowBlur // default 0
  DOMString shadowColor // default transparent black
  // text
  DOMString font // default 10px sans-serif
  DOMString textAlign // "start", "end", "left", "right", "center" (default: "start")
  DOMString textBaseline -"top", "hanging", "middle", "alphabetic", "ideographic", "bottom" (default: "alphabetic")

Methods

  // state
  void save() // push state on state stack
  void restore() // pop state stack and restore state

  // transformations (default transform is the identity matrix)
  void scale(in float x, in float y);
  void rotate(in float angle);
  void translate(in float x, in float y);
  void transform(in float m11, in float m12, in float m21, in float m22, in float dx, in float dy);
  void setTransform(in float m11, in float m12, in float m21, in float m22, in float dx, in float dy);
  // colors and styles
  CanvasGradient createLinearGradient(in float x0, in float y0, in float x1, in float y1);
  CanvasGradient createRadialGradient(in float x0, in float y0, in float r0, in float x1, in float y1, in float r1);
  CanvasPattern createPattern(in HTMLImageElement image, in DOMString repetition);
  CanvasPattern createPattern(in HTMLCanvasElement image, in DOMString repetition);
  CanvasPattern createPattern(in HTMLVideoElement image, in DOMString repetition);

  // rects
  void clearRect(in float x, in float y, in float w, in float h);
  void fillRect(in float x, in float y, in float w, in float h);
  void strokeRect(in float x, in float y, in float w, in float h);

  // path API
  void beginPath();
  void closePath();
  void moveTo(in float x, in float y);
  void lineTo(in float x, in float y);
  void quadraticCurveTo(in float cpx, in float cpy, in float x, in float y);
  void bezierCurveTo(in float cp1x, in float cp1y, in float cp2x, in float cp2y, in float x, in float y);
  void arcTo(in float x1, in float y1, in float x2, in float y2, in float radius);
  void rect(in float x, in float y, in float w, in float h);
  void arc(in float x, in float y, in float radius, in float startAngle, in float endAngle, in boolean anticlockwise);
  void fill();
  void stroke();
  void clip();
  boolean isPointInPath(in float x, in float y);

  // focus management
  boolean drawFocusRing(in Element element, in float xCaret, in float yCaret, in optional boolean canDrawCustom) -Unimplemented
  // text
  void fillText(in DOMString text, in float x, in float y, in optional float maxWidth);
  void strokeText(in DOMString text, in float x, in float y, in optional float maxWidth);
  TextMetrics measureText(in DOMString text);

  // drawing images
  void drawImage(in HTMLImageElement image, in float dx, in float dy, in optional float dw, in float dh);
  void drawImage(in HTMLImageElement image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh);
  void drawImage(in HTMLCanvasElement image, in float dx, in float dy, in optional float dw, in float dh);
  void drawImage(in HTMLCanvasElement image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh);
  void drawImage(in HTMLVideoElement image, in float dx, in float dy, in optional float dw, in float dh);
  void drawImage(in HTMLVideoElement image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh);

  // pixel manipulation
  ImageData createImageData(in float sw, in float sh);
  ImageData createImageData(in ImageData imagedata);
  ImageData getImageData(in float sx, in float sy, in float sw, in float sh);
  void putImageData(in ImageData imagedata, in float dx, in float dy, in optional float dirtyX, in float dirtyY, in float dirtyWidth, in float dirtyHeight);

Notes

{{ gecko_callout_heading("2.0") }}

Starting in Gecko 2.0 {{ geckoRelease("2.0") }}, the following corrections were made to various behaviors, in order to improve compliance with the HTML5 specification:

  • Specifying a negative radius when calling arc() now correctly throws an INDEX_SIZE_ERR exception.
  • Specifying non-finite values when calling createLinearGradient() and createRadialGradient() now throws NOT_SUPPORTED_ERR instead of SYNTAX_ERR.
  • Setting miterLimit to a negative value no longer throws an exception; instead, it properly ignores non-positive values.
  • Setting lineWidth to a negative value no longer throws an exception; instead, it properly ignores non-positive values.

{{ gecko_callout_heading("5.0") }}

Starting in Gecko 5.0 {{ geckoRelease("5.0") }}, the following corrections were made to various behaviors, in order to improve compliance with the HTML5 specification:

  • getImageData() now correctly accepts rectangles that extend beyond the bounds of the canvas; pixels outside the canvas are returned as transparent black.
  • drawImage() and createImageData() now handle negative arguments in accordance with the specification, by flipping the rectangle around the appropriate axis. We need an article about CSS sizing and how this works.
  • Specifying non-finite values when calling createImageData() now properly throws a NOT_SUPPORTED_ERR exception.
  • createImageData() and getImageData() now correctly return at least one pixel's worth of image data if a rectangle smaller than one pixel is specified.
  • Specifying a negative radius when calling createRadialGradient() now correctly throws INDEX_SIZE_ERR.
  • Specifying a null or undefined image when calling createPattern() or drawImage() now correctly throws a TYPE_MISMATCH_ERR exception.
  • Specifying invalid values for globalAlpha no longer throws a SYNTAX_ERR exception; these are now correctly silently ignored.
  • Specifying invalid values when calling translate(), transform(), rect(), clearRect(), fillRect(), strokeRect(), lineTo(), moveTo(), quadraticCurveTo(), or arc() no longer throws an exception; these calls are now correctly silently ignored.
  • Setting the value of shadowOffsetX, shadowOffsetY, or shadowBlur to an invalid value is now silently ignored.
  • Setting the value of rotate or scale to an invalid value is now silently ignored.

Specification

Revision Source

<p>The bulk of the operations available at present with {{ HTMLElement("canvas") }} are available through this interface, returned by a call to <code>getContext</code> on the {{ HTMLElement("canvas") }} element, with "2d" as its argument.</p>
<div class="note"><strong>Note:</strong> This page needs to be turned into a properly-formatted, thorough reference, and the notes at the bottom of the page moved into the docs for the corresponding methods and attributes.</div>
<h2>Attributes</h2>
<pre style="white-space:pre-wrap;">  // back-reference to the canvas
  readonly <a href="mks://localhost/en/HTML/Element/canvas" title="en/DOM/HTMLCanvasElement">HTMLCanvasElement</a> <strong>canvas</strong>

  // compositing
  float <strong>globalAlpha</strong> // (default 1.0)
  DOMString <strong>globalCompositeOperation</strong> // default source-over

  // colors and styles
  any <strong>strokeStyle</strong> // default black
  any <strong>fillStyle</strong> // default black
  // line caps/joins
  float <strong>lineWidth</strong> // default 1
  DOMString <strong>lineCap</strong> // "butt", "round", "square" (default "butt")
  DOMString <strong>lineJoin</strong> // "round", "bevel", "miter" (default "miter")
  float <strong>miterLimit</strong> // default 10

  // shadows
  float <strong>shadowOffsetX</strong> // default 0
  float <strong>shadowOffsetY</strong> // default 0
  float <strong>shadowBlur</strong> // default 0
  DOMString <strong>shadowColor</strong> // default transparent black
  // text
  DOMString <strong>font</strong> // default 10px sans-serif
  DOMString <strong>textAlign</strong> // "start", "end", "left", "right", "center" (default: "start")
  DOMString <strong>textBaseline</strong> -"top", "hanging", "middle", "alphabetic", "ideographic", "bottom" (default: "alphabetic")
</pre>
<h2>Methods</h2>
<pre style="white-space:pre-wrap;">  // state
  void <strong>save</strong>() // push state on state stack
  void <strong>restore</strong>() // pop state stack and restore state

  // transformations (default transform is the identity matrix)
  void <strong>scale</strong>(in float x, in float y);
  void <strong>rotate</strong>(in float angle);
  void <strong>translate</strong>(in float x, in float y);
  void <strong>transform</strong>(in float m11, in float m12, in float m21, in float m22, in float dx, in float dy);
  void <strong>setTransform</strong>(in float m11, in float m12, in float m21, in float m22, in float dx, in float dy);
  // colors and styles
  <a href="mks://localhost/en/DOM/CanvasGradient" title="en/DOM/CanvasGradient">CanvasGradient</a> <strong>createLinearGradient</strong>(in float x0, in float y0, in float x1, in float y1);
  <a href="mks://localhost/en/DOM/CanvasGradient" title="en/DOM/CanvasGradient">CanvasGradient</a> <strong>createRadialGradient</strong>(in float x0, in float y0, in float r0, in float x1, in float y1, in float r1);
  <a href="mks://localhost/en/DOM/CanvasPattern" title="en/DOM/CanvasPattern">CanvasPattern</a> <strong>createPattern</strong>(in <a href="mks://localhost/en/DOM/HTMLImageElement" title="en/DOM/HTMLImageElement">HTMLImageElement</a> image, in DOMString repetition);
  <a href="mks://localhost/en/DOM/CanvasPattern" title="en/DOM/CanvasPattern">CanvasPattern</a> <strong>createPattern</strong>(in <a href="mks://localhost/en/HTML/Element/canvas" title="en/DOM/HTMLCanvasElement">HTMLCanvasElement</a> image, in DOMString repetition);
  <a href="mks://localhost/en/DOM/CanvasPattern" title="en/DOM/CanvasPattern">CanvasPattern</a> <strong>createPattern</strong>(in <a href="mks://localhost/en/DOM/HTMLVideoElement" title="en/DOM/HTMLVideoElement">HTMLVideoElement</a> image, in DOMString repetition);

  // rects
  void <strong>clearRect</strong>(in float x, in float y, in float w, in float h);
  void <strong>fillRect</strong>(in float x, in float y, in float w, in float h);
  void <strong>strokeRect</strong>(in float x, in float y, in float w, in float h);

  // path API
  void <strong>beginPath</strong>();
  void <strong>closePath</strong>();
  void <strong>moveTo</strong>(in float x, in float y);
  void <strong>lineTo</strong>(in float x, in float y);
  void <strong>quadraticCurveTo</strong>(in float cpx, in float cpy, in float x, in float y);
  void <strong>bezierCurveTo</strong>(in float cp1x, in float cp1y, in float cp2x, in float cp2y, in float x, in float y);
  void <strong>arcTo</strong>(in float x1, in float y1, in float x2, in float y2, in float radius);
  void <strong>rect</strong>(in float x, in float y, in float w, in float h);
  void <strong>arc</strong>(in float x, in float y, in float radius, in float startAngle, in float endAngle, in boolean anticlockwise);
  void <strong>fill</strong>();
  void <strong>stroke</strong>();
  void <strong>clip</strong>();
  boolean <strong>isPointInPath</strong>(in float x, in float y);

  // focus management
  boolean <strong>drawFocusRing</strong>(in Element element, in float xCaret, in float yCaret, in optional boolean canDrawCustom) -<span class="lang lang-en"><span style="border: 1px solid rgb(255, 205, 154); background-color: rgb(255, 153, 204); font-size: x-small; white-space: nowrap; padding: 2px;">Unimplemented</span></span>
  // text
  void <strong>fillText</strong>(in DOMString text, in float x, in float y, in optional float maxWidth);
  void <strong>strokeText</strong>(in DOMString text, in float x, in float y, in optional float maxWidth);
  <a href="mks://localhost/en/DOM/TextMetrics" title="en/DOM/TextMetrics">TextMetrics</a> <strong>measureText</strong>(in DOMString text);

  // drawing images
  void <strong>drawImage</strong>(in <a href="mks://localhost/en/DOM/HTMLImageElement" title="en/DOM/HTMLImageElement">HTMLImageElement</a> image, in float dx, in float dy, in optional float dw, in float dh);
  void <strong>drawImage</strong>(in <a href="mks://localhost/en/DOM/HTMLImageElement" title="en/DOM/HTMLImageElement">HTMLImageElement</a> image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh);
  void <strong>drawImage</strong>(in <a href="mks://localhost/en/HTML/Element/canvas" title="en/DOM/HTMLCanvasElement">HTMLCanvasElement</a> image, in float dx, in float dy, in optional float dw, in float dh);
  void <strong>drawImage</strong>(in <a href="mks://localhost/en/HTML/Element/canvas" title="en/DOM/HTMLCanvasElement">HTMLCanvasElement</a> image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh);
  void <strong>drawImage</strong>(in <a href="mks://localhost/en/DOM/HTMLVideoElement" title="en/DOM/HTMLVideoElement">HTMLVideoElement</a> image, in float dx, in float dy, in optional float dw, in float dh);
  void <strong>drawImage</strong>(in <a href="mks://localhost/en/DOM/HTMLVideoElement" title="en/DOM/HTMLVideoElement">HTMLVideoElement</a> image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh);

  // pixel manipulation
  <a href="mks://localhost/en/DOM/ImageData" title="en/DOM/ImageData">ImageData</a> <strong>createImageData</strong>(in float sw, in float sh);
  <a href="mks://localhost/en/DOM/ImageData" title="en/DOM/ImageData">ImageData</a> <strong>createImageData</strong>(in <a href="mks://localhost/en/DOM/ImageData" title="en/DOM/ImageData">ImageData</a> imagedata);
  <a href="mks://localhost/en/DOM/ImageData" title="en/DOM/ImageData">ImageData</a> <strong>getImageData</strong>(in float sx, in float sy, in float sw, in float sh);
  void <strong>putImageData</strong>(in <a href="mks://localhost/en/DOM/ImageData" title="en/DOM/ImageData">ImageData</a> imagedata, in float dx, in float dy, in optional float dirtyX, in float dirtyY, in float dirtyWidth, in float dirtyHeight);
</pre>
<h2>Notes</h2>
<div class="geckoVersionNote">
<p>{{ gecko_callout_heading("2.0") }}</p>
<p>Starting in Gecko 2.0 {{ geckoRelease("2.0") }}, the following corrections were made to various behaviors, in order to improve compliance with the HTML5 specification:</p>
<ul> <li>Specifying a negative radius when calling <code>arc()</code> now correctly throws an <code>INDEX_SIZE_ERR</code> exception.</li> <li>Specifying non-finite values when calling <code>createLinearGradient()</code> and <code>createRadialGradient()</code> now throws <code>NOT_SUPPORTED_ERR</code> instead of <code>SYNTAX_ERR</code>.</li> <li>Setting <code>miterLimit</code> to a negative value no longer throws an exception; instead, it properly ignores non-positive values.</li> <li>Setting <code>lineWidth</code> to a negative value no longer throws an exception; instead, it properly ignores non-positive values.</li>
</ul>
</div>
<div class="geckoVersionNote">
<p>{{ gecko_callout_heading("5.0") }}</p>
<p>Starting in Gecko 5.0 {{ geckoRelease("5.0") }}, the following corrections were made to various behaviors, in order to improve compliance with the HTML5 specification:</p>
<ul> <li><code>getImageData()</code> now correctly accepts rectangles that extend beyond the bounds of the canvas; pixels outside the canvas are returned as transparent black.</li> <li><code>drawImage()</code> and <code>createImageData()</code> now handle negative arguments in accordance with the specification, by flipping the rectangle around the appropriate axis. <strong>We need an article about <a class=" external" href="http://dev.w3.org/csswg/css3-images/#default-sizing" title="http://dev.w3.org/csswg/css3-images/#default-sizing">CSS sizing</a> and how this works.</strong></li> <li>Specifying non-finite values when calling <code>createImageData()</code> now properly throws a <code>NOT_SUPPORTED_ERR</code> exception.</li> <li><code>createImageData()</code> and <code>getImageData()</code> now correctly return at least one pixel's worth of image data if a rectangle smaller than one pixel is specified.</li> <li>Specifying a negative radius when calling <code>createRadialGradient()</code> now correctly throws <code>INDEX_SIZE_ERR</code>.</li> <li>Specifying a <code>null</code> or <code>undefined</code> image when calling <code>createPattern()</code> or <code>drawImage()</code> now correctly throws a <code>TYPE_MISMATCH_ERR</code> exception.</li> <li>Specifying invalid values for <code>globalAlpha</code> no longer throws a <code>SYNTAX_ERR</code> exception; these are now correctly silently ignored.</li> <li>Specifying invalid values when calling <code>translate()</code>, <code>transform()</code>, <code>rect()</code>, <code>clearRect()</code>, <code>fillRect()</code>, <code>strokeRect()</code>, <code>lineTo()</code>, <code>moveTo()</code>, <code>quadraticCurveTo()</code>, or <code>arc()</code> no longer throws an exception; these calls are now correctly silently ignored.</li> <li>Setting the value of <code>shadowOffsetX</code>, <code>shadowOffsetY</code>, or <code>shadowBlur</code> to an invalid value is now silently ignored.</li> <li>Setting the value of <code>rotate</code> or <code>scale</code> to an invalid value is now silently ignored.</li>
</ul>
</div>
<h2>Specification</h2>
<ul> <li><a class=" external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#canvasrenderingcontext2d" rel="freelink">http://www.whatwg.org/specs/web-apps...eringcontext2d</a></li>
</ul>
Revert to this revision