CanvasRenderingContext2D

  • Revision slug: DOM/CanvasRenderingContext2D
  • Revision title: CanvasRenderingContext2D
  • Revision id: 18422
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 154 words added, 2 words removed

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:

  • 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.

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:</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>
<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