| <?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 > :not(input) { display: none; } |
| .status > input { position: absolute; left: 0; top: 0; width: 1em; height: 1em; border: none; background: transparent; padding: 0; margin: 0; } |
| .status > p { font-size: 0.6em; margin: 0; padding: 0; } |
| .status > p + p { padding-top: 0.5em; } |
| .status > p > strong { margin-left: 1.5em; } |
| .status > .support { display: block; } |
| .status > .support > span { padding: 0.2em 0; display: block; display: table; } |
| .status > .support > span.partial { color: #666666; filter: grayscale(50%); } |
| .status > .support > span.no { color: #CCCCCC; filter: grayscale(100%); } |
| .status > .support > span.no::before { opacity: 0.5; } |
| .status > .support > span:first-of-type { padding-top: 0.5em; } |
| .status > .support > span > span { padding: 0 0.5em; display: table-cell; vertical-align: top; } |
| .status > .support > span > span:first-child { width: 100%; } |
| .status > .support > span > span:last-child { width: 100%; white-space: pre; padding: 0; } |
| .status > .support > 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 > .support > .and_chr::before { background-image: url(https://resources.whatwg.org/browser-logos/chrome.svg); } |
| .status > .support > .and_ff::before { background-image: url(https://resources.whatwg.org/browser-logos/firefox.png); } |
| .status > .support > .and_uc::before { background-image: url(https://resources.whatwg.org/browser-logos/uc.png); } /* UC Browser for Android */ |
| .status > .support > .android::before { background-image: url(https://resources.whatwg.org/browser-logos/android.svg); } |
| .status > .support > .bb::before { background-image: url(https://resources.whatwg.org/browser-logos/bb.jpg); } /* Blackberry Browser */ |
| .status > .support > .chrome::before { background-image: url(https://resources.whatwg.org/browser-logos/chrome.svg); } |
| .status > .support > .edge::before { background-image: url(https://resources.whatwg.org/browser-logos/edge.svg); } |
| .status > .support > .firefox::before { background-image: url(https://resources.whatwg.org/browser-logos/firefox.png); } |
| .status > .support > .ie::before { background-image: url(https://resources.whatwg.org/browser-logos/ie.png); } |
| .status > .support > .ie_mob::before { background-image: url(https://resources.whatwg.org/browser-logos/ie-mobile.svg); } |
| .status > .support > .ios_saf::before { background-image: url(https://resources.whatwg.org/browser-logos/safari-ios.svg); } |
| .status > .support > .op_mini::before { background-image: url(https://resources.whatwg.org/browser-logos/opera-mini.png); } |
| .status > .support > .op_mob::before { background-image: url(https://resources.whatwg.org/browser-logos/opera.png); } |
| .status > .support > .opera::before { background-image: url(https://resources.whatwg.org/browser-logos/opera.png); } |
| .status > .support > .safari::before { background-image: url(https://resources.whatwg.org/browser-logos/safari.png); } |
| .status > .support > .samsung::before { background-image: url(https://resources.whatwg.org/browser-logos/samsung.png); } |
| .status > .caniuse { text-align: right; font-style: italic; width: 100%; } |
| .status > .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 > * { 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 > th[rowspan="2"]:first-child + th, |
| .vertical-summary-table tr > td[rowspan="2"]: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(". "); } |
| #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: "Times", 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(". ") } |
| .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 > td:first-child, |
| .three-column-nowrap tr > td:first-child + td, |
| .three-column-nowrap tr > td:first-child + td + td { white-space: nowrap; } |
| |
| .details-example img { vertical-align: top; } |
| |
| .parse-error-table td > p:first-child { margin-top: 0; } |
| |
| #named-character-references-table { |
| white-space: nowrap; |
| font-size: 0.6em; |
| column-width: 30em; |
| column-gap: 1em; |
| -webkit-column-width: 30em; |
| -webkit-column-gap: 1em; |
| } |
| #named-character-references-table > table > tbody > tr > td:first-child + td, |
| #named-character-references-table > table > tbody > tr > td:last-child { text-align: center; } |
| #named-character-references-table > table > tbody > tr > td:last-child:hover > 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 > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; } |
| |
| .glyph.control { color: red; } |
| |
| #table-example-1 * { font-family: "Essays1743", 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 "<code id="the-canvas-element:canvas-context-2d"><a href="#canvas-context-2d">2d</a></code>", "<code id="the-canvas-element:canvas-context-bitmaprenderer"><a href="#canvas-context-bitmaprenderer">bitmaprenderer</a></code>" or "<code id="the-canvas-element:canvas-context-webgl"><a href="#canvas-context-webgl">webgl</a></code>". Subsequent arguments are handled by that API.</p> |
| |
| <p>This specification defines the "<code id="the-canvas-element:canvas-context-2d-2"><a href="#canvas-context-2d">2d</a></code>" and "<code id="the-canvas-element:canvas-context-bitmaprenderer-2"><a href="#canvas-context-bitmaprenderer">bitmaprenderer</a></code>" contexts below. There is also a |
| specification that defines a "<code id="the-canvas-element:canvas-context-webgl-2"><a href="#canvas-context-webgl">webgl</a></code>" 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 "<code id="the-canvas-element:canvas-context-2d-3"><a href="#canvas-context-2d">2d</a></code>" context after getting a "<code id="the-canvas-element:canvas-context-webgl-3"><a href="#canvas-context-webgl">webgl</a></code>" 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>"<dfn id="canvas-context-2d"><code>2d</code></dfn>" |
| </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">"<code>InvalidStateError</code>"</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>"<dfn id="canvas-context-bitmaprenderer"><code>bitmaprenderer</code></dfn>" |
| </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">"<code>InvalidStateError</code>"</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>"<dfn id="canvas-context-webgl"><code>webgl</code></dfn>", 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">"<code>InvalidStateError</code>"</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">"<code>InvalidStateError</code>"</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 "<code id="the-canvas-element:canvas-context-webgl-4"><a href="#canvas-context-webgl">webgl</a></code>" |
| 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 "<code id="the-canvas-element:image/png"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/png">image/png</a></code>"; 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 "<code id="the-canvas-element:image/jpeg"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/jpeg">image/jpeg</a></code>"), 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 "<code id="the-canvas-element:image/png-2"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/png">image/png</a></code>", 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 "<code>data:image/png,</code>" or "<code>data:image/png;</code>". 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 "<code>data:,</code>".)</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 "<code id="the-canvas-element:image/png-3"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/png">image/png</a></code>"; 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 "<code id="the-canvas-element:image/jpeg-2"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/jpeg">image/jpeg</a></code>"), 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">"<code>SecurityError</code>"</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 "<code>data:,</code>" 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 "<code>data:,</code>".</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">"<code>SecurityError</code>"</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">"<code>InvalidStateError</code>"</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> { "<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero">nonzero</a>", "<a href="#dom-context-2d-fillrule-evenodd" id="2dcontext:dom-context-2d-fillrule-evenodd">evenodd</a>" }; |
| |
| 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> { "<a href="#dom-context-2d-imagesmoothingquality-low" id="2dcontext:dom-context-2d-imagesmoothingquality-low">low</a>", "<a href="#dom-context-2d-imagesmoothingquality-medium" id="2dcontext:dom-context-2d-imagesmoothingquality-medium">medium</a>", "<a href="#dom-context-2d-imagesmoothingquality-high" id="2dcontext:dom-context-2d-imagesmoothingquality-high">high</a>" }; |
| |
| 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 "none") |
| }; |
| |
| [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 = "<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-2">nonzero</a>"); |
| 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 = "<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-3">nonzero</a>"); |
| 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 = "<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-4">nonzero</a>"); |
| 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 = "<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-5">nonzero</a>"); |
| 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 = "<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-6">nonzero</a>"); |
| 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 = "<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-7">nonzero</a>"); |
| 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> { "butt", "round", "square" }; |
| enum <dfn id="canvaslinejoin">CanvasLineJoin</dfn> { "round", "bevel", "miter" }; |
| enum <dfn id="canvastextalign">CanvasTextAlign</dfn> { "<a href="#dom-context-2d-textalign-start" id="2dcontext:dom-context-2d-textalign-start">start</a>", "<a href="#dom-context-2d-textalign-end" id="2dcontext:dom-context-2d-textalign-end">end</a>", "<a href="#dom-context-2d-textalign-left" id="2dcontext:dom-context-2d-textalign-left">left</a>", "<a href="#dom-context-2d-textalign-right" id="2dcontext:dom-context-2d-textalign-right">right</a>", "<a href="#dom-context-2d-textalign-center" id="2dcontext:dom-context-2d-textalign-center">center</a>" }; |
| enum <dfn id="canvastextbaseline">CanvasTextBaseline</dfn> { "<a href="#dom-context-2d-textbaseline-top" id="2dcontext:dom-context-2d-textbaseline-top">top</a>", "<a href="#dom-context-2d-textbaseline-hanging" id="2dcontext:dom-context-2d-textbaseline-hanging">hanging</a>", "<a href="#dom-context-2d-textbaseline-middle" id="2dcontext:dom-context-2d-textbaseline-middle">middle</a>", "<a href="#dom-context-2d-textbaseline-alphabetic" id="2dcontext:dom-context-2d-textbaseline-alphabetic">alphabetic</a>", "<a href="#dom-context-2d-textbaseline-ideographic" id="2dcontext:dom-context-2d-textbaseline-ideographic">ideographic</a>", "<a href="#dom-context-2d-textbaseline-bottom" id="2dcontext:dom-context-2d-textbaseline-bottom">bottom</a>" }; |
| enum <dfn id="canvasdirection">CanvasDirection</dfn> { "<a href="#dom-context-2d-direction-ltr" id="2dcontext:dom-context-2d-direction-ltr">ltr</a>", "<a href="#dom-context-2d-direction-rtl" id="2dcontext:dom-context-2d-direction-rtl">rtl</a>", "<a href="#dom-context-2d-direction-inherit" id="2dcontext:dom-context-2d-direction-inherit">inherit</a>" }; |
| |
| [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 "butt") |
| 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 "miter") |
| 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<unrestricted double> segments); // default empty |
| sequence<unrestricted double> <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: "start") |
| 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: "alphabetic") |
| 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: "inherit") |
| }; |
| |
| [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<<a href="#path2d" id="2dcontext:path2d-9">Path2D</a>> paths, optional <a href="#canvasfillrule" id="2dcontext:canvasfillrule-7">CanvasFillRule</a> fillRule = "<a href="#dom-context-2d-fillrule-nonzero" id="2dcontext:dom-context-2d-fillrule-nonzero-8">nonzero</a>"), |
| <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 <canvas> 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 "<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" 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 |
| "element in question" 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 "<dfn id="dom-context-2d-fillrule-nonzero"><code>nonzero</code></dfn>" 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 "<dfn id="dom-context-2d-fillrule-evenodd"><code>evenodd</code></dfn>" 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 "<dfn id="dom-context-2d-imagesmoothingquality-low"><code>low</code></dfn>" 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 "<dfn id="dom-context-2d-imagesmoothingquality-medium"><code>medium</code></dfn>" value |
| indicates a preference for a medium level of image interpolation quality.</p> |
| |
| <p>The "<dfn id="dom-context-2d-imagesmoothingquality-high"><code>high</code></dfn>" 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 "<code>butt</code>", "<code>round</code>", and "<code>square</code>". 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 "<code>bevel</code>", "<code>round</code>", and "<code>miter</code>". 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 "<code>butt</code>", "<code>round</code>", and "<code>square</code>".</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 |
| "<code>butt</code>".</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 |
| "<code>bevel</code>", "<code>round</code>", and "<code>miter</code>".</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 |
| "<code>miter</code>".</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 "<code>miter</code>", 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 "phase" of the dash pattern, e.g. to achieve a "marching |
| ants" 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 "<code>butt</code>" value means that no additional line cap is added. The "<code>round</code>" 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 "<code>square</code>" 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 "<code>bevel</code>" value means that this is all that is rendered at |
| joins.</p> |
| |
| <p>The "<code>round</code>" 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 "<code>miter</code>" 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 "<code>start</code>".</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 "<code id="text-styles:dom-context-2d-textbaseline-alphabetic"><a href="#dom-context-2d-textbaseline-alphabetic">alphabetic</a></code>".</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 "<code id="text-styles:dom-context-2d-direction-inherit"><a href="#dom-context-2d-direction-inherit">inherit</a></code>".</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 <'font'> |
| 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 "<code>italic 12px "Unknown Font", sans-serif</code>". The "400" |
| font-weight doesn't appear because that is the default value. The line-height doesn't appear |
| because it is forced to "normal", 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 "<code id="text-styles:dom-context-2d-direction-inherit-2"><a href="#dom-context-2d-direction-inherit">inherit</a></code>".</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 "<code id="text-styles:dom-context-2d-direction-ltr"><a href="#dom-context-2d-direction-ltr">ltr</a></code>"</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 "<code id="text-styles:dom-context-2d-direction-rtl"><a href="#dom-context-2d-direction-rtl">rtl</a></code>"</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">"<code>IndexSizeError</code>"</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">"<code>IndexSizeError</code>"</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">"<code>IndexSizeError</code>"</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 |
| "closing" 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">"<code>IndexSizeError</code>"</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">"<code>IndexSizeError</code>"</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 "nonzero"</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 "evenodd"</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">"<code>InvalidStateError</code>"</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">"<code>InvalidStateError</code>"</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 <color> 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 |
| <color> 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 "#" 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 "<code>rgba</code>" (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">"<code>IndexSizeError</code>"</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">"<code>SyntaxError</code>"</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">"<code>IndexSizeError</code>"</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">"<code>IndexSizeError</code>"</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 <color> value</a>, then a |
| <a data-x-internal="syntaxerror" href="https://heycam.github.io/webidl/#syntaxerror" id="fill-and-stroke-styles:syntaxerror-2">"<code>SyntaxError</code>"</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 <color> 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">"<code>IndexSizeError</code>"</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>) > 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">"<code>InvalidStateError</code>"</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 "<code>repeat</code>".</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 |
| "<code>repeat</code>", "<code>repeat-x</code>", "<code>repeat-y</code>", or "<code>no-repeat</code>", then throw a |
| <a data-x-internal="syntaxerror" href="https://heycam.github.io/webidl/#syntaxerror" id="fill-and-stroke-styles:syntaxerror-3">"<code>SyntaxError</code>"</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 "<code>repeat-x</code>", or vertically up and |
| down, if the repetition behavior is "<code>repeat-y</code>", or in all four |
| directions all over the bitmap, if the repetition behavior is "<code>repeat</code>".</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 "using a font" 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">"<code>SecurityError</code>"</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 |
| "o" from an alphabetic baseline would be less than that of an uppercase "F". 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 "<code id="drawing-text-to-the-bitmap:dom-context-2d-textbaseline-top"><a href="#dom-context-2d-textbaseline-top">top</a></code>") to the top of the bounding rectangle when |
| the given text is just a single comma "<code>,</code>" 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="<canvas>: 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><canvas height=400 width=750> |
| <label><input type=checkbox id=showA> Show As</label> |
| <label><input type=checkbox id=showB> Show Bs</label> |
| <!-- ... --> |
| </canvas> |
| <script> |
| 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(); |
| </script></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">"Inform the user", 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">"<code>InvalidStateError</code>"</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 "<a href="https://drafts.csswg.org/css-images/#default-sizing">Concrete Object |
| Size Resolution</a>" 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">"<code>IndexSizeError</code>"</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">"<code>IndexSizeError</code>"</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">"<code>IndexSizeError</code>"</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">"<code>InvalidStateError</code>"</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">"<code>IndexSizeError</code>"</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">"<code>InvalidStateError</code>"</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">"<code>IndexSizeError</code>"</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">"<code>IndexSizeError</code>"</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">"<code>IndexSizeError</code>"</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">"<code>IndexSizeError</code>"</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">"<code>SecurityError</code>"</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">"<code>InvalidStateError</code>"</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> < <span><var>dirtyX</var>+<var>dirtyWidth</var></span></span> and <span><var>dirtyY</var> ≤ <var>y</var> < <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 <canvas> 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><!DOCTYPE HTML> |
| <html lang="en"> |
| <head> |
| <title>Edge detection demo</title> |
| <script> |
| var image = new Image(); |
| function init() { |
| image.onload = demo; |
| image.src = "image.jpeg"; |
| } |
| 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 < h-1; y += 1) { |
| for (var x = 1; x < w-1; x += 1) { |
| for (var c = 0; c < 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); |
| } |
| </script> |
| </head> |
| <body onload="init()"> |
| <canvas></canvas> |
| </body> |
| </html></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 |
| "<code id="image-smoothing:dom-context-2d-imagesmoothingquality-low"><a href="#dom-context-2d-imagesmoothingquality-low">low</a></code>", "<code id="image-smoothing:dom-context-2d-imagesmoothingquality-medium"><a href="#dom-context-2d-imagesmoothingquality-medium">medium</a></code>" and "<code id="image-smoothing:dom-context-2d-imagesmoothingquality-high"><a href="#dom-context-2d-imagesmoothingquality-high">high</a></code>". 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 "<code id="image-smoothing:dom-context-2d-imagesmoothingquality-low-2"><a href="#dom-context-2d-imagesmoothingquality-low">low</a></code>".</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 <color> 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 <color> 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"><filter-function-list></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"><filter-function-list></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"><filter-function-list></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"><filter-function-list></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><canvas width="800" height="450"></canvas> |
| <script> |
| |
| 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); |
| |
| </script></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><!DOCTYPE HTML> |
| <meta charset="utf-8"> |
| <title>Blue Robot Demo</title> |
| <style> |
| 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; } |
| </style> |
| <canvas width="380" height="200"></canvas> |
| <script> |
| 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(); |
| }; |
| }; |
| </script> |
| <script> |
| 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 >= 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); |
| }; |
| }; |
| </script> |
| <script> |
| 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); |
| </script> |
| <p class="buttons"> |
| <input type=button value="Walk" onclick="blueRobot.walk()"> |
| <input type=button value="Stop" onclick="blueRobot.stop()"> |
| <footer> |
| <small> Blue Robot Player Sprite by <a href="https://johncolburn.deviantart.com/">JohnColburn</a>. |
| Licensed under the terms of the Creative Commons Attribution Share-Alike 3.0 Unported license.</small> |
| <small> This work is itself licensed under a <a rel="license" href="https://creativecommons.org/licenses/by-sa/3.0/">Creative |
| Commons Attribution-ShareAlike 3.0 Unported License</a>.</small> |
| </footer> |
| </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 => { |
| const canvas = document.createElement('canvas'); |
| const context = canvas.getContext('bitmaprenderer'); |
| context.transferFromImageBitmap(image); |
| |
| canvas.toBlob(outputJPEGBlob => { |
| // 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">"<code>InvalidStateError</code>"</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> = "image/png"; |
| 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> { "<a href="#offscreen-context-type-2d" id="the-offscreencanvas-interface:offscreen-context-type-2d">2d</a>", "<a href="#offscreen-context-type-webgl" id="the-offscreencanvas-interface:offscreen-context-type-webgl">webgl</a>" }; |
| |
| [<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<<a data-x-internal="blob" href="https://w3c.github.io/FileAPI/#blob" id="the-offscreencanvas-interface:blob">Blob</a>> <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 "<code id="the-offscreencanvas-interface:offscreen-context-type-2d-2"><a href="#offscreen-context-type-2d">2d</a></code>", or "<code id="the-offscreencanvas-interface:offscreen-context-type-webgl-2"><a href="#offscreen-context-type-webgl">webgl</a></code>". Subsequent arguments are handled by that |
| API.</p> |
| |
| <p>This specification defines the "<code id="the-offscreencanvas-interface:canvas-context-2d"><a href="#canvas-context-2d">2d</a></code>" context below, |
| which is similar but distinct from the "<code id="the-offscreencanvas-interface:offscreen-context-type-2d-3"><a href="#offscreen-context-type-2d">2d</a></code>" |
| 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 "<code id="the-offscreencanvas-interface:offscreen-context-type-webgl-3"><a href="#offscreen-context-type-webgl">webgl</a></code>" 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 "<code id="the-offscreencanvas-interface:offscreen-context-type-2d-4"><a href="#offscreen-context-type-2d">2d</a></code>" context after getting a |
| "<code id="the-offscreencanvas-interface:offscreen-context-type-webgl-4"><a href="#offscreen-context-type-webgl">webgl</a></code>" 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">"<code>InvalidStateError</code>"</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>"<dfn id="offscreen-context-type-2d"><code>2d</code></dfn>" |
| </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">"<code>InvalidStateError</code>"</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>"<dfn id="offscreen-context-type-webgl"><code>webgl</code></dfn>" |
| </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">"<code>InvalidStateError</code>"</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 "<code id="the-offscreencanvas-interface:offscreen-context-type-webgl-5"><a href="#offscreen-context-type-webgl">webgl</a></code>" |
| 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 "<code id="the-offscreencanvas-interface:image/png"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/png">image/png</a></code>"; that type |
| is also used if the requested type isn't supported. If the image format supports variable |
| quality (such as "<code id="the-offscreencanvas-interface:image/jpeg"><a href="https://html.spec.whatwg.org/multipage/indices.html#image/jpeg">image/jpeg</a></code>"), 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">"<code>InvalidStateError</code>"</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">"<code>SecurityError</code>"</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">"<code>IndexSizeError</code>"</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">"<code>EncodingError</code>"</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">"<code>InvalidStateError</code>"</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">"<code>InvalidStateError</code>"</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 "<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>" would mean to generate a PNG |
| image, the value "<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>" would mean to generate a JPEG image, and the value |
| "<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>" 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 ("<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>"). 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 |
| "<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>") 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">"<code>SecurityError</code>"</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> |