Mirrors/servo
1
0
Fork 0
mirror of https://github.com/servo/servo.git synced 2025-07-01 04:23:39 +01:00
Code Issues Projects Releases Packages Wiki Activity
servo/tests/wpt/web-platform-tests/2dcontext/tools/current-work-canvas.xhtml

4578 lines
No EOL
456 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8"?><html class="split" lang="en-US-x-hixie" xmlns="http://www.w3.org/1999/xhtml"><head><meta charset="utf-8"/><meta content="width=device-width, initial-scale=1, shrink-to-fit=no" name="viewport"/><title>HTML Standard</title><meta content="#3c790a" name="theme-color"/><link href="https://resources.whatwg.org/standard.css" rel="stylesheet"/><link href="https://resources.whatwg.org/logo.svg" rel="icon"/><style>
.status { min-height: 0.6em; font: 1em sans-serif; width: 9em; padding: 0.3em; position: absolute; z-index: 8; right: 0.3em; background: #EEE; color: black; box-shadow: 0 0 3px #999; overflow: hidden; margin: -2em 0 0 0; border-collapse: initial; border-spacing: initial; }
.status:hover { z-index: 9; }
.status:focus-within { z-index: 9; }
.status.wrapped &gt; :not(input) { display: none; }
.status &gt; input { position: absolute; left: 0; top: 0; width: 1em; height: 1em; border: none; background: transparent; padding: 0; margin: 0; }
.status &gt; p { font-size: 0.6em; margin: 0; padding: 0; }
.status &gt; p + p { padding-top: 0.5em; }
.status &gt; p &gt; strong { margin-left: 1.5em; }
.status &gt; .support { display: block; }
.status &gt; .support &gt; span { padding: 0.2em 0; display: block; display: table; }
.status &gt; .support &gt; span.partial { color: #666666; filter: grayscale(50%); }
.status &gt; .support &gt; span.no { color: #CCCCCC; filter: grayscale(100%); }
.status &gt; .support &gt; span.no::before { opacity: 0.5; }
.status &gt; .support &gt; span:first-of-type { padding-top: 0.5em; }
.status &gt; .support &gt; span &gt; span { padding: 0 0.5em; display: table-cell; vertical-align: top; }
.status &gt; .support &gt; span &gt; span:first-child { width: 100%; }
.status &gt; .support &gt; span &gt; span:last-child { width: 100%; white-space: pre; padding: 0; }
.status &gt; .support &gt; span::before { content: ' '; display: table-cell; min-width: 1.5em; height: 1.5em; background: no-repeat center center; background-size: contain; text-align: right; font-size: 0.75em; font-weight: bold; }
.status &gt; .support &gt; .and_chr::before { background-image: url(https://resources.whatwg.org/browser-logos/chrome.svg); }
.status &gt; .support &gt; .and_ff::before { background-image: url(https://resources.whatwg.org/browser-logos/firefox.png); }
.status &gt; .support &gt; .and_uc::before { background-image: url(https://resources.whatwg.org/browser-logos/uc.png); } /* UC Browser for Android */
.status &gt; .support &gt; .android::before { background-image: url(https://resources.whatwg.org/browser-logos/android.svg); }
.status &gt; .support &gt; .bb::before { background-image: url(https://resources.whatwg.org/browser-logos/bb.jpg); } /* Blackberry Browser */
.status &gt; .support &gt; .chrome::before { background-image: url(https://resources.whatwg.org/browser-logos/chrome.svg); }
.status &gt; .support &gt; .edge::before { background-image: url(https://resources.whatwg.org/browser-logos/edge.svg); }
.status &gt; .support &gt; .firefox::before { background-image: url(https://resources.whatwg.org/browser-logos/firefox.png); }
.status &gt; .support &gt; .ie::before { background-image: url(https://resources.whatwg.org/browser-logos/ie.png); }
.status &gt; .support &gt; .ie_mob::before { background-image: url(https://resources.whatwg.org/browser-logos/ie-mobile.svg); }
.status &gt; .support &gt; .ios_saf::before { background-image: url(https://resources.whatwg.org/browser-logos/safari-ios.svg); }
.status &gt; .support &gt; .op_mini::before { background-image: url(https://resources.whatwg.org/browser-logos/opera-mini.png); }
.status &gt; .support &gt; .op_mob::before { background-image: url(https://resources.whatwg.org/browser-logos/opera.png); }
.status &gt; .support &gt; .opera::before { background-image: url(https://resources.whatwg.org/browser-logos/opera.png); }
.status &gt; .support &gt; .safari::before { background-image: url(https://resources.whatwg.org/browser-logos/safari.png); }
.status &gt; .support &gt; .samsung::before { background-image: url(https://resources.whatwg.org/browser-logos/samsung.png); }
.status &gt; .caniuse { text-align: right; font-style: italic; width: 100%; }
.status &gt; .caniuse + p { margin-top: 0.5em; border-top: 1px solid silver; }
@media (max-width: 767px) {
.status { right: -9em; }
}
</style><style>
[hidden] { display: none; }
.bad, .bad *:not(.X\58X) { color: gray; border-color: gray; background: transparent; }
.fingerprint { position: absolute; right: 0; z-index: 5; }
@media (max-width: 767px) {
.fingerprint { max-width: 35px; }
}
.applies .yes, .yesno .yes { background: yellow; }
.yesno .yes, .yesno .no { text-align: center; }
.applies thead th &gt; * { display: block; }
.applies thead code { display: block; }
.applies td { text-align: center; }
.matrix, .matrix td { border: hidden; text-align: right; }
.matrix { margin-left: 2em; }
.vertical-summary-table tr &gt; th[rowspan=&quot;2&quot;]:first-child + th,
.vertical-summary-table tr &gt; td[rowspan=&quot;2&quot;]:first-child + td { border-bottom: hidden; }
.dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
.dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
.dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
td.eg { border-width: thin; text-align: center; }
#table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
#table-example-1 caption { padding-bottom: 0.5em; }
#table-example-1 thead, #table-example-1 tbody { border: none; }
#table-example-1 th, #table-example-1 td { border: solid thin; }
#table-example-1 th { font-weight: normal; }
#table-example-1 td { border-style: none solid; vertical-align: top; }
#table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
#table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
#table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
#table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
#table-example-1 tbody td:first-child::after { content: leader(&quot;. &quot;); }
#table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
#table-example-1 tbody td:first-child + td { width: 10em; }
#table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
#table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
.apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
.apple-table-examples * { font-family: &quot;Times&quot;, serif; }
.apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
.apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
.apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
.apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(&quot;. &quot;) }
.apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
.apple-table-examples td { text-align: right; vertical-align: top; }
.apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
.apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
.apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
.apple-table-examples sup { line-height: 0; }
.three-column-nowrap tr &gt; td:first-child,
.three-column-nowrap tr &gt; td:first-child + td,
.three-column-nowrap tr &gt; td:first-child + td + td { white-space: nowrap; }
.details-example img { vertical-align: top; }
.parse-error-table td &gt; p:first-child { margin-top: 0; }
#named-character-references-table {
white-space: nowrap;
font-size: 0.6em;
column-width: 30em;
column-gap: 1em;
-moz-column-width: 30em;
-moz-column-gap: 1em;
-webkit-column-width: 30em;
-webkit-column-gap: 1em;
}
#named-character-references-table &gt; table &gt; tbody &gt; tr &gt; td:first-child + td,
#named-character-references-table &gt; table &gt; tbody &gt; tr &gt; td:last-child { text-align: center; }
#named-character-references-table &gt; table &gt; tbody &gt; tr &gt; td:last-child:hover &gt; span { position: absolute; top: auto; left: auto; margin-left: 0.5em; line-height: 1.2; font-size: 5em; border: outset; padding: 0.25em 0.5em; background: white; width: 1.25em; height: auto; text-align: center; }
#named-character-references-table &gt; table &gt; tbody &gt; tr#entity-CounterClockwiseContourIntegral &gt; td:first-child { font-size: 0.5em; }
.glyph.control { color: red; }
#table-example-1 * { font-family: &quot;Essays1743&quot;, serif; line-height: 1.01em; }
@font-face {
font-family: 'Essays1743';
src: url('/fonts/Essays1743.ttf');
}
@font-face {
font-family: 'Essays1743';
font-weight: bold;
src: url('/fonts/Essays1743-Bold.ttf');
}
@font-face {
font-family: 'Essays1743';
font-style: italic;
src: url('/fonts/Essays1743-Italic.ttf');
}
@font-face {
font-family: 'Essays1743';
font-style: italic;
font-weight: bold;
src: url('/fonts/Essays1743-BoldItalic.ttf');
}
@media (max-width: 767px) {
#abstractimg { width: 100%; }
}
#abstractimg, #abstractimg text { font: inherit; }
#abstractimg rect { fill: #424242; }
#abstractimg text { fill: #ffffff; font-size: 18px }
#abstractimg .top { word-spacing: 50px; text-anchor: middle; }
#abstractimg .left, #abstractimg .bottom { word-spacing: 12px; }
#abstractimg .right { font-size: 25px; }
</style></head><body><header class="head with-buttons" id="head">
<a class="logo" href="https://whatwg.org/"><img alt="WHATWG" height="100" src="https://resources.whatwg.org/logo.svg" width="100"/></a>
<hgroup><h1 class="allcaps">HTML</h1><h2 class="no-num no-toc" id="living-standard">Living Standard — Last Updated <span class="pubdate">31 August 2017</span></h2></hgroup>
<p class="copyright">Parts of this specification are © Copyright 2004-2014 Apple Inc., Mozilla Foundation, and Opera Software ASA. You are granted a license to use, reproduce and create derivative works of this document.</p></header><h4 id="the-canvas-element"><span class="secno">4.12.5</span> The <dfn id="canvas"><code>canvas</code></dfn> element<a class="self-link" href="#the-canvas-element"/></h4><div class="status"><input onclick="toggleStatus(this)" type="button" value="⋰"/><p class="support"><strong>Support:</strong> canvas<span class="and_chr yes"><span>Chrome for Android</span> <span>59+</span></span><span class="chrome yes"><span>Chrome</span> <span>4+</span></span><span class="and_uc yes"><span>UC Browser for Android</span> <span>11.4+</span></span><span class="ios_saf yes"><span>iOS Safari</span> <span>3.2+</span></span><span class="firefox yes"><span>Firefox</span> <span>3.6+</span></span><span class="ie yes"><span>IE</span> <span>9+</span></span><span class="samsung yes"><span>Samsung Internet</span> <span>4+</span></span><span class="op_mini partial"><span>Opera Mini (limited)</span> <span>all+</span></span><span class="safari yes"><span>Safari</span> <span>4+</span></span><span class="android yes"><span>Android Browser</span> <span>3+</span></span><span class="opera yes"><span>Opera</span> <span>9+</span></span><span class="edge yes"><span>Edge</span> <span>12+</span></span></p><p class="caniuse">Source: <a href="https://caniuse.com/#feat=canvas">caniuse.com</a></p></div>
<dl class="element"><dt><a href="https://html.spec.whatwg.org/multipage/dom.html#concept-element-categories" id="the-canvas-element:concept-element-categories">Categories</a>:</dt><dd><a href="https://html.spec.whatwg.org/multipage/dom.html#flow-content-2" id="the-canvas-element:flow-content-2">Flow content</a>.</dd><dd><a href="https://html.spec.whatwg.org/multipage/dom.html#phrasing-content-2" id="the-canvas-element:phrasing-content-2">Phrasing content</a>.</dd><dd><a href="https://html.spec.whatwg.org/multipage/dom.html#embedded-content-category" id="the-canvas-element:embedded-content-category">Embedded content</a>.</dd><dd><a href="https://html.spec.whatwg.org/multipage/dom.html#palpable-content-2" id="the-canvas-element:palpable-content-2">Palpable content</a>.</dd><dt><a href="https://html.spec.whatwg.org/multipage/dom.html#concept-element-contexts" id="the-canvas-element:concept-element-contexts">Contexts in which this element can be used</a>:</dt><dd>Where <a href="https://html.spec.whatwg.org/multipage/dom.html#embedded-content-category" id="the-canvas-element:embedded-content-category-2">embedded content</a> is expected.</dd><dt><a href="https://html.spec.whatwg.org/multipage/dom.html#concept-element-content-model" id="the-canvas-element:concept-element-content-model">Content model</a>:</dt><dd><a href="https://html.spec.whatwg.org/multipage/dom.html#transparent" id="the-canvas-element:transparent">Transparent</a>, but with no <a href="https://html.spec.whatwg.org/multipage/dom.html#interactive-content-2" id="the-canvas-element:interactive-content-2">interactive content</a> descendants except
for <code id="the-canvas-element:the-a-element"><a href="https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element">a</a></code> elements, <code id="the-canvas-element:the-img-element"><a href="https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element">img</a></code> elements with
<code id="the-canvas-element:attr-hyperlink-usemap"><a href="https://html.spec.whatwg.org/multipage/image-maps.html#attr-hyperlink-usemap">usemap</a></code> attributes, <code id="the-canvas-element:the-button-element"><a href="https://html.spec.whatwg.org/multipage/form-elements.html#the-button-element">button</a></code> elements,
<code id="the-canvas-element:the-input-element"><a href="https://html.spec.whatwg.org/multipage/input.html#the-input-element">input</a></code> elements whose <code id="the-canvas-element:attr-input-type"><a href="https://html.spec.whatwg.org/multipage/input.html#attr-input-type">type</a></code> attribute are in
the <a href="https://html.spec.whatwg.org/multipage/input.html#checkbox-state-(type=checkbox)" id="the-canvas-element:checkbox-state-(type=checkbox)">Checkbox</a> or <a href="https://html.spec.whatwg.org/multipage/input.html#radio-button-state-(type=radio)" id="the-canvas-element:radio-button-state-(type=radio)">Radio Button</a> states, <code id="the-canvas-element:the-input-element-2"><a href="https://html.spec.whatwg.org/multipage/input.html#the-input-element">input</a></code> elements that are
<a href="https://html.spec.whatwg.org/multipage/forms.html#concept-button" id="the-canvas-element:concept-button">buttons</a>, <code id="the-canvas-element:the-select-element"><a href="https://html.spec.whatwg.org/multipage/form-elements.html#the-select-element">select</a></code> elements with a <code id="the-canvas-element:attr-select-multiple"><a href="https://html.spec.whatwg.org/multipage/form-elements.html#attr-select-multiple">multiple</a></code> attribute or a <a href="https://html.spec.whatwg.org/multipage/form-elements.html#concept-select-size" id="the-canvas-element:concept-select-size">display size</a> greater than 1, and elements that would not be
<a href="https://html.spec.whatwg.org/multipage/dom.html#interactive-content-2" id="the-canvas-element:interactive-content-2-2">interactive content</a> except for having the <code id="the-canvas-element:attr-tabindex"><a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-tabindex">tabindex</a></code> attribute specified.</dd><dt><a href="https://html.spec.whatwg.org/multipage/dom.html#concept-element-tag-omission" id="the-canvas-element:concept-element-tag-omission">Tag omission in text/html</a>:</dt><dd>Neither tag is omissible.</dd><dt><a href="https://html.spec.whatwg.org/multipage/dom.html#concept-element-attributes" id="the-canvas-element:concept-element-attributes">Content attributes</a>:</dt><dd><a href="https://html.spec.whatwg.org/multipage/dom.html#global-attributes" id="the-canvas-element:global-attributes">Global attributes</a></dd><dd><code id="the-canvas-element:attr-canvas-width"><a href="#attr-canvas-width">width</a></code> — Horizontal dimension</dd><dd><code id="the-canvas-element:attr-canvas-height"><a href="#attr-canvas-height">height</a></code> — Vertical dimension</dd><dt><a href="https://html.spec.whatwg.org/multipage/dom.html#concept-element-dom" id="the-canvas-element:concept-element-dom">DOM interface</a>:</dt><dd>
<pre class="idl">typedef (<a href="#canvasrenderingcontext2d" id="the-canvas-element:canvasrenderingcontext2d">CanvasRenderingContext2D</a> or <a data-x-internal="webglrenderingcontext" href="https://www.khronos.org/registry/webgl/specs/latest/1.0/#WebGLRenderingContext" id="the-canvas-element:webglrenderingcontext">WebGLRenderingContext</a>) <dfn id="renderingcontext">RenderingContext</dfn>;
[Exposed=Window,
<a href="https://html.spec.whatwg.org/multipage/dom.html#htmlconstructor" id="the-canvas-element:htmlconstructor">HTMLConstructor</a>]
interface <dfn id="htmlcanvaselement">HTMLCanvasElement</dfn> : <a href="https://html.spec.whatwg.org/multipage/dom.html#htmlelement" id="the-canvas-element:htmlelement">HTMLElement</a> {
[<a href="https://html.spec.whatwg.org/multipage/custom-elements.html#cereactions" id="the-canvas-element:cereactions">CEReactions</a>] attribute unsigned long <a href="#dom-canvas-width" id="the-canvas-element:dom-canvas-width">width</a>;
[<a href="https://html.spec.whatwg.org/multipage/custom-elements.html#cereactions" id="the-canvas-element:cereactions-2">CEReactions</a>] attribute unsigned long <a href="#dom-canvas-height" id="the-canvas-element:dom-canvas-height">height</a>;
<a href="#renderingcontext" id="the-canvas-element:renderingcontext">RenderingContext</a>? <a href="#dom-canvas-getcontext-2" id="the-canvas-element:dom-canvas-getcontext-2">getContext</a>(DOMString contextId, any... arguments);
USVString <a href="#dom-canvas-todataurl-2" id="the-canvas-element:dom-canvas-todataurl-2">toDataURL</a>(optional DOMString type, optional any quality);
void <a href="#dom-canvas-toblob-2" id="the-canvas-element:dom-canvas-toblob-2">toBlob</a>(<a href="#blobcallback" id="the-canvas-element:blobcallback">BlobCallback</a> _callback, optional DOMString type, optional any quality);
<a href="#offscreencanvas" id="the-canvas-element:offscreencanvas">OffscreenCanvas</a> <a href="#dom-canvas-transfercontroltooffscreen-2" id="the-canvas-element:dom-canvas-transfercontroltooffscreen-2">transferControlToOffscreen</a>();
};
callback <dfn id="blobcallback">BlobCallback</dfn> = void (<a data-x-internal="blob" href="https://w3c.github.io/FileAPI/#blob" id="the-canvas-element:blob">Blob</a>? blob);</pre>
</dd></dl>
<p>The <code id="the-canvas-element:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element provides scripts with a resolution-dependent bitmap canvas,
which can be used for rendering graphs, game graphics, art, or other visual images on the fly.</p>
<p>Authors should not use the <code id="the-canvas-element:the-canvas-element-2"><a href="#the-canvas-element">canvas</a></code> element in a document when a more suitable
element is available. For example, it is inappropriate to use a <code id="the-canvas-element:the-canvas-element-3"><a href="#the-canvas-element">canvas</a></code> element to
render a page heading: if the desired presentation of the heading is graphically intense, it
should be marked up using appropriate elements (typically <code id="the-canvas-element:the-h1,-h2,-h3,-h4,-h5,-and-h6-elements"><a href="https://html.spec.whatwg.org/multipage/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements">h1</a></code>) and then styled using
CSS and supporting technologies such as Web Components.</p>
<p>When authors use the <code id="the-canvas-element:the-canvas-element-4"><a href="#the-canvas-element">canvas</a></code> element, they must also provide content that, when
presented to the user, conveys essentially the same function or purpose as the
<code id="the-canvas-element:the-canvas-element-5"><a href="#the-canvas-element">canvas</a></code>'s bitmap. This content may be placed as content of the <code id="the-canvas-element:the-canvas-element-6"><a href="#the-canvas-element">canvas</a></code>
element. The contents of the <code id="the-canvas-element:the-canvas-element-7"><a href="#the-canvas-element">canvas</a></code> element, if any, are the element's <a href="https://html.spec.whatwg.org/multipage/dom.html#fallback-content" id="the-canvas-element:fallback-content">fallback
content</a>.</p>
<hr/>
<p>In interactive visual media, if <a href="https://html.spec.whatwg.org/multipage/webappapis.html#concept-n-script" id="the-canvas-element:concept-n-script">scripting is enabled</a> for
the <code id="the-canvas-element:the-canvas-element-8"><a href="#the-canvas-element">canvas</a></code> element, and if support for <code id="the-canvas-element:the-canvas-element-9"><a href="#the-canvas-element">canvas</a></code> elements has been enabled,
then the <code id="the-canvas-element:the-canvas-element-10"><a href="#the-canvas-element">canvas</a></code> element <a href="https://html.spec.whatwg.org/multipage/dom.html#represents" id="the-canvas-element:represents">represents</a> <a href="https://html.spec.whatwg.org/multipage/dom.html#embedded-content-category" id="the-canvas-element:embedded-content-category-3">embedded content</a>
consisting of a dynamically created image, the element's bitmap.</p>
<p>In non-interactive, static, visual media, if the <code id="the-canvas-element:the-canvas-element-11"><a href="#the-canvas-element">canvas</a></code> element has been
previously associated with a rendering context (e.g. if the page was viewed in an interactive
visual medium and is now being printed, or if some script that ran during the page layout process
painted on the element), then the <code id="the-canvas-element:the-canvas-element-12"><a href="#the-canvas-element">canvas</a></code> element <a href="https://html.spec.whatwg.org/multipage/dom.html#represents" id="the-canvas-element:represents-2">represents</a>
<a href="https://html.spec.whatwg.org/multipage/dom.html#embedded-content-category" id="the-canvas-element:embedded-content-category-4">embedded content</a> with the element's current bitmap and size. Otherwise, the element
represents its <a href="https://html.spec.whatwg.org/multipage/dom.html#fallback-content" id="the-canvas-element:fallback-content-2">fallback content</a> instead.</p>
<p>In non-visual media, and in visual media if <a href="https://html.spec.whatwg.org/multipage/webappapis.html#concept-n-noscript" id="the-canvas-element:concept-n-noscript">scripting is
disabled</a> for the <code id="the-canvas-element:the-canvas-element-13"><a href="#the-canvas-element">canvas</a></code> element or if support for <code id="the-canvas-element:the-canvas-element-14"><a href="#the-canvas-element">canvas</a></code> elements
has been disabled, the <code id="the-canvas-element:the-canvas-element-15"><a href="#the-canvas-element">canvas</a></code> element <a href="https://html.spec.whatwg.org/multipage/dom.html#represents" id="the-canvas-element:represents-3">represents</a> its <a href="https://html.spec.whatwg.org/multipage/dom.html#fallback-content" id="the-canvas-element:fallback-content-3">fallback
content</a> instead.</p>
<p>When a <code id="the-canvas-element:the-canvas-element-16"><a href="#the-canvas-element">canvas</a></code> element <a href="https://html.spec.whatwg.org/multipage/dom.html#represents" id="the-canvas-element:represents-4">represents</a> <a href="https://html.spec.whatwg.org/multipage/dom.html#embedded-content-category" id="the-canvas-element:embedded-content-category-5">embedded content</a>, the
user can still focus descendants of the <code id="the-canvas-element:the-canvas-element-17"><a href="#the-canvas-element">canvas</a></code> element (in the <a href="https://html.spec.whatwg.org/multipage/dom.html#fallback-content" id="the-canvas-element:fallback-content-4">fallback
content</a>). When an element is <a href="https://html.spec.whatwg.org/multipage/interaction.html#focused" id="the-canvas-element:focused">focused</a>, it is the target of keyboard interaction
events (even though the element itself is not visible). This allows authors to make an interactive
canvas keyboard-accessible: authors should have a one-to-one mapping of interactive regions to <i id="the-canvas-element:focusable-area"><a href="https://html.spec.whatwg.org/multipage/interaction.html#focusable-area">focusable areas</a></i> in the <a href="https://html.spec.whatwg.org/multipage/dom.html#fallback-content" id="the-canvas-element:fallback-content-5">fallback content</a>. (Focus has no
effect on mouse interaction events.) <a href="https://html.spec.whatwg.org/multipage/references.html#refsUIEVENTS">[UIEVENTS]</a></p>
<p>An element whose nearest <code id="the-canvas-element:the-canvas-element-18"><a href="#the-canvas-element">canvas</a></code> element ancestor is <a href="https://html.spec.whatwg.org/multipage/rendering.html#being-rendered" id="the-canvas-element:being-rendered">being rendered</a>
and <a href="https://html.spec.whatwg.org/multipage/dom.html#represents" id="the-canvas-element:represents-5">represents</a> <a href="https://html.spec.whatwg.org/multipage/dom.html#embedded-content-category" id="the-canvas-element:embedded-content-category-6">embedded content</a> is an element that is <dfn id="being-used-as-relevant-canvas-fallback-content">being used as
relevant canvas fallback content</dfn>.</p>
<hr/>
<p>The <code id="the-canvas-element:the-canvas-element-19"><a href="#the-canvas-element">canvas</a></code> element has two attributes to control the size of the element's bitmap:
<dfn id="attr-canvas-width"><code>width</code></dfn> and <dfn id="attr-canvas-height"><code>height</code></dfn>. These attributes, when specified, must have
values that are <a href="https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-non-negative-integer" id="the-canvas-element:valid-non-negative-integer">valid non-negative integers</a>. The <a href="https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#rules-for-parsing-non-negative-integers" id="the-canvas-element:rules-for-parsing-non-negative-integers">rules for parsing non-negative integers</a> must be used to obtain their
numeric values. If an attribute is missing, or if parsing its value returns an error, then the
default value must be used instead. The <code id="the-canvas-element:attr-canvas-width-2"><a href="#attr-canvas-width">width</a></code>
attribute defaults to 300, and the <code id="the-canvas-element:attr-canvas-height-2"><a href="#attr-canvas-height">height</a></code> attribute
defaults to 150.</p>
<p>The <a data-x-internal="intrinsic-dimensions" href="https://drafts.csswg.org/css2/conform.html#intrinsic" id="the-canvas-element:intrinsic-dimensions">intrinsic dimensions</a> of the <code id="the-canvas-element:the-canvas-element-20"><a href="#the-canvas-element">canvas</a></code> element when it
<a href="https://html.spec.whatwg.org/multipage/dom.html#represents" id="the-canvas-element:represents-6">represents</a> <a href="https://html.spec.whatwg.org/multipage/dom.html#embedded-content-category" id="the-canvas-element:embedded-content-category-7">embedded content</a> are equal to the dimensions of the
element's bitmap.</p>
<p>The user agent must use a square pixel density consisting of one pixel of image data per
coordinate space unit for the bitmaps of a <code id="the-canvas-element:the-canvas-element-21"><a href="#the-canvas-element">canvas</a></code> and its rendering contexts.</p>
<p class="note">A <code id="the-canvas-element:the-canvas-element-22"><a href="#the-canvas-element">canvas</a></code> element can be sized arbitrarily by a style sheet, its
bitmap is then subject to the <a data-x-internal="'object-fit'" href="https://drafts.csswg.org/css-images/#the-object-fit" id="the-canvas-element:'object-fit'">'object-fit'</a> CSS property.</p>
<hr/>
<p>The bitmaps of <code id="the-canvas-element:the-canvas-element-23"><a href="#the-canvas-element">canvas</a></code> elements, the bitmaps of <code id="the-canvas-element:imagebitmap"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code> objects,
as well as some of the bitmaps of rendering contexts, such as those described in the sections on
the <code id="the-canvas-element:canvasrenderingcontext2d-2"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> and <code id="the-canvas-element:imagebitmaprenderingcontext"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> objects
below, have an <dfn id="concept-canvas-origin-clean">origin-clean</dfn> flag, which can be
set to true or false. Initially, when the <code id="the-canvas-element:the-canvas-element-24"><a href="#the-canvas-element">canvas</a></code> element or <code id="the-canvas-element:imagebitmap-2"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code>
object is created, its bitmap's <a href="#concept-canvas-origin-clean" id="the-canvas-element:concept-canvas-origin-clean">origin-clean</a>
flag must be set to true.</p>
<p>A <code id="the-canvas-element:the-canvas-element-25"><a href="#the-canvas-element">canvas</a></code> element can have a rendering context bound to it. Initially, it does not
have a bound rendering context. To keep track of whether it has a rendering context or not, and
what kind of rendering context it is, a <code id="the-canvas-element:the-canvas-element-26"><a href="#the-canvas-element">canvas</a></code> also has a <dfn id="concept-canvas-context-mode">canvas context mode</dfn>, which is initially <dfn id="concept-canvas-none">none</dfn> but can be changed to either <dfn id="concept-canvas-placeholder">placeholder</dfn>, <dfn id="concept-canvas-2d">2d</dfn>, <dfn id="concept-canvas-bitmaprenderer">bitmaprenderer</dfn>, or <dfn id="concept-canvas-webgl">webgl</dfn> by algorithms defined in this specification.</p>
<p>When its <a href="#concept-canvas-context-mode" id="the-canvas-element:concept-canvas-context-mode">canvas context mode</a> is <a href="#concept-canvas-none" id="the-canvas-element:concept-canvas-none">none</a>, a <code id="the-canvas-element:the-canvas-element-27"><a href="#the-canvas-element">canvas</a></code> element has no rendering context,
and its bitmap must be fully transparent black with an <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#intrinsic-width" id="the-canvas-element:intrinsic-width">intrinsic width</a> equal to the
numeric value of the element's <code id="the-canvas-element:attr-canvas-width-3"><a href="#attr-canvas-width">width</a></code> attribute and an
<a href="https://html.spec.whatwg.org/multipage/infrastructure.html#intrinsic-height" id="the-canvas-element:intrinsic-height">intrinsic height</a> equal to the numeric value of the element's <code id="the-canvas-element:attr-canvas-height-3"><a href="#attr-canvas-height">height</a></code> attribute, those values being interpreted in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="the-canvas-element:'px'">CSS pixels</a>, and being updated as the attributes are set, changed, or
removed.</p>
<p>When its <a href="#concept-canvas-context-mode" id="the-canvas-element:concept-canvas-context-mode-2">canvas context mode</a> is <a href="#concept-canvas-placeholder" id="the-canvas-element:concept-canvas-placeholder">placeholder</a>, a <code id="the-canvas-element:the-canvas-element-28"><a href="#the-canvas-element">canvas</a></code> element has no
rendering context. It serves as a placeholder for an <code id="the-canvas-element:offscreencanvas-2"><a href="#offscreencanvas">OffscreenCanvas</a></code> object, and
the content of the <code id="the-canvas-element:the-canvas-element-29"><a href="#the-canvas-element">canvas</a></code> element is updated by calling the <code id="the-canvas-element:offscreencontext-commit"><a href="#offscreencontext-commit">commit()</a></code> method of the <code id="the-canvas-element:offscreencanvas-3"><a href="#offscreencanvas">OffscreenCanvas</a></code>
object's rendering context.</p>
<p>When a <code id="the-canvas-element:the-canvas-element-30"><a href="#the-canvas-element">canvas</a></code> element represents <a href="https://html.spec.whatwg.org/multipage/dom.html#embedded-content-category" id="the-canvas-element:embedded-content-category-8">embedded content</a>, it provides a
<a data-x-internal="paint-source" href="https://drafts.csswg.org/css-images-4/#paint-source" id="the-canvas-element:paint-source">paint source</a> whose width is the element's <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#intrinsic-width" id="the-canvas-element:intrinsic-width-2">intrinsic width</a>, whose height
is the element's <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#intrinsic-height" id="the-canvas-element:intrinsic-height-2">intrinsic height</a>, and whose appearance is the element's bitmap.</p>
<p>Whenever the <code id="the-canvas-element:attr-canvas-width-4"><a href="#attr-canvas-width">width</a></code> and <code id="the-canvas-element:attr-canvas-height-4"><a href="#attr-canvas-height">height</a></code> content attributes are set, removed, changed, or
redundantly set to the value they already have, then the user agent must perform the action
from the row of the following table that corresponds to the <code id="the-canvas-element:the-canvas-element-31"><a href="#the-canvas-element">canvas</a></code> element's <a href="#concept-canvas-context-mode" id="the-canvas-element:concept-canvas-context-mode-3">context mode</a>.</p>
<table><thead><tr><th>
<p><a href="#concept-canvas-context-mode" id="the-canvas-element:concept-canvas-context-mode-4">Context Mode</a></p>
</th><th>
<p>Action</p>
</th></tr></thead><tbody><tr><th>
<p><a href="#concept-canvas-2d" id="the-canvas-element:concept-canvas-2d">2d</a></p>
</th><td>
<p>Follow the steps to <a href="#concept-canvas-set-bitmap-dimensions" id="the-canvas-element:concept-canvas-set-bitmap-dimensions">set bitmap
dimensions</a> to the numeric values of the <code id="the-canvas-element:attr-canvas-width-5"><a href="#attr-canvas-width">width</a></code>
and <code id="the-canvas-element:attr-canvas-height-5"><a href="#attr-canvas-height">height</a></code> content attributes.</p>
</td></tr><tr><th>
<p><a href="#concept-canvas-webgl" id="the-canvas-element:concept-canvas-webgl">webgl</a></p>
</th><td>
<p>Follow the behavior defined in the WebGL specification. <a href="https://html.spec.whatwg.org/multipage/references.html#refsWEBGL">[WEBGL]</a></p>
</td></tr><tr><th>
<p><a href="#concept-canvas-bitmaprenderer" id="the-canvas-element:concept-canvas-bitmaprenderer">bitmaprenderer</a></p>
</th><td>
<p>If the context's <a href="#concept-imagebitmaprenderingcontext-bitmap-mode" id="the-canvas-element:concept-imagebitmaprenderingcontext-bitmap-mode">bitmap
mode</a> is set to <a href="#concept-imagebitmaprenderingcontext-blank" id="the-canvas-element:concept-imagebitmaprenderingcontext-blank">blank</a>,
run the steps to <a href="#set-an-imagebitmaprenderingcontext's-output-bitmap" id="the-canvas-element:set-an-imagebitmaprenderingcontext's-output-bitmap">set an <code>ImageBitmapRenderingContext</code>'s output bitmap</a>,
passing the <code id="the-canvas-element:the-canvas-element-32"><a href="#the-canvas-element">canvas</a></code> element's rendering context.</p>
</td></tr><tr><th>
<p><a href="#concept-canvas-placeholder" id="the-canvas-element:concept-canvas-placeholder-2">placeholder</a></p>
</th><td>
<p>Do nothing.</p>
</td></tr><tr><th>
<p><a href="#concept-canvas-none" id="the-canvas-element:concept-canvas-none-2">none</a></p>
</th><td>
<p>Do nothing.</p>
</td></tr></tbody></table>
<p>The <dfn id="dom-canvas-width"><code>width</code></dfn> and <dfn id="dom-canvas-height"><code>height</code></dfn> IDL attributes must <a href="https://html.spec.whatwg.org/multipage/common-dom-interfaces.html#reflect" id="the-canvas-element:reflect">reflect</a> the
respective content attributes of the same name, with the same defaults.</p>
<hr/>
<dl class="domintro"><dt><var>context</var> = <var>canvas</var> . <code id="dom-canvas-getcontext"><a href="#dom-canvas-getcontext-2">getContext</a></code>(<var>contextId</var> [, ... ] )</dt><dd>
<p>Returns an object that exposes an API for drawing on the canvas. The first argument
specifies the desired API, either &quot;<code id="the-canvas-element:canvas-context-2d"><a href="#canvas-context-2d">2d</a></code>&quot;, &quot;<code id="the-canvas-element:canvas-context-bitmaprenderer"><a href="#canvas-context-bitmaprenderer">bitmaprenderer</a></code>&quot; or &quot;<code id="the-canvas-element:canvas-context-webgl"><a href="#canvas-context-webgl">webgl</a></code>&quot;. Subsequent arguments are handled by that API.</p>
<p>This specification defines the &quot;<code id="the-canvas-element:canvas-context-2d-2"><a href="#canvas-context-2d">2d</a></code>&quot; and &quot;<code id="the-canvas-element:canvas-context-bitmaprenderer-2"><a href="#canvas-context-bitmaprenderer">bitmaprenderer</a></code>&quot; contexts below. There is also a
specification that defines a &quot;<code id="the-canvas-element:canvas-context-webgl-2"><a href="#canvas-context-webgl">webgl</a></code>&quot; context.
<a href="https://html.spec.whatwg.org/multipage/references.html#refsWEBGL">[WEBGL]</a></p>
<p>Returns null if the given context ID is not supported, or if the canvas has already been
initialized with another context type (e.g. trying to get a &quot;<code id="the-canvas-element:canvas-context-2d-3"><a href="#canvas-context-2d">2d</a></code>&quot; context after getting a &quot;<code id="the-canvas-element:canvas-context-webgl-3"><a href="#canvas-context-webgl">webgl</a></code>&quot; context).</p>
</dd></dl>
<p>The <dfn id="dom-canvas-getcontext-2"><code>getContext(<var>contextId</var>,
<var>arguments...</var>)</code></dfn> method of the <code id="the-canvas-element:the-canvas-element-33"><a href="#the-canvas-element">canvas</a></code> element, when invoked,
must run the steps in the cell of the following table whose column header describes the
<code id="the-canvas-element:the-canvas-element-34"><a href="#the-canvas-element">canvas</a></code> element's <a href="#concept-canvas-context-mode" id="the-canvas-element:concept-canvas-context-mode-5">canvas context
mode</a> and whose row header describes the method's first argument.</p>
<table><thead><tr><td>
</td><th><a href="#concept-canvas-none" id="the-canvas-element:concept-canvas-none-3">none</a>
</th><th><a href="#concept-canvas-2d" id="the-canvas-element:concept-canvas-2d-2">2d</a>
</th><th><a href="#concept-canvas-bitmaprenderer" id="the-canvas-element:concept-canvas-bitmaprenderer-2">bitmaprenderer</a>
</th><th><a href="#concept-canvas-webgl" id="the-canvas-element:concept-canvas-webgl-2">webgl</a>
</th><th><a href="#concept-canvas-placeholder" id="the-canvas-element:concept-canvas-placeholder-3">placeholder</a>
</th></tr></thead><tbody><tr><th>&quot;<dfn id="canvas-context-2d"><code>2d</code></dfn>&quot;
</th><td>
Follow the <a href="#2d-context-creation-algorithm" id="the-canvas-element:2d-context-creation-algorithm">2D context creation algorithm</a> defined in the section below, passing
it the <code id="the-canvas-element:the-canvas-element-35"><a href="#the-canvas-element">canvas</a></code> element and the method's <var>arguments...</var>, to obtain a
<code id="the-canvas-element:canvasrenderingcontext2d-3"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object; if this does not throw an exception, then
set the <code id="the-canvas-element:the-canvas-element-36"><a href="#the-canvas-element">canvas</a></code> element's <a href="#concept-canvas-context-mode" id="the-canvas-element:concept-canvas-context-mode-6">context
mode</a> to <a href="#concept-canvas-2d" id="the-canvas-element:concept-canvas-2d-3">2d</a>, and return the
<code id="the-canvas-element:canvasrenderingcontext2d-4"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object.
</td><td>
Return the same object as was returned the last time the method was invoked with this same
first argument.
</td><td>
Return null.
</td><td>
Return null.
</td><td>
Throw an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-canvas-element:invalidstateerror">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-canvas-element:domexception"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.
</td></tr><tr><th>&quot;<dfn id="canvas-context-bitmaprenderer"><code>bitmaprenderer</code></dfn>&quot;
</th><td>
Follow the <a href="#imagebitmaprenderingcontext-creation-algorithm" id="the-canvas-element:imagebitmaprenderingcontext-creation-algorithm"><code>ImageBitmapRenderingContext</code> creation algorithm</a> defined
in the section below, passing it the <code id="the-canvas-element:the-canvas-element-37"><a href="#the-canvas-element">canvas</a></code> element and the method's
<var>arguments...</var>, to obtain an <code id="the-canvas-element:imagebitmaprenderingcontext-2"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object; then
set the <code id="the-canvas-element:the-canvas-element-38"><a href="#the-canvas-element">canvas</a></code> element's <a href="#concept-canvas-context-mode" id="the-canvas-element:concept-canvas-context-mode-7">context
mode</a> to <a href="#concept-canvas-bitmaprenderer" id="the-canvas-element:concept-canvas-bitmaprenderer-3">bitmaprenderer</a>, and return the
<code id="the-canvas-element:imagebitmaprenderingcontext-3"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object.
</td><td>
Return null.
</td><td>
Return the same object as was returned the last time the method was invoked with this same
first argument.
</td><td>
Return null.
</td><td>
Throw an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-canvas-element:invalidstateerror-2">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-canvas-element:domexception-2"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.
</td></tr><tr><th>&quot;<dfn id="canvas-context-webgl"><code>webgl</code></dfn>&quot;, if the user agent supports the WebGL feature in its current configuration
</th><td>
Follow the instructions given in the WebGL specification's <i>Context Creation</i> section to
obtain either a <code id="the-canvas-element:webglrenderingcontext-2"><a data-x-internal="webglrenderingcontext" href="https://www.khronos.org/registry/webgl/specs/latest/1.0/#WebGLRenderingContext">WebGLRenderingContext</a></code> or null; if the returned value is null,
then return null and abort these steps, otherwise, set the <code id="the-canvas-element:the-canvas-element-39"><a href="#the-canvas-element">canvas</a></code> element's
<a href="#concept-canvas-context-mode" id="the-canvas-element:concept-canvas-context-mode-8">context mode</a> to <a href="#concept-canvas-webgl" id="the-canvas-element:concept-canvas-webgl-3">webgl</a>, and return the <code id="the-canvas-element:webglrenderingcontext-3"><a data-x-internal="webglrenderingcontext" href="https://www.khronos.org/registry/webgl/specs/latest/1.0/#WebGLRenderingContext">WebGLRenderingContext</a></code>
object <a href="https://html.spec.whatwg.org/multipage/references.html#refsWEBGL">[WEBGL]</a>
</td><td>
Return null.
</td><td>
Return null.
</td><td>
Return the same object as was returned the last time the method was invoked with this same
first argument.
</td><td>
Throw an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-canvas-element:invalidstateerror-3">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-canvas-element:domexception-3"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.
</td></tr><tr><th>An unsupported value*
</th><td>
Return null.
</td><td>
Return null.
</td><td>
Return null.
</td><td>
Return null.
</td><td>
Throw an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-canvas-element:invalidstateerror-4">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-canvas-element:domexception-4"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.
</td></tr></tbody></table>
<p class="tablenote"><small>* For example, the &quot;<code id="the-canvas-element:canvas-context-webgl-4"><a href="#canvas-context-webgl">webgl</a></code>&quot;
value in the case of a user agent having exhausted the graphics hardware's abilities and having no
software fallback implementation.</small></p>
<hr/>
<dl class="domintro"><dt><var>url</var> = <var>canvas</var> . <code id="dom-canvas-todataurl"><a href="#dom-canvas-todataurl-2">toDataURL</a></code>( [ <var>type</var> [, <var>quality</var> ] ] )</dt><dd>
<p>Returns a <a data-x-internal="data-protocol" href="https://tools.ietf.org/html/rfc2397#section-2" id="the-canvas-element:data-protocol"><code>data:</code> URL</a> for the image in the
canvas.</p>
<p>The first argument, if provided, controls the type of the image to be returned (e.g. PNG or
JPEG). The default is &quot;<code id="the-canvas-element:image/png"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/png">image/png</a></code>&quot;; that type is also used if the given type isn't
supported. The second argument applies if the type is an image format that supports variable
quality (such as &quot;<code id="the-canvas-element:image/jpeg"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/jpeg">image/jpeg</a></code>&quot;), and is a number in the range 0.0 to 1.0 inclusive
indicating the desired quality level for the resulting image.</p>
<p>When trying to use types other than &quot;<code id="the-canvas-element:image/png-2"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/png">image/png</a></code>&quot;, authors can check if the image
was really returned in the requested format by checking to see if the returned string starts
with one of the exact strings &quot;<code>data:image/png,</code>&quot; or &quot;<code>data:image/png;</code>&quot;. If it does, the image is PNG, and thus the requested type was
not supported. (The one exception to this is if the canvas has either no height or no width, in
which case the result might simply be &quot;<code>data:,</code>&quot;.)</p>
</dd><dt><var>canvas</var> . <code id="dom-canvas-toblob"><a href="#dom-canvas-toblob-2">toBlob</a></code>(<var>callback</var> [, <var>type</var> [, quality ] ] )</dt><dd>
<p>Creates a <code id="the-canvas-element:blob-2"><a data-x-internal="blob" href="https://w3c.github.io/FileAPI/#blob">Blob</a></code> object representing a file containing the image in the canvas,
and invokes a callback with a handle to that object.</p>
<p>The second argument, if provided, controls the type of the image to be returned (e.g. PNG or
JPEG). The default is &quot;<code id="the-canvas-element:image/png-3"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/png">image/png</a></code>&quot;; that type is also used if the given type isn't
supported. The third argument applies if the type is an image format that supports variable
quality (such as &quot;<code id="the-canvas-element:image/jpeg-2"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/jpeg">image/jpeg</a></code>&quot;), and is a number in the range 0.0 to 1.0 inclusive
indicating the desired quality level for the resulting image.</p>
</dd><dt><var>canvas</var> . <code id="dom-canvas-transfercontroltooffscreen"><a href="#dom-canvas-transfercontroltooffscreen-2">transferControlToOffscreen</a></code>()</dt><dd>
<p>Returns a newly created <code id="the-canvas-element:offscreencanvas-4"><a href="#offscreencanvas">OffscreenCanvas</a></code> object that uses the
<code id="the-canvas-element:the-canvas-element-40"><a href="#the-canvas-element">canvas</a></code> element as a placeholder. Once the <code id="the-canvas-element:the-canvas-element-41"><a href="#the-canvas-element">canvas</a></code> element has become a
placeholder for an <code id="the-canvas-element:offscreencanvas-5"><a href="#offscreencanvas">OffscreenCanvas</a></code> object, its intrinsic size can no longer be
changed, and it cannot have a rendering context. The content of the placeholder canvas is
updated by calling the <code id="the-canvas-element:offscreencontext-commit-2"><a href="#offscreencontext-commit">commit()</a></code> method of the
<code id="the-canvas-element:offscreencanvas-6"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's rendering context.
</p>
</dd></dl>
<p>The <dfn id="dom-canvas-todataurl-2"><code>toDataURL(<var>type</var>,
<var>quality</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol><li><p>If this <code id="the-canvas-element:the-canvas-element-42"><a href="#the-canvas-element">canvas</a></code> element's bitmap's <a href="#concept-canvas-origin-clean" id="the-canvas-element:concept-canvas-origin-clean-2">origin-clean</a> flag is set to false, then throw a
<a data-x-internal="securityerror" href="https://heycam.github.io/webidl/#securityerror" id="the-canvas-element:securityerror">&quot;<code>SecurityError</code>&quot;</a> <code id="the-canvas-element:domexception-5"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these steps.</p>
</li><li><p>If this <code id="the-canvas-element:the-canvas-element-43"><a href="#the-canvas-element">canvas</a></code> element's bitmap has no pixels (i.e. either its horizontal
dimension or its vertical dimension is zero) then return the string &quot;<code>data:,</code>&quot; and abort these steps. (This is the shortest <a data-x-internal="data-protocol" href="https://tools.ietf.org/html/rfc2397#section-2" id="the-canvas-element:data-protocol-2"><code>data:</code> URL</a>; it represents the empty string in a <code>text/plain</code> resource.)</p></li><li><p>Let <var>file</var> be <a href="#a-serialisation-of-the-bitmap-as-a-file" id="the-canvas-element:a-serialisation-of-the-bitmap-as-a-file">a
serialization of this <code>canvas</code> element's bitmap as a file</a>, passing
<var>type</var> and <var>quality</var> if they were given.</p></li><li><p>If <var>file</var> is null then return &quot;<code>data:,</code>&quot;.</p></li><li><p>Return a <a data-x-internal="data-protocol" href="https://tools.ietf.org/html/rfc2397#section-2" id="the-canvas-element:data-protocol-3"><code>data:</code> URL</a> representing
<var>file</var>. <a href="https://html.spec.whatwg.org/multipage/references.html#refsRFC2397">[RFC2397]</a></p>
</li></ol>
<p>The <dfn id="dom-canvas-toblob-2"><code>toBlob(<var>callback</var>, <var>type</var>,
<var>quality</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol><li><p>If this <code id="the-canvas-element:the-canvas-element-44"><a href="#the-canvas-element">canvas</a></code> element's bitmap's <a href="#concept-canvas-origin-clean" id="the-canvas-element:concept-canvas-origin-clean-3">origin-clean</a> flag is set to false, then throw a
<a data-x-internal="securityerror" href="https://heycam.github.io/webidl/#securityerror" id="the-canvas-element:securityerror-2">&quot;<code>SecurityError</code>&quot;</a> <code id="the-canvas-element:domexception-6"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these steps.</p>
</li><li>
<p>If this <code id="the-canvas-element:the-canvas-element-45"><a href="#the-canvas-element">canvas</a></code> element's bitmap has no pixels (i.e. either its horizontal
dimension or its vertical dimension is zero) then let <var>result</var> be null.</p>
<p>Otherwise, let <var>result</var> be a <code id="the-canvas-element:blob-3"><a data-x-internal="blob" href="https://w3c.github.io/FileAPI/#blob">Blob</a></code> object representing <a href="#a-serialisation-of-the-bitmap-as-a-file" id="the-canvas-element:a-serialisation-of-the-bitmap-as-a-file-2">a serialization of this <code>canvas</code> element's
bitmap as a file</a>, passing <var>type</var> and <var>quality</var> if they were given. <a href="https://html.spec.whatwg.org/multipage/references.html#refsFILEAPI">[FILEAPI]</a></p>
</li><li><p>Return, but continue running these steps <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#in-parallel" id="the-canvas-element:in-parallel">in parallel</a>.</p></li><li><p><a href="https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-task" id="the-canvas-element:queue-a-task">Queue a task</a> to <a data-x-internal="es-invoking-callback-functions" href="https://heycam.github.io/webidl/#invoke-a-callback-function" id="the-canvas-element:es-invoking-callback-functions">invoke</a>
the <code id="the-canvas-element:blobcallback-2"><a href="#blobcallback">BlobCallback</a></code> <var>callback</var> with <var>result</var> as its argument. The
<a href="https://html.spec.whatwg.org/multipage/webappapis.html#task-source" id="the-canvas-element:task-source">task source</a> for this task is the
<dfn id="canvas-blob-serialisation-task-source">canvas blob serialization task
source</dfn>.</p></li></ol>
<p>The <dfn id="dom-canvas-transfercontroltooffscreen-2"><code>transferControlToOffscreen()</code></dfn> method,
when invoked, must run these steps:</p>
<ol><li><p>If this <code id="the-canvas-element:the-canvas-element-46"><a href="#the-canvas-element">canvas</a></code> element's <a href="#concept-canvas-context-mode" id="the-canvas-element:concept-canvas-context-mode-9">context
mode</a> is not set to <a href="#concept-canvas-none" id="the-canvas-element:concept-canvas-none-4">none</a>, throw an
<a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-canvas-element:invalidstateerror-5">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-canvas-element:domexception-7"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these
steps.</p></li><li><p>Let <var>offscreenCanvas</var> be a new <code id="the-canvas-element:offscreencanvas-7"><a href="#offscreencanvas">OffscreenCanvas</a></code> object with its
width and height equal to the values of the <code id="the-canvas-element:attr-canvas-width-6"><a href="#attr-canvas-width">width</a></code>
and <code id="the-canvas-element:attr-canvas-height-6"><a href="#attr-canvas-height">height</a></code> content attributes of this
<code id="the-canvas-element:the-canvas-element-47"><a href="#the-canvas-element">canvas</a></code> element.</p></li><li><p>Set the <a href="#offscreencanvas-placeholder" id="the-canvas-element:offscreencanvas-placeholder">placeholder <code>canvas</code>
element</a> of <var>offscreenCanvas</var> to be a weak reference to this <code id="the-canvas-element:the-canvas-element-48"><a href="#the-canvas-element">canvas</a></code>
element.</p></li><li><p>Set this <code id="the-canvas-element:the-canvas-element-49"><a href="#the-canvas-element">canvas</a></code> element's <a href="#concept-canvas-context-mode" id="the-canvas-element:concept-canvas-context-mode-10">context
mode</a> to <a href="#concept-canvas-placeholder" id="the-canvas-element:concept-canvas-placeholder-4">placeholder</a>.</p></li><li><p>Return <var>offscreenCanvas</var>.</p></li></ol>
<h5 id="2dcontext"><span class="secno">4.12.5.1</span> The 2D rendering context<a class="self-link" href="#2dcontext"/></h5>
<pre class="idl">typedef (<a href="https://html.spec.whatwg.org/multipage/embedded-content.html#htmlimageelement" id="2dcontext:htmlimageelement">HTMLImageElement</a> or
<a data-x-internal="svgimageelement" href="https://www.w3.org/TR/SVG11/struct.html#InterfaceSVGImageElement" id="2dcontext:svgimageelement">SVGImageElement</a>) <dfn id="htmlorsvgimageelement">HTMLOrSVGImageElement</dfn>;
typedef (<a href="#htmlorsvgimageelement" id="2dcontext:htmlorsvgimageelement">HTMLOrSVGImageElement</a> or
<a href="https://html.spec.whatwg.org/multipage/media.html#htmlvideoelement" id="2dcontext:htmlvideoelement">HTMLVideoElement</a> or
<a href="#htmlcanvaselement" id="2dcontext:htmlcanvaselement">HTMLCanvasElement</a> or
<a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap" id="2dcontext:imagebitmap">ImageBitmap</a> or
<a href="#offscreencanvas" id="2dcontext:offscreencanvas">OffscreenCanvas</a>) <dfn id="canvasimagesource">CanvasImageSource</dfn>;
enum <dfn id="canvasfillrule">CanvasFillRule</dfn> { &quot;<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero">nonzero</a>&quot;, &quot;<a href="#dom-context-2d-fillrule-evenodd" id="2dcontext:dom-context-2d-fillrule-evenodd">evenodd</a>&quot; };
dictionary <dfn id="canvasrenderingcontext2dsettings">CanvasRenderingContext2DSettings</dfn> {
boolean <a href="#dom-canvasrenderingcontext2dsettings-alpha" id="2dcontext:dom-canvasrenderingcontext2dsettings-alpha">alpha</a> = true;
};
enum <dfn id="imagesmoothingquality">ImageSmoothingQuality</dfn> { &quot;<a href="#dom-context-2d-imagesmoothingquality-low" id="2dcontext:dom-context-2d-imagesmoothingquality-low">low</a>&quot;, &quot;<a href="#dom-context-2d-imagesmoothingquality-medium" id="2dcontext:dom-context-2d-imagesmoothingquality-medium">medium</a>&quot;, &quot;<a href="#dom-context-2d-imagesmoothingquality-high" id="2dcontext:dom-context-2d-imagesmoothingquality-high">high</a>&quot; };
interface <dfn id="canvasrenderingcontext2d">CanvasRenderingContext2D</dfn> {
// back-reference to the canvas
readonly attribute <a href="#htmlcanvaselement" id="2dcontext:htmlcanvaselement-2">HTMLCanvasElement</a> <a href="#dom-context-2d-canvas-2" id="2dcontext:dom-context-2d-canvas-2">canvas</a>;
};
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d">CanvasRenderingContext2D</a> implements <a href="#canvasstate" id="2dcontext:canvasstate">CanvasState</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-2">CanvasRenderingContext2D</a> implements <a href="#canvastransform" id="2dcontext:canvastransform">CanvasTransform</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-3">CanvasRenderingContext2D</a> implements <a href="#canvascompositing" id="2dcontext:canvascompositing">CanvasCompositing</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-4">CanvasRenderingContext2D</a> implements <a href="#canvasimagesmoothing" id="2dcontext:canvasimagesmoothing">CanvasImageSmoothing</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-5">CanvasRenderingContext2D</a> implements <a href="#canvasfillstrokestyles" id="2dcontext:canvasfillstrokestyles">CanvasFillStrokeStyles</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-6">CanvasRenderingContext2D</a> implements <a href="#canvasshadowstyles" id="2dcontext:canvasshadowstyles">CanvasShadowStyles</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-7">CanvasRenderingContext2D</a> implements <a href="#canvasfilters" id="2dcontext:canvasfilters">CanvasFilters</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-8">CanvasRenderingContext2D</a> implements <a href="#canvasrect" id="2dcontext:canvasrect">CanvasRect</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-9">CanvasRenderingContext2D</a> implements <a href="#canvasdrawpath" id="2dcontext:canvasdrawpath">CanvasDrawPath</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-10">CanvasRenderingContext2D</a> implements <a href="#canvasuserinterface" id="2dcontext:canvasuserinterface">CanvasUserInterface</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-11">CanvasRenderingContext2D</a> implements <a href="#canvastext" id="2dcontext:canvastext">CanvasText</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-12">CanvasRenderingContext2D</a> implements <a href="#canvasdrawimage" id="2dcontext:canvasdrawimage">CanvasDrawImage</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-13">CanvasRenderingContext2D</a> implements <a href="#canvasimagedata" id="2dcontext:canvasimagedata">CanvasImageData</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-14">CanvasRenderingContext2D</a> implements <a href="#canvaspathdrawingstyles" id="2dcontext:canvaspathdrawingstyles">CanvasPathDrawingStyles</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-15">CanvasRenderingContext2D</a> implements <a href="#canvastextdrawingstyles" id="2dcontext:canvastextdrawingstyles">CanvasTextDrawingStyles</a>;
<a href="#canvasrenderingcontext2d" id="2dcontext:canvasrenderingcontext2d-16">CanvasRenderingContext2D</a> implements <a href="#canvaspath" id="2dcontext:canvaspath">CanvasPath</a>;
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvasstate">CanvasState</dfn> {
// state
void <a href="#dom-context-2d-save-2" id="2dcontext:dom-context-2d-save-2">save</a>(); // push state on state stack
void <a href="#dom-context-2d-restore-2" id="2dcontext:dom-context-2d-restore-2">restore</a>(); // pop state stack and restore state
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvastransform">CanvasTransform</dfn> {
// transformations (default transform is the identity matrix)
void <a href="#dom-context-2d-scale-2" id="2dcontext:dom-context-2d-scale-2">scale</a>(unrestricted double x, unrestricted double y);
void <a href="#dom-context-2d-rotate-2" id="2dcontext:dom-context-2d-rotate-2">rotate</a>(unrestricted double angle);
void <a href="#dom-context-2d-translate-2" id="2dcontext:dom-context-2d-translate-2">translate</a>(unrestricted double x, unrestricted double y);
void <a href="#dom-context-2d-transform-2" id="2dcontext:dom-context-2d-transform-2">transform</a>(unrestricted double a, unrestricted double b, unrestricted double c, unrestricted double d, unrestricted double e, unrestricted double f);
[NewObject] <a data-x-internal="dommatrix" href="https://drafts.fxtf.org/geometry/#dommatrix" id="2dcontext:dommatrix">DOMMatrix</a> <a href="#dom-context-2d-gettransform-2" id="2dcontext:dom-context-2d-gettransform-2">getTransform</a>();
void <a href="#dom-context-2d-settransform-2" id="2dcontext:dom-context-2d-settransform-2">setTransform</a>(unrestricted double a, unrestricted double b, unrestricted double c, unrestricted double d, unrestricted double e, unrestricted double f);
void <a href="#dom-context-2d-settransform-2" id="2dcontext:dom-context-2d-settransform-2-2">setTransform</a>(optional <a data-x-internal="dommatrix2dinit" href="https://drafts.fxtf.org/geometry/#dictdef-dommatrix2dinit" id="2dcontext:dommatrix2dinit">DOMMatrix2DInit</a> transform);
void <a href="#dom-context-2d-resettransform-2" id="2dcontext:dom-context-2d-resettransform-2">resetTransform</a>();
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvascompositing">CanvasCompositing</dfn> {
// compositing
attribute unrestricted double <a href="#dom-context-2d-globalalpha-2" id="2dcontext:dom-context-2d-globalalpha-2">globalAlpha</a>; // (default 1.0)
attribute DOMString <a href="#dom-context-2d-globalcompositeoperation-2" id="2dcontext:dom-context-2d-globalcompositeoperation-2">globalCompositeOperation</a>; // (default source-over)
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvasimagesmoothing">CanvasImageSmoothing</dfn> {
// image smoothing
attribute boolean <a href="#dom-context-2d-imagesmoothingenabled-2" id="2dcontext:dom-context-2d-imagesmoothingenabled-2">imageSmoothingEnabled</a>; // (default true)
attribute <a href="#imagesmoothingquality" id="2dcontext:imagesmoothingquality">ImageSmoothingQuality</a> <a href="#dom-context-2d-imagesmoothingquality-2" id="2dcontext:dom-context-2d-imagesmoothingquality-2">imageSmoothingQuality</a>; // (default low)
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvasfillstrokestyles">CanvasFillStrokeStyles</dfn> {
// colors and styles (see also the <a href="#canvaspathdrawingstyles" id="2dcontext:canvaspathdrawingstyles-2">CanvasPathDrawingStyles</a> and <a href="#canvastextdrawingstyles" id="2dcontext:canvastextdrawingstyles-2">CanvasTextDrawingStyles</a> interfaces)
attribute (DOMString or CanvasGradient or CanvasPattern) <a href="#dom-context-2d-strokestyle-2" id="2dcontext:dom-context-2d-strokestyle-2">strokeStyle</a>; // (default black)
attribute (DOMString or CanvasGradient or CanvasPattern) <a href="#dom-context-2d-fillstyle-2" id="2dcontext:dom-context-2d-fillstyle-2">fillStyle</a>; // (default black)
<a href="#canvasgradient" id="2dcontext:canvasgradient">CanvasGradient</a> <a href="#dom-context-2d-createlineargradient-2" id="2dcontext:dom-context-2d-createlineargradient-2">createLinearGradient</a>(double x0, double y0, double x1, double y1);
<a href="#canvasgradient" id="2dcontext:canvasgradient-2">CanvasGradient</a> <a href="#dom-context-2d-createradialgradient-2" id="2dcontext:dom-context-2d-createradialgradient-2">createRadialGradient</a>(double x0, double y0, double r0, double x1, double y1, double r1);
<a href="#canvaspattern" id="2dcontext:canvaspattern">CanvasPattern</a>? <a href="#dom-context-2d-createpattern-2" id="2dcontext:dom-context-2d-createpattern-2">createPattern</a>(<a href="#canvasimagesource" id="2dcontext:canvasimagesource">CanvasImageSource</a> image, [TreatNullAs=EmptyString] DOMString repetition);
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvasshadowstyles">CanvasShadowStyles</dfn> {
// shadows
attribute unrestricted double <a href="#dom-context-2d-shadowoffsetx-2" id="2dcontext:dom-context-2d-shadowoffsetx-2">shadowOffsetX</a>; // (default 0)
attribute unrestricted double <a href="#dom-context-2d-shadowoffsety-2" id="2dcontext:dom-context-2d-shadowoffsety-2">shadowOffsetY</a>; // (default 0)
attribute unrestricted double <a href="#dom-context-2d-shadowblur-2" id="2dcontext:dom-context-2d-shadowblur-2">shadowBlur</a>; // (default 0)
attribute DOMString <a href="#dom-context-2d-shadowcolor-2" id="2dcontext:dom-context-2d-shadowcolor-2">shadowColor</a>; // (default transparent black)
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvasfilters">CanvasFilters</dfn> {
// filters
attribute DOMString <a href="#dom-context-2d-filter" id="2dcontext:dom-context-2d-filter">filter</a>; // (default &quot;none&quot;)
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvasrect">CanvasRect</dfn> {
// rects
void <a href="#dom-context-2d-clearrect-2" id="2dcontext:dom-context-2d-clearrect-2">clearRect</a>(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
void <a href="#dom-context-2d-fillrect-2" id="2dcontext:dom-context-2d-fillrect-2">fillRect</a>(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
void <a href="#dom-context-2d-strokerect-2" id="2dcontext:dom-context-2d-strokerect-2">strokeRect</a>(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvasdrawpath">CanvasDrawPath</dfn> {
// path API (see also <a href="#canvaspath" id="2dcontext:canvaspath-2">CanvasPath</a>)
void <a href="#dom-context-2d-beginpath-2" id="2dcontext:dom-context-2d-beginpath-2">beginPath</a>();
void <a href="#dom-context-2d-fill-2" id="2dcontext:dom-context-2d-fill-2">fill</a>(optional <a href="#canvasfillrule" id="2dcontext:canvasfillrule">CanvasFillRule</a> fillRule = &quot;<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-2">nonzero</a>&quot;);
void <a href="#dom-context-2d-fill-2" id="2dcontext:dom-context-2d-fill-2-2">fill</a>(<a href="#path2d" id="2dcontext:path2d">Path2D</a> path, optional <a href="#canvasfillrule" id="2dcontext:canvasfillrule-2">CanvasFillRule</a> fillRule = &quot;<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-3">nonzero</a>&quot;);
void <a href="#dom-context-2d-stroke-2" id="2dcontext:dom-context-2d-stroke-2">stroke</a>();
void <a href="#dom-context-2d-stroke-2" id="2dcontext:dom-context-2d-stroke-2-2">stroke</a>(<a href="#path2d" id="2dcontext:path2d-2">Path2D</a> path);
void <a href="#dom-context-2d-clip-2" id="2dcontext:dom-context-2d-clip-2">clip</a>(optional <a href="#canvasfillrule" id="2dcontext:canvasfillrule-3">CanvasFillRule</a> fillRule = &quot;<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-4">nonzero</a>&quot;);
void <a href="#dom-context-2d-clip-2" id="2dcontext:dom-context-2d-clip-2-2">clip</a>(<a href="#path2d" id="2dcontext:path2d-3">Path2D</a> path, optional <a href="#canvasfillrule" id="2dcontext:canvasfillrule-4">CanvasFillRule</a> fillRule = &quot;<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-5">nonzero</a>&quot;);
void <a href="#dom-context-2d-resetclip-2" id="2dcontext:dom-context-2d-resetclip-2">resetClip</a>();
boolean <a href="#dom-context-2d-ispointinpath-2" id="2dcontext:dom-context-2d-ispointinpath-2">isPointInPath</a>(unrestricted double x, unrestricted double y, optional <a href="#canvasfillrule" id="2dcontext:canvasfillrule-5">CanvasFillRule</a> fillRule = &quot;<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-6">nonzero</a>&quot;);
boolean <a href="#dom-context-2d-ispointinpath-2" id="2dcontext:dom-context-2d-ispointinpath-2-2">isPointInPath</a>(<a href="#path2d" id="2dcontext:path2d-4">Path2D</a> path, unrestricted double x, unrestricted double y, optional <a href="#canvasfillrule" id="2dcontext:canvasfillrule-6">CanvasFillRule</a> fillRule = &quot;<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-7">nonzero</a>&quot;);
boolean <a href="#dom-context-2d-ispointinstroke-2" id="2dcontext:dom-context-2d-ispointinstroke-2">isPointInStroke</a>(unrestricted double x, unrestricted double y);
boolean <a href="#dom-context-2d-ispointinstroke-2" id="2dcontext:dom-context-2d-ispointinstroke-2-2">isPointInStroke</a>(<a href="#path2d" id="2dcontext:path2d-5">Path2D</a> path, unrestricted double x, unrestricted double y);
};
[Exposed=Window,
NoInterfaceObject]
interface <dfn id="canvasuserinterface">CanvasUserInterface</dfn> {
void <a href="#dom-context-2d-drawfocusifneeded-2" id="2dcontext:dom-context-2d-drawfocusifneeded-2">drawFocusIfNeeded</a>(<a data-x-internal="element" href="https://dom.spec.whatwg.org/#interface-element" id="2dcontext:element">Element</a> element);
void <a href="#dom-context-2d-drawfocusifneeded-2" id="2dcontext:dom-context-2d-drawfocusifneeded-2-2">drawFocusIfNeeded</a>(<a href="#path2d" id="2dcontext:path2d-6">Path2D</a> path, <a data-x-internal="element" href="https://dom.spec.whatwg.org/#interface-element" id="2dcontext:element-2">Element</a> element);
void <a href="#dom-context-2d-scrollpathintoview-2" id="2dcontext:dom-context-2d-scrollpathintoview-2">scrollPathIntoView</a>();
void <a href="#dom-context-2d-scrollpathintoview-2" id="2dcontext:dom-context-2d-scrollpathintoview-2-2">scrollPathIntoView</a>(<a href="#path2d" id="2dcontext:path2d-7">Path2D</a> path);
};
[Exposed=Window,
NoInterfaceObject]
interface <dfn id="canvastext">CanvasText</dfn> {
// text (see also the <a href="#canvaspathdrawingstyles" id="2dcontext:canvaspathdrawingstyles-3">CanvasPathDrawingStyles</a> and <a href="#canvastextdrawingstyles" id="2dcontext:canvastextdrawingstyles-3">CanvasTextDrawingStyles</a> interfaces)
void <a href="#dom-context-2d-filltext-2" id="2dcontext:dom-context-2d-filltext-2">fillText</a>(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
void <a href="#dom-context-2d-stroketext-2" id="2dcontext:dom-context-2d-stroketext-2">strokeText</a>(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
<a href="#textmetrics" id="2dcontext:textmetrics">TextMetrics</a> <a href="#dom-context-2d-measuretext-2" id="2dcontext:dom-context-2d-measuretext-2">measureText</a>(DOMString text);
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvasdrawimage">CanvasDrawImage</dfn> {
// drawing images
void <a href="#dom-context-2d-drawimage" id="2dcontext:dom-context-2d-drawimage">drawImage</a>(<a href="#canvasimagesource" id="2dcontext:canvasimagesource-2">CanvasImageSource</a> image, unrestricted double dx, unrestricted double dy);
void <a href="#dom-context-2d-drawimage" id="2dcontext:dom-context-2d-drawimage-2">drawImage</a>(<a href="#canvasimagesource" id="2dcontext:canvasimagesource-3">CanvasImageSource</a> image, unrestricted double dx, unrestricted double dy, unrestricted double dw, unrestricted double dh);
void <a href="#dom-context-2d-drawimage" id="2dcontext:dom-context-2d-drawimage-3">drawImage</a>(<a href="#canvasimagesource" id="2dcontext:canvasimagesource-4">CanvasImageSource</a> image, unrestricted double sx, unrestricted double sy, unrestricted double sw, unrestricted double sh, unrestricted double dx, unrestricted double dy, unrestricted double dw, unrestricted double dh);
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvasimagedata">CanvasImageData</dfn> {
// <a href="#pixel-manipulation" id="2dcontext:pixel-manipulation">pixel manipulation</a>
<a href="#imagedata" id="2dcontext:imagedata">ImageData</a> <a href="#dom-context-2d-createimagedata-2" id="2dcontext:dom-context-2d-createimagedata-2">createImageData</a>(long sw, long sh);
<a href="#imagedata" id="2dcontext:imagedata-2">ImageData</a> <a href="#dom-context-2d-createimagedata-2" id="2dcontext:dom-context-2d-createimagedata-2-2">createImageData</a>(<a href="#imagedata" id="2dcontext:imagedata-3">ImageData</a> imagedata);
<a href="#imagedata" id="2dcontext:imagedata-4">ImageData</a> <a href="#dom-context-2d-getimagedata-2" id="2dcontext:dom-context-2d-getimagedata-2">getImageData</a>(long sx, long sy, long sw, long sh);
void <a href="#dom-context-2d-putimagedata-2" id="2dcontext:dom-context-2d-putimagedata-2">putImageData</a>(<a href="#imagedata" id="2dcontext:imagedata-5">ImageData</a> imagedata, long dx, long dy);
void <a href="#dom-context-2d-putimagedata-2" id="2dcontext:dom-context-2d-putimagedata-2-2">putImageData</a>(<a href="#imagedata" id="2dcontext:imagedata-6">ImageData</a> imagedata, long dx, long dy, long dirtyX, long dirtyY, long dirtyWidth, long dirtyHeight);
};
enum <dfn id="canvaslinecap">CanvasLineCap</dfn> { &quot;butt&quot;, &quot;round&quot;, &quot;square&quot; };
enum <dfn id="canvaslinejoin">CanvasLineJoin</dfn> { &quot;round&quot;, &quot;bevel&quot;, &quot;miter&quot; };
enum <dfn id="canvastextalign">CanvasTextAlign</dfn> { &quot;<a href="#dom-context-2d-textalign-start" id="2dcontext:dom-context-2d-textalign-start">start</a>&quot;, &quot;<a href="#dom-context-2d-textalign-end" id="2dcontext:dom-context-2d-textalign-end">end</a>&quot;, &quot;<a href="#dom-context-2d-textalign-left" id="2dcontext:dom-context-2d-textalign-left">left</a>&quot;, &quot;<a href="#dom-context-2d-textalign-right" id="2dcontext:dom-context-2d-textalign-right">right</a>&quot;, &quot;<a href="#dom-context-2d-textalign-center" id="2dcontext:dom-context-2d-textalign-center">center</a>&quot; };
enum <dfn id="canvastextbaseline">CanvasTextBaseline</dfn> { &quot;<a href="#dom-context-2d-textbaseline-top" id="2dcontext:dom-context-2d-textbaseline-top">top</a>&quot;, &quot;<a href="#dom-context-2d-textbaseline-hanging" id="2dcontext:dom-context-2d-textbaseline-hanging">hanging</a>&quot;, &quot;<a href="#dom-context-2d-textbaseline-middle" id="2dcontext:dom-context-2d-textbaseline-middle">middle</a>&quot;, &quot;<a href="#dom-context-2d-textbaseline-alphabetic" id="2dcontext:dom-context-2d-textbaseline-alphabetic">alphabetic</a>&quot;, &quot;<a href="#dom-context-2d-textbaseline-ideographic" id="2dcontext:dom-context-2d-textbaseline-ideographic">ideographic</a>&quot;, &quot;<a href="#dom-context-2d-textbaseline-bottom" id="2dcontext:dom-context-2d-textbaseline-bottom">bottom</a>&quot; };
enum <dfn id="canvasdirection">CanvasDirection</dfn> { &quot;<a href="#dom-context-2d-direction-ltr" id="2dcontext:dom-context-2d-direction-ltr">ltr</a>&quot;, &quot;<a href="#dom-context-2d-direction-rtl" id="2dcontext:dom-context-2d-direction-rtl">rtl</a>&quot;, &quot;<a href="#dom-context-2d-direction-inherit" id="2dcontext:dom-context-2d-direction-inherit">inherit</a>&quot; };
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvaspathdrawingstyles">CanvasPathDrawingStyles</dfn> {
// line caps/joins
attribute unrestricted double <a href="#dom-context-2d-linewidth-2" id="2dcontext:dom-context-2d-linewidth-2">lineWidth</a>; // (default 1)
attribute <a href="#canvaslinecap" id="2dcontext:canvaslinecap">CanvasLineCap</a> <a href="#dom-context-2d-linecap-2" id="2dcontext:dom-context-2d-linecap-2">lineCap</a>; // (default &quot;butt&quot;)
attribute <a href="#canvaslinejoin" id="2dcontext:canvaslinejoin">CanvasLineJoin</a> <a href="#dom-context-2d-linejoin-2" id="2dcontext:dom-context-2d-linejoin-2">lineJoin</a>; // (default &quot;miter&quot;)
attribute unrestricted double <a href="#dom-context-2d-miterlimit-2" id="2dcontext:dom-context-2d-miterlimit-2">miterLimit</a>; // (default 10)
// dashed lines
void <a href="#dom-context-2d-setlinedash-2" id="2dcontext:dom-context-2d-setlinedash-2">setLineDash</a>(sequence&lt;unrestricted double&gt; segments); // default empty
sequence&lt;unrestricted double&gt; <a href="#dom-context-2d-getlinedash-2" id="2dcontext:dom-context-2d-getlinedash-2">getLineDash</a>();
attribute unrestricted double <a href="#dom-context-2d-linedashoffset-2" id="2dcontext:dom-context-2d-linedashoffset-2">lineDashOffset</a>;
};
[Exposed=Window,
NoInterfaceObject]
interface <dfn id="canvastextdrawingstyles">CanvasTextDrawingStyles</dfn> {
// text
attribute DOMString <a href="#dom-context-2d-font-2" id="2dcontext:dom-context-2d-font-2">font</a>; // (default 10px sans-serif)
attribute <a href="#canvastextalign" id="2dcontext:canvastextalign">CanvasTextAlign</a> <a href="#dom-context-2d-textalign-2" id="2dcontext:dom-context-2d-textalign-2">textAlign</a>; // (default: &quot;start&quot;)
attribute <a href="#canvastextbaseline" id="2dcontext:canvastextbaseline">CanvasTextBaseline</a> <a href="#dom-context-2d-textbaseline-2" id="2dcontext:dom-context-2d-textbaseline-2">textBaseline</a>; // (default: &quot;alphabetic&quot;)
attribute <a href="#canvasdirection" id="2dcontext:canvasdirection">CanvasDirection</a> <a href="#dom-context-2d-direction-2" id="2dcontext:dom-context-2d-direction-2">direction</a>; // (default: &quot;inherit&quot;)
};
[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn id="canvaspath">CanvasPath</dfn> {
// shared path API methods
void <a href="#dom-context-2d-closepath-2" id="2dcontext:dom-context-2d-closepath-2">closePath</a>();
void <a href="#dom-context-2d-moveto-2" id="2dcontext:dom-context-2d-moveto-2">moveTo</a>(unrestricted double x, unrestricted double y);
void <a href="#dom-context-2d-lineto-2" id="2dcontext:dom-context-2d-lineto-2">lineTo</a>(unrestricted double x, unrestricted double y);
void <a href="#dom-context-2d-quadraticcurveto-2" id="2dcontext:dom-context-2d-quadraticcurveto-2">quadraticCurveTo</a>(unrestricted double cpx, unrestricted double cpy, unrestricted double x, unrestricted double y);
void <a href="#dom-context-2d-beziercurveto-2" id="2dcontext:dom-context-2d-beziercurveto-2">bezierCurveTo</a>(unrestricted double cp1x, unrestricted double cp1y, unrestricted double cp2x, unrestricted double cp2y, unrestricted double x, unrestricted double y);
void <a href="#dom-context-2d-arcto-2" id="2dcontext:dom-context-2d-arcto-2">arcTo</a>(unrestricted double x1, unrestricted double y1, unrestricted double x2, unrestricted double y2, unrestricted double radius);
void <a href="#dom-context-2d-arcto-2" id="2dcontext:dom-context-2d-arcto-2-2">arcTo</a>(unrestricted double x1, unrestricted double y1, unrestricted double x2, unrestricted double y2, unrestricted double radiusX, unrestricted double radiusY, unrestricted double rotation);
void <a href="#dom-context-2d-rect-2" id="2dcontext:dom-context-2d-rect-2">rect</a>(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
void <a href="#dom-context-2d-arc-2" id="2dcontext:dom-context-2d-arc-2">arc</a>(unrestricted double x, unrestricted double y, unrestricted double radius, unrestricted double startAngle, unrestricted double endAngle, optional boolean anticlockwise = false);
void <a href="#dom-context-2d-ellipse-2" id="2dcontext:dom-context-2d-ellipse-2">ellipse</a>(unrestricted double x, unrestricted double y, unrestricted double radiusX, unrestricted double radiusY, unrestricted double rotation, unrestricted double startAngle, unrestricted double endAngle, optional boolean anticlockwise = false);
};
[Exposed=(Window,Worker)]
interface <dfn id="canvasgradient">CanvasGradient</dfn> {
// opaque object
void <a href="#dom-canvasgradient-addcolorstop-2" id="2dcontext:dom-canvasgradient-addcolorstop-2">addColorStop</a>(double offset, DOMString color);
};
[Exposed=(Window,Worker)]
interface <dfn id="canvaspattern">CanvasPattern</dfn> {
// opaque object
void <a href="#dom-canvaspattern-settransform-2" id="2dcontext:dom-canvaspattern-settransform-2">setTransform</a>(optional <a data-x-internal="dommatrix2dinit" href="https://drafts.fxtf.org/geometry/#dictdef-dommatrix2dinit" id="2dcontext:dommatrix2dinit-2">DOMMatrix2DInit</a> transform);
};
[Exposed=Window]
interface <dfn id="textmetrics">TextMetrics</dfn> {
// x-direction
readonly attribute double <a href="#dom-textmetrics-width-2" id="2dcontext:dom-textmetrics-width-2">width</a>; // advance width
readonly attribute double <a href="#dom-textmetrics-actualboundingboxleft-2" id="2dcontext:dom-textmetrics-actualboundingboxleft-2">actualBoundingBoxLeft</a>;
readonly attribute double <a href="#dom-textmetrics-actualboundingboxright-2" id="2dcontext:dom-textmetrics-actualboundingboxright-2">actualBoundingBoxRight</a>;
// y-direction
readonly attribute double <a href="#dom-textmetrics-fontboundingboxascent-2" id="2dcontext:dom-textmetrics-fontboundingboxascent-2">fontBoundingBoxAscent</a>;
readonly attribute double <a href="#dom-textmetrics-fontboundingboxdescent-2" id="2dcontext:dom-textmetrics-fontboundingboxdescent-2">fontBoundingBoxDescent</a>;
readonly attribute double <a href="#dom-textmetrics-actualboundingboxascent-2" id="2dcontext:dom-textmetrics-actualboundingboxascent-2">actualBoundingBoxAscent</a>;
readonly attribute double <a href="#dom-textmetrics-actualboundingboxdescent-2" id="2dcontext:dom-textmetrics-actualboundingboxdescent-2">actualBoundingBoxDescent</a>;
readonly attribute double <a href="#dom-textmetrics-emheightascent-2" id="2dcontext:dom-textmetrics-emheightascent-2">emHeightAscent</a>;
readonly attribute double <a href="#dom-textmetrics-emheightdescent-2" id="2dcontext:dom-textmetrics-emheightdescent-2">emHeightDescent</a>;
readonly attribute double <a href="#dom-textmetrics-hangingbaseline-2" id="2dcontext:dom-textmetrics-hangingbaseline-2">hangingBaseline</a>;
readonly attribute double <a href="#dom-textmetrics-alphabeticbaseline-2" id="2dcontext:dom-textmetrics-alphabeticbaseline-2">alphabeticBaseline</a>;
readonly attribute double <a href="#dom-textmetrics-ideographicbaseline-2" id="2dcontext:dom-textmetrics-ideographicbaseline-2">ideographicBaseline</a>;
};
[<a href="#dom-imagedata" id="2dcontext:dom-imagedata">Constructor</a>(unsigned long sw, unsigned long sh),
<a href="#dom-imagedata" id="2dcontext:dom-imagedata-2">Constructor</a>(<a data-x-internal="idl-uint8clampedarray" href="https://heycam.github.io/webidl/#idl-Uint8ClampedArray" id="2dcontext:idl-uint8clampedarray">Uint8ClampedArray</a> data, unsigned long sw, optional unsigned long sh),
Exposed=(Window,Worker),
<a href="https://html.spec.whatwg.org/multipage/structured-data.html#serializable" id="2dcontext:serializable">Serializable</a>]
interface <dfn id="imagedata">ImageData</dfn> {
readonly attribute unsigned long <a href="#dom-imagedata-width-2" id="2dcontext:dom-imagedata-width-2">width</a>;
readonly attribute unsigned long <a href="#dom-imagedata-height-2" id="2dcontext:dom-imagedata-height-2">height</a>;
readonly attribute <a data-x-internal="idl-uint8clampedarray" href="https://heycam.github.io/webidl/#idl-Uint8ClampedArray" id="2dcontext:idl-uint8clampedarray-2">Uint8ClampedArray</a> <a href="#dom-imagedata-data-2" id="2dcontext:dom-imagedata-data-2">data</a>;
};
[<a href="#dom-path2d" id="2dcontext:dom-path2d">Constructor</a>,
<a href="#dom-path2d-copy" id="2dcontext:dom-path2d-copy">Constructor</a>(<a href="#path2d" id="2dcontext:path2d-8">Path2D</a> path),
<a href="#dom-path2d-merge" id="2dcontext:dom-path2d-merge">Constructor</a>(sequence&lt;<a href="#path2d" id="2dcontext:path2d-9">Path2D</a>&gt; paths, optional <a href="#canvasfillrule" id="2dcontext:canvasfillrule-7">CanvasFillRule</a> fillRule = &quot;<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-8">nonzero</a>&quot;),
<a href="#dom-path2d-withdata" id="2dcontext:dom-path2d-withdata">Constructor</a>(DOMString d),
Exposed=(Window,Worker)]
interface <dfn id="path2d">Path2D</dfn> {
void <a href="#dom-path2d-addpath-2" id="2dcontext:dom-path2d-addpath-2">addPath</a>(<a href="#path2d" id="2dcontext:path2d-10">Path2D</a> path, optional <a data-x-internal="dommatrix2dinit" href="https://drafts.fxtf.org/geometry/#dictdef-dommatrix2dinit" id="2dcontext:dommatrix2dinit-3">DOMMatrix2DInit</a> transform);
};
<a href="#path2d" id="2dcontext:path2d-11">Path2D</a> implements <a href="#canvaspath" id="2dcontext:canvaspath-3">CanvasPath</a>;</pre>
<p class="note">To maintain compatibility with existing Web content, user agents need to
enumerate methods defined in <code id="2dcontext:canvasuserinterface-2"><a href="#canvasuserinterface">CanvasUserInterface</a></code> immediately after the <code id="2dcontext:dom-context-2d-stroke-2-3"><a href="#dom-context-2d-stroke-2">stroke()</a></code> method on <code id="2dcontext:canvasrenderingcontext2d-17"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>
objects.</p>
<dl class="domintro"><dt><var>context</var> = <var>canvas</var> . <code id="2dcontext:dom-canvas-getcontext-2"><a href="#dom-canvas-getcontext-2">getContext</a></code>('2d' [, { [ <code id="2dcontext:dom-canvasrenderingcontext2dsettings-alpha-2"><a href="#dom-canvasrenderingcontext2dsettings-alpha">alpha</a></code>: false ] } ] )</dt><dd>
<p>Returns a <code id="2dcontext:canvasrenderingcontext2d-18"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object that is permanently bound to a
particular <code id="2dcontext:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element.</p>
<p>If the <code id="2dcontext:dom-canvasrenderingcontext2dsettings-alpha-3"><a href="#dom-canvasrenderingcontext2dsettings-alpha">alpha</a></code> setting is
provided and set to false, then the canvas is forced to always be opaque.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-canvas"><a href="#dom-context-2d-canvas-2">canvas</a></code></dt><dd>
<p>Returns the <code id="2dcontext:the-canvas-element-2"><a href="#the-canvas-element">canvas</a></code> element.</p>
</dd></dl>
<p>A <code id="2dcontext:canvasrenderingcontext2d-19"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object has an <dfn id="output-bitmap">output bitmap</dfn> that
is initialized when the object is created.</p>
<p>The <a href="#output-bitmap" id="2dcontext:output-bitmap">output bitmap</a> has an <a href="#concept-canvas-origin-clean" id="2dcontext:concept-canvas-origin-clean">origin-clean</a> flag, which can be set to true or false.
Initially, when one of these bitmaps is created, its <a href="#concept-canvas-origin-clean" id="2dcontext:concept-canvas-origin-clean-2">origin-clean</a> flag must be set to true.</p>
<p>The <code id="2dcontext:canvasrenderingcontext2d-20"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object also has an <dfn id="concept-canvas-alpha">alpha</dfn> flag, which can be set to true or false. Initially,
when the context is created, its <a href="#concept-canvas-alpha" id="2dcontext:concept-canvas-alpha">alpha</a> flag must be
set to true. When a <code id="2dcontext:canvasrenderingcontext2d-21"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object has its <a href="#concept-canvas-alpha" id="2dcontext:concept-canvas-alpha-2">alpha</a> flag set to false, then its alpha channel must be
fixed to 1.0 (fully opaque) for all pixels, and attempts to change the alpha component of any
pixel must be silently ignored.</p>
<p class="note">Thus, the bitmap of such a context starts off as fully-opaque black instead of
fully-transparent black; <code id="2dcontext:dom-context-2d-clearrect-2-2"><a href="#dom-context-2d-clearrect-2">clearRect()</a></code> always
results in fully-opaque black pixels, every fourth byte from <code id="2dcontext:dom-context-2d-getimagedata-2-2"><a href="#dom-context-2d-getimagedata-2">getImageData()</a></code> is always 255, the <code id="2dcontext:dom-context-2d-putimagedata-2-3"><a href="#dom-context-2d-putimagedata-2">putImageData()</a></code> method effectively ignores every
fourth byte in its input, and so on. However, the alpha component of styles and images drawn
onto the canvas are still honoured up to the point where they would impact the <a href="#output-bitmap" id="2dcontext:output-bitmap-2">output
bitmap</a>'s alpha channel; for instance, drawing a 50% transparent white square on a freshly
created <a href="#output-bitmap" id="2dcontext:output-bitmap-3">output bitmap</a> with its <a href="#concept-canvas-alpha" id="2dcontext:concept-canvas-alpha-3">alpha</a>
flag set to false will result in a fully-opaque gray square.</p>
<hr/>
<p>The <code id="2dcontext:canvasrenderingcontext2d-22"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> 2D rendering context represents a flat linear
Cartesian surface whose origin (0,0) is at the top left corner, with the coordinate space having
<var>x</var> values increasing when going right, and <var>y</var> values increasing when going
down. The <var>x</var>-coordinate of the right-most edge is equal to the width of the rendering
context's <a href="#output-bitmap" id="2dcontext:output-bitmap-4">output bitmap</a> in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="2dcontext:'px'">CSS pixels</a>; similarly, the
<var>y</var>-coordinate of the bottom-most edge is equal to the height of the rendering context's
<a href="#output-bitmap" id="2dcontext:output-bitmap-5">output bitmap</a> in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="2dcontext:'px'-2">CSS pixels</a>.</p>
<p>The size of the coordinate space does not necessarily represent the size of the actual bitmaps
that the user agent will use internally or during rendering. On high-definition displays, for
instance, the user agent may internally use bitmaps with two device pixels per unit in the
coordinate space, so that the rendering remains at high quality throughout. Anti-aliasing can
similarly be implemented using over-sampling with bitmaps of a higher resolution than the final
image on the display.</p>
<hr/>
<p>The <dfn id="2d-context-creation-algorithm">2D context creation algorithm</dfn>, which is passed a <var>target</var> (a
<code id="2dcontext:the-canvas-element-3"><a href="#the-canvas-element">canvas</a></code> element) and optionally some arguments, consists of running the following
steps:</p>
<ol><li><p>If the algorithm was passed some arguments, then let <var>arg</var> be the first such
argument. Otherwise, let <var>arg</var> be undefined.</p></li><li><p>Let <var>settings</var> be the result of <a href="#coerce-context-arguments-for-2d" id="2dcontext:coerce-context-arguments-for-2d">coercing the <var>arg</var> context arguments for 2D</a>.</p></li><li><p>Create a new <code id="2dcontext:canvasrenderingcontext2d-23"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object.</p></li><li><p>Initialize its <code id="2dcontext:dom-context-2d-canvas-2-2"><a href="#dom-context-2d-canvas-2">canvas</a></code> attribute to point to
<var>target</var>.</p></li><li><p>Let the new <code id="2dcontext:canvasrenderingcontext2d-24"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object's <a href="#output-bitmap" id="2dcontext:output-bitmap-6">output bitmap</a> be
the same bitmap as <var>target</var>'s bitmap (so that they are shared).</p></li><li><p><a href="#concept-canvas-set-bitmap-dimensions" id="2dcontext:concept-canvas-set-bitmap-dimensions">Set bitmap dimensions</a> to the
numeric values of <var>target</var>'s <code id="2dcontext:attr-canvas-width"><a href="#attr-canvas-width">width</a></code> and
<code id="2dcontext:attr-canvas-height"><a href="#attr-canvas-height">height</a></code> content attributes.</p></li><li>
<p>Process each of the members of <var>settings</var> as follows:</p>
<dl><dt><dfn id="dom-canvasrenderingcontext2dsettings-alpha"><code>alpha</code></dfn></dt><dd>If false, then set the new <code id="2dcontext:canvasrenderingcontext2d-25"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object's <a href="#concept-canvas-alpha" id="2dcontext:concept-canvas-alpha-4">alpha</a> flag to false.</dd></dl>
</li><li><p>Return the new <code id="2dcontext:canvasrenderingcontext2d-26"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object.</p></li></ol>
<hr/>
<hr/>
<p>When a user agent is required to <dfn id="coerce-context-arguments-for-2d">coerce context arguments for 2D</dfn>, it must run these
steps:</p>
<ol><li><p>Let <var>input</var> be the argument to coerce.</p></li><li><p>Let <var>jsval</var> be the result of <a data-x-internal="concept-idl-convert" href="https://heycam.github.io/webidl/#es-type-mapping" id="2dcontext:concept-idl-convert">converting</a>
<var>input</var> to a JavaScript value. (This can throw an exception.)</p></li><li><p>Let <var>dict</var> be the result of <a data-x-internal="concept-idl-convert" href="https://heycam.github.io/webidl/#es-type-mapping" id="2dcontext:concept-idl-convert-2">converting</a>
<var>jsval</var> to the dictionary type <code id="2dcontext:canvasrenderingcontext2dsettings"><a href="#canvasrenderingcontext2dsettings">CanvasRenderingContext2DSettings</a></code>. (This can
throw an exception.)</p></li><li><p>Return <var>dict</var>.</p></li></ol>
<hr/>
<p>When the user agent is to <dfn id="concept-canvas-set-bitmap-dimensions">set bitmap
dimensions</dfn> to <var>width</var> and <var>height</var>, it must run these steps:</p>
<ol><li><p><a href="#reset-the-rendering-context-to-its-default-state" id="2dcontext:reset-the-rendering-context-to-its-default-state">Reset the rendering context to its default state</a>.</p></li><li><p>Resize the <a href="#output-bitmap" id="2dcontext:output-bitmap-7">output bitmap</a> to the new <var>width</var> and <var>height</var>
and clear it to fully transparent black.</p></li><li><p>Let <var>canvas</var> be the <code id="2dcontext:the-canvas-element-4"><a href="#the-canvas-element">canvas</a></code> element to which the rendering
context's <code id="2dcontext:dom-context-2d-canvas-2-3"><a href="#dom-context-2d-canvas-2">canvas</a></code> attribute was initialized.</p></li><li><p>If the numeric value of <var>canvas</var>'s <code id="2dcontext:attr-canvas-width-2"><a href="#attr-canvas-width">width</a></code>
content attribute differs from <var>width</var>, then set <var>canvas</var>'s <code id="2dcontext:attr-canvas-width-3"><a href="#attr-canvas-width">width</a></code> content attribute to the shortest possible string
representing <var>width</var> as a <a href="https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-non-negative-integer" id="2dcontext:valid-non-negative-integer">valid non-negative integer</a>.</p></li><li><p>If the numeric value of <var>canvas</var>'s <code id="2dcontext:attr-canvas-height-2"><a href="#attr-canvas-height">height</a></code>
content attribute differs from <var>height</var>, then set <var>canvas</var>'s <code id="2dcontext:attr-canvas-height-3"><a href="#attr-canvas-height">height</a></code> content attribute to the shortest possible string
representing <var>height</var> as a <a href="https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-non-negative-integer" id="2dcontext:valid-non-negative-integer-2">valid non-negative integer</a>.</p></li></ol>
<div class="example">
<p>Only one square appears to be drawn in the following example:</p>
<pre>// canvas is a reference to a &lt;canvas&gt; element
var context = canvas.getContext('2d');
context.fillRect(0,0,50,50);
canvas.setAttribute('width', '300'); // clears the canvas
context.fillRect(0,100,50,50);
canvas.width = canvas.width; // clears the canvas
context.fillRect(100,0,50,50); // only this square remains</pre>
</div>
<hr/>
<p>When the user agent is to run the <dfn id="concept-canvas-unbinding-steps">unbinding
steps</dfn> for a rendering context, it must run these steps:</p>
<ol><li><p><a href="#reset-the-rendering-context-to-its-default-state" id="2dcontext:reset-the-rendering-context-to-its-default-state-2">Reset the rendering context to its default state</a>.</p></li><li><p>Clear the <code id="2dcontext:canvasrenderingcontext2d-27"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object's <a href="#output-bitmap" id="2dcontext:output-bitmap-8">output bitmap</a> to a
transparent black.</p></li><li><p>Set the <code id="2dcontext:canvasrenderingcontext2d-28"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object's <a href="#concept-canvas-origin-clean" id="2dcontext:concept-canvas-origin-clean-3">origin-clean</a> flag to true.</p></li><li><p>Let the <code id="2dcontext:canvasrenderingcontext2d-29"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object have no <a href="#output-bitmap" id="2dcontext:output-bitmap-9">output
bitmap</a>.</p></li></ol>
<p>When the user agent is to run the <dfn id="concept-canvas-binding-steps">binding
steps</dfn> to bind the rendering context to the <code id="2dcontext:the-canvas-element-5"><a href="#the-canvas-element">canvas</a></code> element <var>target</var>, it
must run these steps:</p>
<ol><li><p><a href="#reset-the-rendering-context-to-its-default-state" id="2dcontext:reset-the-rendering-context-to-its-default-state-3">Reset the rendering context to its default state</a>.</p></li><li><p>Resize the <code id="2dcontext:canvasrenderingcontext2d-30"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object's <a href="#output-bitmap" id="2dcontext:output-bitmap-10">output bitmap</a> to
the dimensions of <var>target</var>'s bitmap and clear it to fully transparent black.</p></li><li><p>Set the <code id="2dcontext:canvasrenderingcontext2d-31"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object's <a href="#concept-canvas-origin-clean" id="2dcontext:concept-canvas-origin-clean-4">origin-clean</a> flag to true.</p></li><li><p>Let the <code id="2dcontext:canvasrenderingcontext2d-32"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object's <a href="#output-bitmap" id="2dcontext:output-bitmap-11">output bitmap</a> be <var>target</var>'s bitmap.</p></li></ol>
<hr/>
<p>The <dfn id="dom-context-2d-canvas-2"><code>canvas</code></dfn> attribute must return the
value it was initialized to when the object was created.</p>
<hr/>
<p id="canvasrenderingcontext2d-currentcolor">Whenever the CSS value <code>currentColor</code> is used as a color in the <code id="2dcontext:canvasrenderingcontext2d-33"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>
API, the <a data-x-internal="computed-value" href="https://drafts.csswg.org/css-cascade/#computed-value" id="2dcontext:computed-value">computed value</a> of the <code>currentColor</code> keyword is
the <a data-x-internal="computed-value" href="https://drafts.csswg.org/css-cascade/#computed-value" id="2dcontext:computed-value-2">computed value</a> of the <a data-x-internal="'color'" href="https://drafts.csswg.org/css-color/#the-color-property" id="2dcontext:'color'">'color'</a> property on the <code id="2dcontext:the-canvas-element-6"><a href="#the-canvas-element">canvas</a></code>
element at the time that the color is specified (e.g. when the appropriate attribute is set, or
when the method is called; not when the color is rendered or otherwise used). If the computed
value of the <a data-x-internal="'color'" href="https://drafts.csswg.org/css-color/#the-color-property" id="2dcontext:'color'-2">'color'</a> property is undefined for a particular case (e.g. because the element is
not in a document), then the <a data-x-internal="computed-value" href="https://drafts.csswg.org/css-cascade/#computed-value" id="2dcontext:computed-value-3">computed value</a> of the <a data-x-internal="'color'" href="https://drafts.csswg.org/css-color/#the-color-property" id="2dcontext:'color'-3">'color'</a> property
for the purposes of determining the computed value of the <code>currentColor</code>
keyword is fully opaque black. <a href="https://html.spec.whatwg.org/multipage/references.html#refsCSSCOLOR">[CSSCOLOR]</a></p>
<p>In the case of <code id="2dcontext:dom-canvasgradient-addcolorstop-2-2"><a href="#dom-canvasgradient-addcolorstop-2">addColorStop()</a></code> on
<code id="2dcontext:canvasgradient-3"><a href="#canvasgradient">CanvasGradient</a></code>, the &quot;<a data-x-internal="computed-value" href="https://drafts.csswg.org/css-cascade/#computed-value" id="2dcontext:computed-value-4">computed value</a> of the <a data-x-internal="'color'" href="https://drafts.csswg.org/css-color/#the-color-property" id="2dcontext:'color'-4">'color'</a>
property&quot; for the purposes of determining the <a data-x-internal="computed-value" href="https://drafts.csswg.org/css-cascade/#computed-value" id="2dcontext:computed-value-5">computed value</a> of the <code>currentColor</code> keyword is always fully opaque black (there is no associated
element). <a href="https://html.spec.whatwg.org/multipage/references.html#refsCSSCOLOR">[CSSCOLOR]</a></p>
<p class="note">This is because <code id="2dcontext:canvasgradient-4"><a href="#canvasgradient">CanvasGradient</a></code> objects are
<code id="2dcontext:the-canvas-element-7"><a href="#the-canvas-element">canvas</a></code>-neutral — a <code id="2dcontext:canvasgradient-5"><a href="#canvasgradient">CanvasGradient</a></code> object created by one
<code id="2dcontext:the-canvas-element-8"><a href="#the-canvas-element">canvas</a></code> can be used by another, and there is therefore no way to know which is the
&quot;element in question&quot; at the time that the color is specified.</p>
<p class="note">Similar concerns exist with font-related properties; the rules for those are
described in detail in the relevant section below.</p>
<hr/>
<p>The <code id="2dcontext:canvasfillrule-8"><a href="#canvasfillrule">CanvasFillRule</a></code> enumeration is used to select the <dfn id="fill-rule">fill rule</dfn>
algorithm by which to determine if a point is inside or outside a path.</p>
<p>The value &quot;<dfn id="dom-context-2d-fillrule-nonzero"><code>nonzero</code></dfn>&quot; value
indicates the non-zero winding rule, wherein
a point is considered to be outside a shape if the number of times a half-infinite straight
line drawn from that point crosses the shape's path going in one direction is equal to the
number of times it crosses the path going in the other direction.
</p>
<p>The &quot;<dfn id="dom-context-2d-fillrule-evenodd"><code>evenodd</code></dfn>&quot; value indicates
the even-odd rule, wherein
a point is considered to be outside a shape if the number of times a half-infinite straight
line drawn from that point crosses the shape's path is even.
</p>
<p>If a point is not outside a shape, it is inside the shape.</p>
<hr/>
<p>The <code id="2dcontext:imagesmoothingquality-2"><a href="#imagesmoothingquality">ImageSmoothingQuality</a></code> enumeration is used to express a preference for the
interpolation quality to use when smoothing images.</p>
<p>The &quot;<dfn id="dom-context-2d-imagesmoothingquality-low"><code>low</code></dfn>&quot; value
indicates a preference for a low level of image interpolation quality. Low-quality image
interpolation may be more computationally efficient than higher settings.</p>
<p>The &quot;<dfn id="dom-context-2d-imagesmoothingquality-medium"><code>medium</code></dfn>&quot; value
indicates a preference for a medium level of image interpolation quality.</p>
<p>The &quot;<dfn id="dom-context-2d-imagesmoothingquality-high"><code>high</code></dfn>&quot; value
indicates a preference for a high level of image interpolation quality. High-quality image
interpolation may be more computationally expensive than lower settings.</p>
<p class="note">Bilinear scaling is an example of a relatively fast, lower-quality image-smoothing
algorithm. Bicubic or Lanczos scaling are examples of image-smoothing algorithms that produce
higher-quality output. This specification does not mandate that specific interpolation algorithms
be used.</p>
<h6 id="implementation-notes"><span class="secno">4.12.5.1.1</span> Implementation notes<a class="self-link" href="#implementation-notes"/></h6>
<p><i>This section is non-normative.</i></p>
<p>The <a href="#output-bitmap" id="implementation-notes:output-bitmap">output bitmap</a>, when it is not directly displayed by the user agent,
implementations can, instead of updating this bitmap, merely remember the sequence of drawing
operations that have been applied to it until such time as the bitmap's actual data is needed
(for example because of a call to <code id="implementation-notes:dom-context-2d-drawimage"><a href="#dom-context-2d-drawimage">drawImage()</a></code>, or
the <code id="implementation-notes:dom-createimagebitmap-2"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#dom-createimagebitmap-2">createImageBitmap()</a></code> factory method). In many
cases, this will be more memory efficient.</p>
<p>The bitmap of a <code id="implementation-notes:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element is the one bitmap that's pretty much always going
to be needed in practice. The <a href="#output-bitmap" id="implementation-notes:output-bitmap-2">output bitmap</a> of a rendering context, when it has one,
is always just an alias to a <code id="implementation-notes:the-canvas-element-2"><a href="#the-canvas-element">canvas</a></code> element's bitmap.</p>
<p>Additional bitmaps are sometimes needed, e.g. to enable fast drawing when the canvas is being
painted at a different size than its <a data-x-internal="intrinsic-dimensions" href="https://drafts.csswg.org/css2/conform.html#intrinsic" id="implementation-notes:intrinsic-dimensions">intrinsic size</a>,
or to enable double buffering so that graphics updates, like page scrolling for example, can be
processed concurrently while canvas draw commands are being executed.</p>
<h6 id="the-canvas-state"><span class="secno">4.12.5.1.2</span> The canvas state<a class="self-link" href="#the-canvas-state"/></h6>
<p>Objects that implement the <code id="the-canvas-state:canvasstate"><a href="#canvasstate">CanvasState</a></code> interface maintain a stack of drawing
states. <dfn id="drawing-state">Drawing states</dfn> consist of:</p>
<ul class="brief"><li>The current <a href="#transformations" id="the-canvas-state:transformations">transformation matrix</a>.</li><li>The current <a href="#clipping-region" id="the-canvas-state:clipping-region">clipping region</a>.</li><li>The current values of the following attributes: <code id="the-canvas-state:dom-context-2d-strokestyle-2"><a href="#dom-context-2d-strokestyle-2">strokeStyle</a></code>, <code id="the-canvas-state:dom-context-2d-fillstyle-2"><a href="#dom-context-2d-fillstyle-2">fillStyle</a></code>, <code id="the-canvas-state:dom-context-2d-globalalpha-2"><a href="#dom-context-2d-globalalpha-2">globalAlpha</a></code>, <code id="the-canvas-state:dom-context-2d-linewidth-2"><a href="#dom-context-2d-linewidth-2">lineWidth</a></code>, <code id="the-canvas-state:dom-context-2d-linecap-2"><a href="#dom-context-2d-linecap-2">lineCap</a></code>, <code id="the-canvas-state:dom-context-2d-linejoin-2"><a href="#dom-context-2d-linejoin-2">lineJoin</a></code>, <code id="the-canvas-state:dom-context-2d-miterlimit-2"><a href="#dom-context-2d-miterlimit-2">miterLimit</a></code>, <code id="the-canvas-state:dom-context-2d-linedashoffset-2"><a href="#dom-context-2d-linedashoffset-2">lineDashOffset</a></code>, <code id="the-canvas-state:dom-context-2d-shadowoffsetx-2"><a href="#dom-context-2d-shadowoffsetx-2">shadowOffsetX</a></code>, <code id="the-canvas-state:dom-context-2d-shadowoffsety-2"><a href="#dom-context-2d-shadowoffsety-2">shadowOffsetY</a></code>, <code id="the-canvas-state:dom-context-2d-shadowblur-2"><a href="#dom-context-2d-shadowblur-2">shadowBlur</a></code>, <code id="the-canvas-state:dom-context-2d-shadowcolor-2"><a href="#dom-context-2d-shadowcolor-2">shadowColor</a></code>, <code id="the-canvas-state:dom-context-2d-filter"><a href="#dom-context-2d-filter">filter</a></code>, <code id="the-canvas-state:dom-context-2d-globalcompositeoperation-2"><a href="#dom-context-2d-globalcompositeoperation-2">globalCompositeOperation</a></code>, <code id="the-canvas-state:dom-context-2d-font-2"><a href="#dom-context-2d-font-2">font</a></code>, <code id="the-canvas-state:dom-context-2d-textalign-2"><a href="#dom-context-2d-textalign-2">textAlign</a></code>, <code id="the-canvas-state:dom-context-2d-textbaseline-2"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code>, <code id="the-canvas-state:dom-context-2d-direction-2"><a href="#dom-context-2d-direction-2">direction</a></code>, <code id="the-canvas-state:dom-context-2d-imagesmoothingenabled-2"><a href="#dom-context-2d-imagesmoothingenabled-2">imageSmoothingEnabled</a></code>, <code id="the-canvas-state:dom-context-2d-imagesmoothingquality-2"><a href="#dom-context-2d-imagesmoothingquality-2">imageSmoothingQuality</a></code>.</li><li>The current <a href="#dash-list" id="the-canvas-state:dash-list">dash list</a>.</li></ul>
<p class="note">The <a href="#current-default-path" id="the-canvas-state:current-default-path">current default path</a> and the rendering context's bitmaps are not
part of the drawing state. The <a href="#current-default-path" id="the-canvas-state:current-default-path-2">current default path</a> is persistent, and can only be
reset using the <code id="the-canvas-state:dom-context-2d-beginpath-2"><a href="#dom-context-2d-beginpath-2">beginPath()</a></code> method. The bitmaps
depend on whether and how the rendering context is bound to a <code id="the-canvas-state:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element.</p>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-save"><a href="#dom-context-2d-save-2">save</a></code>()</dt><dd>
<p>Pushes the current state onto the stack.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-restore"><a href="#dom-context-2d-restore-2">restore</a></code>()</dt><dd>
<p>Pops the top state on the stack, restoring the context to that state.</p>
</dd></dl>
<p>The <dfn id="dom-context-2d-save-2"><code>save()</code></dfn> method, when invoked, must push
a copy of the current drawing state onto the drawing state stack.</p>
<p>The <dfn id="dom-context-2d-restore-2"><code>restore()</code></dfn> method, when invoked,
must pop the top entry in the drawing state stack, and reset the drawing state it describes. If
there is no saved state, then the method must do nothing.</p>
<p>When the user agent is to <dfn id="reset-the-rendering-context-to-its-default-state">reset the rendering context to its default state</dfn>, it must
clear the drawing state stack and everything that <a href="#drawing-state" id="the-canvas-state:drawing-state">drawing state</a> consists of to
initial values.</p>
<h6 id="line-styles"><span class="secno">4.12.5.1.3</span> Line styles<a class="self-link" href="#line-styles"/></h6>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-linewidth"><a href="#dom-context-2d-linewidth-2">lineWidth</a></code> [ = <var>value</var> ]</dt><dt><var>styles</var> . <code id="line-styles:dom-context-2d-linewidth-2"><a href="#dom-context-2d-linewidth-2">lineWidth</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current line width.</p>
<p>Can be set, to change the line width. Values that are not finite values greater than zero are
ignored.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-linecap"><a href="#dom-context-2d-linecap-2">lineCap</a></code> [ = <var>value</var> ]</dt><dt><var>styles</var> . <code id="line-styles:dom-context-2d-linecap-2"><a href="#dom-context-2d-linecap-2">lineCap</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current line cap style.</p>
<p>Can be set, to change the line cap style.</p>
<p>The possible line cap styles are &quot;<code>butt</code>&quot;, &quot;<code>round</code>&quot;, and &quot;<code>square</code>&quot;. Other values are ignored.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-linejoin"><a href="#dom-context-2d-linejoin-2">lineJoin</a></code> [ = <var>value</var> ]</dt><dt><var>styles</var> . <code id="line-styles:dom-context-2d-linejoin-2"><a href="#dom-context-2d-linejoin-2">lineJoin</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current line join style.</p>
<p>Can be set, to change the line join style.</p>
<p>The possible line join styles are &quot;<code>bevel</code>&quot;, &quot;<code>round</code>&quot;, and &quot;<code>miter</code>&quot;. Other values are ignored.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-miterlimit"><a href="#dom-context-2d-miterlimit-2">miterLimit</a></code> [ = <var>value</var> ]</dt><dt><var>styles</var> . <code id="line-styles:dom-context-2d-miterlimit-2"><a href="#dom-context-2d-miterlimit-2">miterLimit</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current miter limit ratio.</p>
<p>Can be set, to change the miter limit ratio. Values that are not finite values greater than
zero are ignored.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-setlinedash"><a href="#dom-context-2d-setlinedash-2">setLineDash</a></code>(<var>segments</var>)</dt><dt><var>styles</var> . <code id="line-styles:dom-context-2d-setlinedash-2"><a href="#dom-context-2d-setlinedash-2">setLineDash</a></code>(<var>segments</var>)</dt><dd>
<p>Sets the current line dash pattern (as used when stroking). The argument is a list of
distances for which to alternately have the line on and the line off.</p>
</dd><dt><var>segments</var> = <var>context</var> . <code id="dom-context-2d-getlinedash"><a href="#dom-context-2d-getlinedash-2">getLineDash</a></code>()</dt><dt><var>segments</var> = <var>styles</var> . <code id="line-styles:dom-context-2d-getlinedash-2"><a href="#dom-context-2d-getlinedash-2">getLineDash</a></code>()</dt><dd>
<p>Returns a copy of the current line dash pattern. The array returned will always have an even
number of entries (i.e. the pattern is normalized).</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-linedashoffset"><a href="#dom-context-2d-linedashoffset-2">lineDashOffset</a></code></dt><dt><var>styles</var> . <code id="line-styles:dom-context-2d-linedashoffset-2"><a href="#dom-context-2d-linedashoffset-2">lineDashOffset</a></code></dt><dd>
<p>Returns the phase offset (in the same units as the line dash pattern).</p>
<p>Can be set, to change the phase offset. Values that are not finite values are ignored.</p>
</dd></dl>
<p>Objects that implement the <code id="line-styles:canvaspathdrawingstyles"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> interface have attributes and
methods (defined in this section) that control how lines are treated by the object.</p>
<p>The <dfn id="dom-context-2d-linewidth-2"><code>lineWidth</code></dfn> attribute gives the
width of lines, in coordinate space units. On getting, it must return the current value. On
setting, zero, negative, infinite, and NaN values must be ignored, leaving the value unchanged;
other values must change the current value to the new value.</p>
<p>When the object implementing the <code id="line-styles:canvaspathdrawingstyles-2"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> interface is created, the
<code id="line-styles:dom-context-2d-linewidth-2-2"><a href="#dom-context-2d-linewidth-2">lineWidth</a></code> attribute must initially have the value
1.0.</p>
<hr/>
<p>The <dfn id="dom-context-2d-linecap-2"><code>lineCap</code></dfn> attribute defines the type
of endings that UAs will place on the end of lines. The three valid values are &quot;<code>butt</code>&quot;, &quot;<code>round</code>&quot;, and &quot;<code>square</code>&quot;.</p>
<p>On getting, it must return the current value. On setting, the current value must be changed
to the new value.</p>
<p>When the object implementing the <code id="line-styles:canvaspathdrawingstyles-3"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> interface is created, the
<code id="line-styles:dom-context-2d-linecap-2-2"><a href="#dom-context-2d-linecap-2">lineCap</a></code> attribute must initially have the value
&quot;<code>butt</code>&quot;.</p>
<hr/>
<p>The <dfn id="dom-context-2d-linejoin-2"><code>lineJoin</code></dfn> attribute defines the type
of corners that UAs will place where two lines meet. The three valid values are
&quot;<code>bevel</code>&quot;, &quot;<code>round</code>&quot;, and &quot;<code>miter</code>&quot;.</p>
<p>On getting, it must return the current value. On setting, the current value must be changed
to the new value.</p>
<p>When the object implementing the <code id="line-styles:canvaspathdrawingstyles-4"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> interface is created, the
<code id="line-styles:dom-context-2d-linejoin-2-2"><a href="#dom-context-2d-linejoin-2">lineJoin</a></code> attribute must initially have the value
&quot;<code>miter</code>&quot;.</p>
<hr/>
<p>When the <code id="line-styles:dom-context-2d-linejoin-2-3"><a href="#dom-context-2d-linejoin-2">lineJoin</a></code> attribute has the value &quot;<code>miter</code>&quot;, strokes use the miter limit ratio to decide how to render joins. The
miter limit ratio can be explicitly set using the <dfn id="dom-context-2d-miterlimit-2"><code>miterLimit</code></dfn> attribute. On getting, it must return
the current value. On setting, zero, negative, infinite, and NaN values must be ignored, leaving
the value unchanged; other values must change the current value to the new value.</p>
<p>When the object implementing the <code id="line-styles:canvaspathdrawingstyles-5"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> interface is created, the
<code id="line-styles:dom-context-2d-miterlimit-2-2"><a href="#dom-context-2d-miterlimit-2">miterLimit</a></code> attribute must initially have the value
10.0.</p>
<hr/>
<p>Each <code id="line-styles:canvaspathdrawingstyles-6"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> object has a <dfn id="dash-list">dash list</dfn>, which is either
empty or consists of an even number of non-negative numbers. Initially, the <a href="#dash-list" id="line-styles:dash-list">dash list</a>
must be empty.</p>
<p>The <dfn id="dom-context-2d-setlinedash-2"><code>setLineDash()</code></dfn> method, when
invoked, must run these steps:</p>
<ol><li><p>Let <var>a</var> be the argument.</p></li><li><p>If any value in <var>a</var> is not finite (e.g. an Infinity or a NaN value), or
if any value is negative (less than zero), then abort these steps (without throwing an exception;
user agents could show a message on a developer console, though, as that would be helpful for
debugging).</p></li><li><p>If the number of elements in <var>a</var> is odd, then let <var>a</var>
be the concatenation of two copies of <var>a</var>.</p></li><li><p>Let the object's <a href="#dash-list" id="line-styles:dash-list-2">dash list</a> be <var>a</var>.</p></li></ol>
<p>When the <dfn id="dom-context-2d-getlinedash-2"><code>getLineDash()</code></dfn> method is
invoked, it must return a sequence whose values are the values of the object's <a href="#dash-list" id="line-styles:dash-list-3">dash
list</a>, in the same order.</p>
<p>It is sometimes useful to change the &quot;phase&quot; of the dash pattern, e.g. to achieve a &quot;marching
ants&quot; effect. The phase can be set using the <dfn id="dom-context-2d-linedashoffset-2"><code>lineDashOffset</code></dfn> attribute. On getting, it must
return the current value. On setting, infinite and NaN values must be ignored, leaving the value
unchanged; other values must change the current value to the new value.</p>
<p>When the object implementing the <code id="line-styles:canvaspathdrawingstyles-7"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> interface is created, the
<code id="line-styles:dom-context-2d-linedashoffset-2-2"><a href="#dom-context-2d-linedashoffset-2">lineDashOffset</a></code> attribute must initially have
the value 0.0.</p>
<hr/>
<p>When a user agent is to <dfn id="trace-a-path">trace a path</dfn>, given an object <var>style</var>
that implements the <code id="line-styles:canvaspathdrawingstyles-8"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> interface, it must run the following
algorithm. This algorithm returns a new <a href="#concept-path" id="line-styles:concept-path">path</a>.</p>
<ol><li><p>Let <var>path</var> be a copy of the path being traced.</p></li><li><p>Prune all zero-length <a href="#line-segments" id="line-styles:line-segments">line segments</a> from <var>path</var>.</p></li><li><p>Remove from <var>path</var> any subpaths containing no lines (i.e. subpaths with
just one point).</p></li><li><p>Replace each point in each subpath of <var>path</var> other than the first point
and the last point of each subpath by a <i>join</i> that joins the line leading to that point to
the line leading out of that point, such that the subpaths all consist of two points (a starting
point with a line leading out of it, and an ending point with a line leading into it), one or
more lines (connecting the points and the joins), and zero or more joins (each connecting one
line to another), connected together such that each subpath is a series of one or more lines with
a join between each one and a point on each end.</p></li><li><p>Add a straight closing line to each closed subpath in <var>path</var> connecting
the last point and the first point of that subpath; change the last point to a join (from the
previously last line to the newly added closing line), and change the first point to a join (from
the newly added closing line to the first line).</p>
</li><li><p>If the <var>styles</var> <a href="#dash-list" id="line-styles:dash-list-4">dash list</a> is empty, then jump to the step
labeled <i>convert</i>.</p></li><li><p>Let <var>pattern width</var> be the concatenation of all the entries of the <var>styles</var> <a href="#dash-list" id="line-styles:dash-list-5">dash list</a>, in coordinate space units.</p>
</li><li><p>For each subpath <var>subpath</var> in <var>path</var>, run the
following substeps. These substeps mutate the subpaths in <var>path</var> <i>in
vivo</i>.</p>
<ol><li><p>Let <var>subpath width</var> be the length of all the lines of <var>subpath</var>, in coordinate space units.</p>
</li><li><p>Let <var>offset</var> be the value of the <var>styles</var> <code id="line-styles:dom-context-2d-linedashoffset-2-3"><a href="#dom-context-2d-linedashoffset-2">lineDashOffset</a></code>, in coordinate space
units.</p></li><li>
<p>While <var>offset</var> is greater than <var>pattern width</var>,
decrement it by <var>pattern width</var>.</p>
<p>While <var>offset</var> is less than zero, increment it by <var>pattern
width</var>.</p>
</li><li><p>Define <var>L</var> to be a linear coordinate line defined along all lines in
<var>subpath</var>, such that the start of the first line in the subpath is defined
as coordinate 0, and the end of the last line in the subpath is defined as coordinate <var>subpath width</var>.</p></li><li><p>Let <var>position</var> be zero minus <var>offset</var>.</p></li><li><p>Let <var>index</var> be 0.</p></li><li><p>Let <var>current state</var> be <i>off</i> (the other states being <i>on</i>
and <i>zero-on</i>).</p></li><li><p><i>Dash on</i>: Let <var>segment length</var> be
the value of the <var>styles</var> <a href="#dash-list" id="line-styles:dash-list-6">dash
list</a>'s <var>index</var>th entry.</p></li><li><p>Increment <var>position</var> by <var>segment length</var>.</p></li><li><p>If <var>position</var> is greater than <var>subpath width</var>,
then end these substeps for this subpath and start them again for the next subpath; if there
are no more subpaths, then jump to the step labeled <i>convert</i> instead.</p></li><li><p>If <var>segment length</var> is non-zero, then let <var>current state</var> be
<i>on</i>.</p></li><li><p>Increment <var>index</var> by one.</p></li><li><p><i>Dash off</i>: Let <var>segment
length</var> be the value of the <var>styles</var> <a href="#dash-list" id="line-styles:dash-list-7">dash list</a>'s <var>index</var>th entry.</p></li><li><p>Let <var>start</var> be the offset <var>position</var> on <var>L</var>.</p></li><li><p>Increment <var>position</var> by <var>segment length</var>.</p></li><li><p>If <var>position</var> is less than zero, then jump to the step labeled
<i>post-cut</i>.</p></li><li><p>If <var>start</var> is less than zero, then let <var>start</var> be
zero.</p></li><li><p>If <var>position</var> is greater than <var>subpath width</var>,
then let <var>end</var> be the offset <var>subpath width</var> on <var>L</var>. Otherwise, let <var>end</var> be the offset <var>position</var> on <var>L</var>.</p></li><li>
<p>Jump to the first appropriate step:</p>
<dl class="switch"><dt>If <var>segment length</var> is zero and <var>current state</var> is
<i>off</i></dt><dd>
<p>Do nothing, just continue to the next step.</p>
</dd><dt>If <var>current state</var> is <i>off</i></dt><dd>
<p>Cut the line on which <var>end</var> finds itself short at <var>end</var> and place a point there, cutting the subpath that it was in in two;
remove all line segments, joins, points, and subpaths that are between <var>start</var> and <var>end</var>; and finally place a single point at <var>start</var> with no lines connecting to it.</p>
<p>The point has a <i>directionality</i> for the purposes of drawing line caps (see below).
The directionality is the direction that the original line had at that point (i.e. when <var>L</var> was defined above).</p>
</dd><dt>Otherwise</dt><dd>
<p>Cut the line on which <var>start</var> finds itself into two at <var>start</var> and place a point there, cutting the subpath that it was in in two, and
similarly cut the line on which <var>end</var> finds itself short at <var>end</var> and place a point there, cutting the subpath that <em>it</em> was in in
two, and then remove all line segments, joins, points, and subpaths that are between <var>start</var> and <var>end</var>.</p>
<p>If <var>start</var> and <var>end</var> are the same point, then this
results in just the line being cut in two and two points being inserted there, with nothing
being removed, unless a join also happens to be at that point, in which case the join must
be removed.</p>
</dd></dl>
</li><li><p><i>Post-cut</i>: If <var>position</var> is greater than <var>subpath width</var>, then jump to the step labeled <i>convert</i>.</p></li><li><p>If <var>segment length</var> is greater than zero, then let
<var>positioned-at-on-dash</var> be false.</p></li><li><p>Increment <var>index</var> by one. If it is equal to the number of entries in
the <var>styles</var> <a href="#dash-list" id="line-styles:dash-list-8">dash list</a>, then let <var>index</var> be
0.</p></li><li><p>Return to the step labeled <i>dash on</i>.</p></li></ol>
</li><li>
<p><i>Convert</i>: This is the step that converts the path to a new path that represents its
stroke.</p>
<p>Create a new <a href="#concept-path" id="line-styles:concept-path-2">path</a> that describes the edge of the areas
that would be covered if a straight line of length equal to the <var>styles</var>
<code id="line-styles:dom-context-2d-linewidth-2-3"><a href="#dom-context-2d-linewidth-2">lineWidth</a></code> was swept along each subpath in <var>path</var> while being kept at an angle such that the line is orthogonal to the path
being swept, replacing each point with the end cap necessary to satisfy the <var>styles</var> <code id="line-styles:dom-context-2d-linecap-2-3"><a href="#dom-context-2d-linecap-2">lineCap</a></code> attribute as
described previously and elaborated below, and replacing each join with the join necessary to
satisfy the <var>styles</var> <code id="line-styles:dom-context-2d-linejoin-2-4"><a href="#dom-context-2d-linejoin-2">lineJoin</a></code>
type, as defined below.</p>
<p><strong>Caps</strong>: Each point has a flat edge perpendicular to the direction of the line
coming out of it. This is then augmented according to the value of the <var>styles</var> <code id="line-styles:dom-context-2d-linecap-2-4"><a href="#dom-context-2d-linecap-2">lineCap</a></code>. The &quot;<code>butt</code>&quot; value means that no additional line cap is added. The &quot;<code>round</code>&quot; value means that a semi-circle with the diameter equal to the <var>styles</var> <code id="line-styles:dom-context-2d-linewidth-2-4"><a href="#dom-context-2d-linewidth-2">lineWidth</a></code> width must
additionally be placed on to the line coming out of each point. The &quot;<code>square</code>&quot; value means that a rectangle with the length of the <var>styles</var> <code id="line-styles:dom-context-2d-linewidth-2-5"><a href="#dom-context-2d-linewidth-2">lineWidth</a></code> width and the
width of half the <var>styles</var> <code id="line-styles:dom-context-2d-linewidth-2-6"><a href="#dom-context-2d-linewidth-2">lineWidth</a></code> width, placed flat against the edge
perpendicular to the direction of the line coming out of the point, must be added at each
point.</p>
<p>Points with no lines coming out of them must have two caps placed back-to-back as if it was
really two points connected to each other by an infinitesimally short straight line in the
direction of the point's <i>directionality</i> (as defined above).</p>
<p><strong>Joins</strong>: In addition to the point where a join occurs, two additional points
are relevant to each join, one for each line: the two corners found half the line width away
from the join point, one perpendicular to each line, each on the side furthest from the other
line.</p>
<p>A triangle connecting these two opposite corners with a straight line, with the third point
of the triangle being the join point, must be added at all joins. The <code id="line-styles:dom-context-2d-linejoin-2-5"><a href="#dom-context-2d-linejoin-2">lineJoin</a></code> attribute controls whether anything else is
rendered. The three aforementioned values have the following meanings:</p>
<p>The &quot;<code>bevel</code>&quot; value means that this is all that is rendered at
joins.</p>
<p>The &quot;<code>round</code>&quot; value means that an arc connecting the two aforementioned
corners of the join, abutting (and not overlapping) the aforementioned triangle, with the
diameter equal to the line width and the origin at the point of the join, must be added at
joins.</p>
<p>The &quot;<code>miter</code>&quot; value means that a second triangle must (if it can given
the miter length) be added at the join, with one line being the line between the two
aforementioned corners, abutting the first triangle, and the other two being continuations of
the outside edges of the two joining lines, as long as required to intersect without going over
the miter length.</p>
<p>The miter length is the distance from the point where the join occurs to the intersection of
the line edges on the outside of the join. The miter limit ratio is the maximum allowed ratio of
the miter length to half the line width. If the miter length would cause the miter limit ratio
(as set by the <var>style</var> <code id="line-styles:dom-context-2d-miterlimit-2-3"><a href="#dom-context-2d-miterlimit-2">miterLimit</a></code> attribute) to be exceeded, then this second
triangle must not be added.</p>
<p>The subpaths in the newly created path must be oriented such that for any point, the number
of times a half-infinite straight line drawn from that point crosses a subpath is even if and
only if the number of times a half-infinite straight line drawn from that same point crosses a
subpath going in one direction is equal to the number of times it crosses a subpath going in the
other direction.</p>
</li><li><p>Return the newly created path.</p></li></ol>
<h6 id="text-styles"><span class="secno">4.12.5.1.4</span> Text styles<a class="self-link" href="#text-styles"/></h6>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-font"><a href="#dom-context-2d-font-2">font</a></code> [ = <var>value</var> ]</dt><dt><var>styles</var> . <code id="text-styles:dom-context-2d-font-2"><a href="#dom-context-2d-font-2">font</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current font settings.</p>
<p>Can be set, to change the font. The syntax is the same as for the CSS <a data-x-internal="'font'" href="https://drafts.csswg.org/css-fonts/#font-prop" id="text-styles:'font'">'font'</a>
property; values that cannot be parsed as CSS font values are ignored.</p>
<p>Relative keywords and lengths are computed relative to the font of the <code id="text-styles:the-canvas-element"><a href="#the-canvas-element">canvas</a></code>
element.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-textalign"><a href="#dom-context-2d-textalign-2">textAlign</a></code> [ = <var>value</var> ]</dt><dt><var>styles</var> . <code id="text-styles:dom-context-2d-textalign-2"><a href="#dom-context-2d-textalign-2">textAlign</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current text alignment settings.</p>
<p>Can be set, to change the alignment. The possible values are and their meanings are given
below. Other values are ignored. The default is &quot;<code>start</code>&quot;.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-textbaseline"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> [ = <var>value</var> ]</dt><dt><var>styles</var> . <code id="text-styles:dom-context-2d-textbaseline-2"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current baseline alignment settings.</p>
<p>Can be set, to change the baseline alignment. The possible values and their meanings are
given below. Other values are ignored. The default is &quot;<code id="text-styles:dom-context-2d-textbaseline-alphabetic"><a href="#dom-context-2d-textbaseline-alphabetic">alphabetic</a></code>&quot;.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-direction"><a href="#dom-context-2d-direction-2">direction</a></code> [ = <var>value</var> ]</dt><dt><var>styles</var> . <code id="text-styles:dom-context-2d-direction-2"><a href="#dom-context-2d-direction-2">direction</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current directionality.</p>
<p>Can be set, to change the directionality. The possible values and their meanings are given
below. Other values are ignored. The default is &quot;<code id="text-styles:dom-context-2d-direction-inherit"><a href="#dom-context-2d-direction-inherit">inherit</a></code>&quot;.</p>
</dd></dl>
<p>Objects that implement the <code id="text-styles:canvastextdrawingstyles"><a href="#canvastextdrawingstyles">CanvasTextDrawingStyles</a></code> interface have attributes
(defined in this section) that control how text is laid out (rasterized or outlined) by the
object. Such objects can also have a <dfn id="font-style-source-object">font style source object</dfn>. For
<code id="text-styles:canvasrenderingcontext2d"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> objects, this is the <code id="text-styles:the-canvas-element-2"><a href="#the-canvas-element">canvas</a></code> element
referenced by the context's canvas property.</p>
<p>The <dfn id="dom-context-2d-font-2"><code>font</code></dfn> IDL attribute, on setting, must
be <a data-x-internal="parse-something-according-to-a-css-grammar" href="https://drafts.csswg.org/css-syntax/#parse-grammar" id="text-styles:parse-something-according-to-a-css-grammar">parsed as a CSS &lt;'font'&gt;
value</a> (but without supporting property-independent style sheet syntax like 'inherit'), and
the resulting font must be assigned to the context, with the <a data-x-internal="'line-height'" href="https://drafts.csswg.org/css2/visudet.html#propdef-line-height" id="text-styles:'line-height'">'line-height'</a> component
forced to 'normal', with the <a data-x-internal="'font-size'" href="https://drafts.csswg.org/css-fonts/#font-size-prop" id="text-styles:'font-size'">'font-size'</a> component converted to <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="text-styles:'px'">CSS pixels</a>, and with system fonts being computed to explicit values. If the
new value is syntactically incorrect (including using property-independent style sheet syntax like
'inherit' or 'initial'), then it must be ignored, without assigning a new font value. <a href="https://html.spec.whatwg.org/multipage/references.html#refsCSS">[CSS]</a></p>
<p>Font family names must be interpreted in the context of the <a href="#font-style-source-object" id="text-styles:font-style-source-object">font style source
object</a> when the font is to be used; any fonts embedded using <code>@font-face</code> or loaded using <code id="text-styles:fontface"><a href="https://html.spec.whatwg.org/multipage/infrastructure.html#fontface">FontFace</a></code> objects that are visible to the
<a href="#font-style-source-object" id="text-styles:font-style-source-object-2">font style source object</a> must therefore be available once they are loaded. (Each <a href="#font-style-source-object" id="text-styles:font-style-source-object-3">font style source
object</a> has a <a data-x-internal="font-source" href="https://drafts.csswg.org/css-font-loading/#font-source" id="text-styles:font-source">font source</a>, which determines what fonts are available.) If a font
is used before it is fully loaded, or if the <a href="#font-style-source-object" id="text-styles:font-style-source-object-4">font style source object</a> does not have
that font in scope at the time the font is to be used, then it must be treated as if it was an
unknown font, falling back to another as described by the relevant CSS specifications. <a href="https://html.spec.whatwg.org/multipage/references.html#refsCSSFONTS">[CSSFONTS]</a> <a href="https://html.spec.whatwg.org/multipage/references.html#refsCSSFONTLOAD">[CSSFONTLOAD]</a></p>
<p>On getting, the <code id="text-styles:dom-context-2d-font-2-2"><a href="#dom-context-2d-font-2">font</a></code> attribute must return the <a data-x-internal="serializing-a-css-value" href="https://drafts.csswg.org/cssom/#serialize-a-css-value" id="text-styles:serializing-a-css-value">serialized form</a> of the current font of the context (with
no <a data-x-internal="'line-height'" href="https://drafts.csswg.org/css2/visudet.html#propdef-line-height" id="text-styles:'line-height'-2">'line-height'</a> component). <a href="https://html.spec.whatwg.org/multipage/references.html#refsCSSOM">[CSSOM]</a></p>
<div class="example">
<p>For example, after the following statement:</p>
<pre>context.font = 'italic 400 12px/2 Unknown Font, sans-serif';</pre>
<p>...the expression <code>context.font</code> would evaluate to the string &quot;<code>italic 12px &quot;Unknown Font&quot;, sans-serif</code>&quot;. The &quot;400&quot;
font-weight doesn't appear because that is the default value. The line-height doesn't appear
because it is forced to &quot;normal&quot;, the default value.</p>
</div>
<p>When the object implementing the <code id="text-styles:canvastextdrawingstyles-2"><a href="#canvastextdrawingstyles">CanvasTextDrawingStyles</a></code> interface is created, the
font of the context must be set to 10px sans-serif. When the <a data-x-internal="'font-size'" href="https://drafts.csswg.org/css-fonts/#font-size-prop" id="text-styles:'font-size'-2">'font-size'</a> component is
set to lengths using percentages, <a data-x-internal="'em'" href="https://drafts.csswg.org/css-values/#em" id="text-styles:'em'">'em'</a> or <a data-x-internal="'ex'" href="https://drafts.csswg.org/css-values/#ex" id="text-styles:'ex'">'ex'</a> units, or the 'larger' or
'smaller' keywords, these must be interpreted relative to the <a data-x-internal="computed-value" href="https://drafts.csswg.org/css-cascade/#computed-value" id="text-styles:computed-value">computed value</a> of the
<a data-x-internal="'font-size'" href="https://drafts.csswg.org/css-fonts/#font-size-prop" id="text-styles:'font-size'-3">'font-size'</a> property of the <a href="#font-style-source-object" id="text-styles:font-style-source-object-5">font style source object</a> at the time that
the attribute is set, if it is an element. When the <a data-x-internal="'font-weight'" href="https://drafts.csswg.org/css-fonts/#font-weight-prop" id="text-styles:'font-weight'">'font-weight'</a> component is set to
the relative values 'bolder' and 'lighter', these must be interpreted relative to the
<a data-x-internal="computed-value" href="https://drafts.csswg.org/css-cascade/#computed-value" id="text-styles:computed-value-2">computed value</a> of the <a data-x-internal="'font-weight'" href="https://drafts.csswg.org/css-fonts/#font-weight-prop" id="text-styles:'font-weight'-2">'font-weight'</a> property of the <a href="#font-style-source-object" id="text-styles:font-style-source-object-6">font style
source object</a> at the time that the attribute is set, if it is an element. If the <a data-x-internal="computed-value" href="https://drafts.csswg.org/css-cascade/#computed-value" id="text-styles:computed-value-3">computed values</a> are undefined for a particular case (e.g. because
the <a href="#font-style-source-object" id="text-styles:font-style-source-object-7">font style source object</a> is not an element or is not <a href="https://html.spec.whatwg.org/multipage/rendering.html#being-rendered" id="text-styles:being-rendered">being
rendered</a>), then the relative keywords must be interpreted relative to the normal-weight
10px sans-serif default.</p>
<p>The <dfn id="dom-context-2d-textalign-2"><code>textAlign</code></dfn> IDL attribute, on
getting, must return the current value. On setting, the current value must be changed to the new
value. When the object implementing the <code id="text-styles:canvastextdrawingstyles-3"><a href="#canvastextdrawingstyles">CanvasTextDrawingStyles</a></code> interface is
created, the <code id="text-styles:dom-context-2d-textalign-2-2"><a href="#dom-context-2d-textalign-2">textAlign</a></code> attribute must initially
have the value <code id="text-styles:dom-context-2d-textalign-start"><a href="#dom-context-2d-textalign-start">start</a></code>.</p>
<p>The <dfn id="dom-context-2d-textbaseline-2"><code>textBaseline</code></dfn> IDL attribute, on
getting, must return the current value. On setting, the current value must be changed to the new
value. When the object implementing the <code id="text-styles:canvastextdrawingstyles-4"><a href="#canvastextdrawingstyles">CanvasTextDrawingStyles</a></code> interface is
created, the <code id="text-styles:dom-context-2d-textbaseline-2-2"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> attribute must
initially have the value <code id="text-styles:dom-context-2d-textbaseline-alphabetic-2"><a href="#dom-context-2d-textbaseline-alphabetic">alphabetic</a></code>.</p>
<p>The <dfn id="dom-context-2d-direction-2"><code>direction</code></dfn> IDL attribute, on
getting, must return the current value. On setting, the current value must be changed to the new
value. When the object implementing the <code id="text-styles:canvastextdrawingstyles-5"><a href="#canvastextdrawingstyles">CanvasTextDrawingStyles</a></code> interface is
created, the <code id="text-styles:dom-context-2d-direction-2-2"><a href="#dom-context-2d-direction-2">direction</a></code> attribute must initially
have the value &quot;<code id="text-styles:dom-context-2d-direction-inherit-2"><a href="#dom-context-2d-direction-inherit">inherit</a></code>&quot;.</p>
<p>The <code id="text-styles:dom-context-2d-textalign-2-3"><a href="#dom-context-2d-textalign-2">textAlign</a></code> attribute's allowed keywords are
as follows:</p>
<dl><dt><dfn id="dom-context-2d-textalign-start"><code>start</code></dfn>
</dt><dd><p>Align to the start edge of the text (left side in left-to-right text, right side in
right-to-left text).</p></dd><dt><dfn id="dom-context-2d-textalign-end"><code>end</code></dfn>
</dt><dd><p>Align to the end edge of the text (right side in left-to-right text, left side in
right-to-left text).</p></dd><dt><dfn id="dom-context-2d-textalign-left"><code>left</code></dfn>
</dt><dd><p>Align to the left.</p></dd><dt><dfn id="dom-context-2d-textalign-right"><code>right</code></dfn>
</dt><dd><p>Align to the right.</p></dd><dt><dfn id="dom-context-2d-textalign-center"><code>center</code></dfn>
</dt><dd><p>Align to the center.</p></dd></dl>
<p>The <code id="text-styles:dom-context-2d-textbaseline-2-3"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code>
attribute's allowed keywords correspond to alignment points in the
font:</p>
<p><img alt="The top of the em square is roughly at the top of the glyphs in a font, the hanging baseline is where some glyphs like आ are anchored, the middle is half-way between the top of the em square and the bottom of the em square, the alphabetic baseline is where characters like Á, ÿ, f, and Ω are anchored, the ideographic baseline is where glyphs like 私 and 達 are anchored, and the bottom of the em square is roughly at the bottom of the glyphs in a font. The top and bottom of the bounding box can be far from these baselines, due to glyphs extending far outside the em square." height="300" src="https://html.spec.whatwg.org/images/baselines.png" width="738"/></p>
<p>The keywords map to these alignment points as follows:</p>
<dl><dt><dfn id="dom-context-2d-textbaseline-top"><code>top</code></dfn>
</dt><dd>The top of the em square</dd><dt><dfn id="dom-context-2d-textbaseline-hanging"><code>hanging</code></dfn>
</dt><dd>The hanging baseline</dd><dt><dfn id="dom-context-2d-textbaseline-middle"><code>middle</code></dfn>
</dt><dd>The middle of the em square</dd><dt><dfn id="dom-context-2d-textbaseline-alphabetic"><code>alphabetic</code></dfn>
</dt><dd>The alphabetic baseline</dd><dt><dfn id="dom-context-2d-textbaseline-ideographic"><code>ideographic</code></dfn>
</dt><dd>The ideographic baseline</dd><dt><dfn id="dom-context-2d-textbaseline-bottom"><code>bottom</code></dfn>
</dt><dd>The bottom of the em square</dd></dl>
<p>The <code id="text-styles:dom-context-2d-direction-2-3"><a href="#dom-context-2d-direction-2">direction</a></code> attribute's allowed keywords are
as follows:</p>
<dl><dt><dfn id="dom-context-2d-direction-ltr"><code>ltr</code></dfn>
</dt><dd><p>Treat input to the <a href="#text-preparation-algorithm" id="text-styles:text-preparation-algorithm">text preparation algorithm</a> as left-to-right text.</p></dd><dt><dfn id="dom-context-2d-direction-rtl"><code>rtl</code></dfn>
</dt><dd><p>Treat input to the <a href="#text-preparation-algorithm" id="text-styles:text-preparation-algorithm-2">text preparation algorithm</a> as right-to-left text.</p></dd><dt><dfn id="dom-context-2d-direction-inherit"><code>inherit</code></dfn>
</dt><dd><p>Default to the directionality of the <code id="text-styles:the-canvas-element-3"><a href="#the-canvas-element">canvas</a></code> element or <code id="text-styles:document"><a href="https://html.spec.whatwg.org/multipage/dom.html#document">Document</a></code>
as appropriate.</p></dd></dl>
<p>The <dfn id="text-preparation-algorithm">text preparation algorithm</dfn> is as follows. It takes as input a string <var>text
</var>, a <code id="text-styles:canvastextdrawingstyles-6"><a href="#canvastextdrawingstyles">CanvasTextDrawingStyles</a></code> object <var>target</var>, and an optional length
<var>maxWidth</var>. It returns an array of glyph shapes, each positioned on a common coordinate
space, a <var>physical alignment</var> whose value is one of <i>left</i>, <i>right</i>, and
<i>center</i>, and an <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box">inline box</a>. (Most callers of this algorithm ignore the
<var>physical alignment</var> and the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-2">inline box</a>.)</p>
<ol><li><p>If <var>maxWidth</var> was provided but is less than or equal to zero or equal to NaN,
then return an empty array.</p></li><li><p>Replace all <a data-x-internal="space-characters" href="https://infra.spec.whatwg.org/#ascii-whitespace" id="text-styles:space-characters">ASCII whitespace</a> in <var>text</var> with U+0020 SPACE
characters.</p></li><li><p>Let <var>font</var> be the current font of <var>target</var>, as given
by that object's <code id="text-styles:dom-context-2d-font-2-3"><a href="#dom-context-2d-font-2">font</a></code> attribute.</p></li><li>
<p>Apply the appropriate step from the following list to determine the value of <var>direction</var>:</p>
<dl class="switch"><dt>If the <var>target</var> object's <code id="text-styles:dom-context-2d-direction-2-4"><a href="#dom-context-2d-direction-2">direction</a></code> attribute has the value &quot;<code id="text-styles:dom-context-2d-direction-ltr"><a href="#dom-context-2d-direction-ltr">ltr</a></code>&quot;</dt><dd>Let <var>direction</var> be '<a href="https://html.spec.whatwg.org/multipage/dom.html#concept-ltr" id="text-styles:concept-ltr">ltr</a>'.</dd><dt>If the <var>target</var> object's <code id="text-styles:dom-context-2d-direction-2-5"><a href="#dom-context-2d-direction-2">direction</a></code> attribute has the value &quot;<code id="text-styles:dom-context-2d-direction-rtl"><a href="#dom-context-2d-direction-rtl">rtl</a></code>&quot;</dt><dd>Let <var>direction</var> be '<a href="https://html.spec.whatwg.org/multipage/dom.html#concept-rtl" id="text-styles:concept-rtl">rtl</a>'.</dd><dt>If the <var>target</var> object's <a href="#font-style-source-object" id="text-styles:font-style-source-object-8">font style source object</a> is an
element</dt><dd>Let <var>direction</var> be <a href="https://html.spec.whatwg.org/multipage/dom.html#the-directionality" id="text-styles:the-directionality">the directionality</a> of the <var>target</var> object's <a href="#font-style-source-object" id="text-styles:font-style-source-object-9">font style source object</a>.</dd><dt>If the <var>target</var> object's <a href="#font-style-source-object" id="text-styles:font-style-source-object-10">font style source object</a> is a
<code id="text-styles:document-2"><a href="https://html.spec.whatwg.org/multipage/dom.html#document">Document</a></code> with a non-null <a data-x-internal="document-element" href="https://dom.spec.whatwg.org/#document-element" id="text-styles:document-element">document element</a></dt><dd>Let <var>direction</var> be <a href="https://html.spec.whatwg.org/multipage/dom.html#the-directionality" id="text-styles:the-directionality-2">the directionality</a> of the <var>target</var>
object's <a href="#font-style-source-object" id="text-styles:font-style-source-object-11">font style source object</a>'s <a data-x-internal="document-element" href="https://dom.spec.whatwg.org/#document-element" id="text-styles:document-element-2">document element</a>.</dd><dt>Otherwise</dt><dd>Let <var>direction</var> be '<a href="https://html.spec.whatwg.org/multipage/dom.html#concept-ltr" id="text-styles:concept-ltr-2">ltr</a>'.</dd></dl>
</li><li><p>Form a hypothetical infinitely-wide CSS <a data-x-internal="line-box" href="https://drafts.csswg.org/css2/visuren.html#line-box" id="text-styles:line-box">line box</a> containing a single
<a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-3">inline box</a> containing the text <var>text</var>, with all the properties at their
initial values except the <a data-x-internal="'font'" href="https://drafts.csswg.org/css-fonts/#font-prop" id="text-styles:'font'-2">'font'</a> property of the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-4">inline box</a> set to
<var>font</var>, the <a data-x-internal="'direction'" href="https://drafts.csswg.org/css-writing-modes/#direction" id="text-styles:'direction'">'direction'</a> property of the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-5">inline box</a> set to
<var>direction</var>, and the <a data-x-internal="'white-space'" href="https://drafts.csswg.org/css-text/#white-space-property" id="text-styles:'white-space'">'white-space'</a> property set to 'pre'. <a href="https://html.spec.whatwg.org/multipage/references.html#refsCSS">[CSS]</a></p></li><li><p>If <var>maxWidth</var> was provided and the hypothetical width of the
<a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-6">inline box</a> in the hypothetical <a data-x-internal="line-box" href="https://drafts.csswg.org/css2/visuren.html#line-box" id="text-styles:line-box-2">line box</a> is greater than
<var>maxWidth</var> <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="text-styles:'px'-2">CSS pixels</a>, then change <var>font</var> to have a
more condensed font (if one is available or if a reasonably readable one can be synthesized by
applying a horizontal scale factor to the font) or a smaller font, and return to the previous
step.</p></li><li>
<p>The <var>anchor point</var> is a point on the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-7">inline box</a>, and the <var>physical
alignment</var> is one of the values <i>left</i>, <i>right</i>, and <i>center</i>. These
variables are determined by the <code id="text-styles:dom-context-2d-textalign-2-4"><a href="#dom-context-2d-textalign-2">textAlign</a></code> and
<code id="text-styles:dom-context-2d-textbaseline-2-4"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> values as follows:</p>
<p>Horizontal position:</p>
<dl><dt>If <code id="text-styles:dom-context-2d-textalign-2-5"><a href="#dom-context-2d-textalign-2">textAlign</a></code> is <code id="text-styles:dom-context-2d-textalign-left"><a href="#dom-context-2d-textalign-left">left</a></code></dt><dt>If <code id="text-styles:dom-context-2d-textalign-2-6"><a href="#dom-context-2d-textalign-2">textAlign</a></code> is <code id="text-styles:dom-context-2d-textalign-start-2"><a href="#dom-context-2d-textalign-start">start</a></code> and <var>direction</var> is
'ltr'</dt><dt>If <code id="text-styles:dom-context-2d-textalign-2-7"><a href="#dom-context-2d-textalign-2">textAlign</a></code> is <code id="text-styles:dom-context-2d-textalign-end"><a href="#dom-context-2d-textalign-end">end</a></code> and <var>direction</var> is 'rtl'</dt><dd>Let the <var>anchor point</var>'s horizontal position be the left edge of the
<a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-8">inline box</a>, and let <var>physical alignment</var> be <i>left</i>.</dd><dt>If <code id="text-styles:dom-context-2d-textalign-2-8"><a href="#dom-context-2d-textalign-2">textAlign</a></code> is <code id="text-styles:dom-context-2d-textalign-right"><a href="#dom-context-2d-textalign-right">right</a></code></dt><dt>If <code id="text-styles:dom-context-2d-textalign-2-9"><a href="#dom-context-2d-textalign-2">textAlign</a></code> is <code id="text-styles:dom-context-2d-textalign-end-2"><a href="#dom-context-2d-textalign-end">end</a></code> and <var>direction</var> is 'ltr'</dt><dt>If <code id="text-styles:dom-context-2d-textalign-2-10"><a href="#dom-context-2d-textalign-2">textAlign</a></code> is <code id="text-styles:dom-context-2d-textalign-start-3"><a href="#dom-context-2d-textalign-start">start</a></code> and <var>direction</var> is
'rtl'</dt><dd>Let the <var>anchor point</var>'s horizontal position be the right edge of the
<a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-9">inline box</a>, and let <var>physical alignment</var> be <i>right</i>.</dd><dt>If <code id="text-styles:dom-context-2d-textalign-2-11"><a href="#dom-context-2d-textalign-2">textAlign</a></code> is <code id="text-styles:dom-context-2d-textalign-center"><a href="#dom-context-2d-textalign-center">center</a></code></dt><dd>Let the <var>anchor point</var>'s horizontal position be half way between the left
and right edges of the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-10">inline box</a>, and let <var>physical alignment</var> be
<i>center</i>.</dd></dl>
<p>Vertical position:</p>
<dl><dt>If <code id="text-styles:dom-context-2d-textbaseline-2-5"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> is <code id="text-styles:dom-context-2d-textbaseline-top"><a href="#dom-context-2d-textbaseline-top">top</a></code></dt><dd>Let the <var>anchor point</var>'s vertical position be the top of the em box of
the first available font of the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-11">inline box</a>.</dd><dt>If <code id="text-styles:dom-context-2d-textbaseline-2-6"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> is <code id="text-styles:dom-context-2d-textbaseline-hanging"><a href="#dom-context-2d-textbaseline-hanging">hanging</a></code></dt><dd>Let the <var>anchor point</var>'s vertical position be the hanging baseline of the
first available font of the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-12">inline box</a>.</dd><dt>If <code id="text-styles:dom-context-2d-textbaseline-2-7"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> is <code id="text-styles:dom-context-2d-textbaseline-middle"><a href="#dom-context-2d-textbaseline-middle">middle</a></code></dt><dd>Let the <var>anchor point</var>'s vertical position be half way between the bottom
and the top of the em box of the first available font of the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-13">inline box</a>.</dd><dt>If <code id="text-styles:dom-context-2d-textbaseline-2-8"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> is <code id="text-styles:dom-context-2d-textbaseline-alphabetic-3"><a href="#dom-context-2d-textbaseline-alphabetic">alphabetic</a></code></dt><dd>Let the <var>anchor point</var>'s vertical position be the alphabetic baseline of
the first available font of the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-14">inline box</a>.</dd><dt>If <code id="text-styles:dom-context-2d-textbaseline-2-9"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> is <code id="text-styles:dom-context-2d-textbaseline-ideographic"><a href="#dom-context-2d-textbaseline-ideographic">ideographic</a></code></dt><dd>Let the <var>anchor point</var>'s vertical position be the ideographic baseline of
the first available font of the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-15">inline box</a>.</dd><dt>If <code id="text-styles:dom-context-2d-textbaseline-2-10"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> is <code id="text-styles:dom-context-2d-textbaseline-bottom"><a href="#dom-context-2d-textbaseline-bottom">bottom</a></code></dt><dd>Let the <var>anchor point</var>'s vertical position be the bottom of the em box of
the first available font of the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-16">inline box</a>.</dd></dl>
</li><li>
<p>Let <var>result</var> be an array constructed by iterating over each glyph in the
<a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-17">inline box</a> from left to right (if any), adding to the array, for each glyph, the
shape of the glyph as it is in the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="text-styles:inline-box-18">inline box</a>, positioned on a coordinate space
using <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="text-styles:'px'-3">CSS pixels</a> with its origin is at the <var>anchor
point</var>.</p>
</li><li><p>Return <var>result</var>, <var>physical alignment</var>, and the inline
box.</p></li></ol>
<h6 id="building-paths"><span class="secno">4.12.5.1.5</span> Building paths<a class="self-link" href="#building-paths"/></h6>
<p>Objects that implement the <code id="building-paths:canvaspath"><a href="#canvaspath">CanvasPath</a></code> interface have a <a href="#concept-path" id="building-paths:concept-path">path</a>. A <dfn id="concept-path">path</dfn> has a list of zero or
more subpaths. Each subpath consists of a list of one or more points, connected by straight or
curved <dfn id="line-segments">line segments</dfn>, and a flag indicating whether the subpath is closed or not. A
closed subpath is one where the last point of the subpath is connected to the first point of the
subpath by a straight line. Subpaths with only one point are ignored when painting the path.</p>
<p><a href="#concept-path" id="building-paths:concept-path-2">Paths</a> have a <dfn id="need-new-subpath">need new subpath</dfn> flag. When this
flag is set, certain APIs create a new subpath rather than extending the previous one. When a
<a href="#concept-path" id="building-paths:concept-path-3">path</a> is created, its <a href="#need-new-subpath" id="building-paths:need-new-subpath">need new subpath</a> flag must be
set.</p>
<p>When an object implementing the <code id="building-paths:canvaspath-2"><a href="#canvaspath">CanvasPath</a></code> interface is created, its <a href="#concept-path" id="building-paths:concept-path-4">path</a> must be initialized to zero subpaths.</p>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-moveto"><a href="#dom-context-2d-moveto-2">moveTo</a></code>(<var>x</var>, <var>y</var>)</dt><dt><var>path</var> . <code id="building-paths:dom-context-2d-moveto-2"><a href="#dom-context-2d-moveto-2">moveTo</a></code>(<var>x</var>, <var>y</var>)</dt><dd>
<p>Creates a new subpath with the given point.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-closepath"><a href="#dom-context-2d-closepath-2">closePath</a></code>()</dt><dt><var>path</var> . <code id="building-paths:dom-context-2d-closepath-2"><a href="#dom-context-2d-closepath-2">closePath</a></code>()</dt><dd>
<p>Marks the current subpath as closed, and starts a new subpath with a point the same as the
start and end of the newly closed subpath.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-lineto"><a href="#dom-context-2d-lineto-2">lineTo</a></code>(<var>x</var>, <var>y</var>)</dt><dt><var>path</var> . <code id="building-paths:dom-context-2d-lineto-2"><a href="#dom-context-2d-lineto-2">lineTo</a></code>(<var>x</var>, <var>y</var>)</dt><dd>
<p>Adds the given point to the current subpath, connected to the previous one by a straight
line.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-quadraticcurveto"><a href="#dom-context-2d-quadraticcurveto-2">quadraticCurveTo</a></code>(<var>cpx</var>, <var>cpy</var>, <var>x</var>, <var>y</var>)</dt><dt><var>path</var> . <code id="building-paths:dom-context-2d-quadraticcurveto-2"><a href="#dom-context-2d-quadraticcurveto-2">quadraticCurveTo</a></code>(<var>cpx</var>, <var>cpy</var>, <var>x</var>, <var>y</var>)</dt><dd>
<p>Adds the given point to the current subpath, connected to the previous one by a quadratic
Bézier curve with the given control point.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-beziercurveto"><a href="#dom-context-2d-beziercurveto-2">bezierCurveTo</a></code>(<var>cp1x</var>, <var>cp1y</var>, <var>cp2x</var>, <var>cp2y</var>, <var>x</var>, <var>y</var>)</dt><dt><var>path</var> . <code id="building-paths:dom-context-2d-beziercurveto-2"><a href="#dom-context-2d-beziercurveto-2">bezierCurveTo</a></code>(<var>cp1x</var>, <var>cp1y</var>, <var>cp2x</var>, <var>cp2y</var>, <var>x</var>, <var>y</var>)</dt><dd>
<p>Adds the given point to the current subpath, connected to the previous one by a cubic
Bézier curve with the given control points.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-arcto"><a href="#dom-context-2d-arcto-2">arcTo</a></code>(<var>x1</var>, <var>y1</var>, <var>x2</var>, <var>y2</var>, <var>radiusX</var> [, <var>radiusY</var>, <var>rotation</var> ] )</dt><dt><var>path</var> . <code id="building-paths:dom-context-2d-arcto-2"><a href="#dom-context-2d-arcto-2">arcTo</a></code>(<var>x1</var>, <var>y1</var>, <var>x2</var>, <var>y2</var>, <var>radiusX</var> [, <var>radiusY</var>, <var>rotation</var> ] )</dt><dd>
<p>Adds an arc with the given control points and radius to the current subpath, connected to the
previous point by a straight line.</p>
<p>If two radii are provided, then the first controls the width of the arc's ellipse, and the
second controls the height. If only one is provided, or if they are the same, then the arc is
from a circle. In the case of an ellipse, the rotation argument controls the clockwise
inclination of the ellipse relative to the x-axis.</p>
<p>Throws an <a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="building-paths:indexsizeerror">&quot;<code>IndexSizeError</code>&quot;</a> <code id="building-paths:domexception"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> if the given
radius is negative.</p>
<figure class="diagrams">
<img alt="" height="254" src="https://html.spec.whatwg.org/images/arcTo1.png" width="357"/>
<img alt="" height="310" src="https://html.spec.whatwg.org/images/arcTo2.png" width="468"/>
<img alt="" height="233" src="https://html.spec.whatwg.org/images/arcTo3.png" width="513"/>
</figure>
</dd><dt><var>context</var> . <code id="dom-context-2d-arc"><a href="#dom-context-2d-arc-2">arc</a></code>(<var>x</var>, <var>y</var>, <var>radius</var>, <var>startAngle</var>, <var>endAngle</var> [, <var>anticlockwise</var> ] )</dt><dt><var>path</var> . <code id="building-paths:dom-context-2d-arc-2"><a href="#dom-context-2d-arc-2">arc</a></code>(<var>x</var>, <var>y</var>, <var>radius</var>, <var>startAngle</var>, <var>endAngle</var> [, <var>anticlockwise</var> ] )</dt><dd>
<p>Adds points to the subpath such that the arc described by the circumference of the circle
described by the arguments, starting at the given start angle and ending at the given end angle,
going in the given direction (defaulting to clockwise), is added to the path, connected to the
previous point by a straight line.</p>
<p>Throws an <a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="building-paths:indexsizeerror-2">&quot;<code>IndexSizeError</code>&quot;</a> <code id="building-paths:domexception-2"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> if the given
radius is negative.</p>
<figure class="diagrams">
<img alt="" height="255" src="https://html.spec.whatwg.org/images/arc1.png" width="590"/>
</figure>
</dd><dt><var>context</var> . <code id="dom-context-2d-ellipse"><a href="#dom-context-2d-ellipse-2">ellipse</a></code>(<var>x</var>, <var>y</var>, <var>radiusX</var>, <var>radiusY</var>, <var>rotation</var>, <var>startAngle</var>, <var>endAngle</var> [, <var>anticlockwise</var>] )</dt><dt><var>path</var> . <code id="building-paths:dom-context-2d-ellipse-2"><a href="#dom-context-2d-ellipse-2">ellipse</a></code>(<var>x</var>, <var>y</var>, <var>radiusX</var>, <var>radiusY</var>, <var>rotation</var>, <var>startAngle</var>, <var>endAngle</var> [, <var>anticlockwise</var>] )</dt><dd>
<p>Adds points to the subpath such that the arc described by the circumference of the ellipse
described by the arguments, starting at the given start angle and ending at the given end angle,
going in the given direction (defaulting to clockwise), is added to the path, connected to the
previous point by a straight line.</p>
<p>Throws an <a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="building-paths:indexsizeerror-3">&quot;<code>IndexSizeError</code>&quot;</a> <code id="building-paths:domexception-3"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> if the given
radius is negative.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-rect"><a href="#dom-context-2d-rect-2">rect</a></code>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>)</dt><dt><var>path</var> . <code id="building-paths:dom-context-2d-rect-2"><a href="#dom-context-2d-rect-2">rect</a></code>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>)</dt><dd>
<p>Adds a new closed subpath to the path, representing the given rectangle.</p>
</dd></dl>
<p>The following methods allow authors to manipulate the <a href="#concept-path" id="building-paths:concept-path-5">paths</a>
of objects implementing the <code id="building-paths:canvaspath-3"><a href="#canvaspath">CanvasPath</a></code> interface.</p>
<p>For objects implementing the <code id="building-paths:canvasdrawpath"><a href="#canvasdrawpath">CanvasDrawPath</a></code> and <code id="building-paths:canvastransform"><a href="#canvastransform">CanvasTransform</a></code>
interfaces, the points passed to the methods, and the resulting lines added to <a href="#current-default-path" id="building-paths:current-default-path">current
default path</a> by these methods, must be transformed according to the <a href="#transformations" id="building-paths:transformations">current transformation matrix</a> before being added to
the path.</p>
<p>The <dfn id="dom-context-2d-moveto-2"><code>moveTo(<var>x</var>, <var>y</var>)</code></dfn>
method, when invoked, must run these steps:</p>
<ol><li><p>If either of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>Create a new subpath with the specified point as its first (and only) point.</p></li></ol>
<p>When the user agent is to <dfn id="ensure-there-is-a-subpath">ensure there is a subpath</dfn> for a coordinate (<var>x</var>,
<var>y</var>) on a <a href="#concept-path" id="building-paths:concept-path-6">path</a>, the user agent must check to see if
the <a href="#concept-path" id="building-paths:concept-path-7">path</a> has its <a href="#need-new-subpath" id="building-paths:need-new-subpath-2">need new subpath</a> flag set. If it
does, then the user agent must create a new subpath with the point (<var>x</var>, <var>y</var>) as
its first (and only) point, as if the <code id="building-paths:dom-context-2d-moveto-2-2"><a href="#dom-context-2d-moveto-2">moveTo()</a></code> method
had been called, and must then unset the <a href="#concept-path" id="building-paths:concept-path-8">path</a>'s <a href="#need-new-subpath" id="building-paths:need-new-subpath-3">need new
subpath</a> flag.</p>
<p>The <dfn id="dom-context-2d-closepath-2"><code>closePath()</code></dfn> method, when invoked,
must do nothing if the object's path has no subpaths. Otherwise, it must mark the last subpath as
closed, create a new subpath whose first point is the same as the previous subpath's first point,
and finally add this new subpath to the path.</p>
<p class="note">If the last subpath had more than one point in its list of points, then this is
equivalent to adding a straight line connecting the last point back to the first point, thus
&quot;closing&quot; the shape, and then repeating the last (possibly implied) <code id="building-paths:dom-context-2d-moveto-2-3"><a href="#dom-context-2d-moveto-2">moveTo()</a></code> call.</p>
<p>New points and the lines connecting them are added to subpaths using the methods described
below. In all cases, the methods only modify the last subpath in the object's path.</p>
<p>The <dfn id="dom-context-2d-lineto-2"><code>lineTo(<var>x</var>, <var>y</var>)</code></dfn>
method, when invoked, must run these steps:</p>
<ol><li><p>If either of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>If the object's path has no subpaths, then <a href="#ensure-there-is-a-subpath" id="building-paths:ensure-there-is-a-subpath">ensure there is a subpath</a> for
<span>(<var>x</var>, <var>y</var>)</span>.</p></li><li><p>Otherwise, connect the last point in the subpath to the given point (<var>x</var>,
<var>y</var>) using a straight line, and then add the given point (<var>x</var>, <var>y</var>) to
the subpath.</p></li></ol>
<p>The <dfn id="dom-context-2d-quadraticcurveto-2"><code>quadraticCurveTo(<var>cpx</var>,
<var>cpy</var>, <var>x</var>, <var>y</var>)</code></dfn> method, when invoked, must run these
steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p><a href="#ensure-there-is-a-subpath" id="building-paths:ensure-there-is-a-subpath-2">Ensure there is a subpath</a> for <span>(<var>cpx</var>,
<var>cpy</var>)</span></p></li><li><p>Connect the last point in the subpath to the given point (<var>x</var>, <var>y</var>)
using a quadratic Bézier curve with control point (<var>cpx</var>, <var>cpy</var>). <a href="https://html.spec.whatwg.org/multipage/references.html#refsBEZIER">[BEZIER]</a></p></li><li><p>Add the given point (<var>x</var>, <var>y</var>) to the subpath.</p></li></ol>
<p>The <dfn id="dom-context-2d-beziercurveto-2"><code>bezierCurveTo(<var>cp1x</var>,
<var>cp1y</var>, <var>cp2x</var>, <var>cp2y</var>, <var>x</var>, <var>y</var>)</code></dfn>
method, when invoked, must run these steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p><a href="#ensure-there-is-a-subpath" id="building-paths:ensure-there-is-a-subpath-3">Ensure there is a subpath</a> for <span>(<var>cp1x</var>,
<var>cp1y</var>)</span>.</p></li><li><p>Connect the last point in the subpath to the given point (<var>x</var>, <var>y</var>)
using a cubic Bézier curve with control points (<var>cp1x</var>, <var>cp1y</var>) and
(<var>cp2x</var>, <var>cp2y</var>). <a href="https://html.spec.whatwg.org/multipage/references.html#refsBEZIER">[BEZIER]</a></p></li><li><p>Add the point (<var>x</var>, <var>y</var>) to the subpath.</p></li></ol>
<hr/>
<p>The <dfn id="dom-context-2d-arcto-2"><code>arcTo(<var>x1</var>, <var>y1</var>, <var>x2</var>,
<var>y2</var>, <var>radiusX</var>, <var>radiusY</var>, <var>rotation</var>)</code></dfn> method,
when invoked, must run these steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p><a href="#ensure-there-is-a-subpath" id="building-paths:ensure-there-is-a-subpath-4">Ensure there is a subpath</a> for <span>(<var>x1</var>,
<var>y1</var>)</span>.</p></li><li><p>If either <var>radiusX</var> or <var>radiusY</var> are negative, then throw an
<a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="building-paths:indexsizeerror-4">&quot;<code>IndexSizeError</code>&quot;</a> <code id="building-paths:domexception-4"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.</p></li><li><p>If <var>radiusY</var> is omitted, then set <var>radiusY</var> to
<var>radiusX</var>.</p></li><li><p>Let the point (<var>x0</var>, <var>y0</var>) be the last point in the subpath, transformed
by the inverse of the <a href="#transformations" id="building-paths:transformations-2">current transformation
matrix</a> (so that it is in the same coordinate system as the points passed to the
method).</p></li><li><p>If the point (<var>x0</var>, <var>y0</var>) is equal to the point (<var>x1</var>,
<var>y1</var>), or if the point (<var>x1</var>, <var>y1</var>) is equal to the point
(<var>x2</var>, <var>y2</var>), or if both <var>radiusX</var> and <var>radiusY</var> are zero,
then add the point (<var>x1</var>, <var>y1</var>) to the subpath, and connect that point to the
previous point (<var>x0</var>, <var>y0</var>) by a straight line.</p></li><li><p>Otherwise, if the points (<var>x0</var>, <var>y0</var>), (<var>x1</var>, <var>y1</var>),
and (<var>x2</var>, <var>y2</var>) all lie on a single straight line, then add the point
(<var>x1</var>, <var>y1</var>) to the subpath, and connect that point to the previous point
(<var>x0</var>, <var>y0</var>) by a straight line.</p></li><li><p>Otherwise, let <var>The Arc</var> be the shortest arc given by circumference of the
ellipse that has radius <var>radiusX</var> on the major axis and radius <var>radiusY</var> on the
minor axis, and whose semi-major axis is rotated <var>rotation</var> radians clockwise from the
positive x-axis, and that has one point tangent to the half-infinite line that crosses the point
(<var>x0</var>, <var>y0</var>) and ends at the point (<var>x1</var>, <var>y1</var>), and that has
a different point tangent to the half-infinite line that ends at the point (<var>x1</var>,
<var>y1</var>) and crosses the point (<var>x2</var>, <var>y2</var>). The points at which this
ellipse touches these two lines are called the start and end tangent points respectively. Connect
the point (<var>x0</var>, <var>y0</var>) to the start tangent point by a straight line, adding
the start tangent point to the subpath, and then connect the start tangent point to the end
tangent point by <var>The Arc</var>, adding the end tangent point to the subpath.</p></li></ol>
<hr/>
<p>The <dfn id="dom-context-2d-arc-2"><code>arc(<var>x</var>, <var>y</var>,
<var>radius</var>, <var>startAngle</var>, <var>endAngle</var>, <var>anticlockwise</var>)</code></dfn> and <dfn id="dom-context-2d-ellipse-2"><code>ellipse(<var>x</var>, <var>y</var>, <var>radiusX</var>, <var>radiusY</var>, <var>rotation</var>, <var>startAngle</var>, <var>endAngle</var>, <var>anticlockwise</var>)</code></dfn> methods draw arcs.</p>
<p>The <code id="building-paths:dom-context-2d-arc-2-2"><a href="#dom-context-2d-arc-2">arc()</a></code> method is equivalent to the <code id="building-paths:dom-context-2d-ellipse-2-2"><a href="#dom-context-2d-ellipse-2">ellipse()</a></code> method in the case where the two radii are equal.
When the <code id="building-paths:dom-context-2d-arc-2-3"><a href="#dom-context-2d-arc-2">arc()</a></code> method is invoked, it must act as if the
<code id="building-paths:dom-context-2d-ellipse-2-3"><a href="#dom-context-2d-ellipse-2">ellipse()</a></code> method had been invoked with the <var>radiusX</var> and <var>radiusY</var> arguments set to the value of the <var>radius</var> argument, the <var>rotation</var> argument set to zero, and the
other arguments set to the same values as their identically named arguments on the <code id="building-paths:dom-context-2d-arc-2-4"><a href="#dom-context-2d-arc-2">arc()</a></code> method.</p>
<p>The <code id="building-paths:dom-context-2d-ellipse-2-4"><a href="#dom-context-2d-ellipse-2">ellipse()</a></code> method, when invoked, must run these
steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>If either <var>radiusX</var> or <var>radiusY</var> are negative, then throw an
<a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="building-paths:indexsizeerror-5">&quot;<code>IndexSizeError</code>&quot;</a> <code id="building-paths:domexception-5"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.</p></li><li><p>If the object's path has any subpaths, then add a straight line from the last point in the
subpath to the start point of the arc.</p></li><li>
<p>Add the start and end points of the arc to the subpath, and connect them with an arc. The arc
and its start and end points are defined as follows:</p>
<p>Consider an ellipse that has its origin at (<var>x</var>, <var>y</var>), that has a
major-axis radius <var>radiusX</var> and a minor-axis radius <var>radiusY</var>, and that is
rotated about its origin such that its semi-major axis is inclined <var>rotation</var> radians
clockwise from the x-axis.</p>
<p>If <var>anticlockwise</var> is false and <span><var>endAngle</var>-<var>startAngle</var></span> is equal to or greater than <span>2π</span>, or, if <var>anticlockwise</var> is <em>true</em> and <span><var>startAngle</var>-<var>endAngle</var></span> is equal to or greater than <span>2π</span>, then the arc is the whole circumference of this ellipse, and the point
at <var>startAngle</var> along this circle's circumference, measured in radians clockwise from
the ellipse's semi-major axis, acts as both the start point and the end point.</p>
<p>Otherwise, the points at <var>startAngle</var> and <var>endAngle</var> along this circle's
circumference, measured in radians clockwise from the ellipse's semi-major axis, are the start
and end points respectively, and the arc is the path along the circumference of this ellipse
from the start point to the end point, going anti-clockwise if <var>anticlockwise</var> is true,
and clockwise otherwise. Since the points are on the ellipse, as opposed to being simply angles
from zero, the arc can never cover an angle greater than <span>2π</span>
radians.</p>
<p class="note">Even if the arc covers the entire circumference of the ellipse and there are no
other points in the subpath, the path is not closed unless the <code id="building-paths:dom-context-2d-closepath-2-2"><a href="#dom-context-2d-closepath-2">closePath()</a></code> method is appropriately invoked.</p>
</li></ol>
<hr/>
<p>The <dfn id="dom-context-2d-rect-2"><code>rect(<var>x</var>, <var>y</var>, <var>w</var>,
<var>h</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>Create a new subpath containing just the four points (<var>x</var>, <var>y</var>),
(<var>x</var>+<var>w</var>, <var>y</var>), (<var>x</var>+<var>w</var>,
<var>y</var>+<var>h</var>), (<var>x</var>, <var>y</var>+<var>h</var>), in that order, with those
four points connected by straight lines.</p></li><li><p>Mark the subpath as closed.</p></li><li><p>Create a new subpath with the point (<var>x</var>, <var>y</var>) as the only point in the
subpath.</p></li></ol>
<h6 id="path2d-objects"><span class="secno">4.12.5.1.6</span> <code id="path2d-objects:path2d"><a href="#path2d">Path2D</a></code> objects<a class="self-link" href="#path2d-objects"/></h6>
<p><code id="path2d-objects:path2d-2"><a href="#path2d">Path2D</a></code> objects can be used to declare paths that are then later used on
objects implementing the <code id="path2d-objects:canvasdrawpath"><a href="#canvasdrawpath">CanvasDrawPath</a></code> interface. In addition to many of the APIs
described in earlier sections, <code id="path2d-objects:path2d-3"><a href="#path2d">Path2D</a></code> objects have methods to combine paths, and to
add text to paths.</p>
<dl class="domintro"><dt><var>path</var> = new <code id="path2d-objects:dom-path2d"><a href="#dom-path2d">Path2D</a></code>()</dt><dd>
<p>Creates a new empty <code id="path2d-objects:path2d-4"><a href="#path2d">Path2D</a></code> object.</p>
</dd><dt><var>path</var> = new <code id="path2d-objects:dom-path2d-copy"><a href="#dom-path2d-copy">Path2D</a></code>(<var>path</var>)</dt><dd>
<p>Creates a new <code id="path2d-objects:path2d-5"><a href="#path2d">Path2D</a></code> object that is a copy of the argument.</p>
</dd><dt><var>path</var> = new <code id="path2d-objects:dom-path2d-merge"><a href="#dom-path2d-merge">Path2D</a></code>(<var>paths</var> [, <var>fillRule</var> ] )</dt><dd>
<p>Creates a new <code id="path2d-objects:path2d-6"><a href="#path2d">Path2D</a></code> object that describes a path that outlines the given <var>paths</var>, using the given fill rule.</p>
</dd><dt><var>path</var> = new <code id="path2d-objects:dom-path2d-withdata"><a href="#dom-path2d-withdata">Path2D</a></code>(<var>d</var>)</dt><dd>
<p>Creates a new path with the path described by the argument, interpreted as SVG path data. <a href="https://html.spec.whatwg.org/multipage/references.html#refsSVG">[SVG]</a></p>
</dd><dt><var>path</var> . <code id="dom-path2d-addpath"><a href="#dom-path2d-addpath-2">addPath</a></code>(<var>path</var> [, <var>transform</var> ] )</dt><dd>
<p>Adds to the path the path given by the argument.</p>
</dd></dl>
<p>The <dfn id="dom-path2d"><code>Path2D()</code></dfn> constructor, when invoked, must return a
newly created <code id="path2d-objects:path2d-7"><a href="#path2d">Path2D</a></code> object.</p>
<hr/>
<p>The <dfn id="dom-path2d-copy"><code>Path2D(<var>path</var>)</code></dfn>
constructor, when invoked, must return a newly created <code id="path2d-objects:path2d-8"><a href="#path2d">Path2D</a></code> object, to which the
subpaths of the argument are added. (In other words, it returns a copy of the argument.)</p>
<hr/>
<p>The <dfn id="dom-path2d-merge"><code>Path2D(<var>paths</var>,
<var>fillRule</var>)</code></dfn> constructor, when invoked, must run these steps:</p>
<ol><li>
<p>Run the appropriate step from the following list, based on the constructor's second
argument:</p>
<dl class="switch"><dt>If it is &quot;nonzero&quot;</dt><dd>
<p>Let <var>merged path</var> be a <a href="#concept-path" id="path2d-objects:concept-path">path</a> that
consists of a set of non-overlapping subpaths that exactly outline the points from which, in
any of the <a href="#concept-path" id="path2d-objects:concept-path-2">paths</a> provided in the constructor's first
argument, the number of times a half-infinite straight line drawn from that point crosses a
subpath going in one direction is not equal to the number of times it crosses a subpath going
in the other direction.</p>
</dd><dt>If it is &quot;evenodd&quot;</dt><dd>
<p>Let <var>merged path</var> be a <a href="#concept-path" id="path2d-objects:concept-path-3">path</a> that
consists of a set of non-overlapping subpaths that exactly outline the points from which, in
any of the <a href="#concept-path" id="path2d-objects:concept-path-4">paths</a> provided in the constructor's first
argument, the number of times a half-infinite straight line drawn from that point crosses that
path is odd.</p>
</dd></dl>
<p>The subpaths in <var>merged path</var> must be oriented such that for any point,
the number of times a half-infinite straight line drawn from that point crosses a subpath is
even if and only if the number of times a half-infinite straight line drawn from that same point
crosses a subpath going in one direction is equal to the number of times it crosses a subpath
going in the other direction.</p>
</li><li><p>Add all the subpaths in <var>merged path</var> to the <code id="path2d-objects:path2d-9"><a href="#path2d">Path2D</a></code>
object.</p></li><li><p>Set the <code id="path2d-objects:path2d-10"><a href="#path2d">Path2D</a></code> object's <a href="#need-new-subpath" id="path2d-objects:need-new-subpath">need new subpath</a> flag.</p></li></ol>
<hr/>
<p>The <dfn id="dom-path2d-withdata"><code>Path2D(<var>d</var>)</code></dfn>
constructor, when invoked, must run these steps:</p>
<ol><li>
<p>Parse and interpret the <var>d</var> argument according to the SVG specification's
rules for path data, thus obtaining an SVG path. <a href="https://html.spec.whatwg.org/multipage/references.html#refsSVG">[SVG]</a></p>
<p class="note">The resulting path could be empty. SVG defines error handling rules for parsing
and applying path data.</p>
</li><li><p>Let (<var>x</var>, <var>y</var>) be the last point in the SVG
path.</p></li><li><p>Create a new <code id="path2d-objects:path2d-11"><a href="#path2d">Path2D</a></code> object and add all the subpaths in the SVG path, if any,
to that <code id="path2d-objects:path2d-12"><a href="#path2d">Path2D</a></code> object. </p>
</li><li><p>Create a new subpath in the <code id="path2d-objects:path2d-13"><a href="#path2d">Path2D</a></code> object with (<var>x</var>, <var>y</var>) as the only point in the subpath.</p></li><li><p>Return the <code id="path2d-objects:path2d-14"><a href="#path2d">Path2D</a></code> object as the constructed object.</p></li></ol>
<hr/>
<p>The <dfn id="dom-path2d-addpath-2"><code>addPath(<var>b</var>,
<var>transform</var>)</code></dfn> method, when invoked on a <code id="path2d-objects:path2d-15"><a href="#path2d">Path2D</a></code> object
<var>a</var>, must run these steps:</p>
<ol><li><p>If the <code id="path2d-objects:path2d-16"><a href="#path2d">Path2D</a></code> object <var>b</var> has no subpaths, then abort these
steps.</p></li><li><p>Create a copy of all the subpaths in <var>b</var>. Let this copy be known as <var>c</var>.</p></li><li><p>Let <var>matrix</var> be the result of <a data-x-internal="create-a-dommatrix-from-a-dictionary" href="https://drafts.fxtf.org/geometry/#create-a-dommatrix-from-the-dictionary" id="path2d-objects:create-a-dommatrix-from-a-dictionary">creating a <code>DOMMatrix</code> from a dictionary</a>
<var>transform</var>, with <var>ignore3D</var> set to true.</p></li><li><p>Transform all the coordinates and lines in <var>c</var> by the transform matrix
<var>matrix</var>.</p></li><li><p>Let (<var>x</var>, <var>y</var>) be the last point in the last subpath
of <var>c</var>.</p></li><li><p>Add all the subpaths in <var>c</var> to <var>a</var>.</p></li><li><p>Create a new subpath in <var>a</var> with (<var>x</var>, <var>y</var>) as the only point in the subpath.</p></li></ol>
<h6 id="transformations"><span class="secno">4.12.5.1.7</span> <dfn>Transformations</dfn><a class="self-link" href="#transformations"/></h6><div class="status"><input onclick="toggleStatus(this)" type="button" value="⋰"/><p class="bugs"><strong>Spec bugs:</strong> <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=28333" title="Show on example how a,b,c,d,e,f affect the point position">28333</a></p></div>
<p>Objects that implement the <code id="transformations:canvastransform"><a href="#canvastransform">CanvasTransform</a></code> interface have a <dfn id="current-transformation-matrix">current
transformation matrix</dfn>, as well as methods (described in this section) to manipulate it. When
an object implementing the <code id="transformations:canvastransform-2"><a href="#canvastransform">CanvasTransform</a></code> interface is created, its transformation
matrix must be initialized to the identity transform.</p>
<p>The <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix">current transformation matrix</a> is applied to coordinates when creating the
<a href="#current-default-path" id="transformations:current-default-path">current default path</a>, and when painting text, shapes, and <code id="transformations:path2d"><a href="#path2d">Path2D</a></code>
objects, on objects implementing the <code id="transformations:canvastransform-3"><a href="#canvastransform">CanvasTransform</a></code> interface.</p>
<p class="note">Most of the API uses <code id="transformations:dommatrix"><a data-x-internal="dommatrix" href="https://drafts.fxtf.org/geometry/#dommatrix">DOMMatrix</a></code> objects rather than this API. This API
remains mostly for historical reasons.</p>
<p>The transformations must be performed in reverse order.</p>
<p class="note">For instance, if a scale transformation that doubles the width is applied to the
canvas, followed by a rotation transformation that rotates drawing operations by a quarter turn,
and a rectangle twice as wide as it is tall is then drawn on the canvas, the actual result will be
a square.</p>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-scale"><a href="#dom-context-2d-scale-2">scale</a></code>(<var>x</var>, <var>y</var>)</dt><dd>
<p>Changes the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-2">current transformation matrix</a> to apply a scaling transformation
with the given characteristics.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-rotate"><a href="#dom-context-2d-rotate-2">rotate</a></code>(<var>angle</var>)</dt><dd>
<p>Changes the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-3">current transformation matrix</a> to apply a rotation transformation
with the given characteristics. The angle is in radians.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-translate"><a href="#dom-context-2d-translate-2">translate</a></code>(<var>x</var>, <var>y</var>)</dt><dd>
<p>Changes the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-4">current transformation matrix</a> to apply a translation transformation
with the given characteristics.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-transform"><a href="#dom-context-2d-transform-2">transform</a></code>(<var>a</var>, <var>b</var>, <var>c</var>, <var>d</var>, <var>e</var>, <var>f</var>)</dt><dd>
<p>Changes the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-5">current transformation matrix</a> to apply the matrix given by the
arguments as described below.</p>
</dd><dt><var>matrix</var> = <var>context</var> . <code id="dom-context-2d-gettransform"><a href="#dom-context-2d-gettransform-2">getTransform</a></code>()</dt><dd>
<p>Returns a copy of the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-6">current transformation matrix</a>, as a newly created
<code id="transformations:dommatrix-2"><a data-x-internal="dommatrix" href="https://drafts.fxtf.org/geometry/#dommatrix">DOMMatrix</a></code> object.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-settransform"><a href="#dom-context-2d-settransform-2">setTransform</a></code>(<var>a</var>, <var>b</var>, <var>c</var>, <var>d</var>, <var>e</var>, <var>f</var>)</dt><dd>
<p>Changes the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-7">current transformation matrix</a> <em>to</em> the matrix given by the
arguments as described below.</p>
</dd><dt><var>context</var> . <code id="transformations:dom-context-2d-settransform-2"><a href="#dom-context-2d-settransform-2">setTransform</a></code>(<var>transform</var>)</dt><dd>
<p>Changes the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-8">current transformation matrix</a> <em>to</em> the matrix represented by
the passed <code id="transformations:dommatrix2dinit"><a data-x-internal="dommatrix2dinit" href="https://drafts.fxtf.org/geometry/#dictdef-dommatrix2dinit">DOMMatrix2DInit</a></code> dictionary.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-resettransform"><a href="#dom-context-2d-resettransform-2">resetTransform</a></code>()</dt><dd>
<p>Changes the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-9">current transformation matrix</a> to the identity transform.</p>
</dd></dl>
<p>The <dfn id="dom-context-2d-scale-2"><code>scale(<var>x</var>, <var>y</var>)</code></dfn>
method, when invoked, must run these steps:</p>
<ol><li><p>If either of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>Add the scaling transformation described by the arguments to the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-10">current
transformation matrix</a>. The <var>x</var> argument represents the scale factor in the
horizontal direction and the <var>y</var> argument represents the scale factor in the vertical
direction. The factors are multiples.</p></li></ol>
<p>The <dfn id="dom-context-2d-rotate-2"><code>rotate(<var>angle</var>)</code></dfn> method,
when invoked, must run these steps:</p>
<ol><li><p>If <var>angle</var> is infinite or NaN, then abort these steps.</p></li><li><p>Add the rotation transformation described by the argument to the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-11">current
transformation matrix</a>. The <var>angle</var> argument represents a clockwise rotation angle
expressed in radians.</p></li></ol>
<p>The <dfn id="dom-context-2d-translate-2"><code>translate(<var>x</var>,
<var>y</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol><li><p>If either of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>Add the translation transformation described by the arguments to the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-12">current
transformation matrix</a>. The <var>x</var> argument represents the translation distance in
the horizontal direction and the <var>y</var> argument represents the translation distance in the
vertical direction. The arguments are in coordinate space units.</p></li></ol>
<p>The <dfn id="dom-context-2d-transform-2"><code>transform(<var>a</var>, <var>b</var>,
<var>c</var>, <var>d</var>, <var>e</var>, <var>f</var>)</code></dfn> method, when invoked, must
run these steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>Replace the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-13">current transformation matrix</a> with the result of multiplying the
current transformation matrix with the matrix described by:</p></li></ol>
<table class="matrix"><tbody><tr><td><var>a</var></td><td><var>c</var></td><td><var>e</var></td></tr><tr><td><var>b</var></td><td><var>d</var></td><td><var>f</var></td></tr><tr><td>0</td><td>0</td><td>1</td></tr></tbody></table>
<p class="note">The arguments <var>a</var>, <var>b</var>, <var>c</var>, <var>d</var>,
<var>e</var>, and <var>f</var> are sometimes called <var>m11</var>, <var>m12</var>,
<var>m21</var>, <var>m22</var>, <var>dx</var>, and <var>dy</var> or <var>m11</var>,
<var>m21</var>, <var>m12</var>, <var>m22</var>, <var>dx</var>, and <var>dy</var>. Care ought to be
taken in particular with the order of the second and third arguments (<var>b</var> and
<var>c</var>) as their order varies from API to API and APIs sometimes use the notation
<var>m12</var>/<var>m21</var> and sometimes <var>m21</var>/<var>m12</var> for those positions.</p>
<p>The <dfn id="dom-context-2d-gettransform-2"><code>getTransform()</code></dfn> method, when
invoked, must return a newly created <code id="transformations:dommatrix-3"><a data-x-internal="dommatrix" href="https://drafts.fxtf.org/geometry/#dommatrix">DOMMatrix</a></code> representing a copy of the
<a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-14">current transformation matrix</a> matrix of the context.</p>
<p class="note">This returned object is not live, so updating it will not affect the
<a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-15">current transformation matrix</a>, and updating the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-16">current transformation
matrix</a> will not affect an already returned <code id="transformations:dommatrix-4"><a data-x-internal="dommatrix" href="https://drafts.fxtf.org/geometry/#dommatrix">DOMMatrix</a></code>.</p>
<p>The <dfn id="dom-context-2d-settransform-2"><code>setTransform(<var>a</var>, <var>b</var>,
<var>c</var>, <var>d</var>, <var>e</var>, <var>f</var>)</code></dfn> method, when invoked, must
run these steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>Reset the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-17">current transformation matrix</a> to the identity matrix.</p></li><li><p>Invoke the <code><a href="#dom-context-2d-transform-2" id="transformations:dom-context-2d-transform-2">transform</a>(<var>a</var>, <var>b</var>, <var>c</var>,
<var>d</var>, <var>e</var>, <var>f</var>)</code> method with the same arguments.</p></li></ol>
<p>The <dfn><code>setTransform(<var>transform</var>)</code></dfn> method, when invoked,
must reset the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-18">current transformation matrix</a> to the value represented by the result
of <a data-x-internal="create-a-dommatrix-from-a-dictionary" href="https://drafts.fxtf.org/geometry/#create-a-dommatrix-from-the-dictionary" id="transformations:create-a-dommatrix-from-a-dictionary">creating a <code>DOMMatrix</code> from a
dictionary</a> <var>transform</var>, with <var>ignore3D</var> set to true.</p>
<p>The <dfn id="dom-context-2d-resettransform-2"><code>resetTransform()</code></dfn> method,
when invoked, must reset the <a href="#current-transformation-matrix" id="transformations:current-transformation-matrix-19">current transformation matrix</a> to the identity
matrix.</p>
<h6 id="image-sources-for-2d-rendering-contexts"><span class="secno">4.12.5.1.8</span> Image sources for 2D rendering contexts<a class="self-link" href="#image-sources-for-2d-rendering-contexts"/></h6>
<p>Some methods on the <code id="image-sources-for-2d-rendering-contexts:canvasdrawimage"><a href="#canvasdrawimage">CanvasDrawImage</a></code> and <code id="image-sources-for-2d-rendering-contexts:canvasfillstrokestyles"><a href="#canvasfillstrokestyles">CanvasFillStrokeStyles</a></code>
interfaces take the union type <code id="image-sources-for-2d-rendering-contexts:canvasimagesource"><a href="#canvasimagesource">CanvasImageSource</a></code> as an argument.</p>
<p>This union type allows objects implementing any of the following interfaces to be used as image
sources:</p>
<ul><li><code id="image-sources-for-2d-rendering-contexts:htmlorsvgimageelement"><a href="#htmlorsvgimageelement">HTMLOrSVGImageElement</a></code> (<code id="image-sources-for-2d-rendering-contexts:the-img-element"><a href="https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element">img</a></code> or <a data-x-internal="svg-image" href="https://www.w3.org/TR/SVG11/struct.html#ImageElement" id="image-sources-for-2d-rendering-contexts:svg-image">SVG <code>image</code></a>
elements)</li><li><code id="image-sources-for-2d-rendering-contexts:htmlvideoelement"><a href="https://html.spec.whatwg.org/multipage/media.html#htmlvideoelement">HTMLVideoElement</a></code> (<code id="image-sources-for-2d-rendering-contexts:the-video-element"><a href="https://html.spec.whatwg.org/multipage/media.html#the-video-element">video</a></code> elements)</li><li><code id="image-sources-for-2d-rendering-contexts:htmlcanvaselement"><a href="#htmlcanvaselement">HTMLCanvasElement</a></code> (<code id="image-sources-for-2d-rendering-contexts:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> elements)</li><li><code id="image-sources-for-2d-rendering-contexts:imagebitmap"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code></li></ul>
<p class="note">Although not formally specified as such, <a data-x-internal="svg-image" href="https://www.w3.org/TR/SVG11/struct.html#ImageElement" id="image-sources-for-2d-rendering-contexts:svg-image-2">SVG <code>image</code></a>
elements are expected to be implemented nearly identical to <code id="image-sources-for-2d-rendering-contexts:the-img-element-2"><a href="https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element">img</a></code> elements. That is,
<a data-x-internal="svg-image" href="https://www.w3.org/TR/SVG11/struct.html#ImageElement" id="image-sources-for-2d-rendering-contexts:svg-image-3">SVG <code>image</code></a> elements share the fundamental concepts and features of
<code id="image-sources-for-2d-rendering-contexts:the-img-element-3"><a href="https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element">img</a></code> elements.</p>
<p class="note">The <code id="image-sources-for-2d-rendering-contexts:imagebitmap-2"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code> interface can be created from a number of other
image-representing types, including <code id="image-sources-for-2d-rendering-contexts:imagedata"><a href="#imagedata">ImageData</a></code>.</p>
<p>When a user agent is required to <dfn id="check-the-usability-of-the-image-argument">check the usability of the <var>image</var>
argument</dfn>, where <var>image</var> is a <code id="image-sources-for-2d-rendering-contexts:canvasimagesource-2"><a href="#canvasimagesource">CanvasImageSource</a></code> object, the
user agent must run these steps, which return either <i>good</i>, <i>bad</i>, or
<i>aborted</i>:</p>
<ol><li><p>If <var>image</var> is an <code id="image-sources-for-2d-rendering-contexts:htmlorsvgimageelement-2"><a href="#htmlorsvgimageelement">HTMLOrSVGImageElement</a></code> object that is in the <a href="https://html.spec.whatwg.org/multipage/images.html#img-error" id="image-sources-for-2d-rendering-contexts:img-error">broken</a> state, then throw an
<a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="image-sources-for-2d-rendering-contexts:invalidstateerror">&quot;<code>InvalidStateError</code>&quot;</a> <code id="image-sources-for-2d-rendering-contexts:domexception"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>, return <i>aborted</i>,
and abort these steps.</p></li><li><p>If <var>image</var> is an <code id="image-sources-for-2d-rendering-contexts:htmlorsvgimageelement-3"><a href="#htmlorsvgimageelement">HTMLOrSVGImageElement</a></code> object that is not <a href="https://html.spec.whatwg.org/multipage/images.html#img-good" id="image-sources-for-2d-rendering-contexts:img-good">fully decodable</a>, or if <var>image</var> is an
<code id="image-sources-for-2d-rendering-contexts:htmlvideoelement-2"><a href="https://html.spec.whatwg.org/multipage/media.html#htmlvideoelement">HTMLVideoElement</a></code> object whose <code id="image-sources-for-2d-rendering-contexts:dom-media-readystate-2"><a href="https://html.spec.whatwg.org/multipage/media.html#dom-media-readystate-2">readyState</a></code>
attribute is either <code id="image-sources-for-2d-rendering-contexts:dom-media-have_nothing"><a href="https://html.spec.whatwg.org/multipage/media.html#dom-media-have_nothing">HAVE_NOTHING</a></code> or <code id="image-sources-for-2d-rendering-contexts:dom-media-have_metadata"><a href="https://html.spec.whatwg.org/multipage/media.html#dom-media-have_metadata">HAVE_METADATA</a></code>, then return <i>bad</i> and abort these
steps.</p></li><li><p>If <var>image</var> is an <code id="image-sources-for-2d-rendering-contexts:htmlorsvgimageelement-4"><a href="#htmlorsvgimageelement">HTMLOrSVGImageElement</a></code> object with an
<a href="https://html.spec.whatwg.org/multipage/infrastructure.html#intrinsic-width" id="image-sources-for-2d-rendering-contexts:intrinsic-width">intrinsic width</a> or <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#intrinsic-height" id="image-sources-for-2d-rendering-contexts:intrinsic-height">intrinsic height</a> (or both) equal to zero, then
return <i>bad</i> and abort these steps.</p></li><li><p>If <var>image</var> is an <code id="image-sources-for-2d-rendering-contexts:htmlcanvaselement-2"><a href="#htmlcanvaselement">HTMLCanvasElement</a></code> object with either a horizontal
dimension or a vertical dimension equal to zero, then return <i>bad</i> and abort these
steps.</p></li><li><p>If <var>image</var> is an <code id="image-sources-for-2d-rendering-contexts:imagebitmap-3"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code> object with its
<a href="https://html.spec.whatwg.org/multipage/structured-data.html#detached" id="image-sources-for-2d-rendering-contexts:detached">[[Detached]]</a> internal slot value set to true, then throw an
<a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="image-sources-for-2d-rendering-contexts:invalidstateerror-2">&quot;<code>InvalidStateError</code>&quot;</a> <code id="image-sources-for-2d-rendering-contexts:domexception-2"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>, return <i>aborted</i>,
and abort these steps.</p></li><li><p>Return <i>good</i>.</p></li></ol>
<p>When a <code id="image-sources-for-2d-rendering-contexts:canvasimagesource-3"><a href="#canvasimagesource">CanvasImageSource</a></code> object represents an <code id="image-sources-for-2d-rendering-contexts:htmlorsvgimageelement-5"><a href="#htmlorsvgimageelement">HTMLOrSVGImageElement</a></code>,
the element's image must be used as the source image.</p>
<p>Specifically, when a <code id="image-sources-for-2d-rendering-contexts:canvasimagesource-4"><a href="#canvasimagesource">CanvasImageSource</a></code> object represents an animated image in an
<code id="image-sources-for-2d-rendering-contexts:htmlorsvgimageelement-6"><a href="#htmlorsvgimageelement">HTMLOrSVGImageElement</a></code>, the user agent must use the default image of the animation
(the one that the format defines is to be used when animation is not supported or is disabled),
or, if there is no such image, the first frame of the animation, when rendering the image for
<code id="image-sources-for-2d-rendering-contexts:canvasrenderingcontext2d"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> APIs.</p>
<p>When a <code id="image-sources-for-2d-rendering-contexts:canvasimagesource-5"><a href="#canvasimagesource">CanvasImageSource</a></code> object represents an <code id="image-sources-for-2d-rendering-contexts:htmlvideoelement-3"><a href="https://html.spec.whatwg.org/multipage/media.html#htmlvideoelement">HTMLVideoElement</a></code>, then
the frame at the <a href="https://html.spec.whatwg.org/multipage/media.html#current-playback-position" id="image-sources-for-2d-rendering-contexts:current-playback-position">current playback position</a> when the method with the argument is
invoked must be used as the source image when rendering the image for
<code id="image-sources-for-2d-rendering-contexts:canvasrenderingcontext2d-2"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> APIs, and the source image's dimensions must be the <a href="https://html.spec.whatwg.org/multipage/media.html#concept-video-intrinsic-width" id="image-sources-for-2d-rendering-contexts:concept-video-intrinsic-width">intrinsic width</a> and <a href="https://html.spec.whatwg.org/multipage/media.html#concept-video-intrinsic-height" id="image-sources-for-2d-rendering-contexts:concept-video-intrinsic-height">intrinsic height</a> of the <a href="https://html.spec.whatwg.org/multipage/media.html#media-resource" id="image-sources-for-2d-rendering-contexts:media-resource">media resource</a>
(i.e. after any aspect-ratio correction has been applied).</p>
<p>When a <code id="image-sources-for-2d-rendering-contexts:canvasimagesource-6"><a href="#canvasimagesource">CanvasImageSource</a></code> object represents an <code id="image-sources-for-2d-rendering-contexts:htmlcanvaselement-3"><a href="#htmlcanvaselement">HTMLCanvasElement</a></code>, the
element's bitmap must be used as the source image.</p>
<p>When a <code id="image-sources-for-2d-rendering-contexts:canvasimagesource-7"><a href="#canvasimagesource">CanvasImageSource</a></code> object represents an element that is <a href="https://html.spec.whatwg.org/multipage/rendering.html#being-rendered" id="image-sources-for-2d-rendering-contexts:being-rendered">being
rendered</a> and that element has been resized, the original image data of the source image
must be used, not the image as it is rendered (e.g. <code id="image-sources-for-2d-rendering-contexts:attr-dim-width"><a href="https://html.spec.whatwg.org/multipage/embedded-content-other.html#attr-dim-width">width</a></code> and
<code id="image-sources-for-2d-rendering-contexts:attr-dim-height"><a href="https://html.spec.whatwg.org/multipage/embedded-content-other.html#attr-dim-height">height</a></code> attributes on the source element have no effect on how
the object is interpreted when rendering the image for <code id="image-sources-for-2d-rendering-contexts:canvasrenderingcontext2d-3"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>
APIs).</p>
<p>When a <code id="image-sources-for-2d-rendering-contexts:canvasimagesource-8"><a href="#canvasimagesource">CanvasImageSource</a></code> object represents an <code id="image-sources-for-2d-rendering-contexts:imagebitmap-4"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code>, the
object's bitmap image data must be used as the source image.</p>
<p><dfn id="the-image-argument-is-not-origin-clean">The <var>image argument</var> is not origin-clean</dfn> if it is an
<code id="image-sources-for-2d-rendering-contexts:htmlorsvgimageelement-7"><a href="#htmlorsvgimageelement">HTMLOrSVGImageElement</a></code> or <code id="image-sources-for-2d-rendering-contexts:htmlvideoelement-4"><a href="https://html.spec.whatwg.org/multipage/media.html#htmlvideoelement">HTMLVideoElement</a></code> whose <a href="https://html.spec.whatwg.org/multipage/origin.html#concept-origin" id="image-sources-for-2d-rendering-contexts:concept-origin">origin</a> is
not the <a href="https://html.spec.whatwg.org/multipage/origin.html#same-origin" id="image-sources-for-2d-rendering-contexts:same-origin">same</a> as the <a href="https://html.spec.whatwg.org/multipage/webappapis.html#concept-settings-object-origin" id="image-sources-for-2d-rendering-contexts:concept-settings-object-origin">origin</a> specified by the <a href="https://html.spec.whatwg.org/multipage/webappapis.html#entry-settings-object" id="image-sources-for-2d-rendering-contexts:entry-settings-object">entry settings
object</a>, or if it is an <code id="image-sources-for-2d-rendering-contexts:htmlcanvaselement-4"><a href="#htmlcanvaselement">HTMLCanvasElement</a></code> whose bitmap's <a href="#concept-canvas-origin-clean" id="image-sources-for-2d-rendering-contexts:concept-canvas-origin-clean">origin-clean</a> flag is false.</p>
<h6 id="fill-and-stroke-styles"><span class="secno">4.12.5.1.9</span> Fill and stroke styles<a class="self-link" href="#fill-and-stroke-styles"/></h6>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-fillstyle"><a href="#dom-context-2d-fillstyle-2">fillStyle</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current style used for filling shapes.</p>
<p>Can be set, to change the fill style.</p>
<p>The style can be either a string containing a CSS color, or a <code id="fill-and-stroke-styles:canvasgradient"><a href="#canvasgradient">CanvasGradient</a></code> or
<code id="fill-and-stroke-styles:canvaspattern"><a href="#canvaspattern">CanvasPattern</a></code> object. Invalid values are ignored.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-strokestyle"><a href="#dom-context-2d-strokestyle-2">strokeStyle</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current style used for stroking shapes.</p>
<p>Can be set, to change the stroke style.</p>
<p>The style can be either a string containing a CSS color, or a <code id="fill-and-stroke-styles:canvasgradient-2"><a href="#canvasgradient">CanvasGradient</a></code> or
<code id="fill-and-stroke-styles:canvaspattern-2"><a href="#canvaspattern">CanvasPattern</a></code> object. Invalid values are ignored.</p>
</dd></dl>
<p>Objects that implement the <code id="fill-and-stroke-styles:canvasfillstrokestyles"><a href="#canvasfillstrokestyles">CanvasFillStrokeStyles</a></code> interface have attributes and
methods (defined in this section) that control how shapes are treated by the object.</p>
<p>The <dfn id="dom-context-2d-fillstyle-2"><code>fillStyle</code></dfn> attribute represents the
color or style to use inside shapes, and the <dfn id="dom-context-2d-strokestyle-2"><code>strokeStyle</code></dfn> attribute represents the color
or style to use for the lines around the shapes.</p>
<p>Both attributes can be either strings, <code id="fill-and-stroke-styles:canvasgradient-3"><a href="#canvasgradient">CanvasGradient</a></code>s, or
<code id="fill-and-stroke-styles:canvaspattern-3"><a href="#canvaspattern">CanvasPattern</a></code>s. On setting, strings must be <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#parsed-as-a-css-color-value" id="fill-and-stroke-styles:parsed-as-a-css-color-value">parsed as CSS &lt;color&gt; values</a> and the color assigned, and
<code id="fill-and-stroke-styles:canvasgradient-4"><a href="#canvasgradient">CanvasGradient</a></code> and <code id="fill-and-stroke-styles:canvaspattern-4"><a href="#canvaspattern">CanvasPattern</a></code> objects must be assigned themselves. <a href="https://html.spec.whatwg.org/multipage/references.html#refsCSSCOLOR">[CSSCOLOR]</a> If the value is a string but cannot be <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#parsed-as-a-css-color-value" id="fill-and-stroke-styles:parsed-as-a-css-color-value-2">parsed as a CSS
&lt;color&gt; value</a>, then it must be ignored, and the attribute must retain its previous
value.
If the new value is a <code id="fill-and-stroke-styles:canvaspattern-5"><a href="#canvaspattern">CanvasPattern</a></code> object that is marked as <a href="#concept-canvas-pattern-not-origin-clean" id="fill-and-stroke-styles:concept-canvas-pattern-not-origin-clean">not origin-clean</a>, then the
<code id="fill-and-stroke-styles:canvasrenderingcontext2d"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>'s <a href="#concept-canvas-origin-clean" id="fill-and-stroke-styles:concept-canvas-origin-clean">origin-clean</a> flag must be set to false.
</p>
<p>When set to a <code id="fill-and-stroke-styles:canvaspattern-6"><a href="#canvaspattern">CanvasPattern</a></code> or <code id="fill-and-stroke-styles:canvasgradient-5"><a href="#canvasgradient">CanvasGradient</a></code> object, the assignment
is <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#live" id="fill-and-stroke-styles:live">live</a>, meaning that changes made to the object after the assignment do affect
subsequent stroking or filling of shapes.</p>
<p>On getting, if the value is a color, then the <a href="#serialisation-of-a-color" id="fill-and-stroke-styles:serialisation-of-a-color">serialization of the color</a> must be returned. Otherwise, if it is not a color but a
<code id="fill-and-stroke-styles:canvasgradient-6"><a href="#canvasgradient">CanvasGradient</a></code> or <code id="fill-and-stroke-styles:canvaspattern-7"><a href="#canvaspattern">CanvasPattern</a></code>, then the respective object must be
returned. (Such objects are opaque and therefore only useful for assigning to other attributes or
for comparison to other gradients or patterns.)</p>
<p>The <dfn id="serialisation-of-a-color">serialization of a color</dfn> for a color
value is a string, computed as follows: if it has alpha equal to 1.0, then the string is a
lowercase six-digit hex value, prefixed with a &quot;#&quot; character (U+0023 NUMBER SIGN), with the first
two digits representing the red component, the next two digits representing the green component,
and the last two digits representing the blue component, the digits being <a data-x-internal="lowercase-ascii-hex-digits" href="https://infra.spec.whatwg.org/#ascii-lower-hex-digit" id="fill-and-stroke-styles:lowercase-ascii-hex-digits">ASCII lower hex digits</a>. Otherwise, the color value has alpha less than
1.0, and the string is the color value in the CSS <code>rgba()</code>
functional-notation format: the literal string &quot;<code>rgba</code>&quot; (U+0072 U+0067 U+0062
U+0061) followed by a U+0028 LEFT PARENTHESIS, a base-ten integer in the range 0-255 representing
the red component (using <a data-x-internal="ascii-digits" href="https://infra.spec.whatwg.org/#ascii-digit" id="fill-and-stroke-styles:ascii-digits">ASCII digits</a> in the shortest form possible), a literal
U+002C COMMA and U+0020 SPACE, an integer for the green component, a comma and a space, an integer
for the blue component, another comma and space, a U+0030 DIGIT ZERO, if the alpha value is
greater than zero then a U+002E FULL STOP (representing the decimal point), if the alpha value is
greater than zero then one or more <a data-x-internal="ascii-digits" href="https://infra.spec.whatwg.org/#ascii-digit" id="fill-and-stroke-styles:ascii-digits-2">ASCII digits</a> representing the fractional part of
the alpha, and finally a U+0029
RIGHT PARENTHESIS. User agents must express the fractional part of the alpha value, if any, with
the level of precision necessary for the alpha value, when reparsed, to be interpreted as the same
alpha value.</p>
<p>When the context is created, the <code id="fill-and-stroke-styles:dom-context-2d-fillstyle-2"><a href="#dom-context-2d-fillstyle-2">fillStyle</a></code> and <code id="fill-and-stroke-styles:dom-context-2d-strokestyle-2"><a href="#dom-context-2d-strokestyle-2">strokeStyle</a></code> attributes
must initially have the string value <code>#000000</code>.</p>
<p>When the value is a color, it must not be affected by the transformation matrix when used to
draw on bitmaps.</p>
<hr/>
<p>There are two types of gradients, linear gradients and radial gradients, both represented by
objects implementing the opaque <code id="fill-and-stroke-styles:canvasgradient-7"><a href="#canvasgradient">CanvasGradient</a></code> interface.</p>
<p id="interpolation">Once a gradient has been created (see below), stops are placed along it to
define how the colors are distributed along the gradient. The color of the
gradient at each stop is the color specified for that stop. Between each such stop, the colors and
the alpha component must be linearly interpolated over the RGBA space without premultiplying the
alpha value to find the color to use at that offset. Before the first stop, the color must be the
color of the first stop. After the last stop, the color must be the color of the last stop. When
there are no stops, the gradient is transparent black.</p>
<dl class="domintro"><dt><var>gradient</var> . <code id="dom-canvasgradient-addcolorstop"><a href="#dom-canvasgradient-addcolorstop-2">addColorStop</a></code>(<var>offset</var>, <var>color</var>)</dt><dd>
<p>Adds a color stop with the given color to the gradient at the given offset. 0.0 is the offset
at one end of the gradient, 1.0 is the offset at the other end.</p>
<p>Throws an <a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="fill-and-stroke-styles:indexsizeerror">&quot;<code>IndexSizeError</code>&quot;</a> <code id="fill-and-stroke-styles:domexception"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> if the offset
is out of range. Throws a <a data-x-internal="syntaxerror" href="https://heycam.github.io/webidl/#syntaxerror" id="fill-and-stroke-styles:syntaxerror">&quot;<code>SyntaxError</code>&quot;</a> <code id="fill-and-stroke-styles:domexception-2"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> if
the color cannot be parsed.</p>
</dd><dt><var>gradient</var> = <var>context</var> . <code id="dom-context-2d-createlineargradient"><a href="#dom-context-2d-createlineargradient-2">createLinearGradient</a></code>(<var>x0</var>, <var>y0</var>, <var>x1</var>, <var>y1</var>)</dt><dd>
<p>Returns a <code id="fill-and-stroke-styles:canvasgradient-8"><a href="#canvasgradient">CanvasGradient</a></code> object that represents a
linear gradient that paints along the line given by the
coordinates represented by the arguments.</p>
</dd><dt><var>gradient</var> = <var>context</var> . <code id="dom-context-2d-createradialgradient"><a href="#dom-context-2d-createradialgradient-2">createRadialGradient</a></code>(<var>x0</var>, <var>y0</var>, <var>r0</var>, <var>x1</var>, <var>y1</var>, <var>r1</var>)</dt><dd>
<p>Returns a <code id="fill-and-stroke-styles:canvasgradient-9"><a href="#canvasgradient">CanvasGradient</a></code> object that represents a
radial gradient that paints along the cone given by the circles
represented by the arguments.</p>
<p>If either of the radii are negative, throws an
<a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="fill-and-stroke-styles:indexsizeerror-2">&quot;<code>IndexSizeError</code>&quot;</a> <code id="fill-and-stroke-styles:domexception-3"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> exception.</p>
</dd></dl>
<p>The <dfn id="dom-canvasgradient-addcolorstop-2"><code>addColorStop(<var>offset</var>,
<var>color</var>)</code></dfn> method on the <code id="fill-and-stroke-styles:canvasgradient-10"><a href="#canvasgradient">CanvasGradient</a></code> interface adds a new stop
to a gradient. If the <var>offset</var> is less than 0 or greater than 1 then an
<a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="fill-and-stroke-styles:indexsizeerror-3">&quot;<code>IndexSizeError</code>&quot;</a> <code id="fill-and-stroke-styles:domexception-4"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> must be thrown. If the
<var>color</var> cannot be <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#parsed-as-a-css-color-value" id="fill-and-stroke-styles:parsed-as-a-css-color-value-3">parsed as a CSS &lt;color&gt; value</a>, then a
<a data-x-internal="syntaxerror" href="https://heycam.github.io/webidl/#syntaxerror" id="fill-and-stroke-styles:syntaxerror-2">&quot;<code>SyntaxError</code>&quot;</a> <code id="fill-and-stroke-styles:domexception-5"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> must be thrown. Otherwise, the
gradient must have a new stop placed, at offset <var>offset</var> relative to the whole gradient,
and with the color obtained by <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#parsed-as-a-css-color-value" id="fill-and-stroke-styles:parsed-as-a-css-color-value-4">parsing
<var>color</var> as a CSS &lt;color&gt; value</a>. If multiple stops are added at the same
offset on a gradient, then they must be placed in the order added, with the first one closest to
the start of the gradient, and each subsequent one infinitesimally further along towards the end
point (in effect causing all but the first and last stop added at each point to be ignored).</p>
<p>The <dfn id="dom-context-2d-createlineargradient-2"><code>createLinearGradient(<var>x0</var>,
<var>y0</var>, <var>x1</var>, <var>y1</var>)</code></dfn> method takes four arguments that
represent the start point (<var>x0</var>, <var>y0</var>) and end point (<var>x1</var>,
<var>y1</var>) of the gradient. The method, when invoked, must return a linear
<code id="fill-and-stroke-styles:canvasgradient-11"><a href="#canvasgradient">CanvasGradient</a></code> initialized with the specified line.</p>
<p>Linear gradients must be rendered such that all points on a line perpendicular to the line that
crosses the start and end points have the color at the point where those two lines cross (with the
colors coming from the <a href="#interpolation">interpolation and extrapolation</a> described
above). The points in the linear gradient must be transformed as described by the <a href="#transformations" id="fill-and-stroke-styles:transformations">current transformation matrix</a> when rendering.</p>
<p>If <var>x0</var> = <var>x1</var> and <span><var>y0</var> = <var>y1</var></span>, then the linear
gradient must paint nothing.</p>
<p>The <dfn id="dom-context-2d-createradialgradient-2"><code>createRadialGradient(<var>x0</var>,
<var>y0</var>, <var>r0</var>, <var>x1</var>, <var>y1</var>, <var>r1</var>)</code></dfn> method
takes six arguments, the first three representing the start circle with origin (<var>x0</var>,
<var>y0</var>) and radius <var>r0</var>, and the last three representing the end circle with
origin (<var>x1</var>, <var>y1</var>) and radius <var>r1</var>. The values are in coordinate space
units. If either of <var>r0</var> or <var>r1</var> are negative, then an
<a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="fill-and-stroke-styles:indexsizeerror-4">&quot;<code>IndexSizeError</code>&quot;</a> <code id="fill-and-stroke-styles:domexception-6"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> must be thrown. Otherwise,
the method, when invoked, must return a radial <code id="fill-and-stroke-styles:canvasgradient-12"><a href="#canvasgradient">CanvasGradient</a></code> initialized with the
two specified circles.</p>
<p>Radial gradients must be rendered by following these steps:</p>
<ol><li><p>If <var>x<sub>0</sub></var> = <var>x<sub>1</sub></var> and <var>y<sub>0</sub></var> = <var>y<sub>1</sub></var> and <var>r<sub>0</sub></var> = <var>r<sub>1</sub></var>, then the radial gradient must
paint nothing. Abort these steps.</p></li><li>
<p>Let <span>x(<var>ω</var>) = (<var>x<sub>1</sub></var>-<var>x<sub>0</sub></var>)<var>ω</var> + <var>x<sub>0</sub></var></span></p>
<p>Let <span>y(<var>ω</var>) = (<var>y<sub>1</sub></var>-<var>y<sub>0</sub></var>)<var>ω</var> + <var>y<sub>0</sub></var></span></p>
<p>Let <span>r(<var>ω</var>) = (<var>r<sub>1</sub></var>-<var>r<sub>0</sub></var>)<var>ω</var> + <var>r<sub>0</sub></var></span></p>
<p>Let the color at <var>ω</var> be the color at that position on the gradient
(with the colors coming from the <a href="#interpolation">interpolation and extrapolation</a>
described above).</p>
</li><li><p>For all values of <var>ω</var> where <span>r(<var>ω</var>) &gt; 0</span>, starting with the value of <var>ω</var> nearest to positive infinity and ending with the value of <var>ω</var> nearest to negative infinity, draw the circumference of the circle with
radius <span>r(<var>ω</var>)</span> at position (<span>x(<var>ω</var>)</span>, <span>y(<var>ω</var>)</span>), with the
color at <var>ω</var>, but only painting on the parts of the bitmap that have not
yet been painted on by earlier circles in this step for this rendering of the gradient.</p></li></ol>
<p class="note">This effectively creates a cone, touched by the two circles defined in the
creation of the gradient, with the part of the cone before the start circle (0.0) using the color
of the first offset, the part of the cone after the end circle (1.0) using the color of the last
offset, and areas outside the cone untouched by the gradient (transparent black).</p>
<p>The resulting radial gradient must then be transformed as described by the <a href="#transformations" id="fill-and-stroke-styles:transformations-2">current transformation matrix</a> when rendering.</p>
<p>Gradients must be painted only where the relevant stroking or filling effects requires that
they be drawn.</p>
<hr/>
<p>Patterns are represented by objects implementing the opaque <code id="fill-and-stroke-styles:canvaspattern-8"><a href="#canvaspattern">CanvasPattern</a></code>
interface.</p>
<dl class="domintro"><dt><var>pattern</var> = <var>context</var> . <code id="dom-context-2d-createpattern"><a href="#dom-context-2d-createpattern-2">createPattern</a></code>(<var>image</var>, <var>repetition</var>)</dt><dd>
<p>Returns a <code id="fill-and-stroke-styles:canvaspattern-9"><a href="#canvaspattern">CanvasPattern</a></code> object that uses the given image and repeats in the
direction(s) given by the <var>repetition</var> argument.</p>
<p>The allowed values for <var>repetition</var> are <code>repeat</code> (both
directions), <code>repeat-x</code> (horizontal only), <code>repeat-y</code>
(vertical only), and <code>no-repeat</code> (neither). If the <var>repetition</var> argument is empty, the value <code>repeat</code> is used.</p>
<p>If the image isn't yet fully decoded, then nothing is drawn. If the image is a canvas with no
data, throws an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="fill-and-stroke-styles:invalidstateerror">&quot;<code>InvalidStateError</code>&quot;</a> <code id="fill-and-stroke-styles:domexception-7"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.</p>
</dd><dt><var>pattern</var> . <code id="dom-canvaspattern-settransform"><a href="#dom-canvaspattern-settransform-2">setTransform</a></code>(<var>transform</var>)</dt><dd>
<p>Sets the transformation matrix that will be used when rendering the pattern during a fill or
stroke painting operation.</p>
</dd></dl>
<p>The <dfn id="dom-context-2d-createpattern-2"><code>createPattern(<var>image</var>,
<var>repetition</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol><li><p>Let <var>image</var> be the first argument and <var>repetition</var> be
the second argument.</p></li><li><p><a href="#check-the-usability-of-the-image-argument" id="fill-and-stroke-styles:check-the-usability-of-the-image-argument">Check the usability of the <var>image</var> argument</a>. If this
returns <i>aborted</i>, then an exception has been thrown and the method doesn't return anything;
abort these steps. If it returns <i>bad</i>, then return null and abort these steps. Otherwise it
returns <i>good</i>; continue with these steps.</p></li><li><p>If <var>repetition</var> is the empty string, then set it to &quot;<code>repeat</code>&quot;.</p>
</li><li><p>If <var>repetition</var> is not a <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#case-sensitive" id="fill-and-stroke-styles:case-sensitive">case-sensitive</a> match for one of
&quot;<code>repeat</code>&quot;, &quot;<code>repeat-x</code>&quot;, &quot;<code>repeat-y</code>&quot;, or &quot;<code>no-repeat</code>&quot;, then throw a
<a data-x-internal="syntaxerror" href="https://heycam.github.io/webidl/#syntaxerror" id="fill-and-stroke-styles:syntaxerror-3">&quot;<code>SyntaxError</code>&quot;</a> <code id="fill-and-stroke-styles:domexception-8"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these steps.</p></li><li><p>Create a new <code id="fill-and-stroke-styles:canvaspattern-10"><a href="#canvaspattern">CanvasPattern</a></code> object with the image <var>image</var>
and the repetition behavior given by <var>repetition</var>.</p></li><li><p>If <a href="#the-image-argument-is-not-origin-clean" id="fill-and-stroke-styles:the-image-argument-is-not-origin-clean">the <var>image argument</var> is not origin-clean</a>, then mark the
<code id="fill-and-stroke-styles:canvaspattern-11"><a href="#canvaspattern">CanvasPattern</a></code> object as <dfn id="concept-canvas-pattern-not-origin-clean">not
origin-clean</dfn>.</p></li><li><p>Return the <code id="fill-and-stroke-styles:canvaspattern-12"><a href="#canvaspattern">CanvasPattern</a></code> object.</p></li></ol>
<p>Modifying the <var>image</var> used when creating a <code id="fill-and-stroke-styles:canvaspattern-13"><a href="#canvaspattern">CanvasPattern</a></code> object
after calling the <code id="fill-and-stroke-styles:dom-context-2d-createpattern-2"><a href="#dom-context-2d-createpattern-2">createPattern()</a></code> method must
not affect the pattern(s) rendered by the <code id="fill-and-stroke-styles:canvaspattern-14"><a href="#canvaspattern">CanvasPattern</a></code> object.</p>
<p>Patterns have a transformation matrix, which controls how the pattern is used when it is
painted. Initially, a pattern's transformation matrix must be the identity transform.</p>
<p>The <dfn id="dom-canvaspattern-settransform-2"><code>setTransform(<var>transform</var>)</code></dfn> method,
when invoked, must reset the pattern's transformation matrix to the value represented by the
result of <a data-x-internal="create-a-dommatrix-from-a-dictionary" href="https://drafts.fxtf.org/geometry/#create-a-dommatrix-from-the-dictionary" id="fill-and-stroke-styles:create-a-dommatrix-from-a-dictionary">creating a <code>DOMMatrix</code>
from a dictionary</a> <var>transform</var>, with <var>ignore3D</var> set to true.</p>
<p>When a pattern is to be rendered within an area, the user agent must run the following steps to
determine what is rendered:</p>
<ol><li><p>Create an infinite transparent black bitmap.</p></li><li>
<p>Place a copy of the image on the bitmap, anchored such that its top left corner is at the
origin of the coordinate space, with one coordinate space unit per <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="fill-and-stroke-styles:'px'">CSS
pixel</a> of the image, then place repeated copies of this image horizontally to the left and
right, if the repetition behavior is &quot;<code>repeat-x</code>&quot;, or vertically up and
down, if the repetition behavior is &quot;<code>repeat-y</code>&quot;, or in all four
directions all over the bitmap, if the repetition behavior is &quot;<code>repeat</code>&quot;.</p>
<p>If the original image data is a bitmap image, then the value painted at a point in the area
of the repetitions is computed by filtering the original image data. When scaling up, if the
<code id="fill-and-stroke-styles:dom-context-2d-imagesmoothingenabled-2"><a href="#dom-context-2d-imagesmoothingenabled-2">imageSmoothingEnabled</a></code> attribute is
set to false, then the image must be rendered using nearest-neighbor interpolation. Otherwise,
the user agent may use any filtering algorithm (for example bilinear interpolation or
nearest-neighbor). User agents which support multiple filtering algorithms may use the value of
the <code id="fill-and-stroke-styles:dom-context-2d-imagesmoothingquality-2"><a href="#dom-context-2d-imagesmoothingquality-2">imageSmoothingQuality</a></code> attribute
to guide the choice of filtering algorithm. When such a filtering algorithm requires a pixel
value from outside the original image data, it must instead use the value from wrapping the
pixel's coordinates to the original image's dimensions. (That is, the filter uses 'repeat'
behavior, regardless of the value of the pattern's repetition behavior.)</p>
</li><li><p>Transform the resulting bitmap according to the pattern's transformation matrix.</p></li><li><p>Transform the resulting bitmap again, this time according to the <a href="#transformations" id="fill-and-stroke-styles:transformations-3">current transformation matrix</a>.</p></li><li><p>Replace any part of the image outside the area in which the pattern is to be rendered with
transparent black.</p></li><li><p>The resulting bitmap is what is to be rendered, with the same origin and same
scale.</p></li></ol>
<hr/>
<p>If a radial gradient or repeated pattern is used when the transformation matrix is singular,
then the resulting style must be transparent black (otherwise the gradient or pattern would be
collapsed to a point or line, leaving the other pixels undefined). Linear gradients and solid
colors always define all points even with singular transformation matrices.</p>
<h6 id="drawing-rectangles-to-the-bitmap"><span class="secno">4.12.5.1.10</span> Drawing rectangles to the bitmap<a class="self-link" href="#drawing-rectangles-to-the-bitmap"/></h6>
<p>Objects that implement the <code id="drawing-rectangles-to-the-bitmap:canvasrect"><a href="#canvasrect">CanvasRect</a></code> interface provide the following methods for
immediately drawing rectangles to the bitmap. The methods each take four arguments; the first two
give the <var>x</var> and <var>y</var> coordinates of the top left of the rectangle, and the
second two give the width <var>w</var> and height <var>h</var> of the rectangle, respectively.</p>
<p>The <a href="#transformations" id="drawing-rectangles-to-the-bitmap:transformations">current transformation matrix</a> must be
applied to the following four coordinates, which form the path that must then be closed to get the
specified rectangle: <span>(<var>x</var>, <var>y</var>)</span>, <span>(<var>x</var>+<var>w</var>, <var>y</var>)</span>, <span>(<var>x</var>+<var>w</var>, <var>y</var>+<var>h</var>)</span>, <span>(<var>x</var>, <var>y</var>+<var>h</var>)</span>.</p>
<p>Shapes are painted without affecting the <a href="#current-default-path" id="drawing-rectangles-to-the-bitmap:current-default-path">current default path</a>, and are subject to
the <a href="#clipping-region" id="drawing-rectangles-to-the-bitmap:clipping-region">clipping region</a>, and, with the exception of <code id="drawing-rectangles-to-the-bitmap:dom-context-2d-clearrect-2"><a href="#dom-context-2d-clearrect-2">clearRect()</a></code>, also <a href="#shadows" id="drawing-rectangles-to-the-bitmap:shadows">shadow
effects</a>, <a href="#dom-context-2d-globalalpha-2" id="drawing-rectangles-to-the-bitmap:dom-context-2d-globalalpha-2">global alpha</a>, and <a href="#dom-context-2d-globalcompositeoperation-2" id="drawing-rectangles-to-the-bitmap:dom-context-2d-globalcompositeoperation-2">global composition operators</a>.</p>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-clearrect"><a href="#dom-context-2d-clearrect-2">clearRect</a></code>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>)</dt><dd>
<p>Clears all pixels on the bitmap in the given rectangle to transparent black.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-fillrect"><a href="#dom-context-2d-fillrect-2">fillRect</a></code>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>)</dt><dd>
<p>Paints the given rectangle onto the bitmap, using the current fill style.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-strokerect"><a href="#dom-context-2d-strokerect-2">strokeRect</a></code>(<var>x</var>, <var>y</var>, <var>w</var>, <var>h</var>)</dt><dd>
<p>Paints the box that outlines the given rectangle onto the bitmap, using the current stroke
style.</p>
</dd></dl>
<p>The <dfn id="dom-context-2d-clearrect-2"><code>clearRect(<var>x</var>, <var>y</var>,
<var>w</var>, <var>h</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>Let <var>pixels</var> be the set of pixels in the specified rectangle that also
intersect the current <a href="#clipping-region" id="drawing-rectangles-to-the-bitmap:clipping-region-2">clipping region</a>.</p></li><li><p>Clear the pixels in <var>pixels</var> to a fully transparent black, erasing any
previous image.</p></li></ol>
<p class="note">If either height or width are zero, this method has no effect, since the set of
pixels would be empty.</p>
<p>The <dfn id="dom-context-2d-fillrect-2"><code>fillRect(<var>x</var>, <var>y</var>,
<var>w</var>, <var>h</var>)</code></dfn> method, when invoked, must must run these steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>If either <var>w</var> or <var>h</var> are zero, then abort these steps.</p></li><li><p>Paint the specified rectangular area using the <code id="drawing-rectangles-to-the-bitmap:dom-context-2d-fillstyle-2"><a href="#dom-context-2d-fillstyle-2">fillStyle</a></code>.</p>
</li></ol>
<p>The <dfn id="dom-context-2d-strokerect-2"><code>strokeRect(<var>x</var>, <var>y</var>,
<var>w</var>, <var>h</var>)</code></dfn> method, when invoked, must run these steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>Take the result of <a href="#trace-a-path" id="drawing-rectangles-to-the-bitmap:trace-a-path">tracing the path</a> described below,
using the <code id="drawing-rectangles-to-the-bitmap:canvaspathdrawingstyles"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> interface's line styles, and fill it with the
<code id="drawing-rectangles-to-the-bitmap:dom-context-2d-strokestyle-2"><a href="#dom-context-2d-strokestyle-2">strokeStyle</a></code>.</p></li></ol>
<p>If both <var>w</var> and <var>h</var> are zero, the path has a single subpath
with just one point (<var>x</var>, <var>y</var>), and no lines, and this method
thus has no effect (the <a href="#trace-a-path" id="drawing-rectangles-to-the-bitmap:trace-a-path-2">trace a path</a> algorithm returns an empty path in that
case).</p>
<p>If just one of either <var>w</var> or <var>h</var> is zero, then the path has
a single subpath consisting of two points, with coordinates (<var>x</var>, <var>y</var>) and (<var>x</var>+<var>w</var>, <var>y</var>+<var>h</var>), in that order, connected by a single straight line.</p>
<p>Otherwise, the path has a single subpath consisting of four points, with coordinates (<span><var>x</var></span>, <var>y</var>), (<span><var>x</var>+<var>w</var></span>, <var>y</var>), (<var>x</var>+<var>w</var>,
<var>y</var>+<var>h</var>), and (<var>x</var>, <var>y</var>+<var>h</var>),
connected to each other in that order by straight lines.</p>
<h6 id="drawing-text-to-the-bitmap"><span class="secno">4.12.5.1.11</span> Drawing text to the bitmap<a class="self-link" href="#drawing-text-to-the-bitmap"/></h6><div class="status"><input onclick="toggleStatus(this)" type="button" value="⋰"/><p class="support"><strong>Support:</strong> canvas-text<span class="and_chr yes"><span>Chrome for Android</span> <span>59+</span></span><span class="chrome yes"><span>Chrome</span> <span>4+</span></span><span class="and_uc yes"><span>UC Browser for Android</span> <span>11.4+</span></span><span class="ios_saf yes"><span>iOS Safari</span> <span>3.2+</span></span><span class="firefox yes"><span>Firefox</span> <span>3.5+</span></span><span class="ie yes"><span>IE</span> <span>9+</span></span><span class="samsung yes"><span>Samsung Internet</span> <span>4+</span></span><span class="op_mini no"><span>Opera Mini</span> <span>None</span></span><span class="safari yes"><span>Safari</span> <span>4+</span></span><span class="android yes"><span>Android Browser</span> <span>2.1+</span></span><span class="opera yes"><span>Opera</span> <span>10.5+</span></span><span class="edge yes"><span>Edge</span> <span>12+</span></span></p><p class="caniuse">Source: <a href="https://caniuse.com/#feat=canvas-text">caniuse.com</a></p></div>
<dl class="domintro" id="text-0"><dt><var>context</var> . <code id="dom-context-2d-filltext"><a href="#dom-context-2d-filltext-2">fillText</a></code>(<var>text</var>, <var>x</var>, <var>y</var> [, <var>maxWidth</var> ] )</dt><dt><var>context</var> . <code id="dom-context-2d-stroketext"><a href="#dom-context-2d-stroketext-2">strokeText</a></code>(<var>text</var>, <var>x</var>, <var>y</var> [, <var>maxWidth</var> ] )</dt><dd>
<p>Fills or strokes (respectively) the given text at the given position. If a maximum width is
provided, the text will be scaled to fit that width if necessary.</p>
</dd><dt><var>metrics</var> = <var>context</var> . <code id="dom-context-2d-measuretext"><a href="#dom-context-2d-measuretext-2">measureText</a></code>(<var>text</var>)</dt><dd>
<p>Returns a <code id="drawing-text-to-the-bitmap:textmetrics"><a href="#textmetrics">TextMetrics</a></code> object with the metrics of the given text in the current
font.</p>
</dd><dt><var>metrics</var> . <code id="dom-textmetrics-width"><a href="#dom-textmetrics-width-2">width</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-actualboundingboxleft"><a href="#dom-textmetrics-actualboundingboxleft-2">actualBoundingBoxLeft</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-actualboundingboxright"><a href="#dom-textmetrics-actualboundingboxright-2">actualBoundingBoxRight</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-fontboundingboxascent"><a href="#dom-textmetrics-fontboundingboxascent-2">fontBoundingBoxAscent</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-fontboundingboxdescent"><a href="#dom-textmetrics-fontboundingboxdescent-2">fontBoundingBoxDescent</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-actualboundingboxascent"><a href="#dom-textmetrics-actualboundingboxascent-2">actualBoundingBoxAscent</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-actualboundingboxdescent"><a href="#dom-textmetrics-actualboundingboxdescent-2">actualBoundingBoxDescent</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-emheightascent"><a href="#dom-textmetrics-emheightascent-2">emHeightAscent</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-emheightdescent"><a href="#dom-textmetrics-emheightdescent-2">emHeightDescent</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-hangingbaseline"><a href="#dom-textmetrics-hangingbaseline-2">hangingBaseline</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-alphabeticbaseline"><a href="#dom-textmetrics-alphabeticbaseline-2">alphabeticBaseline</a></code></dt><dt><var>metrics</var> . <code id="dom-textmetrics-ideographicbaseline"><a href="#dom-textmetrics-ideographicbaseline-2">ideographicBaseline</a></code></dt><dd>
<p>Returns the measurement described below.</p>
</dd></dl>
<p>Objects that implement the <code id="drawing-text-to-the-bitmap:canvastext"><a href="#canvastext">CanvasText</a></code> interface provide the following methods for
rendering text.</p>
<p>The <dfn id="dom-context-2d-filltext-2"><code>fillText()</code></dfn> and <dfn id="dom-context-2d-stroketext-2"><code>strokeText()</code></dfn> methods take three or four arguments,
<var>text</var>, <var>x</var>, <var>y</var>, and optionally <var>maxWidth</var>, and render the
given <var>text</var> at the given (<var>x</var>, <var>y</var>) coordinates ensuring that the text
isn't wider than <var>maxWidth</var> if specified, using the current <code id="drawing-text-to-the-bitmap:dom-context-2d-font-2"><a href="#dom-context-2d-font-2">font</a></code>, <code id="drawing-text-to-the-bitmap:dom-context-2d-textalign-2"><a href="#dom-context-2d-textalign-2">textAlign</a></code>, and <code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> values. Specifically, when the methods
are invoked, the user agent must run these steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p>Run the <a href="#text-preparation-algorithm" id="drawing-text-to-the-bitmap:text-preparation-algorithm">text preparation algorithm</a>, passing it <var>text</var>, the object
implementing the <code id="drawing-text-to-the-bitmap:canvastext-2"><a href="#canvastext">CanvasText</a></code> interface, and, if the <var>maxWidth</var> argument was
provided, that argument. Let <var>glyphs</var> be the result.</p>
</li><li><p>Move all the shapes in <var>glyphs</var> to the right by <var>x</var>
<a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'">CSS pixels</a> and down by <var>y</var> <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-2">CSS
pixels</a>.</p></li><li>
<p>Paint the shapes given in <var>glyphs</var>, as transformed by the <a href="#transformations" id="drawing-text-to-the-bitmap:transformations">current transformation matrix</a>, with each <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-3">CSS pixel</a> in the coordinate space of <var>glyphs</var> mapped to one
coordinate space unit.</p>
<p>For <code id="drawing-text-to-the-bitmap:dom-context-2d-filltext-2"><a href="#dom-context-2d-filltext-2">fillText()</a></code>, <code id="drawing-text-to-the-bitmap:dom-context-2d-fillstyle-2"><a href="#dom-context-2d-fillstyle-2">fillStyle</a></code> must be applied to the shapes and <code id="drawing-text-to-the-bitmap:dom-context-2d-strokestyle-2"><a href="#dom-context-2d-strokestyle-2">strokeStyle</a></code> must be ignored. For <code id="drawing-text-to-the-bitmap:dom-context-2d-stroketext-2"><a href="#dom-context-2d-stroketext-2">strokeText()</a></code>, the reverse holds: <code id="drawing-text-to-the-bitmap:dom-context-2d-strokestyle-2-2"><a href="#dom-context-2d-strokestyle-2">strokeStyle</a></code> must be applied to the result of <a href="#trace-a-path" id="drawing-text-to-the-bitmap:trace-a-path">tracing</a> the shapes using the object implementing the
<code id="drawing-text-to-the-bitmap:canvastext-3"><a href="#canvastext">CanvasText</a></code> interface for the line styles, and <code id="drawing-text-to-the-bitmap:dom-context-2d-fillstyle-2-2"><a href="#dom-context-2d-fillstyle-2">fillStyle</a></code> must be ignored.</p>
<p>These shapes are painted without affecting the current path, and are subject to <a href="#shadows" id="drawing-text-to-the-bitmap:shadows">shadow effects</a>, <a href="#dom-context-2d-globalalpha-2" id="drawing-text-to-the-bitmap:dom-context-2d-globalalpha-2">global
alpha</a>, the <a href="#clipping-region" id="drawing-text-to-the-bitmap:clipping-region">clipping region</a>, and <a href="#dom-context-2d-globalcompositeoperation-2" id="drawing-text-to-the-bitmap:dom-context-2d-globalcompositeoperation-2">global composition operators</a>.</p>
</li></ol>
<p>The <dfn id="dom-context-2d-measuretext-2"><code>measureText()</code></dfn> method takes one
argument, <var>text</var>. When the method is invoked, the user agent must run the
<a href="#text-preparation-algorithm" id="drawing-text-to-the-bitmap:text-preparation-algorithm-2">text preparation algorithm</a>, passing it <var>text</var> and the object implementing
the <code id="drawing-text-to-the-bitmap:canvastext-4"><a href="#canvastext">CanvasText</a></code> interface, and then using the returned <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="drawing-text-to-the-bitmap:inline-box">inline box</a> must
create a new <code id="drawing-text-to-the-bitmap:textmetrics-2"><a href="#textmetrics">TextMetrics</a></code> object with its attributes set as described in the following
list.
If doing these measurements requires using a font that has an <a href="https://html.spec.whatwg.org/multipage/origin.html#concept-origin" id="drawing-text-to-the-bitmap:concept-origin">origin</a> that is not the
<a href="https://html.spec.whatwg.org/multipage/origin.html#same-origin" id="drawing-text-to-the-bitmap:same-origin">same</a> as that of the <code id="drawing-text-to-the-bitmap:document"><a href="https://html.spec.whatwg.org/multipage/dom.html#document">Document</a></code> object that owns the
<code id="drawing-text-to-the-bitmap:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element (even if &quot;using a font&quot; means just checking if that font has a
particular glyph in it before falling back to another font), then the method, when invoked, must
throw a <a data-x-internal="securityerror" href="https://heycam.github.io/webidl/#securityerror" id="drawing-text-to-the-bitmap:securityerror">&quot;<code>SecurityError</code>&quot;</a> <code id="drawing-text-to-the-bitmap:domexception"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.
Otherwise, it must return the new <code id="drawing-text-to-the-bitmap:textmetrics-3"><a href="#textmetrics">TextMetrics</a></code> object.
<a href="https://html.spec.whatwg.org/multipage/references.html#refsCSS">[CSS]</a>
<a class="fingerprint" href="https://html.spec.whatwg.org/multipage/introduction.html#fingerprinting-vector" id="drawing-text-to-the-bitmap:fingerprinting-vector" title="There is a potential fingerprinting vector here."><img alt="(This is a fingerprinting vector.)" height="64" src="https://html.spec.whatwg.org/images/fingerprint.png" width="46"/></a>
</p>
<dl><dt><dfn id="dom-textmetrics-width-2"><code>width</code></dfn> attribute</dt><dd><p>The width of that <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="drawing-text-to-the-bitmap:inline-box-2">inline box</a>, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-4">CSS pixels</a>. (The
text's advance width.)</p></dd><dt><dfn id="dom-textmetrics-actualboundingboxleft-2"><code>actualBoundingBoxLeft</code></dfn> attribute</dt><dd>
<p>The distance parallel to the baseline from the alignment point given by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textalign-2-2"><a href="#dom-context-2d-textalign-2">textAlign</a></code> attribute to the left side of the bounding
rectangle of the given text, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-5">CSS pixels</a>; positive numbers
indicating a distance going left from the given alignment point.
</p><p class="note">The sum of this value and the next (<code id="drawing-text-to-the-bitmap:dom-textmetrics-actualboundingboxright-2"><a href="#dom-textmetrics-actualboundingboxright-2">actualBoundingBoxRight</a></code>) can be wider than
the width of the <a data-x-internal="inline-box" href="https://drafts.csswg.org/css2/visuren.html#inline-box" id="drawing-text-to-the-bitmap:inline-box-3">inline box</a> (<code id="drawing-text-to-the-bitmap:dom-textmetrics-width-2"><a href="#dom-textmetrics-width-2">width</a></code>), in
particular with slanted fonts where characters overhang their advance width.</p>
</dd><dt><dfn id="dom-textmetrics-actualboundingboxright-2"><code>actualBoundingBoxRight</code></dfn> attribute</dt><dd>
<p>The distance parallel to the baseline from the alignment point given by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textalign-2-3"><a href="#dom-context-2d-textalign-2">textAlign</a></code> attribute to the right side of the bounding
rectangle of the given text, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-6">CSS pixels</a>; positive numbers
indicating a distance going right from the given alignment point.</p>
</dd><dt><dfn id="dom-textmetrics-fontboundingboxascent-2"><code>fontBoundingBoxAscent</code></dfn> attribute</dt><dd>
<p>The distance from the horizontal line indicated by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2-2"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> attribute to the top of the highest
bounding rectangle of all the fonts used to render the text, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-7">CSS
pixels</a>; positive numbers indicating a distance going up from the given baseline.</p>
<p class="note">This value and the next are useful when rendering a background that have to have
a consistent height even if the exact text being rendered changes. The <code id="drawing-text-to-the-bitmap:dom-textmetrics-actualboundingboxascent-2"><a href="#dom-textmetrics-actualboundingboxascent-2">actualBoundingBoxAscent</a></code> attribute (and
its corresponding attribute for the descent) are useful when drawing a bounding box around
specific text.</p>
</dd><dt><dfn id="dom-textmetrics-fontboundingboxdescent-2"><code>fontBoundingBoxDescent</code></dfn> attribute</dt><dd><p>The distance from the horizontal line indicated by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2-3"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> attribute to the bottom of the lowest
bounding rectangle of all the fonts used to render the text, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-8">CSS
pixels</a>; positive numbers indicating a distance going down from the given
baseline.</p></dd><dt><dfn id="dom-textmetrics-actualboundingboxascent-2"><code>actualBoundingBoxAscent</code></dfn> attribute</dt><dd>
<p>The distance from the horizontal line indicated by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2-4"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> attribute to the top of the bounding
rectangle of the given text, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-9">CSS pixels</a>; positive numbers
indicating a distance going up from the given baseline.
</p><p class="note">This number can vary greatly based on the input text, even if the first font
specified covers all the characters in the input. For example, the <code id="drawing-text-to-the-bitmap:dom-textmetrics-actualboundingboxascent-2-2"><a href="#dom-textmetrics-actualboundingboxascent-2">actualBoundingBoxAscent</a></code> of a lowercase
&quot;o&quot; from an alphabetic baseline would be less than that of an uppercase &quot;F&quot;. The value can
easily be negative; for example, the distance from the top of the em box (<code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2-5"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> value &quot;<code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-top"><a href="#dom-context-2d-textbaseline-top">top</a></code>&quot;) to the top of the bounding rectangle when
the given text is just a single comma &quot;<code>,</code>&quot; would likely (unless the font is
quite unusual) be negative.</p>
</dd><dt><dfn id="dom-textmetrics-actualboundingboxdescent-2"><code>actualBoundingBoxDescent</code></dfn> attribute</dt><dd><p>The distance from the horizontal line indicated by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2-6"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> attribute to the bottom of the bounding
rectangle of the given text, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-10">CSS pixels</a>; positive numbers
indicating a distance going down from the given baseline.</p></dd><dt><dfn id="dom-textmetrics-emheightascent-2"><code>emHeightAscent</code></dfn> attribute</dt><dd><p>The distance from the horizontal line indicated by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2-7"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> attribute to the highest top of the em
squares in the <a data-x-internal="line-box" href="https://drafts.csswg.org/css2/visuren.html#line-box" id="drawing-text-to-the-bitmap:line-box">line box</a>, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-11">CSS pixels</a>; positive numbers
indicating that the given baseline is below the top of that em square (so this value will usually
be positive). Zero if the given baseline is the top of that em square; half the font size if the
given baseline is the middle of that em square.</p></dd><dt><dfn id="dom-textmetrics-emheightdescent-2"><code>emHeightDescent</code></dfn> attribute</dt><dd><p>The distance from the horizontal line indicated by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2-8"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> attribute to the lowest bottom of the em
squares in the <a data-x-internal="line-box" href="https://drafts.csswg.org/css2/visuren.html#line-box" id="drawing-text-to-the-bitmap:line-box-2">line box</a>, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-12">CSS pixels</a>; positive numbers
indicating that the given baseline is below the bottom of that em square (so this value will
usually be negative). (Zero if the given baseline is the bottom of that em square.)</p></dd><dt><dfn id="dom-textmetrics-hangingbaseline-2"><code>hangingBaseline</code></dfn> attribute</dt><dd><p>The distance from the horizontal line indicated by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2-9"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> attribute to the hanging baseline of the
<a data-x-internal="line-box" href="https://drafts.csswg.org/css2/visuren.html#line-box" id="drawing-text-to-the-bitmap:line-box-3">line box</a>, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-13">CSS pixels</a>; positive numbers indicating that
the given baseline is below the hanging baseline. (Zero if the given baseline is the hanging
baseline.)</p></dd><dt><dfn id="dom-textmetrics-alphabeticbaseline-2"><code>alphabeticBaseline</code></dfn> attribute</dt><dd><p>The distance from the horizontal line indicated by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2-10"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> attribute to the alphabetic baseline of
the <a data-x-internal="line-box" href="https://drafts.csswg.org/css2/visuren.html#line-box" id="drawing-text-to-the-bitmap:line-box-4">line box</a>, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-14">CSS pixels</a>; positive numbers indicating
that the given baseline is below the alphabetic baseline. (Zero if the given baseline is the
alphabetic baseline.)</p></dd><dt><dfn id="dom-textmetrics-ideographicbaseline-2"><code>ideographicBaseline</code></dfn> attribute</dt><dd><p>The distance from the horizontal line indicated by the <code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-2-11"><a href="#dom-context-2d-textbaseline-2">textBaseline</a></code> attribute to the ideographic baseline of
the <a data-x-internal="line-box" href="https://drafts.csswg.org/css2/visuren.html#line-box" id="drawing-text-to-the-bitmap:line-box-5">line box</a>, in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-text-to-the-bitmap:'px'-15">CSS pixels</a>; positive numbers indicating
that the given baseline is below the ideographic baseline. (Zero if the given baseline is the
ideographic baseline.)</p></dd></dl>
<p class="note">Glyphs rendered using <code id="drawing-text-to-the-bitmap:dom-context-2d-filltext-2-2"><a href="#dom-context-2d-filltext-2">fillText()</a></code> and
<code id="drawing-text-to-the-bitmap:dom-context-2d-stroketext-2-2"><a href="#dom-context-2d-stroketext-2">strokeText()</a></code> can spill out of the box given by the
font size (the em square size) and the width returned by <code id="drawing-text-to-the-bitmap:dom-context-2d-measuretext-2"><a href="#dom-context-2d-measuretext-2">measureText()</a></code> (the text width). Authors are encouraged
to use the bounding box values described above if this is an issue.</p>
<p class="note">A future version of the 2D context API might provide a way to render fragments of
documents, rendered using CSS, straight to the canvas. This would be provided in preference to a
dedicated way of doing multiline layout.</p>
<h6 id="drawing-paths-to-the-canvas"><span class="secno">4.12.5.1.12</span> Drawing paths to the canvas<a class="self-link" href="#drawing-paths-to-the-canvas"/></h6>
<p>Objects that implement the <code id="drawing-paths-to-the-canvas:canvasdrawpath"><a href="#canvasdrawpath">CanvasDrawPath</a></code> interface have a <dfn id="current-default-path">current default
path</dfn>. There is only one <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path">current default path</a>, it is not part of the
<a href="#drawing-state" id="drawing-paths-to-the-canvas:drawing-state">drawing state</a>. The <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-2">current default path</a> is a <a href="#concept-path" id="drawing-paths-to-the-canvas:concept-path">path</a>, as described above.</p>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-beginpath"><a href="#dom-context-2d-beginpath-2">beginPath</a></code>()</dt><dd>
<p>Resets the <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-3">current default path</a>.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-fill"><a href="#dom-context-2d-fill-2">fill</a></code>( [ <var>fillRule</var> ] )</dt><dt><var>context</var> . <code id="drawing-paths-to-the-canvas:dom-context-2d-fill-2"><a href="#dom-context-2d-fill-2">fill</a></code>(<var>path</var> [, <var>fillRule</var> ] )</dt><dd>
<p>Fills the subpaths of the <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-4">current default path</a> or the given path with the
current fill style, obeying the given fill rule.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-stroke"><a href="#dom-context-2d-stroke-2">stroke</a></code>()</dt><dt><var>context</var> . <code id="drawing-paths-to-the-canvas:dom-context-2d-stroke-2"><a href="#dom-context-2d-stroke-2">stroke</a></code>(<var>path</var>)</dt><dd>
<p>Strokes the subpaths of the <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-5">current default path</a> or the given path with the
current stroke style.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-clip"><a href="#dom-context-2d-clip-2">clip</a></code>( [ <var>fillRule</var> ] )</dt><dt><var>context</var> . <code id="drawing-paths-to-the-canvas:dom-context-2d-clip-2"><a href="#dom-context-2d-clip-2">clip</a></code>(<var>path</var> [, <var>fillRule</var> ] )</dt><dd>
<p>Further constrains the clipping region to the <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-6">current default path</a> or the given
path, using the given fill rule to determine what points are in the path.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-resetclip"><a href="#dom-context-2d-resetclip-2">resetClip</a></code>()</dt><dd>
<p>Unconstrains the clipping region.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-ispointinpath"><a href="#dom-context-2d-ispointinpath-2">isPointInPath</a></code>(<var>x</var>, <var>y</var> [, <var>fillRule</var> ] )</dt><dt><var>context</var> . <code id="drawing-paths-to-the-canvas:dom-context-2d-ispointinpath-2"><a href="#dom-context-2d-ispointinpath-2">isPointInPath</a></code>(<var>path</var>, <var>x</var>, <var>y</var> [, <var>fillRule</var> ] )</dt><dd>
<p>Returns true if the given point is in the <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-7">current default path</a> or the given
path, using the given fill rule to determine what points are in the path.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-ispointinstroke"><a href="#dom-context-2d-ispointinstroke-2">isPointInStroke</a></code>(<var>x</var>, <var>y</var>)</dt><dt><var>context</var> . <code id="drawing-paths-to-the-canvas:dom-context-2d-ispointinstroke-2"><a href="#dom-context-2d-ispointinstroke-2">isPointInStroke</a></code>(<var>path</var>, <var>x</var>, <var>y</var>)</dt><dd>
<p>Returns true if the given point would be in the region covered by the stroke of the
<a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-8">current default path</a> or the given path, given the current stroke style.</p>
</dd></dl><div class="status"><input onclick="toggleStatus(this)" type="button" value="⋰"/><p class="bugs"><strong>Spec bugs:</strong> <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=28217" title="&lt;canvas&gt;: not clear if two polygon paths with a common edge should have no line visible">28217</a></p></div>
<p>The <dfn id="dom-context-2d-beginpath-2"><code>beginPath()</code></dfn> method, when invoked,
must empty the list of subpaths in the context's <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-9">current default path</a> so that the it
once again has zero subpaths.</p>
<p>Where the following method definitions use the term <i>intended path</i>, it means the
<code id="drawing-paths-to-the-canvas:path2d"><a href="#path2d">Path2D</a></code> argument, if one was provided, or the <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-10">current default path</a>
otherwise.</p>
<p>When the intended path is a <code id="drawing-paths-to-the-canvas:path2d-2"><a href="#path2d">Path2D</a></code> object, the coordinates and lines of its
subpaths must be transformed according to the <a href="#transformations" id="drawing-paths-to-the-canvas:transformations">
current transformation matrix</a> on the object implementing the
<code id="drawing-paths-to-the-canvas:canvastransform"><a href="#canvastransform">CanvasTransform</a></code> interface when used by these methods (without affecting the
<code id="drawing-paths-to-the-canvas:path2d-3"><a href="#path2d">Path2D</a></code> object itself). When the intended path is the <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-11">current default
path</a>, it is not affected by the transform. (This is because transformations already affect
the <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-12">current default path</a> when it is constructed, so applying it when it is painted as
well would result in a double transformation.)</p>
<p>The <dfn id="dom-context-2d-fill-2"><code>fill()</code></dfn> method, when invoked, must fill
all the subpaths of the intended path, using <code id="drawing-paths-to-the-canvas:dom-context-2d-fillstyle-2"><a href="#dom-context-2d-fillstyle-2">fillStyle</a></code>, and using the <a href="#fill-rule" id="drawing-paths-to-the-canvas:fill-rule">fill rule</a> indicated
by the <var>fillRule</var> argument. Open subpaths must be implicitly closed when being filled
(without affecting the actual subpaths).</p>
<p>The <dfn id="dom-context-2d-stroke-2"><code>stroke()</code></dfn> method, when invoked, must
<a href="#trace-a-path" id="drawing-paths-to-the-canvas:trace-a-path">trace</a> the intended path, using this
<code id="drawing-paths-to-the-canvas:canvaspathdrawingstyles"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> object for the line styles, and then fill the resulting path
using the <code id="drawing-paths-to-the-canvas:dom-context-2d-strokestyle-2"><a href="#dom-context-2d-strokestyle-2">strokeStyle</a></code> attribute, using the <a href="#dom-context-2d-fillrule-nonzero" id="drawing-paths-to-the-canvas:dom-context-2d-fillrule-nonzero">non-zero winding rule</a>.</p>
<p class="note">As a result of how the algorithm to <a href="#trace-a-path" id="drawing-paths-to-the-canvas:trace-a-path-2">trace a path</a> is defined,
overlapping parts of the paths in one stroke operation are treated as if their union was what was
painted.</p>
<p class="note">The stroke <em>style</em> is affected by the transformation during painting, even
if the intended path is the <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-13">current default path</a>.</p>
<p>Paths, when filled or stroked, must be painted without affecting the <a href="#current-default-path" id="drawing-paths-to-the-canvas:current-default-path-14">current default
path</a> or any <code id="drawing-paths-to-the-canvas:path2d-4"><a href="#path2d">Path2D</a></code> objects, and must be subject to <a href="#shadows" id="drawing-paths-to-the-canvas:shadows">shadow effects</a>, <a href="#dom-context-2d-globalalpha-2" id="drawing-paths-to-the-canvas:dom-context-2d-globalalpha-2">global
alpha</a>, the <a href="#clipping-region" id="drawing-paths-to-the-canvas:clipping-region">clipping region</a>, and <a href="#dom-context-2d-globalcompositeoperation-2" id="drawing-paths-to-the-canvas:dom-context-2d-globalcompositeoperation-2">global composition operators</a>. (The effect
of transformations is described above and varies based on which path is being used.)</p>
<hr/>
<p>The <dfn id="dom-context-2d-clip-2"><code>clip()</code></dfn> method, when invoked, must
create a new <dfn id="clipping-region">clipping region</dfn> by calculating the intersection of the current clipping
region and the area described by the intended path, using the <a href="#fill-rule" id="drawing-paths-to-the-canvas:fill-rule-2">fill rule</a> indicated by
the <var>fillRule</var> argument. Open subpaths must be implicitly closed when computing the
clipping region, without affecting the actual subpaths. The new clipping region replaces the
current clipping region.</p>
<p>When the context is initialized, the clipping region must be set to the largest infinite
surface (i.e. by default, no clipping occurs).</p>
<p>The <dfn id="dom-context-2d-resetclip-2"><code>resetClip()</code></dfn> method, when invoked,
must create a new <a href="#clipping-region" id="drawing-paths-to-the-canvas:clipping-region-2">clipping region</a> that is the largest infinite surface. The new
clipping region replaces the current clipping region.</p>
<hr/>
<p>The <dfn id="dom-context-2d-ispointinpath-2"><code>isPointInPath()</code></dfn> method, when
invoked, must return true if the point given by the <var>x</var> and <var>y</var> coordinates
passed to the method, when treated as coordinates in the canvas coordinate space unaffected by the
current transformation, is inside the intended path as determined by the <a href="#fill-rule" id="drawing-paths-to-the-canvas:fill-rule-3">fill rule</a>
indicated by the <var>fillRule</var> argument; and must return false otherwise. Open subpaths must
be implicitly closed when computing the area inside the path, without affecting the actual
subpaths. Points on the path itself must be considered to be inside the path. If either of the
arguments are infinite or NaN, then the method must return false.</p>
<hr/>
<p>The <dfn id="dom-context-2d-ispointinstroke-2"><code>isPointInStroke()</code></dfn> method,
when invoked, must return true if the point given by the <var>x</var> and <var>y</var> coordinates
passed to the method, when treated as coordinates in the canvas coordinate space unaffected by the
current transformation, is inside the path that results from <a href="#trace-a-path" id="drawing-paths-to-the-canvas:trace-a-path-3">tracing</a> the intended path, using the <a href="#dom-context-2d-fillrule-nonzero" id="drawing-paths-to-the-canvas:dom-context-2d-fillrule-nonzero-2">non-zero winding rule</a>, and using the
<code id="drawing-paths-to-the-canvas:canvaspathdrawingstyles-2"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code> interface for the line styles; and must return false
otherwise. Points on the resulting path must be considered to be inside the path. If either of the
arguments are infinite or NaN, then the method must return false.</p>
<hr/>
<div class="example" id="drawCustomFocusRingExample">
<p>This <code id="drawing-paths-to-the-canvas:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element has a couple of checkboxes. The path-related commands are
highlighted:</p>
<pre>&lt;canvas height=400 width=750&gt;
&lt;label&gt;&lt;input type=checkbox id=showA&gt; Show As&lt;/label&gt;
&lt;label&gt;&lt;input type=checkbox id=showB&gt; Show Bs&lt;/label&gt;
&lt;!-- ... --&gt;
&lt;/canvas&gt;
&lt;script&gt;
function drawCheckbox(context, element, x, y, paint) {
context.save();
context.font = '10px sans-serif';
context.textAlign = 'left';
context.textBaseline = 'middle';
var metrics = context.measureText(element.labels[0].textContent);
if (paint) {
<strong> context.beginPath();
context.strokeStyle = 'black';
context.rect(x-5, y-5, 10, 10);
context.stroke();
</strong> if (element.checked) {
<strong> context.fillStyle = 'black';
context.fill();
</strong> }
context.fillText(element.labels[0].textContent, x+5, y);
}
<strong> context.beginPath();
context.rect(x-7, y-7, 12 + metrics.width+2, 14);
</strong>
context.drawFocusIfNeeded(element);
context.restore();
}
function drawBase() { /* ... */ }
function drawAs() { /* ... */ }
function drawBs() { /* ... */ }
function redraw() {
var canvas = document.getElementsByTagName('canvas')[0];
var context = canvas.getContext('2d');
context.clearRect(0, 0, canvas.width, canvas.height);
drawCheckbox(context, document.getElementById('showA'), 20, 40, true);
drawCheckbox(context, document.getElementById('showB'), 20, 60, true);
drawBase();
if (document.getElementById('showA').checked)
drawAs();
if (document.getElementById('showB').checked)
drawBs();
}
function processClick(event) {
var canvas = document.getElementsByTagName('canvas')[0];
var context = canvas.getContext('2d');
var x = event.clientX;
var y = event.clientY;
var node = event.target;
while (node) {
x -= node.offsetLeft - node.scrollLeft;
y -= node.offsetTop - node.scrollTop;
node = node.offsetParent;
}
drawCheckbox(context, document.getElementById('showA'), 20, 40, false);
if (<strong>context.isPointInPath(x, y)</strong>)
document.getElementById('showA').checked = !(document.getElementById('showA').checked);
drawCheckbox(context, document.getElementById('showB'), 20, 60, false);
if (<strong>context.isPointInPath(x, y)</strong>)
document.getElementById('showB').checked = !(document.getElementById('showB').checked);
redraw();
}
document.getElementsByTagName('canvas')[0].addEventListener('focus', redraw, true);
document.getElementsByTagName('canvas')[0].addEventListener('blur', redraw, true);
document.getElementsByTagName('canvas')[0].addEventListener('change', redraw, true);
document.getElementsByTagName('canvas')[0].addEventListener('click', processClick, false);
redraw();
&lt;/script&gt;</pre>
</div>
<h6 id="drawing-focus-rings-and-scrolling-paths-into-view"><span class="secno">4.12.5.1.13</span> Drawing focus rings and scrolling paths into view<a class="self-link" href="#drawing-focus-rings-and-scrolling-paths-into-view"/></h6>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-drawfocusifneeded"><a href="#dom-context-2d-drawfocusifneeded-2">drawFocusIfNeeded</a></code>(<var>element</var>)</dt><dt><var>context</var> . <code id="drawing-focus-rings-and-scrolling-paths-into-view:dom-context-2d-drawfocusifneeded-2"><a href="#dom-context-2d-drawfocusifneeded-2">drawFocusIfNeeded</a></code>(<var>path</var>, <var>element</var>)</dt><dd>
<p>If the given element is <a href="https://html.spec.whatwg.org/multipage/interaction.html#focused" id="drawing-focus-rings-and-scrolling-paths-into-view:focused">focused</a>, draws a focus ring around the <a href="#current-default-path" id="drawing-focus-rings-and-scrolling-paths-into-view:current-default-path">current
default path</a> or the given path, following the platform conventions for focus rings.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-scrollpathintoview"><a href="#dom-context-2d-scrollpathintoview-2">scrollPathIntoView</a></code>()</dt><dt><var>context</var> . <code id="drawing-focus-rings-and-scrolling-paths-into-view:dom-context-2d-scrollpathintoview-2"><a href="#dom-context-2d-scrollpathintoview-2">scrollPathIntoView</a></code>(<var>path</var>)</dt><dd>
<p>Scrolls the <a href="#current-default-path" id="drawing-focus-rings-and-scrolling-paths-into-view:current-default-path-2">current default path</a> or the given path into view. This is especially
useful on devices with small screens, where the whole canvas might not be visible at once.</p>
</dd></dl>
Objects that implement the <code id="drawing-focus-rings-and-scrolling-paths-into-view:canvasuserinterface"><a href="#canvasuserinterface">CanvasUserInterface</a></code> interface provide the following
methods to control drawing focus rings and scrolling paths into view.
<hr/>
<p id="dom-context-2d-drawosfocusring">The <dfn id="dom-context-2d-drawfocusifneeded-2"><code>drawFocusIfNeeded(<var>element</var>)</code></dfn>
method, when invoked, must run these steps:</p>
<ol><li><p>If <var>element</var> is not <a href="https://html.spec.whatwg.org/multipage/interaction.html#focused" id="drawing-focus-rings-and-scrolling-paths-into-view:focused-2">focused</a> or is not a descendant of the element with
whose context the method is associated, then abort these steps.</p></li><li>
<p>Draw a focus ring of the appropriate style along the intended path, following platform
conventions.</p>
<p class="note">Some platforms only draw focus rings around elements that have been focused from
the keyboard, and not those focused from the mouse. Other platforms simply don't draw focus
rings around some elements at all unless relevant accessibility features are enabled. This API
is intended to follow these conventions. User agents that implement distinctions based on the
manner in which the element was focused are encouraged to classify focus driven by the <code id="drawing-focus-rings-and-scrolling-paths-into-view:dom-focus-2"><a href="https://html.spec.whatwg.org/multipage/interaction.html#dom-focus-2">focus()</a></code> method based on the kind of user interaction event from which
the call was triggered (if any).</p>
<p>The focus ring should not be subject to the <a href="#shadows" id="drawing-focus-rings-and-scrolling-paths-into-view:shadows">shadow effects</a>, the
<a href="#dom-context-2d-globalalpha-2" id="drawing-focus-rings-and-scrolling-paths-into-view:dom-context-2d-globalalpha-2">global alpha</a>, the <a href="#dom-context-2d-globalcompositeoperation-2" id="drawing-focus-rings-and-scrolling-paths-into-view:dom-context-2d-globalcompositeoperation-2">global composition operators</a>, or any of
the members in the <code id="drawing-focus-rings-and-scrolling-paths-into-view:canvasfillstrokestyles"><a href="#canvasfillstrokestyles">CanvasFillStrokeStyles</a></code>, <code id="drawing-focus-rings-and-scrolling-paths-into-view:canvaspathdrawingstyles"><a href="#canvaspathdrawingstyles">CanvasPathDrawingStyles</a></code>,
<code id="drawing-focus-rings-and-scrolling-paths-into-view:canvastextdrawingstyles"><a href="#canvastextdrawingstyles">CanvasTextDrawingStyles</a></code> interfaces, but <em>should</em> be subject to the
<a href="#clipping-region" id="drawing-focus-rings-and-scrolling-paths-into-view:clipping-region">clipping region</a>. (The effect of transformations is described above and varies based
on which path is being used.)</p>
</li><li><p><a href="#inform">Inform the user</a> that the focus is at the location given by the
intended path. User agents may wait until the next time the <a href="https://html.spec.whatwg.org/multipage/webappapis.html#event-loop" id="drawing-focus-rings-and-scrolling-paths-into-view:event-loop">event loop</a> reaches its
<a href="https://html.spec.whatwg.org/multipage/webappapis.html#update-the-rendering" id="drawing-focus-rings-and-scrolling-paths-into-view:update-the-rendering">update the rendering</a> step to optionally inform the user.</p></li></ol>
<p>User agents should not implicitly close open subpaths in the intended path when drawing the
focus ring.</p>
<p class="note">This might be a moot point, however. For example, if the focus ring is drawn as an
axis-aligned bounding rectangle around the points in the intended path, then whether the subpaths
are closed or not has no effect. This specification intentionally does not specify precisely how
focus rings are to be drawn: user agents are expected to honor their platform's native
conventions.</p>
<hr/>
<p>The <dfn id="dom-context-2d-scrollpathintoview-2"><code>scrollPathIntoView()</code></dfn>
method, when invoked, must run these steps:</p>
<ol><li><p>Let <var>the specified rectangle</var> be the rectangle of the bounding box of
the intended path.</p></li><li><p>Let <var>notional child</var> be a hypothetical element that is a rendered child
of the <code id="drawing-focus-rings-and-scrolling-paths-into-view:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element whose dimensions are those of <var>the specified
rectangle</var>.</p></li><li><p><a data-x-internal="scroll-an-element-into-view" href="https://drafts.csswg.org/cssom-view/#scroll-an-element-into-view" id="drawing-focus-rings-and-scrolling-paths-into-view:scroll-an-element-into-view">Scroll <var>notional child</var> into
view</a> with the <var>align to top flag</var> set.</p>
</li><li><p>Optionally, <a href="#inform">inform the user</a> that the caret or selection (or both)
cover <var>the specified rectangle</var> of the canvas. The user agent may wait until the next
time the <a href="https://html.spec.whatwg.org/multipage/webappapis.html#event-loop" id="drawing-focus-rings-and-scrolling-paths-into-view:event-loop-2">event loop</a> reaches its <a href="https://html.spec.whatwg.org/multipage/webappapis.html#update-the-rendering" id="drawing-focus-rings-and-scrolling-paths-into-view:update-the-rendering-2">update the rendering</a> step to
optionally inform the user.</p></li></ol>
<p id="inform">&quot;Inform the user&quot;, as used in this section, does not imply any persistent state
change. It could mean, for instance, calling a system accessibility API to notify assistive
technologies such as magnification tools so that the user's magnifier moves to the given area of
the canvas. However, it does not associate the path with the element, or provide a region for
tactile feedback, etc.</p>
<h6 id="drawing-images"><span class="secno">4.12.5.1.14</span> Drawing images<a class="self-link" href="#drawing-images"/></h6>
<p>Objects that implement the <code id="drawing-images:canvasdrawimage"><a href="#canvasdrawimage">CanvasDrawImage</a></code> interface have the <dfn id="dom-context-2d-drawimage"><code>drawImage</code></dfn> method to draw images.</p>
<p>This method can be invoked with three different sets of arguments:</p>
<ul class="brief"><li><code>drawImage(<var>image</var>, <var>dx</var>, <var>dy</var>)</code>
</li><li><code>drawImage(<var>image</var>, <var>dx</var>, <var>dy</var>, <var>dw</var>, <var>dh</var>)</code>
</li><li><code>drawImage(<var>image</var>, <var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var>, <var>dx</var>, <var>dy</var>, <var>dw</var>, <var>dh</var>)</code>
</li></ul>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-drawimage-2"><a href="#dom-context-2d-drawimage">drawImage</a></code>(<var>image</var>, <var>dx</var>, <var>dy</var>)</dt><dt><var>context</var> . <code id="drawing-images:dom-context-2d-drawimage"><a href="#dom-context-2d-drawimage">drawImage</a></code>(<var>image</var>, <var>dx</var>, <var>dy</var>, <var>dw</var>, <var>dh</var>)</dt><dt><var>context</var> . <code id="drawing-images:dom-context-2d-drawimage-2"><a href="#dom-context-2d-drawimage">drawImage</a></code>(<var>image</var>, <var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var>, <var>dx</var>, <var>dy</var>, <var>dw</var>, <var>dh</var>)</dt><dd>
<p>Draws the given image onto the canvas. The arguments are
interpreted as follows:</p>
<p><img alt="The sx and sy parameters give the x and y coordinates of the source rectangle; the sw and sh arguments give the width and height of the source rectangle; the dx and dy give the x and y coordinates of the destination rectangle; and the dw and dh arguments give the width and height of the destination rectangle." height="356" src="https://html.spec.whatwg.org/images/drawImage.png" width="356"/></p>
<p>If the image isn't yet fully decoded, then nothing is drawn. If the image is a canvas with no
data, throws an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="drawing-images:invalidstateerror">&quot;<code>InvalidStateError</code>&quot;</a> <code id="drawing-images:domexception"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.</p>
</dd></dl>
<p>When the <code id="drawing-images:dom-context-2d-drawimage-3"><a href="#dom-context-2d-drawimage">drawImage()</a></code> method is invoked, the user
agent must run these steps:</p>
<ol><li><p>If any of the arguments are infinite or NaN, then abort these steps.</p></li><li><p><a href="#check-the-usability-of-the-image-argument" id="drawing-images:check-the-usability-of-the-image-argument">Check the usability of the <var>image</var> argument</a>. If this
returns <i>aborted</i>, then an exception has been thrown and the method doesn't return anything;
abort these steps. If it returns <i>bad</i>, then abort these steps without drawing anything.
Otherwise it returns <i>good</i>; continue with these steps.</p></li><li>
<p>Establish the source and destination rectangles as follows:</p>
<p>If not specified, the <var>dw</var> and <var>dh</var> arguments must default to the values of
<var>sw</var> and <var>sh</var>, interpreted such that one <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="drawing-images:'px'">CSS pixel</a>
in the image is treated as one unit in the <a href="#output-bitmap" id="drawing-images:output-bitmap">output bitmap</a>'s coordinate space. If the
<var>sx</var>, <var>sy</var>, <var>sw</var>, and <var>sh</var> arguments are omitted, then they
must default to 0, 0, the image's <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#intrinsic-width" id="drawing-images:intrinsic-width">intrinsic width</a> in image pixels, and the image's
<a href="https://html.spec.whatwg.org/multipage/infrastructure.html#intrinsic-height" id="drawing-images:intrinsic-height">intrinsic height</a> in image pixels, respectively. If the image has no <a data-x-internal="intrinsic-dimensions" href="https://drafts.csswg.org/css2/conform.html#intrinsic" id="drawing-images:intrinsic-dimensions">intrinsic
dimensions</a>, then the <i>concrete object size</i> must be used instead, as determined
using the CSS &quot;<a href="https://drafts.csswg.org/css-images/#default-sizing">Concrete Object
Size Resolution</a>&quot; algorithm, with the <i>specified size</i> having neither a definite width
nor height, nor any additional constraints, the object's intrinsic properties being those of the
<var>image</var> argument, and the <a data-x-internal="default-object-size" href="https://drafts.csswg.org/css-images/#default-object-size" id="drawing-images:default-object-size">default object size</a> being the size of the
<a href="#output-bitmap" id="drawing-images:output-bitmap-2">output bitmap</a>. <a href="https://html.spec.whatwg.org/multipage/references.html#refsCSSIMAGES">[CSSIMAGES]</a></p>
<p>The source rectangle is the rectangle whose corners are the four points (<var>sx</var>, <var>sy</var>), (<var>sx</var>+<var>sw</var>, <var>sy</var>), (<var>sx</var>+<var>sw</var>, <var>sy</var>+<var>sh</var>),
(<var>sx</var>, <var>sy</var>+<var>sh</var>).</p>
<p>The destination rectangle is the rectangle whose corners are the four points (<var>dx</var>, <var>dy</var>), (<var>dx</var>+<var>dw</var>, <var>dy</var>), (<var>dx</var>+<var>dw</var>, <var>dy</var>+<var>dh</var>),
(<var>dx</var>, <var>dy</var>+<var>dh</var>).</p>
<p>When the source rectangle is outside the source image, the source rectangle must be clipped
to the source image and the destination rectangle must be clipped in the same proportion.</p>
<p class="note">When the destination rectangle is outside the destination image (the
<a href="#output-bitmap" id="drawing-images:output-bitmap-3">output bitmap</a>), the pixels that land outside the <a href="#output-bitmap" id="drawing-images:output-bitmap-4">output bitmap</a> are
discarded, as if the destination was an infinite canvas whose rendering was clipped to the
dimensions of the <a href="#output-bitmap" id="drawing-images:output-bitmap-5">output bitmap</a>.</p>
</li><li><p>If one of the <var>sw</var> or <var>sh</var> arguments is zero, then abort
these steps. Nothing is painted.</p></li><li>
<p>Paint the region of the <var>image</var> argument specified by the source rectangle
on the region of the rendering context's <a href="#output-bitmap" id="drawing-images:output-bitmap-6">output bitmap</a> specified by the
destination rectangle, after applying the <a href="#transformations" id="drawing-images:transformations">current
transformation matrix</a> to the destination rectangle.</p>
<p>The image data must be processed in the original direction, even if the dimensions given are
negative. </p>
<p>When scaling up, if the <code id="drawing-images:dom-context-2d-imagesmoothingenabled-2"><a href="#dom-context-2d-imagesmoothingenabled-2">imageSmoothingEnabled</a></code> attribute is set to
true, the user agent should attempt to apply a smoothing algorithm to the image data when it is
scaled. User agents which support multiple filtering algorithms may use the value of the <code id="drawing-images:dom-context-2d-imagesmoothingquality-2"><a href="#dom-context-2d-imagesmoothingquality-2">imageSmoothingQuality</a></code> attribute to guide
the choice of filtering algorithm when the <code id="drawing-images:dom-context-2d-imagesmoothingenabled-2-2"><a href="#dom-context-2d-imagesmoothingenabled-2">imageSmoothingEnabled</a></code> attribute is set to
true. Otherwise, the image must be rendered using nearest-neighbor interpolation.</p>
<p class="note">This specification does not define the precise algorithm to use when scaling an
image down, or when scaling an image up when the <code id="drawing-images:dom-context-2d-imagesmoothingenabled-2-3"><a href="#dom-context-2d-imagesmoothingenabled-2">imageSmoothingEnabled</a></code> attribute is set to
true.</p>
<p class="note">When a <code id="drawing-images:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element is drawn onto itself, the <a href="#drawing-model" id="drawing-images:drawing-model">drawing
model</a> requires the source to be copied before the image is drawn, so it is possible to
copy parts of a <code id="drawing-images:the-canvas-element-2"><a href="#the-canvas-element">canvas</a></code> element onto overlapping parts of itself.</p>
<p>If the original image data is a bitmap image, then the value painted at a point in the
destination rectangle is computed by filtering the original image data. The user agent may use
any filtering algorithm (for example bilinear interpolation or nearest-neighbor). When the
filtering algorithm requires a pixel value from outside the original image data, it must instead
use the value from the nearest edge pixel. (That is, the filter uses 'clamp-to-edge' behavior.)
When the filtering algorithm requires a pixel value from outside the source rectangle but inside
the original image data, then the value from the original image data must be used.</p>
<p class="note">Thus, scaling an image in parts or in whole will have the same effect. This does
mean that when sprites coming from a single sprite sheet are to be scaled, adjacent images in
the sprite sheet can interfere. This can be avoided by ensuring each sprite in the sheet is
surrounded by a border of transparent black, or by copying sprites to be scaled into temporary
<code id="drawing-images:the-canvas-element-3"><a href="#the-canvas-element">canvas</a></code> elements and drawing the scaled sprites from there.</p>
<p>Images are painted without affecting the current path, and are subject to <a href="#shadows" id="drawing-images:shadows">shadow effects</a>, <a href="#dom-context-2d-globalalpha-2" id="drawing-images:dom-context-2d-globalalpha-2">global
alpha</a>, the <a href="#clipping-region" id="drawing-images:clipping-region">clipping region</a>, and <a href="#dom-context-2d-globalcompositeoperation-2" id="drawing-images:dom-context-2d-globalcompositeoperation-2">global composition operators</a>.</p>
</li><li><p>If <a href="#the-image-argument-is-not-origin-clean" id="drawing-images:the-image-argument-is-not-origin-clean">the <var>image argument</var> is not origin-clean</a>, then set the
<code id="drawing-images:canvasrenderingcontext2d"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>'s <a href="#concept-canvas-origin-clean" id="drawing-images:concept-canvas-origin-clean">origin-clean</a> flag to false.</p></li></ol>
<h6 id="pixel-manipulation"><span class="secno">4.12.5.1.15</span> <dfn>Pixel manipulation</dfn><a class="self-link" href="#pixel-manipulation"/></h6>
<dl class="domintro"><dt><var>imagedata</var> = new <code id="pixel-manipulation:dom-imagedata"><a href="#dom-imagedata">ImageData</a></code>(<var>sw</var>, <var>sh</var>)</dt><dt><var>imagedata</var> = <var>context</var> . <code id="dom-context-2d-createimagedata"><a href="#dom-context-2d-createimagedata-2">createImageData</a></code>(<var>sw</var>, <var>sh</var>)</dt><dd>
<p>Returns an <code id="pixel-manipulation:imagedata"><a href="#imagedata">ImageData</a></code> object with the given dimensions. All the pixels in the
returned object are transparent black.</p>
<p>Throws an <a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="pixel-manipulation:indexsizeerror">&quot;<code>IndexSizeError</code>&quot;</a> <code id="pixel-manipulation:domexception"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> if either of
the width or height arguments are zero.</p>
</dd><dt><var>imagedata</var> = <var>context</var> . <code id="pixel-manipulation:dom-context-2d-createimagedata-2"><a href="#dom-context-2d-createimagedata-2">createImageData</a></code>(<var>imagedata</var>)</dt><dd>
<p>Returns an <code id="pixel-manipulation:imagedata-2"><a href="#imagedata">ImageData</a></code> object with the same dimensions as the argument. All the
pixels in the returned object are transparent black.</p>
</dd><dt><var>imagedata</var> = new <code id="pixel-manipulation:dom-imagedata-2"><a href="#dom-imagedata">ImageData</a></code>(<var>data</var>, <var>sw</var> [, <var>sh</var> ] )</dt><dd>
<p>Returns an <code id="pixel-manipulation:imagedata-3"><a href="#imagedata">ImageData</a></code> object using the data provided in the <code id="pixel-manipulation:idl-uint8clampedarray"><a data-x-internal="idl-uint8clampedarray" href="https://heycam.github.io/webidl/#idl-Uint8ClampedArray">Uint8ClampedArray</a></code> argument, interpreted using the given
dimensions.</p>
<p>As each pixel in the data is represented by four numbers, the length of the data needs to be
a multiple of four times the given width. If the height is provided as well, then the length
needs to be exactly the width times the height times 4.</p>
<p>Throws an <a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="pixel-manipulation:indexsizeerror-2">&quot;<code>IndexSizeError</code>&quot;</a> <code id="pixel-manipulation:domexception-2"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> if the given
data and dimensions can't be interpreted consistently, or if either dimension is zero.</p>
</dd><dt><var>imagedata</var> = <var>context</var> . <code id="dom-context-2d-getimagedata"><a href="#dom-context-2d-getimagedata-2">getImageData</a></code>(<var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var>)</dt><dd>
<p>Returns an <code id="pixel-manipulation:imagedata-4"><a href="#imagedata">ImageData</a></code> object containing the image data for the given rectangle of
the bitmap.</p>
<p>Throws an <a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="pixel-manipulation:indexsizeerror-3">&quot;<code>IndexSizeError</code>&quot;</a> <code id="pixel-manipulation:domexception-3"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> if the either
of the width or height arguments are zero.</p>
</dd><dt><var>imagedata</var> . <code id="dom-imagedata-width"><a href="#dom-imagedata-width-2">width</a></code></dt><dt><var>imagedata</var> . <code id="dom-imagedata-height"><a href="#dom-imagedata-height-2">height</a></code></dt><dd>
<p>Returns the actual dimensions of the data in the <code id="pixel-manipulation:imagedata-5"><a href="#imagedata">ImageData</a></code> object, in
pixels.</p>
</dd><dt><var>imagedata</var> . <code id="dom-imagedata-data"><a href="#dom-imagedata-data-2">data</a></code></dt><dd>
<p>Returns the one-dimensional array containing the data in RGBA order, as integers in the range
0 to 255.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-putimagedata"><a href="#dom-context-2d-putimagedata-2">putImageData</a></code>(<var>imagedata</var>, <var>dx</var>, <var>dy</var> [, <var>dirtyX</var>, <var>dirtyY</var>, <var>dirtyWidth</var>, <var>dirtyHeight</var> ] )</dt><dd>
<p>Paints the data from the given <code id="pixel-manipulation:imagedata-6"><a href="#imagedata">ImageData</a></code> object onto the bitmap. If a dirty
rectangle is provided, only the pixels from that rectangle are painted.</p>
<p>The <code id="pixel-manipulation:dom-context-2d-globalalpha-2"><a href="#dom-context-2d-globalalpha-2">globalAlpha</a></code> and <code id="pixel-manipulation:dom-context-2d-globalcompositeoperation-2"><a href="#dom-context-2d-globalcompositeoperation-2">globalCompositeOperation</a></code> attributes, as
well as the shadow attributes, are ignored for the purposes of this method call; pixels in the
canvas are replaced wholesale, with no composition, alpha blending, no shadows, etc.</p>
<p>Throws an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="pixel-manipulation:invalidstateerror">&quot;<code>InvalidStateError</code>&quot;</a> <code id="pixel-manipulation:domexception-4"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> if the
<var>imagedata</var> object's data's <a href="https://html.spec.whatwg.org/multipage/structured-data.html#detached" id="pixel-manipulation:detached">[[Detached]]</a> internal slot value is true.</p>
</dd></dl>
<p>Objects that implement the <code id="pixel-manipulation:canvasimagedata"><a href="#canvasimagedata">CanvasImageData</a></code> interface provide the following methods
for reading and writing pixel data to the bitmap.</p>
<p>The <dfn id="dom-imagedata"><code>ImageData()</code></dfn> constructors and the
<dfn id="dom-context-2d-createimagedata-2"><code>createImageData()</code></dfn> methods are
used to instantiate new <code id="pixel-manipulation:imagedata-7"><a href="#imagedata">ImageData</a></code> objects.</p>
<p>When the <code id="pixel-manipulation:dom-imagedata-3"><a href="#dom-imagedata">ImageData()</a></code> constructor is invoked with two
numeric arguments <var>sw</var> and <var>sh</var>, it must <a href="#create-an-imagedata-object" id="pixel-manipulation:create-an-imagedata-object">create an <code>ImageData</code>
object</a> with parameter <var>pixelsPerRow</var> set to <var>sw</var>, and <var>rows</var> set
to <var>sh</var>. The image data of the newly created <code id="pixel-manipulation:imagedata-8"><a href="#imagedata">ImageData</a></code> object must be
initialized to transparent black. If both <var>sw</var> and <var>sh</var> are non-zero, then
return the new <code id="pixel-manipulation:imagedata-9"><a href="#imagedata">ImageData</a></code> object. If one or both of <var>sw</var> and <var>sh</var>
are zero, then the constructor must throw an <a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="pixel-manipulation:indexsizeerror-4">&quot;<code>IndexSizeError</code>&quot;</a>
<code id="pixel-manipulation:domexception-5"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> instead.</p>
<p>When the <code id="pixel-manipulation:dom-imagedata-4"><a href="#dom-imagedata">ImageData()</a></code> constructor is invoked with its first
argument being an <code id="pixel-manipulation:idl-uint8clampedarray-2"><a data-x-internal="idl-uint8clampedarray" href="https://heycam.github.io/webidl/#idl-Uint8ClampedArray">Uint8ClampedArray</a></code> <var>source</var>
and its second and optional third arguments being numeric arguments <var>sw</var> and
<var>sh</var>, it must run these steps:</p>
<ol><li><p>Let <var>length</var> be the number of bytes in <var>source</var>.</p></li><li><p>If <var>length</var> is not a non-zero integral multiple of four, then throw an
<a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="pixel-manipulation:invalidstateerror-2">&quot;<code>InvalidStateError</code>&quot;</a> <code id="pixel-manipulation:domexception-6"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these
steps.</p></li><li><p>Let <var>length</var> be <var>length</var> divided by four.</p>
</li><li>
<p>If <var>length</var> is not an integral multiple of <var>sw</var>, then throw an
<a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="pixel-manipulation:indexsizeerror-5">&quot;<code>IndexSizeError</code>&quot;</a> <code id="pixel-manipulation:domexception-7"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these steps.</p>
<p class="note">At this step, the length is guaranteed to be greater than zero (otherwise the
second step above would have aborted the steps), so if <var>sw</var> is zero, this
step will throw the exception and abort these steps.</p>
</li><li><p>Let <var>height</var> be <var>length</var> divided by <var>sw</var>.</p></li><li><p>If the <var>sh</var> argument was not omitted, and its value is not equal to
<var>height</var>, then throw an <a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="pixel-manipulation:indexsizeerror-6">&quot;<code>IndexSizeError</code>&quot;</a>
<code id="pixel-manipulation:domexception-8"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these steps.</p></li><li>
<p><a href="#create-an-imagedata-object" id="pixel-manipulation:create-an-imagedata-object-2">Create an <code>ImageData</code> object</a>, with parameter <var>pixelsPerRow</var>
set to <var>sw</var>, <var>rows</var> set to <var>sh</var>, and using <var>source</var>.
Return the newly created <code id="pixel-manipulation:imagedata-10"><a href="#imagedata">ImageData</a></code> object.</p>
<p class="note">The resulting object's data is not a <em>copy</em> of <var>source</var>, it's
the actual <code id="pixel-manipulation:idl-uint8clampedarray-3"><a data-x-internal="idl-uint8clampedarray" href="https://heycam.github.io/webidl/#idl-Uint8ClampedArray">Uint8ClampedArray</a></code> object passed as the
first argument to the constructor.</p>
</li></ol>
<p>When the <code id="pixel-manipulation:dom-context-2d-createimagedata-2-2"><a href="#dom-context-2d-createimagedata-2">createImageData()</a></code> method is
invoked with two numeric arguments <var>sw</var> and <var>sh</var>, it must <a href="#create-an-imagedata-object" id="pixel-manipulation:create-an-imagedata-object-3">create an
<code>ImageData</code> object</a>, with parameter <var>pixelsPerRow</var> set to the
absolute magnitude of <var>sw</var>, and parameter <var>rows</var> set to the absolute magnitude
of <var>sh</var>. Initialize the image data of the new <code id="pixel-manipulation:imagedata-11"><a href="#imagedata">ImageData</a></code> object to
transparent black. If both <var>sw</var> and <var>sh</var> are non-zero, then return
the new <code id="pixel-manipulation:imagedata-12"><a href="#imagedata">ImageData</a></code> object. If one or both of <var>sw</var> and <var>sh</var> are
zero, then throw an <a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="pixel-manipulation:indexsizeerror-7">&quot;<code>IndexSizeError</code>&quot;</a> <code id="pixel-manipulation:domexception-9"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>
instead.</p>
<p>When the <code id="pixel-manipulation:dom-context-2d-createimagedata-2-3"><a href="#dom-context-2d-createimagedata-2">createImageData()</a></code> method is
invoked with a single <var>imagedata</var> argument, it must <a href="#create-an-imagedata-object" id="pixel-manipulation:create-an-imagedata-object-4">create an
<code>ImageData</code> object</a>, with parameter <var>pixelsPerRow</var> set to the value of
the <code id="pixel-manipulation:dom-imagedata-width-2"><a href="#dom-imagedata-width-2">width</a></code> attribute of the <code id="pixel-manipulation:imagedata-13"><a href="#imagedata">ImageData</a></code>
object passed as the argument, and the <var>rows</var> parameter set to the value of the
<code id="pixel-manipulation:dom-imagedata-height-2"><a href="#dom-imagedata-height-2">height</a></code> attribute.
Initialize the image data of the new <code id="pixel-manipulation:imagedata-14"><a href="#imagedata">ImageData</a></code> object to transparent black. Return
the newly created <code id="pixel-manipulation:imagedata-15"><a href="#imagedata">ImageData</a></code> object.</p>
<p>The <dfn id="dom-context-2d-getimagedata-2"><code>getImageData(<var>sx</var>,
<var>sy</var>, <var>sw</var>, <var>sh</var>)</code></dfn> method, when invoked, must,
if either the <var>sw</var> or <var>sh</var> arguments are zero, throw an
<a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="pixel-manipulation:indexsizeerror-8">&quot;<code>IndexSizeError</code>&quot;</a> <code id="pixel-manipulation:domexception-10"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>; otherwise,
if the <code id="pixel-manipulation:canvasrenderingcontext2d"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>'s <a href="#concept-canvas-origin-clean" id="pixel-manipulation:concept-canvas-origin-clean">origin-clean</a> flag is set to false, it must throw a
<a data-x-internal="securityerror" href="https://heycam.github.io/webidl/#securityerror" id="pixel-manipulation:securityerror">&quot;<code>SecurityError</code>&quot;</a> <code id="pixel-manipulation:domexception-11"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>;
otherwise, it must <a href="#create-an-imagedata-object" id="pixel-manipulation:create-an-imagedata-object-5">create an <code>ImageData</code> object</a>, with parameter
<var>pixelsPerRow</var> set to <var>sw</var>, and parameter <var>rows</var> set to <var>sh</var>.
Set the pixel values of the image data of the newly created <code id="pixel-manipulation:imagedata-16"><a href="#imagedata">ImageData</a></code> object to
represent the <a href="#output-bitmap" id="pixel-manipulation:output-bitmap">output bitmap</a> for the area of that bitmap denoted by the rectangle
whose corners are the four points (<var>sx</var>, <var>sy</var>), (<span><var>sx</var>+<var>sw</var></span>, <var>sy</var>), (<span><var>sx</var>+<var>sw</var></span>, <span><var>sy</var>+<var>sh</var></span>), (<var>sx</var>,
<var>sy</var>+<var>sh</var>), in the bitmap's coordinate space units.
Pixels outside the <a href="#output-bitmap" id="pixel-manipulation:output-bitmap-2">output bitmap</a> must be set to transparent black. Pixel values
must not be premultiplied by alpha.</p>
<p>When the user agent is required to <dfn id="create-an-imagedata-object">create an <code>ImageData</code> object</dfn>, given a
positive integer number of rows <var>rows</var>, a positive integer number of pixels per row
<var>pixelsPerRow</var>, and an optional <code id="pixel-manipulation:idl-uint8clampedarray-4"><a data-x-internal="idl-uint8clampedarray" href="https://heycam.github.io/webidl/#idl-Uint8ClampedArray">Uint8ClampedArray</a></code> <var>source</var>, it must run these
steps:</p>
<ol><li><p>Let <var>imageData</var> be a new uninitialized <code id="pixel-manipulation:imagedata-17"><a href="#imagedata">ImageData</a></code> object.</p></li><li><p>If <var>source</var> is specified, then assign the <dfn id="dom-imagedata-data-2"><code>data</code></dfn> attribute of <var>imageData</var> to
<var>source</var>.</p></li><li>
<p>If <var>source</var> is not specified, then initialize the <code id="pixel-manipulation:dom-imagedata-data-2"><a href="#dom-imagedata-data-2">data</a></code> attribute of <var>imageData</var> to a new <code id="pixel-manipulation:idl-uint8clampedarray-5"><a data-x-internal="idl-uint8clampedarray" href="https://heycam.github.io/webidl/#idl-Uint8ClampedArray">Uint8ClampedArray</a></code> object. The <code id="pixel-manipulation:idl-uint8clampedarray-6"><a data-x-internal="idl-uint8clampedarray" href="https://heycam.github.io/webidl/#idl-Uint8ClampedArray">Uint8ClampedArray</a></code> object must use a new <a href="#canvas-pixel-arraybuffer" id="pixel-manipulation:canvas-pixel-arraybuffer">Canvas
Pixel <code>ArrayBuffer</code></a> for its storage, and must have a
zero start offset and a length equal to the length of its storage, in bytes. The <a href="#canvas-pixel-arraybuffer" id="pixel-manipulation:canvas-pixel-arraybuffer-2">Canvas
Pixel <code>ArrayBuffer</code></a> must have the correct size to
store <var>rows</var> × <var>pixelsPerRow</var> pixels.</p>
<p>If the <a href="#canvas-pixel-arraybuffer" id="pixel-manipulation:canvas-pixel-arraybuffer-3">Canvas Pixel <code>ArrayBuffer</code></a> cannot be
allocated, then rethrow the <code id="pixel-manipulation:js-rangeerror"><a data-x-internal="js-rangeerror" href="https://tc39.github.io/ecma262/#sec-native-error-types-used-in-this-standard-rangeerror">RangeError</a></code> thrown by JavaScript,
and abort these steps.</p>
</li><li><p>Initialize the <dfn id="dom-imagedata-width-2"><code>width</code></dfn> attribute of
<var>imageData</var> to <var>pixelsPerRow</var>.</p></li><li><p>Initialize the <dfn id="dom-imagedata-height-2"><code>height</code></dfn> attribute of
<var>imageData</var> to <var>rows</var>.</p></li><li><p>Return <var>imageData</var>.</p></li></ol>
<p><code id="pixel-manipulation:imagedata-18"><a href="#imagedata">ImageData</a></code> objects are <a href="https://html.spec.whatwg.org/multipage/structured-data.html#serializable-objects" id="pixel-manipulation:serializable-objects">serializable objects</a>. Their <a href="https://html.spec.whatwg.org/multipage/structured-data.html#serialization-steps" id="pixel-manipulation:serialization-steps">serialization
steps</a>, given <var>value</var> and <var>serialized</var>, are:</p>
<ol><li><p>Set <var>serialized</var>.[[Data]] to the <a href="https://html.spec.whatwg.org/multipage/structured-data.html#sub-serialization" id="pixel-manipulation:sub-serialization">sub-serialization</a> of the value of
<var>value</var>'s <code id="pixel-manipulation:dom-imagedata-data-2-2"><a href="#dom-imagedata-data-2">data</a></code> attribute.</p></li><li><p>Set <var>serialized</var>.[[Width]] to the value of <var>value</var>'s <code id="pixel-manipulation:dom-imagedata-width-2-2"><a href="#dom-imagedata-width-2">width</a></code> attribute.</p></li><li><p>Set <var>serialized</var>.[[Height]] to the value of <var>value</var>'s <code id="pixel-manipulation:dom-imagedata-height-2-2"><a href="#dom-imagedata-height-2">height</a></code> attribute.</p></li></ol>
<p>Their <a href="https://html.spec.whatwg.org/multipage/structured-data.html#deserialization-steps" id="pixel-manipulation:deserialization-steps">deserialization steps</a>, given <var>serialized</var> and <var>value</var>,
are:</p>
<ol><li><p>Initialize <var>value</var>'s <code id="pixel-manipulation:dom-imagedata-data-2-3"><a href="#dom-imagedata-data-2">data</a></code> attribute
to the <a href="https://html.spec.whatwg.org/multipage/structured-data.html#sub-deserialization" id="pixel-manipulation:sub-deserialization">sub-deserialization</a> of <var>serialized</var>.[[Data]].</p></li><li><p>Initialize <var>value</var>'s <code id="pixel-manipulation:dom-imagedata-width-2-3"><a href="#dom-imagedata-width-2">width</a></code> attribute
to <var>serialized</var>.[[Width]].</p></li><li><p>Initialize <var>value</var>'s <code id="pixel-manipulation:dom-imagedata-height-2-3"><a href="#dom-imagedata-height-2">height</a></code> attribute
to <var>serialized</var>.[[Height]].</p></li></ol>
<p>A <dfn id="canvas-pixel-arraybuffer">Canvas Pixel <code>ArrayBuffer</code></dfn> is an <code id="pixel-manipulation:idl-arraybuffer"><a data-x-internal="idl-arraybuffer" href="https://heycam.github.io/webidl/#idl-ArrayBuffer">ArrayBuffer</a></code> whose data is represented in left-to-right order, row
by row top to bottom, starting with the top left, with each pixel's red, green, blue, and alpha
components being given in that order for each pixel. Each component of each pixel represented in
this array must be in the range 0..255, representing the 8 bit value for that component. The
components must be assigned consecutive indices starting with 0 for the top left pixel's red
component.</p>
<p>The <dfn id="dom-context-2d-putimagedata-2"><code>putImageData()</code></dfn> method writes
data from <code id="pixel-manipulation:imagedata-19"><a href="#imagedata">ImageData</a></code> structures back to the rendering context's <a href="#output-bitmap" id="pixel-manipulation:output-bitmap-3">output
bitmap</a>. Its arguments are: <var>imagedata</var>, <var>dx</var>, <var>dy</var>,
<var>dirtyX</var>, <var>dirtyY</var>, <var>dirtyWidth</var>, and <var>dirtyHeight</var>.</p>
<p>When the last four arguments to this method are omitted, they must be assumed to have the
values 0, 0, the <code id="pixel-manipulation:dom-imagedata-width-2-4"><a href="#dom-imagedata-width-2">width</a></code> member of the <var>imagedata</var> structure, and the <code id="pixel-manipulation:dom-imagedata-height-2-4"><a href="#dom-imagedata-height-2">height</a></code>
member of the <var>imagedata</var> structure, respectively.</p>
<p>The method, when invoked, must act as follows:</p>
<ol><li>
<p>If <var>imagedata</var>'s <code id="pixel-manipulation:dom-imagedata-data-2-4"><a href="#dom-imagedata-data-2">data</a></code> attribute value's
<a href="https://html.spec.whatwg.org/multipage/structured-data.html#detached" id="pixel-manipulation:detached-2">[[Detached]]</a> internal slot value is true, then throw an
<a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="pixel-manipulation:invalidstateerror-3">&quot;<code>InvalidStateError</code>&quot;</a> <code id="pixel-manipulation:domexception-12"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these
steps.</p>
</li><li>
<p>If <var>dirtyWidth</var> is negative, then let <var>dirtyX</var> be <span><var>dirtyX</var>+<var>dirtyWidth</var></span>, and let <var>dirtyWidth</var> be equal
to the absolute magnitude of <var>dirtyWidth</var>.</p>
<p>If <var>dirtyHeight</var> is negative, then let <var>dirtyY</var> be <span><var>dirtyY</var>+<var>dirtyHeight</var></span>, and let <var>dirtyHeight</var> be
equal to the absolute magnitude of <var>dirtyHeight</var>.</p>
</li><li>
<p>If <var>dirtyX</var> is negative, then let <var>dirtyWidth</var> be <span><var>dirtyWidth</var>+<var>dirtyX</var></span>, and let <var>dirtyX</var> be zero.</p>
<p>If <var>dirtyY</var> is negative, then let <var>dirtyHeight</var> be <span><var>dirtyHeight</var>+<var>dirtyY</var></span>, and let <var>dirtyY</var> be zero.</p>
</li><li>
<p>If <var>dirtyX</var>+<var>dirtyWidth</var> is greater than the <code id="pixel-manipulation:dom-imagedata-width-2-5"><a href="#dom-imagedata-width-2">width</a></code> attribute of the <var>imagedata</var> argument, then
let <var>dirtyWidth</var> be the value of that <code id="pixel-manipulation:dom-imagedata-width-2-6"><a href="#dom-imagedata-width-2">width</a></code>
attribute, minus the value of <var>dirtyX</var>.</p>
<p>If <var>dirtyY</var>+<var>dirtyHeight</var> is greater than the <code id="pixel-manipulation:dom-imagedata-height-2-5"><a href="#dom-imagedata-height-2">height</a></code> attribute of the <var>imagedata</var> argument, then
let <var>dirtyHeight</var> be the value of that <code id="pixel-manipulation:dom-imagedata-height-2-6"><a href="#dom-imagedata-height-2">height</a></code> attribute, minus the value of <var>dirtyY</var>.</p>
</li><li>
<p>If, after those changes, either <var>dirtyWidth</var> or <var>dirtyHeight</var> are negative
or zero, then abort these steps without affecting any bitmaps.</p>
</li><li><p>For all integer values of <var>x</var> and <var>y</var> where <span><var>dirtyX</var> ≤ <var>x</var> &lt; <span><var>dirtyX</var>+<var>dirtyWidth</var></span></span> and <span><var>dirtyY</var> ≤ <var>y</var> &lt; <span><var>dirtyY</var>+<var>dirtyHeight</var></span></span>, copy the
four channels of the pixel with coordinate (<var>x</var>, <var>y</var>) in
the <var>imagedata</var> data structure's <a href="#canvas-pixel-arraybuffer" id="pixel-manipulation:canvas-pixel-arraybuffer-4">Canvas Pixel
<code>ArrayBuffer</code></a> to the pixel with coordinate (<span><var>dx</var>+<var>x</var></span>, <var>dy</var>+<var>y</var>)
in the rendering context's <a href="#output-bitmap" id="pixel-manipulation:output-bitmap-4">output bitmap</a>.</p></li></ol>
<p class="note">Due to the lossy nature of converting to and from premultiplied alpha color
values, pixels that have just been set using <code id="pixel-manipulation:dom-context-2d-putimagedata-2"><a href="#dom-context-2d-putimagedata-2">putImageData()</a></code> might be returned to an equivalent
<code id="pixel-manipulation:dom-context-2d-getimagedata-2"><a href="#dom-context-2d-getimagedata-2">getImageData()</a></code> as different values.</p>
<p>The current path, <a href="#transformations" id="pixel-manipulation:transformations">transformation matrix</a>,
<a href="#shadows" id="pixel-manipulation:shadows">shadow attributes</a>, <a href="#dom-context-2d-globalalpha-2" id="pixel-manipulation:dom-context-2d-globalalpha-2-2">global
alpha</a>, the <a href="#clipping-region" id="pixel-manipulation:clipping-region">clipping region</a>, and <a href="#dom-context-2d-globalcompositeoperation-2" id="pixel-manipulation:dom-context-2d-globalcompositeoperation-2-2">global composition operator</a> must not
affect the methods described in this section.</p>
<div class="example">
<p>In the following example, the script generates an <code id="pixel-manipulation:imagedata-20"><a href="#imagedata">ImageData</a></code> object so that it can
draw onto it.</p>
<pre>// canvas is a reference to a &lt;canvas&gt; element
var context = canvas.getContext('2d');
// create a blank slate
var data = context.createImageData(canvas.width, canvas.height);
// create some plasma
FillPlasma(data, 'green'); // green plasma
// add a cloud to the plasma
AddCloud(data, data.width/2, data.height/2); // put a cloud in the middle
// paint the plasma+cloud on the canvas
context.putImageData(data, 0, 0);
// support methods
function FillPlasma(data, color) { ... }
function AddCloud(data, x, y) { ... }</pre>
</div>
<div class="example">
<p>Here is an example of using <code id="pixel-manipulation:dom-context-2d-getimagedata-2-2"><a href="#dom-context-2d-getimagedata-2">getImageData()</a></code> and <code id="pixel-manipulation:dom-context-2d-putimagedata-2-2"><a href="#dom-context-2d-putimagedata-2">putImageData()</a></code> to implement an edge detection
filter.</p>
<pre>&lt;!DOCTYPE HTML&gt;
&lt;html lang=&quot;en&quot;&gt;
&lt;head&gt;
&lt;title&gt;Edge detection demo&lt;/title&gt;
&lt;script&gt;
var image = new Image();
function init() {
image.onload = demo;
image.src = &quot;image.jpeg&quot;;
}
function demo() {
var canvas = document.getElementsByTagName('canvas')[0];
var context = canvas.getContext('2d');
// draw the image onto the canvas
context.drawImage(image, 0, 0);
// get the image data to manipulate
var input = context.getImageData(0, 0, canvas.width, canvas.height);
// get an empty slate to put the data into
var output = context.createImageData(canvas.width, canvas.height);
// alias some variables for convenience
// In this case input.width and input.height
// match canvas.width and canvas.height
// but we'll use the former to keep the code generic.
var w = input.width, h = input.height;
var inputData = input.data;
var outputData = output.data;
// edge detection
for (var y = 1; y &lt; h-1; y += 1) {
for (var x = 1; x &lt; w-1; x += 1) {
for (var c = 0; c &lt; 3; c += 1) {
var i = (y*w + x)*4 + c;
outputData[i] = 127 + -inputData[i - w*4 - 4] - inputData[i - w*4] - inputData[i - w*4 + 4] +
-inputData[i - 4] + 8*inputData[i] - inputData[i + 4] +
-inputData[i + w*4 - 4] - inputData[i + w*4] - inputData[i + w*4 + 4];
}
outputData[(y*w + x)*4 + 3] = 255; // alpha
}
}
// put the image data back after manipulation
context.putImageData(output, 0, 0);
}
&lt;/script&gt;
&lt;/head&gt;
&lt;body onload=&quot;init()&quot;&gt;
&lt;canvas&gt;&lt;/canvas&gt;
&lt;/body&gt;
&lt;/html&gt;</pre>
</div>
<h6 id="compositing"><span class="secno">4.12.5.1.16</span> Compositing<a class="self-link" href="#compositing"/></h6>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-globalalpha"><a href="#dom-context-2d-globalalpha-2">globalAlpha</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current alpha value applied to rendering operations.</p>
<p>Can be set, to change the alpha value. Values outside of the range 0.0 .. 1.0 are
ignored.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-globalcompositeoperation"><a href="#dom-context-2d-globalcompositeoperation-2">globalCompositeOperation</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current composition operation, from the values defined in the Compositing and
Blending specification. <a href="https://html.spec.whatwg.org/multipage/references.html#refsCOMPOSITE">[COMPOSITE]</a>.</p>
<p>Can be set, to change the composition operation. Unknown values are ignored.</p>
</dd></dl><div class="status"><input onclick="toggleStatus(this)" type="button" value="⋰"/><p class="bugs"><strong>Spec bugs:</strong> <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=27313" title="It seems like this should be defined in terms of an IDL enum. If not, please clarify the relationshi [...]">27313</a></p></div>
<p>All drawing operations on an object which implements the <code id="compositing:canvascompositing"><a href="#canvascompositing">CanvasCompositing</a></code>
interface are affected by the global compositing attributes, <code id="compositing:dom-context-2d-globalalpha-2"><a href="#dom-context-2d-globalalpha-2">globalAlpha</a></code> and <code id="compositing:dom-context-2d-globalcompositeoperation-2"><a href="#dom-context-2d-globalcompositeoperation-2">globalCompositeOperation</a></code>.</p>
<p>The <dfn id="dom-context-2d-globalalpha-2"><code>globalAlpha</code></dfn> attribute gives an
alpha value that is applied to shapes and images before they are composited onto the <a href="#output-bitmap" id="compositing:output-bitmap">output
bitmap</a>. The value must be in the range from 0.0 (fully transparent) to 1.0 (no additional
transparency). If an attempt is made to set the attribute to a value outside this range, including
Infinity and Not-a-Number (NaN) values, then the attribute must retain its previous value. When
the context is created, the <code id="compositing:dom-context-2d-globalalpha-2-2"><a href="#dom-context-2d-globalalpha-2">globalAlpha</a></code> attribute
must initially have the value 1.0.</p>
<p>The <dfn id="dom-context-2d-globalcompositeoperation-2"><code>globalCompositeOperation</code></dfn> attribute
sets the <dfn id="current-composition-operator">current composition operator</dfn>, which controls how shapes and images are drawn onto the
<a href="#output-bitmap" id="compositing:output-bitmap-2">output bitmap</a>, once they have had <code id="compositing:dom-context-2d-globalalpha-2-3"><a href="#dom-context-2d-globalalpha-2">globalAlpha</a></code> and the current transformation matrix
applied. The possible values are those defined in the Compositing and Blending specification, and
include the values <dfn id="gcop-source-over"><code>source-over</code></dfn>
and <dfn id="gcop-copy"><code>copy</code></dfn>.
<a href="https://html.spec.whatwg.org/multipage/references.html#refsCOMPOSITE">[COMPOSITE]</a></p>
<p>These values are all case-sensitive — they must be used exactly as defined. User agents
must not recognize values that are not a <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#case-sensitive" id="compositing:case-sensitive">case-sensitive</a> match for one of the values
given in the Compositing and Blending specification. <a href="https://html.spec.whatwg.org/multipage/references.html#refsCOMPOSITE">[COMPOSITE]</a></p>
<p>On setting, if the user agent does not recognize the specified value, it must be ignored,
leaving the value of <code id="compositing:dom-context-2d-globalcompositeoperation-2-2"><a href="#dom-context-2d-globalcompositeoperation-2">globalCompositeOperation</a></code> unaffected.
Otherwise, the attribute must be set to the given new value.</p>
<p>When the context is created, the <code id="compositing:dom-context-2d-globalcompositeoperation-2-3"><a href="#dom-context-2d-globalcompositeoperation-2">globalCompositeOperation</a></code> attribute must
initially have the value <code id="compositing:gcop-source-over"><a href="#gcop-source-over">source-over</a></code>.</p>
<h6 id="image-smoothing"><span class="secno">4.12.5.1.17</span> Image smoothing<a class="self-link" href="#image-smoothing"/></h6>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-imagesmoothingenabled"><a href="#dom-context-2d-imagesmoothingenabled-2">imageSmoothingEnabled</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns whether pattern fills and the <code id="image-smoothing:dom-context-2d-drawimage"><a href="#dom-context-2d-drawimage">drawImage()</a></code> method will attempt to smooth images if
their pixels don't line up exactly with the display, when scaling images up.</p>
<p>Can be set, to change whether images are smoothed (true) or not (false).</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-imagesmoothingquality"><a href="#dom-context-2d-imagesmoothingquality-2">imageSmoothingQuality</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current image-smoothing-quality preference.</p>
<p>Can be set, to change the preferred quality of image smoothing. The possible values are
&quot;<code id="image-smoothing:dom-context-2d-imagesmoothingquality-low"><a href="#dom-context-2d-imagesmoothingquality-low">low</a></code>&quot;, &quot;<code id="image-smoothing:dom-context-2d-imagesmoothingquality-medium"><a href="#dom-context-2d-imagesmoothingquality-medium">medium</a></code>&quot; and &quot;<code id="image-smoothing:dom-context-2d-imagesmoothingquality-high"><a href="#dom-context-2d-imagesmoothingquality-high">high</a></code>&quot;. Unknown values are ignored.</p>
</dd></dl>
<p>Objects that implement the <code id="image-smoothing:canvasimagesmoothing"><a href="#canvasimagesmoothing">CanvasImageSmoothing</a></code> interface have attributes that
control how image smoothing is performed.</p>
<p>The <dfn id="dom-context-2d-imagesmoothingenabled-2"><code>imageSmoothingEnabled</code></dfn>
attribute, on getting, must return the last value it was set to. On setting, it must be set to the
new value. When the object implementing the <code id="image-smoothing:canvasimagesmoothing-2"><a href="#canvasimagesmoothing">CanvasImageSmoothing</a></code> interface is
created, the attribute must be set to true.</p>
<p>The <dfn id="dom-context-2d-imagesmoothingquality-2"><code>imageSmoothingQuality</code></dfn>
attribute, on getting, must return the last value it was set to. On setting, it must be set to the
new value. When the object implementing the <code id="image-smoothing:canvasimagesmoothing-3"><a href="#canvasimagesmoothing">CanvasImageSmoothing</a></code> interface is
created, the attribute must be set to &quot;<code id="image-smoothing:dom-context-2d-imagesmoothingquality-low-2"><a href="#dom-context-2d-imagesmoothingquality-low">low</a></code>&quot;.</p>
<h6 id="shadows"><span class="secno">4.12.5.1.18</span> <dfn>Shadows</dfn><a class="self-link" href="#shadows"/></h6>
<p>All drawing operations on an object which implements the <code id="shadows:canvasshadowstyles"><a href="#canvasshadowstyles">CanvasShadowStyles</a></code>
interface are affected by the four global shadow attributes.</p>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-shadowcolor"><a href="#dom-context-2d-shadowcolor-2">shadowColor</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current shadow color.</p>
<p>Can be set, to change the shadow color. Values that cannot be parsed as CSS colors are ignored.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-shadowoffsetx"><a href="#dom-context-2d-shadowoffsetx-2">shadowOffsetX</a></code> [ = <var>value</var> ]</dt><dt><var>context</var> . <code id="dom-context-2d-shadowoffsety"><a href="#dom-context-2d-shadowoffsety-2">shadowOffsetY</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current shadow offset.</p>
<p>Can be set, to change the shadow offset. Values that are not finite numbers are ignored.</p>
</dd><dt><var>context</var> . <code id="dom-context-2d-shadowblur"><a href="#dom-context-2d-shadowblur-2">shadowBlur</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current level of blur applied to shadows.</p>
<p>Can be set, to change the blur level. Values that are not finite numbers greater than or
equal to zero are ignored.</p>
</dd></dl>
<p>The <dfn id="dom-context-2d-shadowcolor-2"><code>shadowColor</code></dfn> attribute sets the
color of the shadow.</p>
<p>When the context is created, the <code id="shadows:dom-context-2d-shadowcolor-2"><a href="#dom-context-2d-shadowcolor-2">shadowColor</a></code>
attribute initially must be fully-transparent black.</p>
<p>On getting, the <a href="#serialisation-of-a-color" id="shadows:serialisation-of-a-color">serialization of the color</a>
must be returned.</p>
<p>On setting, the new value must be <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#parsed-as-a-css-color-value" id="shadows:parsed-as-a-css-color-value">parsed as a CSS &lt;color&gt; value</a> and the
color assigned. If the value cannot be <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#parsed-as-a-css-color-value" id="shadows:parsed-as-a-css-color-value-2">parsed as a CSS &lt;color&gt; value</a> then it
must be ignored, and the attribute must retain its previous value. <a href="https://html.spec.whatwg.org/multipage/references.html#refsCSSCOLOR">[CSSCOLOR]</a></p>
<p>The <dfn id="dom-context-2d-shadowoffsetx-2"><code>shadowOffsetX</code></dfn> and <dfn id="dom-context-2d-shadowoffsety-2"><code>shadowOffsetY</code></dfn> attributes specify the distance
that the shadow will be offset in the positive horizontal and positive vertical distance
respectively. Their values are in coordinate space units. They are not affected by the current
transformation matrix.</p>
<p>When the context is created, the shadow offset attributes must initially have the value
0.</p>
<p>On getting, they must return their current value. On setting, the attribute being set must be
set to the new value, except if the value is infinite or NaN, in which case the new value must be
ignored.</p>
<p>The <dfn id="dom-context-2d-shadowblur-2"><code>shadowBlur</code></dfn> attribute specifies
the level of the blurring effect. (The units do not map to coordinate space units, and are not
affected by the current transformation matrix.)</p>
<p>When the context is created, the <code id="shadows:dom-context-2d-shadowblur-2"><a href="#dom-context-2d-shadowblur-2">shadowBlur</a></code>
attribute must initially have the value 0.</p>
<p>On getting, the attribute must return its current value. On setting the attribute must be set
to the new value, except if the value is negative, infinite or NaN, in which case the new value
must be ignored.</p>
<p><dfn id="when-shadows-are-drawn">Shadows are only drawn if</dfn> the opacity component of
the alpha component of the color of <code id="shadows:dom-context-2d-shadowcolor-2-2"><a href="#dom-context-2d-shadowcolor-2">shadowColor</a></code> is
non-zero and either the <code id="shadows:dom-context-2d-shadowblur-2-2"><a href="#dom-context-2d-shadowblur-2">shadowBlur</a></code> is non-zero, or
the <code id="shadows:dom-context-2d-shadowoffsetx-2"><a href="#dom-context-2d-shadowoffsetx-2">shadowOffsetX</a></code> is non-zero, or the <code id="shadows:dom-context-2d-shadowoffsety-2"><a href="#dom-context-2d-shadowoffsety-2">shadowOffsetY</a></code> is non-zero.</p>
<p><a href="#when-shadows-are-drawn" id="shadows:when-shadows-are-drawn">When shadows are drawn</a>, they must be rendered as follows:</p>
<ol><li><p>Let <var>A</var> be an infinite transparent black bitmap on which the source
image for which a shadow is being created has been rendered.</p></li><li><p>Let <var>B</var> be an infinite transparent black bitmap, with a coordinate
space and an origin identical to <var>A</var>.</p></li><li><p>Copy the alpha channel of <var>A</var> to <var>B</var>, offset by <code id="shadows:dom-context-2d-shadowoffsetx-2-2"><a href="#dom-context-2d-shadowoffsetx-2">shadowOffsetX</a></code> in the positive <var>x</var>
direction, and <code id="shadows:dom-context-2d-shadowoffsety-2-2"><a href="#dom-context-2d-shadowoffsety-2">shadowOffsetY</a></code> in the positive
<var>y</var> direction.</p></li><li>
<p>If <code id="shadows:dom-context-2d-shadowblur-2-3"><a href="#dom-context-2d-shadowblur-2">shadowBlur</a></code> is greater than 0:</p>
<ol><li> <p>Let <var>σ</var> be half the value of <code id="shadows:dom-context-2d-shadowblur-2-4"><a href="#dom-context-2d-shadowblur-2">shadowBlur</a></code>.</p></li><li> <p>Perform a 2D Gaussian Blur on <var>B</var>, using <var>σ</var>
as the standard deviation.</p> </li></ol>
<p>User agents may limit values of <var>σ</var> to an implementation-specific
maximum value to avoid exceeding hardware limitations during the Gaussian blur operation.</p>
</li><li><p>Set the red, green, and blue components of every pixel in <var>B</var> to the
red, green, and blue components (respectively) of the color of <code id="shadows:dom-context-2d-shadowcolor-2-3"><a href="#dom-context-2d-shadowcolor-2">shadowColor</a></code>.</p></li><li><p>Multiply the alpha component of every pixel in <var>B</var> by the alpha
component of the color of <code id="shadows:dom-context-2d-shadowcolor-2-4"><a href="#dom-context-2d-shadowcolor-2">shadowColor</a></code>.</p></li><li><p>The shadow is in the bitmap <var>B</var>, and is rendered as part of the
<a href="#drawing-model" id="shadows:drawing-model">drawing model</a> described below.</p></li></ol>
<p>If the current composition operation is <code id="shadows:gcop-copy"><a href="#gcop-copy">copy</a></code>, then shadows
effectively won't render (since the shape will overwrite the shadow).</p>
<h6 id="filters"><span class="secno">4.12.5.1.19</span> Filters<a class="self-link" href="#filters"/></h6>
<p>All drawing operations on an object which implements the <code id="filters:canvasfilters"><a href="#canvasfilters">CanvasFilters</a></code>
interface are affected by the global <dfn id="dom-context-2d-filter"><code>filter</code></dfn>
attribute.</p>
<dl class="domintro"><dt><var>context</var> . <code id="dom-context-2d-filter-2"><a href="#dom-context-2d-filter">filter</a></code> [ = <var>value</var> ]</dt><dd>
<p>Returns the current filter.</p>
<p>Can be set, to change the filter. Values that cannot be parsed as a
<a data-x-internal="filter-function-list" href="https://drafts.fxtf.org/filters/#typedef-filter-function-list" id="filters:filter-function-list">&lt;filter-function-list&gt;</a> value are ignored.</p>
</dd></dl>
<p>The <code id="filters:dom-context-2d-filter"><a href="#dom-context-2d-filter">filter</a></code> attribute, on getting, must
return the last value it was successfully set to. The value must not be re-serialized. On setting,
if the new value is 'none' (not the empty string, null, or undefined), filters must be disabled
for the context. Otherwise, the value must be parsed as a
<a data-x-internal="filter-function-list" href="https://drafts.fxtf.org/filters/#typedef-filter-function-list" id="filters:filter-function-list-2">&lt;filter-function-list&gt;</a> value. If the value cannot be parsed as a
<a data-x-internal="filter-function-list" href="https://drafts.fxtf.org/filters/#typedef-filter-function-list" id="filters:filter-function-list-3">&lt;filter-function-list&gt;</a> value, where using property-independent style sheet
syntax like 'inherit' or 'initial' is considered an invalid value, then it must be ignored, and
the attribute must retain its previous value. When creating the object implementing the
<code id="filters:canvasfilters-2"><a href="#canvasfilters">CanvasFilters</a></code> interface, the attribute must be set to 'none'.</p>
<p>A <a data-x-internal="filter-function-list" href="https://drafts.fxtf.org/filters/#typedef-filter-function-list" id="filters:filter-function-list-4">&lt;filter-function-list&gt;</a> value consists of a sequence of one or more
filter functions or references to SVG filters. The input to the filter is used as the input
to the first item in the list. Subsequent items take the output of the previous item as
their input. <a href="https://html.spec.whatwg.org/multipage/references.html#refsFILTERS">[FILTERS]</a></p>
<p>Coordinates used in the value of the <code id="filters:dom-context-2d-filter-2"><a href="#dom-context-2d-filter">filter</a></code> attribute are interpreted such that one pixel is
equivalent to one SVG user space unit and to one canvas coordinate space unit. Filter coordinates
are not affected by the <a href="#transformations" id="filters:transformations">current transformation
matrix</a>. The current transformation matrix affects only the input to the filter. Filters
are applied in the <a href="#output-bitmap" id="filters:output-bitmap">output bitmap</a>'s coordinate space.</p>
<p>When the value of the <code id="filters:dom-context-2d-filter-3"><a href="#dom-context-2d-filter">filter</a></code> attribute defines
lengths using percentages or using <a data-x-internal="'em'" href="https://drafts.csswg.org/css-values/#em" id="filters:'em'">'em'</a> or <a data-x-internal="'ex'" href="https://drafts.csswg.org/css-values/#ex" id="filters:'ex'">'ex'</a> units, these must be
interpreted relative to the <a data-x-internal="computed-value" href="https://drafts.csswg.org/css-cascade/#computed-value" id="filters:computed-value">computed value</a> of the <a data-x-internal="'font-size'" href="https://drafts.csswg.org/css-fonts/#font-size-prop" id="filters:'font-size'">'font-size'</a> property
of the <a href="#font-style-source-object" id="filters:font-style-source-object">font style source object</a> at the time that the attribute is set, if it is an
element. If the <a data-x-internal="computed-value" href="https://drafts.csswg.org/css-cascade/#computed-value" id="filters:computed-value-2">computed values</a> are undefined for a
particular case (e.g. because the <a href="#font-style-source-object" id="filters:font-style-source-object-2">font style source object</a> is not an element or is
not <a href="https://html.spec.whatwg.org/multipage/rendering.html#being-rendered" id="filters:being-rendered">being rendered</a>), then the relative keywords must be interpreted relative to the
default value of the <code id="filters:dom-context-2d-font-2"><a href="#dom-context-2d-font-2">font</a></code> attribute. The 'larger' and
'smaller' keywords are not supported.</p>
<p>If the value of the <code id="filters:dom-context-2d-filter-4"><a href="#dom-context-2d-filter">filter</a></code> attribute refers to an
SVG filter in the same document, and this SVG filter changes, then the changed filter is used for
the next draw operation.</p>
<p>If the value of the <code id="filters:dom-context-2d-filter-5"><a href="#dom-context-2d-filter">filter</a></code> attribute refers to an
SVG filter in an external resource document and that document is not loaded when a drawing
operation is invoked, then the drawing operation must proceed with no filtering.</p>
<h6 id="working-with-externally-defined-svg-filters"><span class="secno">4.12.5.1.20</span> Working with externally-defined SVG filters<a class="self-link" href="#working-with-externally-defined-svg-filters"/></h6>
<p><i>This section is non-normative.</i></p>
<p>Since drawing is performed using filter value 'none' until an externally-defined
filter has finished loading, authors might wish to determine whether such a filter
has finished loading before proceeding with a drawing operation. One way to accomplish
this is to load the externally-defined filter elsewhere within the same page in some
element that sends a <code>load</code> event (for example, an <a data-x-internal="svg-use" href="https://www.w3.org/TR/SVG11/struct.html#UseElement" id="working-with-externally-defined-svg-filters:svg-use">SVG
<code>use</code></a> element), and wait for the <code>load</code> event to be
dispatched.</p>
<h6 id="drawing-model"><span class="secno">4.12.5.1.21</span> <dfn>Drawing model</dfn><a class="self-link" href="#drawing-model"/></h6>
<p>When a shape or image is painted, user agents must follow these steps, in the order given (or
act as if they do):</p>
<ol><li><p>Render the shape or image onto an infinite transparent black bitmap, creating image <var>A</var>, as described in the previous sections. For shapes, the current fill, stroke,
and line styles must be honored, and the stroke must itself also be subjected to the current
transformation matrix.</p></li><li><p>When the filter attribute is set to a value other than 'none' and all the
externally-defined filters it references, if any, are in documents that are currently loaded,
then use image <var>A</var> as the input to the <code id="drawing-model:dom-context-2d-filter"><a href="#dom-context-2d-filter">filter</a></code>, creating image <var>B</var>. Otherwise, let
<var>B</var> be an alias for <var>A</var>.</p></li><li><p><a href="#when-shadows-are-drawn" id="drawing-model:when-shadows-are-drawn">When shadows are drawn</a>, render the shadow from image <var>B</var>,
using the current shadow styles, creating image <var>C</var>.</p></li><li><p><a href="#when-shadows-are-drawn" id="drawing-model:when-shadows-are-drawn-2">When shadows are drawn</a>, multiply the alpha component of every pixel in <var>C</var> by <code id="drawing-model:dom-context-2d-globalalpha-2"><a href="#dom-context-2d-globalalpha-2">globalAlpha</a></code>.</p></li><li><p><a href="#when-shadows-are-drawn" id="drawing-model:when-shadows-are-drawn-3">When shadows are drawn</a>, composite <var>C</var> within the
<a href="#clipping-region" id="drawing-model:clipping-region">clipping region</a> over the current <a href="#output-bitmap" id="drawing-model:output-bitmap">output bitmap</a> using the <a href="#current-composition-operator" id="drawing-model:current-composition-operator">current
composition operator</a>.</p></li><li><p>Multiply the alpha component of every pixel in <var>B</var> by <code id="drawing-model:dom-context-2d-globalalpha-2-2"><a href="#dom-context-2d-globalalpha-2">globalAlpha</a></code>.</p></li><li><p>Composite <var>B</var> within the <a href="#clipping-region" id="drawing-model:clipping-region-2">clipping region</a> over the current
<a href="#output-bitmap" id="drawing-model:output-bitmap-2">output bitmap</a> using the <a href="#current-composition-operator" id="drawing-model:current-composition-operator-2">current composition operator</a>.</p></li></ol>
<p>When compositing onto the <a href="#output-bitmap" id="drawing-model:output-bitmap-3">output bitmap</a>, pixels that would fall outside of the
<a href="#output-bitmap" id="drawing-model:output-bitmap-4">output bitmap</a> must be discarded.</p>
<h6 id="best-practices"><span class="secno">4.12.5.1.22</span> Best practices<a class="self-link" href="#best-practices"/></h6>
<p>When a canvas is interactive, authors should include focusable elements in the element's
fallback content corresponding to each focusable part of the canvas, as in the <a href="#drawCustomFocusRingExample">example above</a>.</p>
<p>When rendering focus rings, to ensure that focus rings have the appearance of native focus
rings, authors should use the <code id="best-practices:dom-context-2d-drawfocusifneeded-2"><a href="#dom-context-2d-drawfocusifneeded-2">drawFocusIfNeeded()</a></code> method, passing it the
element for which a ring is being drawn. This method only draws the focus ring if the element is
<a href="https://html.spec.whatwg.org/multipage/interaction.html#focused" id="best-practices:focused">focused</a>, so that it can simply be called whenever drawing the element, without
checking whether the element is focused or not first.</p>
<p>In addition to drawing focus rings, authors should use the <code id="best-practices:dom-context-2d-scrollpathintoview-2"><a href="#dom-context-2d-scrollpathintoview-2">scrollPathIntoView()</a></code> method when an element in
the canvas is focused, to make sure it is visible on the screen (if applicable).</p>
<p id="no-text-editing-in-canvas-please">Authors should avoid implementing text editing controls
using the <code id="best-practices:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element. Doing so has a large number of disadvantages:</p>
<ul><li>Mouse placement of the caret has to be reimplemented.</li><li>Keyboard movement of the caret has to be reimplemented (possibly across lines, for multiline
text input).</li><li>Scrolling of the text control has to be implemented (horizontally for long lines, vertically
for multiline input).</li><li>Native features such as copy-and-paste have to be reimplemented.</li><li>Native features such as spell-checking have to be reimplemented.</li><li>Native features such as drag-and-drop have to be reimplemented.</li><li>Native features such as page-wide text search have to be reimplemented.</li><li>Native features specific to the user, for example custom text services, have to be
reimplemented. This is close to impossible since each user might have different services
installed, and there is an unbounded set of possible such services.</li><li>Bidirectional text editing has to be reimplemented.</li><li>For multiline text editing, line wrapping has to be implemented for all relevant
languages.</li><li>Text selection has to be reimplemented.</li><li>Dragging of bidirectional text selections has to be reimplemented.</li><li>Platform-native keyboard shortcuts have to be reimplemented.</li><li>Platform-native input method editors (IMEs) have to be reimplemented.</li><li>Undo and redo functionality has to be reimplemented.</li><li>Accessibility features such as magnification following the caret or selection have to be
reimplemented.</li></ul>
<p>This is a huge amount of work, and authors are most strongly encouraged to avoid doing any of
it by instead using the <code id="best-practices:the-input-element"><a href="https://html.spec.whatwg.org/multipage/input.html#the-input-element">input</a></code> element, the <code id="best-practices:the-textarea-element"><a href="https://html.spec.whatwg.org/multipage/form-elements.html#the-textarea-element">textarea</a></code> element, or the
<code id="best-practices:attr-contenteditable"><a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-contenteditable">contenteditable</a></code> attribute.</p>
<h6 id="examples"><span class="secno">4.12.5.1.23</span> Examples<a class="self-link" href="#examples"/></h6>
<p><i>This section is non-normative.</i></p>
<div class="example">
<p>Here is an example of a script that uses canvas to draw <a href="data:text/html;charset=utf-8;base64,PCFET0NUWVBFIEhUTUw%2BDQo8aHRtbCBsYW5nPSJlbiI%2BDQogPGhlYWQ%2BDQogIDx0aXRsZT5QcmV0dHkgR2xvd2luZyBMaW5lczwvdGl0bGU%2BDQogPC9oZWFkPg0KIDxib2R5Pg0KPGNhbnZhcyB3aWR0aD0iODAwIiBoZWlnaHQ9IjQ1MCI%2BPC9jYW52YXM%2BDQo8c2NyaXB0Pg0KDQogdmFyIGNvbnRleHQgPSBkb2N1bWVudC5nZXRFbGVtZW50c0J5VGFnTmFtZSgnY2FudmFzJylbMF0uZ2V0Q29udGV4dCgnMmQnKTsNCg0KIHZhciBsYXN0WCA9IGNvbnRleHQuY2FudmFzLndpZHRoICogTWF0aC5yYW5kb20oKTsNCiB2YXIgbGFzdFkgPSBjb250ZXh0LmNhbnZhcy5oZWlnaHQgKiBNYXRoLnJhbmRvbSgpOw0KIHZhciBodWUgPSAwOw0KIGZ1bmN0aW9uIGxpbmUoKSB7DQogICBjb250ZXh0LnNhdmUoKTsNCiAgIGNvbnRleHQudHJhbnNsYXRlKGNvbnRleHQuY2FudmFzLndpZHRoLzIsIGNvbnRleHQuY2FudmFzLmhlaWdodC8yKTsNCiAgIGNvbnRleHQuc2NhbGUoMC45LCAwLjkpOw0KICAgY29udGV4dC50cmFuc2xhdGUoLWNvbnRleHQuY2FudmFzLndpZHRoLzIsIC1jb250ZXh0LmNhbnZhcy5oZWlnaHQvMik7DQogICBjb250ZXh0LmJlZ2luUGF0aCgpOw0KICAgY29udGV4dC5saW5lV2lkdGggPSA1ICsgTWF0aC5yYW5kb20oKSAqIDEwOw0KICAgY29udGV4dC5tb3ZlVG8obGFzdFgsIGxhc3RZKTsNCiAgIGxhc3RYID0gY29udGV4dC5jYW52YXMud2lkdGggKiBNYXRoLnJhbmRvbSgpOw0KICAgbGFzdFkgPSBjb250ZXh0LmNhbnZhcy5oZWlnaHQgKiBNYXRoLnJhbmRvbSgpOw0KICAgY29udGV4dC5iZXppZXJDdXJ2ZVRvKGNvbnRleHQuY2FudmFzLndpZHRoICogTWF0aC5yYW5kb20oKSwNCiAgICAgICAgICAgICAgICAgICAgICAgICBjb250ZXh0LmNhbnZhcy5oZWlnaHQgKiBNYXRoLnJhbmRvbSgpLA0KICAgICAgICAgICAgICAgICAgICAgICAgIGNvbnRleHQuY2FudmFzLndpZHRoICogTWF0aC5yYW5kb20oKSwNCiAgICAgICAgICAgICAgICAgICAgICAgICBjb250ZXh0LmNhbnZhcy5oZWlnaHQgKiBNYXRoLnJhbmRvbSgpLA0KICAgICAgICAgICAgICAgICAgICAgICAgIGxhc3RYLCBsYXN0WSk7DQoNCiAgIGh1ZSA9IGh1ZSArIDEwICogTWF0aC5yYW5kb20oKTsNCiAgIGNvbnRleHQuc3Ryb2tlU3R5bGUgPSAnaHNsKCcgKyBodWUgKyAnLCA1MCUsIDUwJSknOw0KICAgY29udGV4dC5zaGFkb3dDb2xvciA9ICd3aGl0ZSc7DQogICBjb250ZXh0LnNoYWRvd0JsdXIgPSAxMDsNCiAgIGNvbnRleHQuc3Ryb2tlKCk7DQogICBjb250ZXh0LnJlc3RvcmUoKTsNCiB9DQogc2V0SW50ZXJ2YWwobGluZSwgNTApOw0KDQogZnVuY3Rpb24gYmxhbmsoKSB7DQogICBjb250ZXh0LmZpbGxTdHlsZSA9ICdyZ2JhKDAsMCwwLDAuMSknOw0KICAgY29udGV4dC5maWxsUmVjdCgwLCAwLCBjb250ZXh0LmNhbnZhcy53aWR0aCwgY29udGV4dC5jYW52YXMuaGVpZ2h0KTsNCiB9DQogc2V0SW50ZXJ2YWwoYmxhbmssIDQwKTsNCg0KPC9zY3JpcHQ%2BDQogPC9ib2R5Pg0KPC9odG1sPg0K">pretty glowing lines</a>.</p>
<pre>&lt;canvas width=&quot;800&quot; height=&quot;450&quot;&gt;&lt;/canvas&gt;
&lt;script&gt;
var context = document.getElementsByTagName('canvas')[0].getContext('2d');
var lastX = context.canvas.width * Math.random();
var lastY = context.canvas.height * Math.random();
var hue = 0;
function line() {
context.save();
context.translate(context.canvas.width/2, context.canvas.height/2);
context.scale(0.9, 0.9);
context.translate(-context.canvas.width/2, -context.canvas.height/2);
context.beginPath();
context.lineWidth = 5 + Math.random() * 10;
context.moveTo(lastX, lastY);
lastX = context.canvas.width * Math.random();
lastY = context.canvas.height * Math.random();
context.bezierCurveTo(context.canvas.width * Math.random(),
context.canvas.height * Math.random(),
context.canvas.width * Math.random(),
context.canvas.height * Math.random(),
lastX, lastY);
hue = hue + 10 * Math.random();
context.strokeStyle = 'hsl(' + hue + ', 50%, 50%)';
context.shadowColor = 'white';
context.shadowBlur = 10;
context.stroke();
context.restore();
}
setInterval(line, 50);
function blank() {
context.fillStyle = 'rgba(0,0,0,0.1)';
context.fillRect(0, 0, context.canvas.width, context.canvas.height);
}
setInterval(blank, 40);
&lt;/script&gt;</pre>
</div>
<div class="example">
<p>The 2D rendering context for <code id="examples:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> is often used for sprite-based games. The
following example demonstrates this:</p>
<iframe height="216" src="https://html.spec.whatwg.org/demos/canvas/blue-robot/index-idle.html" width="396"/>
<p>Here is the source for this example:</p>
<pre>&lt;!DOCTYPE HTML&gt;
&lt;meta charset=&quot;utf-8&quot;&gt;
&lt;title&gt;Blue Robot Demo&lt;/title&gt;
&lt;style&gt;
html { overflow: hidden; min-height: 200px; min-width: 380px; }
body { height: 200px; position: relative; margin: 8px; }
.buttons { position: absolute; bottom: 0px; left: 0px; margin: 4px; }
&lt;/style&gt;
&lt;canvas width=&quot;380&quot; height=&quot;200&quot;&gt;&lt;/canvas&gt;
&lt;script&gt;
var Landscape = function (context, width, height) {
this.offset = 0;
this.width = width;
this.advance = function (dx) {
this.offset += dx;
};
this.horizon = height * 0.7;
// This creates the sky gradient (from a darker blue to white at the bottom)
this.sky = context.createLinearGradient(0, 0, 0, this.horizon);
this.sky.addColorStop(0.0, 'rgb(55,121,179)');
this.sky.addColorStop(0.7, 'rgb(121,194,245)');
this.sky.addColorStop(1.0, 'rgb(164,200,214)');
// this creates the grass gradient (from a darker green to a lighter green)
this.earth = context.createLinearGradient(0, this.horizon, 0, height);
this.earth.addColorStop(0.0, 'rgb(81,140,20)');
this.earth.addColorStop(1.0, 'rgb(123,177,57)');
this.paintBackground = function (context, width, height) {
// first, paint the sky and grass rectangles
context.fillStyle = this.sky;
context.fillRect(0, 0, width, this.horizon);
context.fillStyle = this.earth;
context.fillRect(0, this.horizon, width, height-this.horizon);
// then, draw the cloudy banner
// we make it cloudy by having the draw text off the top of the
// canvas, and just having the blurred shadow shown on the canvas
context.save();
context.translate(width-((this.offset+(this.width*3.2)) % (this.width*4.0))+0, 0);
context.shadowColor = 'white';
context.shadowOffsetY = 30+this.horizon/3; // offset down on canvas
context.shadowBlur = '5';
context.fillStyle = 'white';
context.textAlign = 'left';
context.textBaseline = 'top';
context.font = '20px sans-serif';
context.fillText('WHATWG ROCKS', 10, -30); // text up above canvas
context.restore();
// then, draw the background tree
context.save();
context.translate(width-((this.offset+(this.width*0.2)) % (this.width*1.5))+30, 0);
context.beginPath();
context.fillStyle = 'rgb(143,89,2)';
context.lineStyle = 'rgb(10,10,10)';
context.lineWidth = 2;
context.rect(0, this.horizon+5, 10, -50); // trunk
context.fill();
context.stroke();
context.beginPath();
context.fillStyle = 'rgb(78,154,6)';
context.arc(5, this.horizon-60, 30, 0, Math.PI*2); // leaves
context.fill();
context.stroke();
context.restore();
};
this.paintForeground = function (context, width, height) {
// draw the box that goes in front
context.save();
context.translate(width-((this.offset+(this.width*0.7)) % (this.width*1.1))+0, 0);
context.beginPath();
context.rect(0, this.horizon - 5, 25, 25);
context.fillStyle = 'rgb(220,154,94)';
context.lineStyle = 'rgb(10,10,10)';
context.lineWidth = 2;
context.fill();
context.stroke();
context.restore();
};
};
&lt;/script&gt;
&lt;script&gt;
var BlueRobot = function () {
this.sprites = new Image();
this.sprites.src = 'blue-robot.png'; // this sprite sheet has 8 cells
this.targetMode = 'idle';
this.walk = function () {
this.targetMode = 'walk';
};
this.stop = function () {
this.targetMode = 'idle';
};
this.frameIndex = {
'idle': [0], // first cell is the idle frame
'walk': [1,2,3,4,5,6], // the walking animation is cells 1-6
'stop': [7], // last cell is the stopping animation
};
this.mode = 'idle';
this.frame = 0; // index into frameIndex
this.tick = function () {
// this advances the frame and the robot
// the return value is how many pixels the robot has moved
this.frame += 1;
if (this.frame &gt;= this.frameIndex[this.mode].length) {
// we've reached the end of this animation cycle
this.frame = 0;
if (this.mode != this.targetMode) {
// switch to next cycle
if (this.mode == 'walk') {
// we need to stop walking before we decide what to do next
this.mode = 'stop';
} else if (this.mode == 'stop') {
if (this.targetMode == 'walk')
this.mode = 'walk';
else
this.mode = 'idle';
} else if (this.mode == 'idle') {
if (this.targetMode == 'walk')
this.mode = 'walk';
}
}
}
if (this.mode == 'walk')
return 8;
return 0;
},
this.paint = function (context, x, y) {
if (!this.sprites.complete) return;
// draw the right frame out of the sprite sheet onto the canvas
// we assume each frame is as high as the sprite sheet
// the x,y coordinates give the position of the bottom center of the sprite
context.drawImage(this.sprites,
this.frameIndex[this.mode][this.frame] * this.sprites.height, 0, this.sprites.height, this.sprites.height,
x-this.sprites.height/2, y-this.sprites.height, this.sprites.height, this.sprites.height);
};
};
&lt;/script&gt;
&lt;script&gt;
var canvas = document.getElementsByTagName('canvas')[0];
var context = canvas.getContext('2d');
var landscape = new Landscape(context, canvas.width, canvas.height);
var blueRobot = new BlueRobot();
// paint when the browser wants us to, using requestAnimationFrame()
function paint() {
context.clearRect(0, 0, canvas.width, canvas.height);
landscape.paintBackground(context, canvas.width, canvas.height);
blueRobot.paint(context, canvas.width/2, landscape.horizon*1.1);
landscape.paintForeground(context, canvas.width, canvas.height);
requestAnimationFrame(paint);
}
paint();
// but tick every 150ms, so that we don't slow down when we don't paint
setInterval(function () {
var dx = blueRobot.tick();
landscape.advance(dx);
}, 100);
&lt;/script&gt;
&lt;p class=&quot;buttons&quot;&gt;
&lt;input type=button value=&quot;Walk&quot; onclick=&quot;blueRobot.walk()&quot;&gt;
&lt;input type=button value=&quot;Stop&quot; onclick=&quot;blueRobot.stop()&quot;&gt;
&lt;footer&gt;
&lt;small&gt; Blue Robot Player Sprite by &lt;a href=&quot;https://johncolburn.deviantart.com/&quot;&gt;JohnColburn&lt;/a&gt;.
Licensed under the terms of the Creative Commons Attribution Share-Alike 3.0 Unported license.&lt;/small&gt;
&lt;small&gt; This work is itself licensed under a &lt;a rel=&quot;license&quot; href=&quot;https://creativecommons.org/licenses/by-sa/3.0/&quot;&gt;Creative
Commons Attribution-ShareAlike 3.0 Unported License&lt;/a&gt;.&lt;/small&gt;
&lt;/footer&gt;
</pre>
</div>
<h5 id="the-imagebitmap-rendering-context"><span class="secno">4.12.5.2</span> The <code id="the-imagebitmap-rendering-context:imagebitmap"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code> rendering context<a class="self-link" href="#the-imagebitmap-rendering-context"/></h5>
<h6 id="introduction-6"><span class="secno">4.12.5.2.1</span> Introduction<a class="self-link" href="#introduction-6"/></h6>
<p><code id="introduction-6:imagebitmaprenderingcontext"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> is a performance-oriented interface that provides a
low overhead method for displaying the contents of <code id="introduction-6:imagebitmap"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code> objects. It uses
transfer semantics to reduce overall memory consumption. It also streamlines performance by
avoiding intermediate compositing, unlike the <code id="introduction-6:dom-context-2d-drawimage"><a href="#dom-context-2d-drawimage">drawImage()</a></code> method of
<code id="introduction-6:canvasrenderingcontext2d"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>.</p>
<p>Using an <code id="introduction-6:the-img-element"><a href="https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element">img</a></code> element as an intermediate for getting an image resource into a
canvas, for example, would result in two copies of the decoded image existing in memory at the
same time: the <code id="introduction-6:the-img-element-2"><a href="https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element">img</a></code> element's copy, and the one in the canvas's backing store. This
memory cost can be prohibitive when dealing with extremely large images. This can be avoided by
using <code id="introduction-6:imagebitmaprenderingcontext-2"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code>.</p>
<div class="example">
<p>Using <code id="introduction-6:imagebitmaprenderingcontext-3"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code>, here is how to transcode an image to the JPEG
format in a memory- and CPU-efficient way:</p>
<pre>createImageBitmap(inputImageBlob).then(image =&gt; {
const canvas = document.createElement('canvas');
const context = canvas.getContext('bitmaprenderer');
context.transferFromImageBitmap(image);
canvas.toBlob(outputJPEGBlob =&gt; {
// Do something with outputJPEGBlob.
}, 'image/jpeg');
});</pre>
</div>
<h6 id="the-imagebitmaprenderingcontext-interface"><span class="secno">4.12.5.2.2</span> The <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> interface<a class="self-link" href="#the-imagebitmaprenderingcontext-interface"/></h6>
<pre class="idl">[Exposed=Window]
interface <dfn id="imagebitmaprenderingcontext">ImageBitmapRenderingContext</dfn> {
readonly attribute <a href="#htmlcanvaselement" id="the-imagebitmaprenderingcontext-interface:htmlcanvaselement">HTMLCanvasElement</a> <a href="#dom-imagebitmaprenderingcontext-canvas-2" id="the-imagebitmaprenderingcontext-interface:dom-imagebitmaprenderingcontext-canvas-2">canvas</a>;
void <a href="#dom-imagebitmaprenderingcontext-transferfromimagebitmap-2" id="the-imagebitmaprenderingcontext-interface:dom-imagebitmaprenderingcontext-transferfromimagebitmap-2">transferFromImageBitmap</a>(ImageBitmap? bitmap);
};
dictionary <dfn id="imagebitmaprenderingcontextsettings">ImageBitmapRenderingContextSettings</dfn> {
boolean <a href="#dom-imagebitmaprenderingcontextsettings-alpha" id="the-imagebitmaprenderingcontext-interface:dom-imagebitmaprenderingcontextsettings-alpha">alpha</a> = true;
};</pre>
<dl class="domintro"><dt><var>context</var> = <var>canvas</var> . <code id="the-imagebitmaprenderingcontext-interface:dom-canvas-getcontext-2"><a href="#dom-canvas-getcontext-2">getContext</a></code>('bitmaprenderer' [, { [ <code id="the-imagebitmaprenderingcontext-interface:dom-imagebitmaprenderingcontextsettings-alpha-2"><a href="#dom-imagebitmaprenderingcontextsettings-alpha">alpha</a></code>: false ] } ] )</dt><dd>
<p>Returns an <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-2"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object that is permanently bound to a
particular <code id="the-imagebitmaprenderingcontext-interface:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element.</p>
<p>If the <code id="the-imagebitmaprenderingcontext-interface:dom-imagebitmaprenderingcontextsettings-alpha-3"><a href="#dom-imagebitmaprenderingcontextsettings-alpha">alpha</a></code> setting is
provided and set to false, then the canvas is forced to always be opaque.</p>
</dd><dt><var>context</var> . <code id="dom-imagebitmaprenderingcontext-canvas"><a href="#dom-imagebitmaprenderingcontext-canvas-2">canvas</a></code></dt><dd>
<p>Returns the <code id="the-imagebitmaprenderingcontext-interface:the-canvas-element-2"><a href="#the-canvas-element">canvas</a></code> element that the context is bound to.</p>
</dd><dt><var>context</var> . <code id="dom-imagebitmaprenderingcontext-transferfromimagebitmap"><a href="#dom-imagebitmaprenderingcontext-transferfromimagebitmap-2">transferFromImageBitmap</a></code>(imageBitmap)</dt><dd>
<p>Transfers the underlying <a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#concept-imagebitmap-bitmap-data" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmap-bitmap-data">bitmap data</a>
from <var>imageBitmap</var> to <var>context</var>, and the bitmap becomes the contents of the
<code id="the-imagebitmaprenderingcontext-interface:the-canvas-element-3"><a href="#the-canvas-element">canvas</a></code> element to which <var>context</var> is bound.</p>
</dd><dt><var>context</var> . <code id="the-imagebitmaprenderingcontext-interface:dom-imagebitmaprenderingcontext-transferfromimagebitmap-2-2"><a href="#dom-imagebitmaprenderingcontext-transferfromimagebitmap-2">transferFromImageBitmap</a></code>(
null)</dt><dd>
<p>Replaces contents of the <code id="the-imagebitmaprenderingcontext-interface:the-canvas-element-4"><a href="#the-canvas-element">canvas</a></code> element to which <var>context</var>
is bound with a transparent black bitmap whose size corresponds to the <code id="the-imagebitmaprenderingcontext-interface:attr-canvas-width"><a href="#attr-canvas-width">width</a></code> and <code id="the-imagebitmaprenderingcontext-interface:attr-canvas-height"><a href="#attr-canvas-height">height</a></code>
content attributes of the <code id="the-imagebitmaprenderingcontext-interface:the-canvas-element-5"><a href="#the-canvas-element">canvas</a></code> element.</p>
</dd></dl>
<p>The <dfn id="dom-imagebitmaprenderingcontext-canvas-2"><code>canvas</code></dfn> attribute
must return the value it was initialized to when the object was created.</p>
<p>An <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-3"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object has an <dfn id="concept-imagebitmaprenderingcontext-output-bitmap">output bitmap</dfn>, which is a
reference to <a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#concept-imagebitmap-bitmap-data" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmap-bitmap-data-2">bitmap data</a>.</p>
<p>An <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-4"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object has a <dfn id="concept-imagebitmaprenderingcontext-bitmap-mode">bitmap mode</dfn>, which can be set to
<dfn id="concept-imagebitmaprenderingcontext-valid">valid</dfn> or <dfn id="concept-imagebitmaprenderingcontext-blank">blank</dfn>. A value of <a href="#concept-imagebitmaprenderingcontext-valid" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-valid">valid</a> indicates that the context's
<a href="#concept-imagebitmaprenderingcontext-output-bitmap" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-output-bitmap">output bitmap</a> refers to
<a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#concept-imagebitmap-bitmap-data" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmap-bitmap-data-3">bitmap data</a> that was acquired via <code id="the-imagebitmaprenderingcontext-interface:dom-imagebitmaprenderingcontext-transferfromimagebitmap-2-3"><a href="#dom-imagebitmaprenderingcontext-transferfromimagebitmap-2">transferFromImageBitmap()</a></code>.
A value <a href="#concept-imagebitmaprenderingcontext-blank" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-blank">blank</a> indicates that the
context's <a href="#concept-imagebitmaprenderingcontext-output-bitmap" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-output-bitmap-2">output
bitmap</a> is a default transparent bitmap.</p>
<p>An <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-5"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object also has an <dfn id="concept-imagebitmaprenderingcontext-alpha">alpha</dfn> flag, which can be set to true or
false. When an <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-6"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object has its <a href="#concept-imagebitmaprenderingcontext-alpha" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-alpha">alpha</a> flag set to false, the contents
of the <code id="the-imagebitmaprenderingcontext-interface:the-canvas-element-6"><a href="#the-canvas-element">canvas</a></code> element to which the context is bound are obtained by
compositing the context's <a href="#concept-imagebitmaprenderingcontext-output-bitmap" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-output-bitmap-3">output bitmap</a> onto an opaque
black bitmap of the same size using the source-over composite operation. If the <a href="#concept-imagebitmaprenderingcontext-alpha" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-alpha-2">alpha</a> flag is set to true, then the
<a href="#concept-imagebitmaprenderingcontext-output-bitmap" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-output-bitmap-4">output bitmap</a> is used
as the contents of the <code id="the-imagebitmaprenderingcontext-interface:the-canvas-element-7"><a href="#the-canvas-element">canvas</a></code> element to which the context is bound. <a href="https://html.spec.whatwg.org/multipage/references.html#refsCOMPOSITE">[COMPOSITE]</a></p>
<p class="note">The step of compositing over an opaque black bitmap ought to be elided whenever
equivalent results can be obtained more efficiently by other means.</p>
<hr/>
<p>When a user agent is required to <dfn id="set-an-imagebitmaprenderingcontext's-output-bitmap">set an <code>ImageBitmapRenderingContext</code>'s output
bitmap</dfn>, with a <var>context</var> argument that is an
<code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-7"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object and an optional argument <var>bitmap</var> that
refers to <a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#concept-imagebitmap-bitmap-data" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmap-bitmap-data-4">bitmap data</a>, it must run these
steps:</p>
<ol><li><p>If a <var>bitmap</var> argument was not provided, then:</p>
<ol><li><p>Set <var>context</var>'s <a href="#concept-imagebitmaprenderingcontext-bitmap-mode" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-bitmap-mode">bitmap mode</a> to <a href="#concept-imagebitmaprenderingcontext-blank" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-blank-2">blank</a>.</p></li><li><p>Let <var>canvas</var> be the <code id="the-imagebitmaprenderingcontext-interface:the-canvas-element-8"><a href="#the-canvas-element">canvas</a></code> element to which <var>context</var>
is bound.</p></li><li><p>Set <var>context</var>'s <a href="#concept-imagebitmaprenderingcontext-output-bitmap" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-output-bitmap-5">output bitmap</a> to be fully
transparent black with an <a href="https://html.spec.whatwg.org/multipage/infrastructure.html#intrinsic-width" id="the-imagebitmaprenderingcontext-interface:intrinsic-width">intrinsic width</a> equal to the numeric value of
<var>canvas</var>'s <code id="the-imagebitmaprenderingcontext-interface:attr-canvas-width-2"><a href="#attr-canvas-width">width</a></code> attribute and an
<a href="https://html.spec.whatwg.org/multipage/infrastructure.html#intrinsic-height" id="the-imagebitmaprenderingcontext-interface:intrinsic-height">intrinsic height</a> equal to the numeric value of <var>canvas</var>'s <code id="the-imagebitmaprenderingcontext-interface:attr-canvas-height-2"><a href="#attr-canvas-height">height</a></code> attribute, those values being interpreted in <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="the-imagebitmaprenderingcontext-interface:'px'">CSS pixels</a>.</p></li><li><p>Set the <a href="#concept-imagebitmaprenderingcontext-output-bitmap" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-output-bitmap-6">output bitmap</a>'s <a href="#concept-canvas-origin-clean" id="the-imagebitmaprenderingcontext-interface:concept-canvas-origin-clean">origin-clean</a> flag to true.</p></li></ol>
</li><li><p>If a <var>bitmap</var> argument was provided, then:</p>
<ol><li><p>Set <var>context</var>'s <a href="#concept-imagebitmaprenderingcontext-bitmap-mode" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-bitmap-mode-2">bitmap mode</a> to <a href="#concept-imagebitmaprenderingcontext-valid" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-valid-2">valid</a>.</p></li><li>
<p>Set <var>context</var>'s <a href="#concept-imagebitmaprenderingcontext-output-bitmap" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-output-bitmap-7">output bitmap</a> to refer
to the same underlying bitmap data as <var>bitmap</var>, without making a copy.</p>
<p class="note">The <a href="#concept-canvas-origin-clean" id="the-imagebitmaprenderingcontext-interface:concept-canvas-origin-clean-2">origin-clean</a> flag of
<var>bitmap</var> is included in the bitmap data to be referenced by <var>context</var>'s
<a href="#concept-imagebitmaprenderingcontext-output-bitmap" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-output-bitmap-8">output bitmap</a>.</p>
</li></ol>
</li></ol>
<hr/>
<p>The <dfn id="imagebitmaprenderingcontext-creation-algorithm"><code>ImageBitmapRenderingContext</code> creation algorithm</dfn>, which is passed a
<var>target</var> (a <code id="the-imagebitmaprenderingcontext-interface:the-canvas-element-9"><a href="#the-canvas-element">canvas</a></code> element) and optionally some arguments, consists of
running the following steps:</p>
<ol><li><p>If the algorithm was passed some arguments, then let <var>arg</var> be the first such
argument. Otherwise, let <var>arg</var> be undefined.</p></li><li><p>Let <var>settings</var> be the result of <a href="#coerce-context-arguments-for-imagebitmaprenderingcontext" id="the-imagebitmaprenderingcontext-interface:coerce-context-arguments-for-imagebitmaprenderingcontext">coercing the <var>arg</var> context arguments for
<code>ImageBitmapRenderingContext</code></a>.</p></li><li><p>Create a new <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-8"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object.</p></li><li><p>Initialize its <code id="the-imagebitmaprenderingcontext-interface:dom-context-2d-canvas-2"><a href="#dom-context-2d-canvas-2">canvas</a></code> attribute to point to
<var>target</var>.</p></li><li><p>Let the new <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-9"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object's <a href="#concept-imagebitmaprenderingcontext-output-bitmap" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-output-bitmap-9">output bitmap</a> and
<var>target</var>'s bitmap be a shared reference to the same bitmap.</p></li><li><p>Run the steps to <a href="#set-an-imagebitmaprenderingcontext's-output-bitmap" id="the-imagebitmaprenderingcontext-interface:set-an-imagebitmaprenderingcontext's-output-bitmap">set an <code>ImageBitmapRenderingContext</code>'s output
bitmap</a>, using the new <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-10"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object as the
<var>context</var> argument, and with no <var>bitmap</var> argument.</p></li><li><p>Initialize <var>context</var>'s <a href="#concept-imagebitmaprenderingcontext-alpha" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-alpha-3">alpha</a> flag to true.
</p></li><li>
<p>Process each of the members of <var>settings</var> as follows:</p>
<dl><dt><dfn id="dom-imagebitmaprenderingcontextsettings-alpha"><code>alpha</code></dfn></dt><dd>If false, then set <var>context</var>'s <a href="#concept-imagebitmaprenderingcontext-alpha" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmaprenderingcontext-alpha-4">alpha</a> flag to false.</dd></dl>
</li><li><p>Return the new <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-11"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object.</p></li></ol>
<hr/>
<p>When a user agent is required to <dfn id="coerce-context-arguments-for-imagebitmaprenderingcontext">coerce context arguments for
<code>ImageBitmapRenderingContext</code></dfn>, it must run these steps:</p>
<ol><li><p>Let <var>input</var> be the argument to coerce.</p></li><li><p>Let <var>jsval</var> be the result of <a data-x-internal="concept-idl-convert" href="https://heycam.github.io/webidl/#es-type-mapping" id="the-imagebitmaprenderingcontext-interface:concept-idl-convert">converting</a> <var>input</var> to a JavaScript value. (This can
throw an exception.)</p></li><li><p>Let <var>dict</var> be the result of <a data-x-internal="concept-idl-convert" href="https://heycam.github.io/webidl/#es-type-mapping" id="the-imagebitmaprenderingcontext-interface:concept-idl-convert-2">converting</a>
<var>jsval</var> to the dictionary type <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontextsettings"><a href="#imagebitmaprenderingcontextsettings">ImageBitmapRenderingContextSettings</a></code>. (This
can throw an exception.)</p></li><li><p>Return <var>dict</var>.</p></li></ol>
<hr/>
<p>The <dfn id="dom-imagebitmaprenderingcontext-transferfromimagebitmap-2"><code>transferFromImageBitmap(<var>imageBitmap</var>)</code></dfn>
method, when invoked, must run these steps:</p>
<ol><li><p>Let <var>bitmapContext</var> be the <code id="the-imagebitmaprenderingcontext-interface:imagebitmaprenderingcontext-12"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code> object on
which the <code id="the-imagebitmaprenderingcontext-interface:dom-imagebitmaprenderingcontext-transferfromimagebitmap-2-4"><a href="#dom-imagebitmaprenderingcontext-transferfromimagebitmap-2">transferFromImageBitmap()</a></code>
method was called.</p></li><li><p>If <var>imageBitmap</var> is null, then run the steps to <a href="#set-an-imagebitmaprenderingcontext's-output-bitmap" id="the-imagebitmaprenderingcontext-interface:set-an-imagebitmaprenderingcontext's-output-bitmap-2">set an
ImageBitmapRenderingContext's output bitmap</a>, with <var>bitmapContext</var> as the
<var>context</var> argument and no <var>bitmap</var> argument, then abort these steps.</p></li><li><p>If the value of <var>imageBitmap</var>'s <a href="https://html.spec.whatwg.org/multipage/structured-data.html#detached" id="the-imagebitmaprenderingcontext-interface:detached">[[Detached]]</a> internal slot is set to
true, then throw an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-imagebitmaprenderingcontext-interface:invalidstateerror">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-imagebitmaprenderingcontext-interface:domexception"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and
abort these steps.</p></li><li><p>Run the steps to <a href="#set-an-imagebitmaprenderingcontext's-output-bitmap" id="the-imagebitmaprenderingcontext-interface:set-an-imagebitmaprenderingcontext's-output-bitmap-3">set an <code>ImageBitmapRenderingContext</code>'s output
bitmap</a>, with the <var>context</var> argument equal to <var>bitmapContext</var>, and the
<var>bitmap</var> argument referring to <var>imageBitmap</var>'s underlying <a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#concept-imagebitmap-bitmap-data" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmap-bitmap-data-5">bitmap data</a>.
</p></li><li><p>Set the value of <var>imageBitmap</var>'s <a href="https://html.spec.whatwg.org/multipage/structured-data.html#detached" id="the-imagebitmaprenderingcontext-interface:detached-2">[[Detached]]</a> internal slot to
true.</p></li><li><p>Unset <var>imageBitmap's</var> <a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#concept-imagebitmap-bitmap-data" id="the-imagebitmaprenderingcontext-interface:concept-imagebitmap-bitmap-data-6">bitmap
data</a>.</p></li></ol>
<h5 id="the-offscreencanvas-interface"><span class="secno">4.12.5.3</span> The <code id="the-offscreencanvas-interface:offscreencanvas"><a href="#offscreencanvas">OffscreenCanvas</a></code> interface<a class="self-link" href="#the-offscreencanvas-interface"/></h5><div class="status"><input onclick="toggleStatus(this)" type="button" value="⋰"/><p class="support"><strong>Support:</strong> offscreencanvas<span class="and_chr no"><span>Chrome for Android</span> <span>None</span></span><span class="chrome no"><span>Chrome</span> <span>None</span></span><span class="and_uc no"><span>UC Browser for Android</span> <span>None</span></span><span class="ios_saf no"><span>iOS Safari</span> <span>None</span></span><span class="firefox no"><span>Firefox</span> <span>None</span></span><span class="ie no"><span>IE</span> <span>None</span></span><span class="samsung no"><span>Samsung Internet</span> <span>None</span></span><span class="op_mini no"><span>Opera Mini</span> <span>None</span></span><span class="safari no"><span>Safari</span> <span>None</span></span><span class="android no"><span>Android Browser</span> <span>None</span></span><span class="opera no"><span>Opera</span> <span>None</span></span><span class="edge no"><span>Edge</span> <span>None</span></span></p><p class="caniuse">Source: <a href="https://caniuse.com/#feat=offscreencanvas">caniuse.com</a></p></div>
<pre class="idl">typedef (<a href="#offscreencanvasrenderingcontext2d" id="the-offscreencanvas-interface:offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a> or
<a data-x-internal="webglrenderingcontext" href="https://www.khronos.org/registry/webgl/specs/latest/1.0/#WebGLRenderingContext" id="the-offscreencanvas-interface:webglrenderingcontext">WebGLRenderingContext</a>) <dfn id="offscreenrenderingcontext">OffscreenRenderingContext</dfn>;
dictionary <dfn id="imageencodeoptions">ImageEncodeOptions</dfn> {
DOMString <a href="#image-encode-options-type" id="the-offscreencanvas-interface:image-encode-options-type">type</a> = &quot;image/png&quot;;
unrestricted double <a href="#image-encode-options-quality" id="the-offscreencanvas-interface:image-encode-options-quality">quality</a> = 1.0;
};
enum <dfn id="offscreenrenderingcontexttype">OffscreenRenderingContextType</dfn> { &quot;<a href="#offscreen-context-type-2d" id="the-offscreencanvas-interface:offscreen-context-type-2d">2d</a>&quot;, &quot;<a href="#offscreen-context-type-webgl" id="the-offscreencanvas-interface:offscreen-context-type-webgl">webgl</a>&quot; };
[<a href="#dom-offscreencanvas-2" id="the-offscreencanvas-interface:dom-offscreencanvas-2">Constructor</a>([EnforceRange] unsigned long long width, [EnforceRange] unsigned long long height), Exposed=(Window,Worker), <a href="https://html.spec.whatwg.org/multipage/structured-data.html#transferable" id="the-offscreencanvas-interface:transferable">Transferable</a>]
interface <dfn id="offscreencanvas">OffscreenCanvas</dfn> : <a data-x-internal="eventtarget" href="https://dom.spec.whatwg.org/#interface-eventtarget" id="the-offscreencanvas-interface:eventtarget">EventTarget</a> {
attribute unsigned long long <a href="#dom-offscreencanvas-width-2" id="the-offscreencanvas-interface:dom-offscreencanvas-width-2">width</a>;
attribute unsigned long long <a href="#dom-offscreencanvas-height-2" id="the-offscreencanvas-interface:dom-offscreencanvas-height-2">height</a>;
<a href="#offscreenrenderingcontext" id="the-offscreencanvas-interface:offscreenrenderingcontext">OffscreenRenderingContext</a>? <a href="#dom-offscreencanvas-getcontext-2" id="the-offscreencanvas-interface:dom-offscreencanvas-getcontext-2">getContext</a>(<a href="#offscreenrenderingcontexttype" id="the-offscreencanvas-interface:offscreenrenderingcontexttype">OffscreenRenderingContextType</a> contextType, any... arguments);
<a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap" id="the-offscreencanvas-interface:imagebitmap">ImageBitmap</a> <a href="#dom-offscreencanvas-transfertoimagebitmap-2" id="the-offscreencanvas-interface:dom-offscreencanvas-transfertoimagebitmap-2">transferToImageBitmap</a>();
Promise&lt;<a data-x-internal="blob" href="https://w3c.github.io/FileAPI/#blob" id="the-offscreencanvas-interface:blob">Blob</a>&gt; <a href="#dom-offscreencanvas-converttoblob-2" id="the-offscreencanvas-interface:dom-offscreencanvas-converttoblob-2">convertToBlob</a>(optional <a href="#imageencodeoptions" id="the-offscreencanvas-interface:imageencodeoptions">ImageEncodeOptions</a> options);
};
</pre>
<p><code id="the-offscreencanvas-interface:offscreencanvas-2"><a href="#offscreencanvas">OffscreenCanvas</a></code> objects are used to create rendering contexts, much like an
<code id="the-offscreencanvas-interface:htmlcanvaselement"><a href="#htmlcanvaselement">HTMLCanvasElement</a></code>, but with no connection to the DOM. This makes it possible to
use canvas rendering contexts in <a href="https://html.spec.whatwg.org/multipage/workers.html#workers">workers</a>.</p>
<p>An <code id="the-offscreencanvas-interface:offscreencanvas-3"><a href="#offscreencanvas">OffscreenCanvas</a></code> object may hold a weak reference to a <dfn id="offscreencanvas-placeholder">placeholder <code>canvas</code> element</dfn>, which is
typically in the DOM, whose embedded content is provided by the <code id="the-offscreencanvas-interface:offscreencanvas-4"><a href="#offscreencanvas">OffscreenCanvas</a></code>
object. The bitmap of the <code id="the-offscreencanvas-interface:offscreencanvas-5"><a href="#offscreencanvas">OffscreenCanvas</a></code> object is pushed to the <a href="#offscreencanvas-placeholder" id="the-offscreencanvas-interface:offscreencanvas-placeholder">placeholder <code>canvas</code> element</a> by
calling the <dfn id="offscreencontext-commit"><code>commit()</code></dfn> method of the
<code id="the-offscreencanvas-interface:offscreencanvas-6"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's rendering context. All rendering context types that
can be created by an <code id="the-offscreencanvas-interface:offscreencanvas-7"><a href="#offscreencanvas">OffscreenCanvas</a></code> object must implement a <code id="the-offscreencanvas-interface:offscreencontext-commit"><a href="#offscreencontext-commit">commit()</a></code> method. The exact behavior of the commit
method (e.g. whether it copies or transfers bitmaps) may vary, as defined by the rendering
contexts' respective specifications. Only the <a href="#offscreencanvasrenderingcontext2d" id="the-offscreencanvas-interface:offscreencanvasrenderingcontext2d-2">2D context for offscreen canvases</a> is defined
in this specification.</p>
<dl class="domintro"><dt><var>offscreenCanvas</var> = new <code id="dom-offscreencanvas"><a href="#dom-offscreencanvas-2">OffscreenCanvas</a></code>(<var>width</var>,
<var>height</var>)</dt><dt>
</dt><dd>
<p>Returns a new <code id="the-offscreencanvas-interface:offscreencanvas-8"><a href="#offscreencanvas">OffscreenCanvas</a></code> object that is not linked to a <a href="#offscreencanvas-placeholder" id="the-offscreencanvas-interface:offscreencanvas-placeholder-2">placeholder <code>canvas</code> element</a>, and
whose bitmap's size is determined by the <var>width</var> and <var>height</var> arguments.</p>
</dd><dt><var>context</var> = <var>offscreenCanvas</var> . <code id="dom-offscreencanvas-getcontext"><a href="#dom-offscreencanvas-getcontext-2">getContext</a></code>(<var>contextType</var> [, ... ] )</dt><dd>
<p>Returns an object that exposes an API for drawing on the <code id="the-offscreencanvas-interface:offscreencanvas-9"><a href="#offscreencanvas">OffscreenCanvas</a></code>
object. The first argument specifies the desired API, either &quot;<code id="the-offscreencanvas-interface:offscreen-context-type-2d-2"><a href="#offscreen-context-type-2d">2d</a></code>&quot;, or &quot;<code id="the-offscreencanvas-interface:offscreen-context-type-webgl-2"><a href="#offscreen-context-type-webgl">webgl</a></code>&quot;. Subsequent arguments are handled by that
API.</p>
<p>This specification defines the &quot;<code id="the-offscreencanvas-interface:canvas-context-2d"><a href="#canvas-context-2d">2d</a></code>&quot; context below,
which is similar but distinct from the &quot;<code id="the-offscreencanvas-interface:offscreen-context-type-2d-3"><a href="#offscreen-context-type-2d">2d</a></code>&quot;
context that is created from a <code id="the-offscreencanvas-interface:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element. There is also a specification that
defines a &quot;<code id="the-offscreencanvas-interface:offscreen-context-type-webgl-3"><a href="#offscreen-context-type-webgl">webgl</a></code>&quot; context.
<a href="https://html.spec.whatwg.org/multipage/references.html#refsWEBGL">[WEBGL]</a></p>
<p>Returns null if the canvas has already been initialized with another context type (e.g.
trying to get a &quot;<code id="the-offscreencanvas-interface:offscreen-context-type-2d-4"><a href="#offscreen-context-type-2d">2d</a></code>&quot; context after getting a
&quot;<code id="the-offscreencanvas-interface:offscreen-context-type-webgl-4"><a href="#offscreen-context-type-webgl">webgl</a></code>&quot; context).</p>
</dd></dl>
<p>An <code id="the-offscreencanvas-interface:offscreencanvas-10"><a href="#offscreencanvas">OffscreenCanvas</a></code> object has an internal <dfn id="offscreencanvas-bitmap">bitmap</dfn> that is initialized when the object
is created. The width and height of the <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap">bitmap</a> are
equal to the values of the <code id="the-offscreencanvas-interface:dom-offscreencanvas-width-2-2"><a href="#dom-offscreencanvas-width-2">width</a></code> and <code id="the-offscreencanvas-interface:dom-offscreencanvas-height-2-2"><a href="#dom-offscreencanvas-height-2">height</a></code> attributes of the <code id="the-offscreencanvas-interface:offscreencanvas-11"><a href="#offscreencanvas">OffscreenCanvas</a></code>
object. Initially, all the bitmap's pixels are transparent black.</p>
<p>An <code id="the-offscreencanvas-interface:offscreencanvas-12"><a href="#offscreencanvas">OffscreenCanvas</a></code> object can have a rendering context bound to it. Initially,
it does not have a bound rendering context. To keep track of whether it has a rendering context
or not, and what kind of rendering context it is, an <code id="the-offscreencanvas-interface:offscreencanvas-13"><a href="#offscreencanvas">OffscreenCanvas</a></code> object also
has a <dfn id="offscreencanvas-context-mode">context mode</dfn>, which is initially <dfn id="offscreencanvas-context-none">none</dfn> but can be changed to either <dfn id="offscreencanvas-context-2d">2d</dfn>, <dfn id="offscreencanvas-context-webgl">webgl</dfn> or <dfn id="offscreencanvas-context-detached">detached</dfn> by algorithms defined in this
specification.</p>
<p>The constructor <dfn id="dom-offscreencanvas-2"><code>OffscreenCanvas(<var>width</var>,
<var>height</var>)</code></dfn>, when invoked, must create a new <code id="the-offscreencanvas-interface:offscreencanvas-14"><a href="#offscreencanvas">OffscreenCanvas</a></code>
object with its <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap-2">bitmap</a> initialized to a rectangular
array of transparent black pixels of the dimensions specified by <var>width</var> and
<var>height</var>; and its <code id="the-offscreencanvas-interface:dom-offscreencanvas-width-2-3"><a href="#dom-offscreencanvas-width-2">width</a></code> and <code id="the-offscreencanvas-interface:dom-offscreencanvas-height-2-3"><a href="#dom-offscreencanvas-height-2">height</a></code> attributes initialized to <var>width</var> and
<var>height</var> respectively.</p>
<hr/>
<p><code id="the-offscreencanvas-interface:offscreencanvas-15"><a href="#offscreencanvas">OffscreenCanvas</a></code> objects are <a href="https://html.spec.whatwg.org/multipage/structured-data.html#transferable-objects" id="the-offscreencanvas-interface:transferable-objects">transferable</a>. Their <a href="https://html.spec.whatwg.org/multipage/structured-data.html#transfer-steps" id="the-offscreencanvas-interface:transfer-steps">transfer steps</a>, given <var>value</var> and
<var>dataHolder</var>, are as follows:</p>
<ol><li><p>If <var>value</var>'s <a href="#offscreencanvas-context-mode" id="the-offscreencanvas-interface:offscreencanvas-context-mode">context mode</a> is
not equal to <a href="#offscreencanvas-context-none" id="the-offscreencanvas-interface:offscreencanvas-context-none">none</a>, then throw an
<a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-offscreencanvas-interface:invalidstateerror">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-offscreencanvas-interface:domexception"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.</p></li><li><p>Set <var>value</var>'s <a href="#offscreencanvas-context-mode" id="the-offscreencanvas-interface:offscreencanvas-context-mode-2">context mode</a> to
<a href="#offscreencanvas-context-detached" id="the-offscreencanvas-interface:offscreencanvas-context-detached">detached</a>.</p></li><li><p>Let <var>width</var> and <var>height</var> be the dimensions of <var>value</var>'s <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap-3">bitmap</a>.</p></li><li><p>Unset <var>value</var>'s <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap-4">bitmap</a>.</p></li><li><p>Set <var>dataHolder</var>.[[With]] to <var>width</var>, and
<var>dataHolder</var>.[[Height]] to <var>height</var>.</p></li><li><p>Set <var>dataHolder</var>.[[PlaceholderCanvas]] to be a weak reference to
<var>value</var>'s <a href="#offscreencanvas-placeholder" id="the-offscreencanvas-interface:offscreencanvas-placeholder-3">placeholder <code>canvas</code>
element</a>, if <var>value</var> has one, or null if it does not.</p></li></ol>
<p>Their <a href="https://html.spec.whatwg.org/multipage/structured-data.html#transfer-receiving-steps" id="the-offscreencanvas-interface:transfer-receiving-steps">transfer-receiving steps</a>, given <var>dataHolder</var> and <var>value</var>,
are:</p>
<ol><li><p>Initialize <var>value</var>'s <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap-5">bitmap</a> to a
rectangular array of transparent black pixels with width given by <var>dataHolder</var>.[[Width]]
and height given by <var>dataHolder</var>.[[Height]].</p></li><li><p>If <var>dataHolder</var>.[[PlaceholderCanvas]] is not null, set <var>value</var>'s <a href="#offscreencanvas-placeholder" id="the-offscreencanvas-interface:offscreencanvas-placeholder-4">placeholder <code>canvas</code> element</a> to
<var>dataHolder</var>.[[PlaceholderCanvas]] (while maintaining the weak reference
semantics).</p></li></ol>
<hr/>
<p>The <dfn id="dom-offscreencanvas-getcontext-2"><code>getContext(<var>contextId</var>,
<var>arguments...</var>)</code></dfn> method of an <code id="the-offscreencanvas-interface:offscreencanvas-16"><a href="#offscreencanvas">OffscreenCanvas</a></code> object, when
invoked, must run the steps in the cell of the following table whose column header describes the
<code id="the-offscreencanvas-interface:offscreencanvas-17"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-context-mode" id="the-offscreencanvas-interface:offscreencanvas-context-mode-3">context
mode</a> and whose row header describes the method's first argument.</p>
<table><thead><tr><td>
</td><th><a href="#offscreencanvas-context-none" id="the-offscreencanvas-interface:offscreencanvas-context-none-2">none</a>
</th><th><a href="#offscreencanvas-context-2d" id="the-offscreencanvas-interface:offscreencanvas-context-2d">2d</a>
</th><th><a href="#offscreencanvas-context-webgl" id="the-offscreencanvas-interface:offscreencanvas-context-webgl">webgl</a>
</th><th><a href="#offscreencanvas-context-detached" id="the-offscreencanvas-interface:offscreencanvas-context-detached-2">detached</a>
</th></tr></thead><tbody><tr><th>&quot;<dfn id="offscreen-context-type-2d"><code>2d</code></dfn>&quot;
</th><td>
Follow the steps to <a href="#offscreen-2d-context-creation-algorithm" id="the-offscreencanvas-interface:offscreen-2d-context-creation-algorithm">create an
offscreen 2D context</a> defined in the section below, passing it the
<code id="the-offscreencanvas-interface:offscreencanvas-18"><a href="#offscreencanvas">OffscreenCanvas</a></code> object and the method's <var>arguments...</var>, to obtain
an <code id="the-offscreencanvas-interface:offscreencanvasrenderingcontext2d-3"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code> object; if this does not throw an
exception, then set the <code id="the-offscreencanvas-interface:offscreencanvas-19"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-context-mode" id="the-offscreencanvas-interface:offscreencanvas-context-mode-4">context mode</a> to <a href="#offscreencanvas-context-2d" id="the-offscreencanvas-interface:offscreencanvas-context-2d-2">2d</a>, and return the new
<code id="the-offscreencanvas-interface:offscreencanvasrenderingcontext2d-4"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code> object.
</td><td>
Return the same object as was returned the last time the method was invoked with this same
first argument.
</td><td>
Return null.
</td><td>
Throw an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-offscreencanvas-interface:invalidstateerror-2">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-offscreencanvas-interface:domexception-2"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.
</td></tr><tr><th>&quot;<dfn id="offscreen-context-type-webgl"><code>webgl</code></dfn>&quot;
</th><td>
Follow the instructions given in the WebGL specification's <i>Context Creation</i> section to
obtain either a <code id="the-offscreencanvas-interface:webglrenderingcontext-2"><a data-x-internal="webglrenderingcontext" href="https://www.khronos.org/registry/webgl/specs/latest/1.0/#WebGLRenderingContext">WebGLRenderingContext</a></code> or null; if the returned value is null,
then return null and abort these steps, otherwise, set the <code id="the-offscreencanvas-interface:offscreencanvas-20"><a href="#offscreencanvas">OffscreenCanvas</a></code>
object's <a href="#offscreencanvas-context-mode" id="the-offscreencanvas-interface:offscreencanvas-context-mode-5">context mode</a> to <a href="#offscreencanvas-context-webgl" id="the-offscreencanvas-interface:offscreencanvas-context-webgl-2">webgl</a>, and return the
<code id="the-offscreencanvas-interface:webglrenderingcontext-3"><a data-x-internal="webglrenderingcontext" href="https://www.khronos.org/registry/webgl/specs/latest/1.0/#WebGLRenderingContext">WebGLRenderingContext</a></code> object. <a href="https://html.spec.whatwg.org/multipage/references.html#refsWEBGL">[WEBGL]</a>
</td><td>
Return null.
</td><td>
Return the same value as was returned the last time the method was invoked with this same
first argument.
</td><td>
Throw an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-offscreencanvas-interface:invalidstateerror-3">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-offscreencanvas-interface:domexception-3"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.
</td></tr></tbody></table>
<hr/>
<dl class="domintro"><dt><var>offscreenCanvas</var> . <code id="dom-offscreencanvas-width"><a href="#dom-offscreencanvas-width-2">width</a></code> [
= <var>value</var> ]</dt><dt><var>offscreenCanvas</var> . <code id="dom-offscreencanvas-height"><a href="#dom-offscreencanvas-height-2">height</a></code> [
= <var>value</var> ]</dt><dd>
<p>These attributes return the dimensions of the <code id="the-offscreencanvas-interface:offscreencanvas-21"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap-6">bitmap</a>.</p>
<p>They can be set, to replace the <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap-7">bitmap</a> with a
new, transparent black bitmap of the specified dimensions (effectively resizing it).</p>
</dd></dl>
<p>If either the <dfn id="dom-offscreencanvas-width-2"><code>width</code></dfn> or <dfn id="dom-offscreencanvas-height-2"><code>height</code></dfn> attributes of an
<code id="the-offscreencanvas-interface:offscreencanvas-22"><a href="#offscreencanvas">OffscreenCanvas</a></code> object are set (to a new value or to the same value as before) and
the <code id="the-offscreencanvas-interface:offscreencanvas-23"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-context-mode" id="the-offscreencanvas-interface:offscreencanvas-context-mode-6">context
mode</a> is <a href="#offscreencanvas-context-2d" id="the-offscreencanvas-interface:offscreencanvas-context-2d-3">2d</a>, then replace the
<code id="the-offscreencanvas-interface:offscreencanvas-24"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap-8">bitmap</a> with a
new transparent black bitmap and <a href="#reset-the-rendering-context-to-its-default-state" id="the-offscreencanvas-interface:reset-the-rendering-context-to-its-default-state">reset the rendering context to its default state</a>.
The new bitmap's dimensions are equal to the new values of the <code id="the-offscreencanvas-interface:dom-offscreencanvas-width-2-4"><a href="#dom-offscreencanvas-width-2">width</a></code> and <code id="the-offscreencanvas-interface:dom-offscreencanvas-height-2-4"><a href="#dom-offscreencanvas-height-2">height</a></code> attributes.</p>
<p>The resizing behavior for &quot;<code id="the-offscreencanvas-interface:offscreen-context-type-webgl-5"><a href="#offscreen-context-type-webgl">webgl</a></code>&quot;
contexts is defined in the WebGL specification. <a href="https://html.spec.whatwg.org/multipage/references.html#refsWEBGL">[WEBGL]</a></p>
<p class="note">If an <code id="the-offscreencanvas-interface:offscreencanvas-25"><a href="#offscreencanvas">OffscreenCanvas</a></code> object whose dimensions were changed has
a <a href="#offscreencanvas-placeholder" id="the-offscreencanvas-interface:offscreencanvas-placeholder-5">placeholder <code>canvas</code> element</a>, then
the <a href="#offscreencanvas-placeholder" id="the-offscreencanvas-interface:offscreencanvas-placeholder-6">placeholder <code>canvas</code> element</a>'s
<a data-x-internal="intrinsic-dimensions" href="https://drafts.csswg.org/css2/conform.html#intrinsic" id="the-offscreencanvas-interface:intrinsic-dimensions">intrinsic size</a> will only be updated via the <code id="the-offscreencanvas-interface:offscreencontext-commit-2"><a href="#offscreencontext-commit">commit()</a></code> method of the <code id="the-offscreencanvas-interface:offscreencanvas-26"><a href="#offscreencanvas">OffscreenCanvas</a></code>
object's rendering context.</p>
<dl class="domintro"><dt><var>promise</var> = <var>offscreenCanvas</var> . <code id="dom-offscreencanvas-converttoblob"><a href="#dom-offscreencanvas-converttoblob-2">convertToBlob</a></code>( [<var>options</var>] )</dt><dd>
<p>Returns a promise that will fulfill with a new <code id="the-offscreencanvas-interface:blob-2"><a data-x-internal="blob" href="https://w3c.github.io/FileAPI/#blob">Blob</a></code> object representing a file
containing the image in the <code id="the-offscreencanvas-interface:offscreencanvas-27"><a href="#offscreencanvas">OffscreenCanvas</a></code> object.</p>
<p>The argument, if provided, is a dictionary that controls the encoding options of the image
file to be created. The <code id="the-offscreencanvas-interface:image-encode-options-type-2"><a href="#image-encode-options-type">type</a></code>
field specifies the file format and has a default value of &quot;<code id="the-offscreencanvas-interface:image/png"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/png">image/png</a></code>&quot;; that type
is also used if the requested type isn't supported. If the image format supports variable
quality (such as &quot;<code id="the-offscreencanvas-interface:image/jpeg"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/jpeg">image/jpeg</a></code>&quot;), then the <code id="the-offscreencanvas-interface:image-encode-options-quality-2"><a href="#image-encode-options-quality">quality</a></code> field is a number in the range 0.0
to 1.0 inclusive indicating the desired quality level for the resulting image.</p>
</dd><dt><var>canvas</var> . <code id="dom-offscreencanvas-transfertoimagebitmap"><a href="#dom-offscreencanvas-transfertoimagebitmap-2">transferToImageBitmap</a></code>()</dt><dd>
<p>Returns a newly created <code id="the-offscreencanvas-interface:imagebitmap-2"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code> object with the image in the
<code id="the-offscreencanvas-interface:offscreencanvas-28"><a href="#offscreencanvas">OffscreenCanvas</a></code> object. The image in the <code id="the-offscreencanvas-interface:offscreencanvas-29"><a href="#offscreencanvas">OffscreenCanvas</a></code> object is
replaced with a new blank image.</p>
</dd></dl>
<p>The <dfn id="dom-offscreencanvas-converttoblob-2"><code>convertToBlob(<var>options</var>)</code></dfn> method,
when invoked, must run the following steps:</p>
<ol><li><p>If the value of this <code id="the-offscreencanvas-interface:offscreencanvas-30"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="https://html.spec.whatwg.org/multipage/structured-data.html#detached" id="the-offscreencanvas-interface:detached">[[Detached]]</a>
internal slot is set to true, then return a promise rejected with an
<a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-offscreencanvas-interface:invalidstateerror-4">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-offscreencanvas-interface:domexception-4"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these
steps.</p></li><li><p>If this <code id="the-offscreencanvas-interface:offscreencanvas-31"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-context-mode" id="the-offscreencanvas-interface:offscreencanvas-context-mode-7">context mode</a> is <a href="#offscreencanvas-context-2d" id="the-offscreencanvas-interface:offscreencanvas-context-2d-4">2d</a> and the rendering context's <a href="#offscreencontext2d-bitmap" id="the-offscreencanvas-interface:offscreencontext2d-bitmap">bitmap</a>'s <a href="#offscreencontext2d-origin-clean" id="the-offscreencanvas-interface:offscreencontext2d-origin-clean">origin-clean</a> flag is set to false, then return a
promise rejected with a <a data-x-internal="securityerror" href="https://heycam.github.io/webidl/#securityerror" id="the-offscreencanvas-interface:securityerror">&quot;<code>SecurityError</code>&quot;</a> <code id="the-offscreencanvas-interface:domexception-5"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and
abort these steps.</p>
</li><li><p>If this <code id="the-offscreencanvas-interface:offscreencanvas-32"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap-9">bitmap</a> has no pixels (i.e. either its
horizontal dimension or its vertical dimension is zero) then return a promise rejected with an
<a data-x-internal="indexsizeerror" href="https://heycam.github.io/webidl/#indexsizeerror" id="the-offscreencanvas-interface:indexsizeerror">&quot;<code>IndexSizeError</code>&quot;</a> <code id="the-offscreencanvas-interface:domexception-6"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these
steps.</p></li><li><p>Let <var>result</var> be a new promise object.</p></li><li><p>Return <var>result</var>, and <a href="https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-task" id="the-offscreencanvas-interface:queue-a-task">queue a task</a> to run the remaining steps
<a href="https://html.spec.whatwg.org/multipage/infrastructure.html#in-parallel" id="the-offscreencanvas-interface:in-parallel">in parallel</a>.</p></li><li><p>Let <var>blob</var> be a <code id="the-offscreencanvas-interface:blob-3"><a data-x-internal="blob" href="https://w3c.github.io/FileAPI/#blob">Blob</a></code> object, created in the <a href="https://html.spec.whatwg.org/multipage/webappapis.html#concept-relevant-realm" id="the-offscreencanvas-interface:concept-relevant-realm">relevant Realm</a> of this <code id="the-offscreencanvas-interface:offscreencanvas-33"><a href="#offscreencanvas">OffscreenCanvas</a></code>
object, representing <a href="#a-serialisation-of-the-bitmap-as-a-file" id="the-offscreencanvas-interface:a-serialisation-of-the-bitmap-as-a-file">a serialization of
this <code>OffscreenCanvas</code> object's <span>bitmap</span> as
a file</a>, passing the values of the <dfn id="image-encode-options-type"><code>type</code></dfn> and <dfn id="image-encode-options-quality"><code>quality</code></dfn> fields of <var>options</var>, if
<var>options</var> was specified. <a href="https://html.spec.whatwg.org/multipage/references.html#refsFILEAPI">[FILEAPI]</a></p></li><li><p>If <var>blob</var> is null, then reject <var>result</var> with an
<a data-x-internal="encodingerror" href="https://heycam.github.io/webidl/#encodingerror" id="the-offscreencanvas-interface:encodingerror">&quot;<code>EncodingError</code>&quot;</a> <code id="the-offscreencanvas-interface:domexception-7"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code>.</p></li><li><p>Otherwise, resolve <var>result</var> with <var>blob</var>.</p></li></ol>
<p>The <dfn id="dom-offscreencanvas-transfertoimagebitmap-2"><code>transferToImageBitmap()</code></dfn> method,
when invoked, must run the following steps:</p>
<ol><li><p>If the value of this <code id="the-offscreencanvas-interface:offscreencanvas-34"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="https://html.spec.whatwg.org/multipage/structured-data.html#detached" id="the-offscreencanvas-interface:detached-2">[[Detached]]</a>
internal slot is set to true, then throw an <a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-offscreencanvas-interface:invalidstateerror-5">&quot;<code>InvalidStateError</code>&quot;</a>
<code id="the-offscreencanvas-interface:domexception-8"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these steps.</p></li><li><p>If this <code id="the-offscreencanvas-interface:offscreencanvas-35"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-context-mode" id="the-offscreencanvas-interface:offscreencanvas-context-mode-8">context mode</a> is set to <a href="#offscreencanvas-context-none" id="the-offscreencanvas-interface:offscreencanvas-context-none-3">none</a>, then throw an
<a data-x-internal="invalidstateerror" href="https://heycam.github.io/webidl/#invalidstateerror" id="the-offscreencanvas-interface:invalidstateerror-6">&quot;<code>InvalidStateError</code>&quot;</a> <code id="the-offscreencanvas-interface:domexception-9"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> and abort these
steps.</p></li><li><p>Let <var>image</var> be a newly created <code id="the-offscreencanvas-interface:imagebitmap-3"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code> object that references
the same underlying bitmap data as this <code id="the-offscreencanvas-interface:offscreencanvas-36"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap-10">bitmap</a>.</p></li><li><p>Set this <code id="the-offscreencanvas-interface:offscreencanvas-37"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-bitmap" id="the-offscreencanvas-interface:offscreencanvas-bitmap-11">bitmap</a> to reference a newly created bitmap of the
same dimensions as the previous bitmap, and with its pixels initialized to transparent black,
or opaque black if the rendering context's <a href="#offscreencontext2d-alpha" id="the-offscreencanvas-interface:offscreencontext2d-alpha">alpha</a> flag is set to false.</p></li><li><p>Return <var>image</var>.</p></li></ol>
<h6 id="the-offscreen-2d-rendering-context"><span class="secno">4.12.5.3.1</span> The offscreen 2D rendering context<a class="self-link" href="#the-offscreen-2d-rendering-context"/></h6>
<pre class="idl">[Exposed=(Window,Worker)]
interface <a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a> {
void <a href="#offscreencontext2d-commit-2" id="the-offscreen-2d-rendering-context:offscreencontext2d-commit-2">commit</a>();
readonly attribute <a href="#offscreencanvas" id="the-offscreen-2d-rendering-context:offscreencanvas">OffscreenCanvas</a> <a href="#offscreencontext2d-canvas-2" id="the-offscreen-2d-rendering-context:offscreencontext2d-canvas-2">canvas</a>;
};
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-2">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvasstate" id="the-offscreen-2d-rendering-context:canvasstate">CanvasState</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-3">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvastransform" id="the-offscreen-2d-rendering-context:canvastransform">CanvasTransform</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-4">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvascompositing" id="the-offscreen-2d-rendering-context:canvascompositing">CanvasCompositing</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-5">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvasimagesmoothing" id="the-offscreen-2d-rendering-context:canvasimagesmoothing">CanvasImageSmoothing</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-6">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvasfillstrokestyles" id="the-offscreen-2d-rendering-context:canvasfillstrokestyles">CanvasFillStrokeStyles</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-7">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvasshadowstyles" id="the-offscreen-2d-rendering-context:canvasshadowstyles">CanvasShadowStyles</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-8">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvasfilters" id="the-offscreen-2d-rendering-context:canvasfilters">CanvasFilters</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-9">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvasrect" id="the-offscreen-2d-rendering-context:canvasrect">CanvasRect</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-10">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvasdrawpath" id="the-offscreen-2d-rendering-context:canvasdrawpath">CanvasDrawPath</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-11">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvasdrawimage" id="the-offscreen-2d-rendering-context:canvasdrawimage">CanvasDrawImage</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-12">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvasimagedata" id="the-offscreen-2d-rendering-context:canvasimagedata">CanvasImageData</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-13">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvaspathdrawingstyles" id="the-offscreen-2d-rendering-context:canvaspathdrawingstyles">CanvasPathDrawingStyles</a>;
<a href="#offscreencanvasrenderingcontext2d" id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-14">OffscreenCanvasRenderingContext2D</a> implements <a href="#canvaspath" id="the-offscreen-2d-rendering-context:canvaspath">CanvasPath</a>;
</pre>
<p>The <dfn id="offscreencanvasrenderingcontext2d"><code>OffscreenCanvasRenderingContext2D</code></dfn> is a rendering context
interface for drawing to the <a href="#offscreencanvas-bitmap" id="the-offscreen-2d-rendering-context:offscreencanvas-bitmap">bitmap</a> of an
<code id="the-offscreen-2d-rendering-context:offscreencanvas-2"><a href="#offscreencanvas">OffscreenCanvas</a></code> object. It is similar to <code id="the-offscreen-2d-rendering-context:canvasrenderingcontext2d"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>,
with the following differences:</p>
<ul><li><p><a href="#canvastext" id="the-offscreen-2d-rendering-context:canvastext">text rendering</a> is not supported;</p></li><li><p>there is no support for <a href="#canvasuserinterface" id="the-offscreen-2d-rendering-context:canvasuserinterface">user interface</a>
features;</p></li><li><p>its <code id="the-offscreen-2d-rendering-context:offscreencontext2d-canvas-2-2"><a href="#offscreencontext2d-canvas-2">canvas</a></code> attribute refers to an
<code id="the-offscreen-2d-rendering-context:offscreencanvas-3"><a href="#offscreencanvas">OffscreenCanvas</a></code> object rather than a <code id="the-offscreen-2d-rendering-context:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> element;</p></li><li><p>it has a <code id="the-offscreen-2d-rendering-context:offscreencontext2d-commit-2-2"><a href="#offscreencontext2d-commit-2">commit()</a></code> method for pushing the
rendered image to the context's <code id="the-offscreen-2d-rendering-context:offscreencanvas-4"><a href="#offscreencanvas">OffscreenCanvas</a></code> object's <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder">placeholder <code>canvas</code> element</a>.</p></li></ul>
<p>An <code id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-15"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code> object has a <dfn id="offscreencontext2d-bitmap">bitmap</dfn> that is initialized when the object is
created.</p>
<p>The <a href="#offscreencontext2d-bitmap" id="the-offscreen-2d-rendering-context:offscreencontext2d-bitmap">bitmap</a> has an <dfn id="offscreencontext2d-origin-clean">origin-clean</dfn> flag, which can be set to true or
false. Initially, when one of these bitmaps is created, its <a href="#offscreencontext2d-origin-clean" id="the-offscreen-2d-rendering-context:offscreencontext2d-origin-clean">origin-clean</a> flag must be set to true.</p>
<p>An <code id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-16"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code> object also has an <dfn id="offscreencontext2d-alpha">alpha</dfn> flag, which can be set to true or false. Initially,
when the context is created, its alpha flag must be set to true. When an
<code id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-17"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code> object has its <a href="#offscreencontext2d-alpha" id="the-offscreen-2d-rendering-context:offscreencontext2d-alpha">alpha</a> flag set to false, then its alpha channel must be
fixed to 1.0 (fully opaque) for all pixels, and attempts to change the alpha component of any pixel
must be silently ignored.</p>
<p>An <code id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-18"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code> object has an <dfn id="associated-offscreencanvas-object">associated
<code>OffscreenCanvas</code> object</dfn>, which is the <code id="the-offscreen-2d-rendering-context:offscreencanvas-5"><a href="#offscreencanvas">OffscreenCanvas</a></code> object
from which the <code id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-19"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code> object was created.
</p><dl class="domintro"><dt><var>offscreenCanvasRenderingContext2D</var> . <code id="offscreencontext2d-commit"><a href="#offscreencontext2d-commit-2">commit</a></code>()</dt><dd>
<p>Copies the rendering context's <a href="#offscreencontext2d-bitmap" id="the-offscreen-2d-rendering-context:offscreencontext2d-bitmap-2">bitmap</a> to
the bitmap of the <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder-2">placeholder <code>canvas</code>
element</a> of the <a href="#associated-offscreencanvas-object" id="the-offscreen-2d-rendering-context:associated-offscreencanvas-object">associated <code>OffscreenCanvas</code> object</a>. The copy
operation is asynchronous.</p>
</dd><dt><var>offscreenCanvas</var> = <var>offscreenCanvasRenderingContext2D</var> . <code id="offscreencontext2d-canvas"><a href="#offscreencontext2d-canvas-2">canvas</a></code></dt><dd>
<p>Returns the <a href="#associated-offscreencanvas-object" id="the-offscreen-2d-rendering-context:associated-offscreencanvas-object-2">associated <code>OffscreenCanvas</code> object</a>.</p>
</dd></dl>
<p>The <dfn id="offscreen-2d-context-creation-algorithm">offscreen 2D context creation algorithm</dfn>, which is passed a
<var>target</var> (an <code id="the-offscreen-2d-rendering-context:offscreencanvas-6"><a href="#offscreencanvas">OffscreenCanvas</a></code> object) and optionally some arguments,
consists of running the following steps:</p>
<ol><li><p>If the algorithm was passed some arguments, let <var>arg</var> be the first such
argument. Otherwise, let <var>arg</var> be undefined.</p></li><li><p>Let <var>settings</var> be the result of <a href="#coerce-context-arguments-for-2d" id="the-offscreen-2d-rendering-context:coerce-context-arguments-for-2d">coercing the <var>arg</var> context arguments
for 2D</a>.</p></li><li><p>Let <var>context</var> be a new <code id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-20"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code>
object.</p></li><li><p>Set <var>context</var>'s <a href="#associated-offscreencanvas-object" id="the-offscreen-2d-rendering-context:associated-offscreencanvas-object-3">associated <code>OffscreenCanvas</code> object</a> to
<var>target</var>.</p></li><li><p>Process each of the members of <var>settings</var> as follows:</p>
<dl><dt><code id="the-offscreen-2d-rendering-context:dom-canvasrenderingcontext2dsettings-alpha"><a href="#dom-canvasrenderingcontext2dsettings-alpha">alpha</a></code></dt><dd>If false, set <var>context</var>'s <a href="#offscreencontext2d-alpha" id="the-offscreen-2d-rendering-context:offscreencontext2d-alpha-2">alpha</a>
flag to false.</dd></dl>
</li><li><p>Set <var>context</var>'s <a href="#offscreencontext2d-bitmap" id="the-offscreen-2d-rendering-context:offscreencontext2d-bitmap-3">bitmap</a> to a newly
created bitmap with the dimensions specified by the <code id="the-offscreen-2d-rendering-context:dom-offscreencanvas-width-2"><a href="#dom-offscreencanvas-width-2">width</a></code> and <code id="the-offscreen-2d-rendering-context:dom-offscreencanvas-height-2"><a href="#dom-offscreencanvas-height-2">height</a></code> attributes of <var>target</var>, and set
<var>target</var>'s bitmap to the same bitmap (so that they are shared).</p></li><li><p>If <var>context</var>'s <a href="#offscreencontext2d-alpha" id="the-offscreen-2d-rendering-context:offscreencontext2d-alpha-3">alpha</a> flag is set
to true, initialize all the pixels of <var>context</var>'s <a href="#offscreencontext2d-bitmap" id="the-offscreen-2d-rendering-context:offscreencontext2d-bitmap-4">bitmap</a> to transparent black. Otherwise, initialize
the pixels to opaque black.</p></li><li><p>Return <var>context</var>.</p></li></ol>
<p>The <dfn id="offscreencontext2d-commit-2"><code>commit()</code></dfn> method, when invoked,
must run the following steps:</p>
<ol><li><p>If this <code id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-21"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code>'s <a href="#associated-offscreencanvas-object" id="the-offscreen-2d-rendering-context:associated-offscreencanvas-object-4">associated
<code>OffscreenCanvas</code> object</a> does not have a <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder-3">placeholder <code>canvas</code> element</a>, abort
these steps.</p></li><li><p>Let <var>image</var> be a copy of this <code id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-22"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code>'s
<a href="#offscreencontext2d-bitmap" id="the-offscreen-2d-rendering-context:offscreencontext2d-bitmap-5">bitmap</a>, including the value of its <a href="#offscreencontext2d-origin-clean" id="the-offscreen-2d-rendering-context:offscreencontext2d-origin-clean-2">origin-clean</a> flag.</p></li><li>
<p><a href="https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-task" id="the-offscreen-2d-rendering-context:queue-a-task">Queue a task</a> in the <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder-4">placeholder <code>canvas</code> element</a>'s
<a href="https://html.spec.whatwg.org/multipage/webappapis.html#relevant-settings-object" id="the-offscreen-2d-rendering-context:relevant-settings-object">relevant settings object</a>'s <a href="https://html.spec.whatwg.org/multipage/webappapis.html#responsible-event-loop" id="the-offscreen-2d-rendering-context:responsible-event-loop">responsible event loop</a> (which will be a
<a href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="the-offscreen-2d-rendering-context:browsing-context">browsing context</a> <a href="https://html.spec.whatwg.org/multipage/webappapis.html#event-loop" id="the-offscreen-2d-rendering-context:event-loop">event loop</a>) to set the <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder-5">placeholder <code>canvas</code> element</a>'s
<a href="#output-bitmap" id="the-offscreen-2d-rendering-context:output-bitmap">output bitmap</a> to be a reference to <var>image</var>.</p>
<p class="note">If <var>image</var> has different dimensions than the bitmap previously
referenced as the <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder-6">placeholder <code>canvas</code>
element</a>'s <a href="#output-bitmap" id="the-offscreen-2d-rendering-context:output-bitmap-2">output bitmap</a>, then this task will result in a change in
the <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder-7">placeholder <code>canvas</code>
element</a>'s <a data-x-internal="intrinsic-dimensions" href="https://drafts.csswg.org/css2/conform.html#intrinsic" id="the-offscreen-2d-rendering-context:intrinsic-dimensions">intrinsic size</a>, which can affect
document layout.</p>
</li></ol>
<p class="note">Implementations are encouraged to short-circuit the graphics update steps of
the <a href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="the-offscreen-2d-rendering-context:browsing-context-2">browsing context</a> <a href="https://html.spec.whatwg.org/multipage/webappapis.html#event-loop" id="the-offscreen-2d-rendering-context:event-loop-2">event loop</a> for the purposes of updating the
contents of a <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder-8">placeholder <code>canvas</code>
element</a> to the display. This could mean, for example, that the <code id="the-offscreen-2d-rendering-context:offscreencontext2d-commit-2-3"><a href="#offscreencontext2d-commit-2">commit()</a></code> method can copy the bitmap contents directly
to a graphics buffer that is mapped to the physical display location of the <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder-9">placeholder <code>canvas</code> element</a>. This or
similar short-circuiting approaches can significantly reduce display latency, especially in cases
where the <code id="the-offscreen-2d-rendering-context:offscreencontext2d-commit-2-4"><a href="#offscreencontext2d-commit-2">commit()</a></code> method is invoked from a worker
and the <a href="https://html.spec.whatwg.org/multipage/webappapis.html#event-loop" id="the-offscreen-2d-rendering-context:event-loop-3">event loop</a> of the <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder-10">placeholder <code>canvas</code> element</a>'s
<a href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="the-offscreen-2d-rendering-context:browsing-context-3">browsing context</a> is busy. However, such shortcuts can not have any
script-observable side-effects. This means that the committed bitmap still needs to be sent to
the <a href="#offscreencanvas-placeholder" id="the-offscreen-2d-rendering-context:offscreencanvas-placeholder-11">placeholder <code>canvas</code> element</a>, in
case the element is used as a <code id="the-offscreen-2d-rendering-context:canvasimagesource"><a href="#canvasimagesource">CanvasImageSource</a></code>, as an
<code id="the-offscreen-2d-rendering-context:imagebitmapsource"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmapsource">ImageBitmapSource</a></code>, or in case <code id="the-offscreen-2d-rendering-context:dom-canvas-todataurl-2"><a href="#dom-canvas-todataurl-2">toDataURL()</a></code>
or <code id="the-offscreen-2d-rendering-context:dom-canvas-toblob-2"><a href="#dom-canvas-toblob-2">toBlob()</a></code> are called on it.</p>
<p>The <dfn id="offscreencontext2d-canvas-2"><code>canvas</code></dfn> attribute, on getting,
must return this <code id="the-offscreen-2d-rendering-context:offscreencanvasrenderingcontext2d-23"><a href="#offscreencanvasrenderingcontext2d">OffscreenCanvasRenderingContext2D</a></code>'s <a href="#associated-offscreencanvas-object" id="the-offscreen-2d-rendering-context:associated-offscreencanvas-object-5">associated
<code>OffscreenCanvas</code> object</a>.
</p>
<h5 id="colour-spaces-and-colour-correction"><span class="secno">4.12.5.4</span> Color spaces and color correction<a class="self-link" href="#colour-spaces-and-colour-correction"/></h5>
<p>The <code id="colour-spaces-and-colour-correction:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> APIs must perform color correction at only two points: when rendering
images with their own gamma correction and color space information onto a bitmap, to convert the
image to the color space used by the bitmaps (e.g. using the 2D Context's <code id="colour-spaces-and-colour-correction:dom-context-2d-drawimage"><a href="#dom-context-2d-drawimage">drawImage()</a></code> method with an
<code id="colour-spaces-and-colour-correction:htmlorsvgimageelement"><a href="#htmlorsvgimageelement">HTMLOrSVGImageElement</a></code> object), and when rendering the actual canvas bitmap to the
output device.</p>
<p class="note">Thus, in the 2D context, colors used to draw shapes onto the canvas will exactly
match colors obtained through the <code id="colour-spaces-and-colour-correction:dom-context-2d-getimagedata-2"><a href="#dom-context-2d-getimagedata-2">getImageData()</a></code> method.</p>
<p>The <code id="colour-spaces-and-colour-correction:dom-canvas-todataurl-2"><a href="#dom-canvas-todataurl-2">toDataURL()</a></code> method, when invoked, must not
include color space information in the resources they return. Where the output format allows it,
the color of pixels in resources created by <code id="colour-spaces-and-colour-correction:dom-canvas-todataurl-2-2"><a href="#dom-canvas-todataurl-2">toDataURL()</a></code>
must match those returned by the <code id="colour-spaces-and-colour-correction:dom-context-2d-getimagedata-2-2"><a href="#dom-context-2d-getimagedata-2">getImageData()</a></code>
method.</p>
<p>In user agents that support CSS, the color space used by a <code id="colour-spaces-and-colour-correction:the-canvas-element-2"><a href="#the-canvas-element">canvas</a></code> element must
match the color space used for processing any colors for that element in CSS.</p>
<p>The gamma correction and color space information of images must be handled in such a way that
an image rendered directly using an <code id="colour-spaces-and-colour-correction:the-img-element"><a href="https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element">img</a></code> element would use the same colors as one
painted on a <code id="colour-spaces-and-colour-correction:the-canvas-element-3"><a href="#the-canvas-element">canvas</a></code> element that is then itself rendered. Furthermore, the rendering
of images that have no color correction information (such as those returned by the <code id="colour-spaces-and-colour-correction:dom-canvas-todataurl-2-3"><a href="#dom-canvas-todataurl-2">toDataURL()</a></code> method) must be rendered with no color
correction.</p>
<p class="note">Thus, in the 2D context, calling the <code id="colour-spaces-and-colour-correction:dom-context-2d-drawimage-2"><a href="#dom-context-2d-drawimage">drawImage()</a></code> method to render the output of the <code id="colour-spaces-and-colour-correction:dom-canvas-todataurl-2-4"><a href="#dom-canvas-todataurl-2">toDataURL()</a></code> method to the canvas, given the appropriate
dimensions, has no visible effect.</p>
<h5 id="serialising-bitmaps-to-a-file"><span class="secno">4.12.5.5</span> Serializing bitmaps to a file<a class="self-link" href="#serialising-bitmaps-to-a-file"/></h5>
<p>When a user agent is to create <dfn id="a-serialisation-of-the-bitmap-as-a-file">a
serialization of the bitmap as a file</dfn>, given an optional <var>type</var> and
<var>quality</var>, it must create an image file in the format given by <var>type</var>, or if
<var>type</var> was not supplied, in the PNG format. If an error occurs during the creation of
the image file (e.g. an internal encoder error), then the result of the serialization is null.
<a href="https://html.spec.whatwg.org/multipage/references.html#refsPNG">[PNG]</a></p>
<p>The image file's pixel data must be the bitmap's pixel data scaled to one image pixel per
coordinate space unit, and if the file format used supports encoding resolution metadata, the
resolution must be given as 96dpi (one image pixel per <a data-x-internal="'px'" href="https://drafts.csswg.org/css-values/#px" id="serialising-bitmaps-to-a-file:'px'">CSS pixel</a>).</p>
<p>If <var>type</var> is supplied, then it must be interpreted as a <a data-x-internal="mime-type" href="https://mimesniff.spec.whatwg.org/#mime-type" id="serialising-bitmaps-to-a-file:mime-type">MIME
type</a> giving the format to use. If the type has any parameters, then it must be treated as
not supported.</p>
<p class="example">For example, the value &quot;<code id="serialising-bitmaps-to-a-file:image/png"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/png">image/png</a></code>&quot; would mean to generate a PNG
image, the value &quot;<code id="serialising-bitmaps-to-a-file:image/jpeg"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/jpeg">image/jpeg</a></code>&quot; would mean to generate a JPEG image, and the value
&quot;<code id="serialising-bitmaps-to-a-file:image/svg+xml"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/svg+xml">image/svg+xml</a></code>&quot; would mean to generate an SVG image (which would require that the
user agent track how the bitmap was generated, an unlikely, though potentially awesome,
feature).</p>
<p>User agents must support PNG (&quot;<code id="serialising-bitmaps-to-a-file:image/png-2"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/png">image/png</a></code>&quot;). User agents may support other types.
If the user agent does not support the requested type, then it must create the file using the PNG
format. <a href="https://html.spec.whatwg.org/multipage/references.html#refsPNG">[PNG]</a></p>
<p>User agents must <a data-x-internal="converted-to-ascii-lowercase" href="https://infra.spec.whatwg.org/#ascii-lowercase" id="serialising-bitmaps-to-a-file:converted-to-ascii-lowercase">convert the provided type to ASCII
lowercase</a> before establishing if they support that type.</p>
<p>For image types that do not support an alpha channel, the serialized image must be the bitmap
image composited onto a solid black background using the source-over operator.</p>
<p>If <var>type</var> is an image format that supports variable quality (such as
&quot;<code id="serialising-bitmaps-to-a-file:image/jpeg-2"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/jpeg">image/jpeg</a></code>&quot;) and <var>quality</var> is given, then, if <a data-x-internal="js-type" href="https://tc39.github.io/ecma262/#sec-ecmascript-data-types-and-values" id="serialising-bitmaps-to-a-file:js-type">Type</a>(<var>quality</var>) is Number, and <var>quality</var> is in the range
0.0 to 1.0 inclusive, the user agent must treat <var>quality</var> as the desired quality level.
If <a data-x-internal="js-type" href="https://tc39.github.io/ecma262/#sec-ecmascript-data-types-and-values" id="serialising-bitmaps-to-a-file:js-type-2">Type</a>(<var>quality</var>) is not Number, or if <var>quality</var>
is outside that range, the user agent must use its default quality value, as if the
<var>quality</var> argument had not been given.</p>
<p class="note">The use of type-testing here, instead of simply declaring <var>quality</var> as
a Web IDL <code>double</code>, is a historical artifact.</p>
<h5 id="security-with-canvas-elements"><span class="secno">4.12.5.6</span> Security with <code id="security-with-canvas-elements:the-canvas-element"><a href="#the-canvas-element">canvas</a></code> elements<a class="self-link" href="#security-with-canvas-elements"/></h5>
<p><i>This section is non-normative.</i></p>
<p><strong>Information leakage</strong> can occur if scripts from one <a href="https://html.spec.whatwg.org/multipage/origin.html#concept-origin" id="security-with-canvas-elements:concept-origin">origin</a> can
access information (e.g. read pixels) from images from another origin (one that isn't the <a href="https://html.spec.whatwg.org/multipage/origin.html#same-origin" id="security-with-canvas-elements:same-origin">same</a>).</p>
<p>To mitigate this, bitmaps used with <code id="security-with-canvas-elements:the-canvas-element-2"><a href="#the-canvas-element">canvas</a></code> elements and <code id="security-with-canvas-elements:imagebitmap"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code>
objects are defined to have a flag indicating whether they are <a href="#concept-canvas-origin-clean" id="security-with-canvas-elements:concept-canvas-origin-clean">origin-clean</a>. All bitmaps start with their <a href="#concept-canvas-origin-clean" id="security-with-canvas-elements:concept-canvas-origin-clean-2">origin-clean</a> set to true. The flag is set to false
when cross-origin images are used.</p>
<p>The <code id="security-with-canvas-elements:dom-canvas-todataurl-2"><a href="#dom-canvas-todataurl-2">toDataURL()</a></code>, <code id="security-with-canvas-elements:dom-canvas-toblob-2"><a href="#dom-canvas-toblob-2">toBlob()</a></code>, and <code id="security-with-canvas-elements:dom-context-2d-getimagedata-2"><a href="#dom-context-2d-getimagedata-2">getImageData()</a></code> methods check the flag and will
throw a <a data-x-internal="securityerror" href="https://heycam.github.io/webidl/#securityerror" id="security-with-canvas-elements:securityerror">&quot;<code>SecurityError</code>&quot;</a> <code id="security-with-canvas-elements:domexception"><a data-x-internal="domexception" href="https://heycam.github.io/webidl/#dfn-DOMException">DOMException</a></code> rather than leak
cross-origin data.</p>
<p>The value of the <a href="#concept-canvas-origin-clean" id="security-with-canvas-elements:concept-canvas-origin-clean-3">origin-clean</a> flag is
propagated from a source <code id="security-with-canvas-elements:the-canvas-element-3"><a href="#the-canvas-element">canvas</a></code> element's bitmap to a new <code id="security-with-canvas-elements:imagebitmap-2"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code>
object by <code id="security-with-canvas-elements:dom-createimagebitmap-2"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#dom-createimagebitmap-2">createImageBitmap()</a></code>. Conversely, a
destination <code id="security-with-canvas-elements:the-canvas-element-4"><a href="#the-canvas-element">canvas</a></code> element's bitmap will have its <a href="#concept-canvas-origin-clean" id="security-with-canvas-elements:concept-canvas-origin-clean-4">origin-clean</a> flags set to false by <code id="security-with-canvas-elements:dom-context-2d-drawimage"><a href="#dom-context-2d-drawimage">drawImage</a></code> if the source image is an
<code id="security-with-canvas-elements:imagebitmap-3"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code> object whose bitmap has its <a href="#concept-canvas-origin-clean" id="security-with-canvas-elements:concept-canvas-origin-clean-5">origin-clean</a> flag set to false.</p>
<p>The flag can be reset in certain situations; for example, when changing the value of the
<code id="security-with-canvas-elements:attr-canvas-width"><a href="#attr-canvas-width">width</a></code> or the <code id="security-with-canvas-elements:attr-canvas-height"><a href="#attr-canvas-height">height</a></code> content attribute of the <code id="security-with-canvas-elements:the-canvas-element-5"><a href="#the-canvas-element">canvas</a></code> element
to which a <code id="security-with-canvas-elements:canvasrenderingcontext2d"><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> is bound, the bitmap is
cleared and its <a href="#concept-canvas-origin-clean" id="security-with-canvas-elements:concept-canvas-origin-clean-6">origin-clean</a> flag is reset.</p>
<p>When using an <code id="security-with-canvas-elements:imagebitmaprenderingcontext"><a href="#imagebitmaprenderingcontext">ImageBitmapRenderingContext</a></code>, the value of the <a href="#concept-canvas-origin-clean" id="security-with-canvas-elements:concept-canvas-origin-clean-7">origin-clean</a> flag is propagated from
<code id="security-with-canvas-elements:imagebitmap-4"><a href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap">ImageBitmap</a></code> objects when they are transferred to the <code id="security-with-canvas-elements:the-canvas-element-6"><a href="#the-canvas-element">canvas</a></code>
via <a href="#dom-imagebitmaprenderingcontext-transferfromimagebitmap-2" id="security-with-canvas-elements:dom-imagebitmaprenderingcontext-transferfromimagebitmap-2">transferFromImageBitmap()</a>.</p>
</body></html>
Reference in a new issue View git blame Copy permalink