diff options
Diffstat (limited to 'testing/web-platform/tests/2dcontext/tools/current-work-canvas.xhtml')
| -rw-r--r-- | testing/web-platform/tests/2dcontext/tools/current-work-canvas.xhtml | 3693 |
1 files changed, 3693 insertions, 0 deletions
diff --git a/testing/web-platform/tests/2dcontext/tools/current-work-canvas.xhtml b/testing/web-platform/tests/2dcontext/tools/current-work-canvas.xhtml new file mode 100644 index 000000000..b41ad7d4d --- /dev/null +++ b/testing/web-platform/tests/2dcontext/tools/current-work-canvas.xhtml @@ -0,0 +1,3693 @@ +<?xml version="1.0" encoding="UTF-8"?><html xml:lang="en-US-x-hixie" xmlns="http://www.w3.org/1999/xhtml"><head><title>HTML Standard</title><link href="http://www.whatwg.org/style/specification" rel="stylesheet"/><link href="http://www.whatwg.org/images/icon" rel="icon"/><style> + .proposal { border: blue solid; padding: 1em; } + .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; } + #updatesStatus { display: none; } + #updatesStatus.relevant { display: block; position: fixed; right: 1em; top: 1em; padding: 0.5em; font: bold small sans-serif; min-width: 25em; width: 30%; max-width: 40em; height: auto; border: ridge 4px gray; background: #EEEEEE; color: black; } + div.head .logo { width: 11em; margin-bottom: 20em; } + #configUI { position: absolute; z-index: 20; top: 10em; right: 0; width: 11em; padding: 0 0.5em 0 0.5em; font-size: small; background: gray; background: rgba(32,32,32,0.9); color: white; border-radius: 1em 0 0 1em; -moz-border-radius: 1em 0 0 1em; } + #configUI p { margin: 0.75em 0; padding: 0.3em; } + #configUI p label { display: block; } + #configUI #updateUI, #configUI .loginUI { text-align: center; } + #configUI input[type=button] { display: block; margin: auto; } + #configUI :link, #configUI :visited { color: white; } + #configUI :link:hover, #configUI :visited:hover { background: transparent; } + #reviewer { position: fixed; bottom: 0; right: 0; padding: 0.15em 0.25em 0em 0.5em; white-space: nowrap; overflow: hidden; z-index: 30; background: gray; background: rgba(32,32,32,0.9); color: white; border-radius: 1em 0 0 0; -moz-border-radius: 1em 0 0 0; max-width: 90%; } + #reviewer input { max-width: 50%; } + #reviewer * { font-size: small; } + #reviewer.off > :not(:first-child) { display: none; } + #alert { position: fixed; top: 20%; left: 20%; right: 20%; font-size: 2em; padding: 0.5em; z-index: 40; background: gray; background: rgba(32,32,32,0.9); color: white; border-radius: 1em; -moz-border-radius: 1em; -webkit-transition: opacity 1s linear; } + #alert.closed { opacity: 0; } + #alert button { position: absolute; top: -1em; right: 2em; border-radius: 1em 1em 0 0; border: none; line-height: 0.9; color: white; background: rgb(64,64,64); font-size: 0.6em; font-weight: 900; cursor: pointer; } + #alert :link, #alert :visited { color: white; } + #alert :link:hover, #alert :visited:hover { background: transparent; } + @media print { #configUI { display: none; } } + .rfc2119 { font-variant: small-caps; text-shadow: 0 0 0.5em yellow; position: static; } + .rfc2119::after { position: absolute; left: 0; width: 25px; text-align: center; color: yellow; text-shadow: 0.075em 0.075em 0.2em black; } + .rfc2119.m\ust::after { content: '\2605'; } + .rfc2119.s\hould::after { content: '\2606'; } + [hidden] { display: none; } + </style><style type="text/css"> + + .applies thead th > * { display: block; } + .applies thead code { display: block; } + .applies tbody th { whitespace: nowrap; } + .applies td { text-align: center; } + .applies .yes { background: yellow; } + + .matrix, .matrix td { border: hidden; text-align: right; } + .matrix { margin-left: 2em; } + + .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 * { font-family: "Essays1743", serif; line-height: 1.01em; } + #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; } + + .details-example img { vertical-align: top; } + + #base64-table { + white-space: nowrap; + font-size: 0.6em; + column-width: 6em; + column-count: 5; + column-gap: 1em; + -moz-column-width: 6em; + -moz-column-count: 5; + -moz-column-gap: 1em; + -webkit-column-width: 6em; + -webkit-column-count: 5; + -webkit-column-gap: 1em; + } + #base64-table thead { display: none; } + #base64-table * { border: none; } + #base64-table tbody td:first-child:after { content: ':'; } + #base64-table tbody td:last-child { text-align: right; } + + #named-character-references-table { + white-space: nowrap; + font-size: 0.6em; + column-width: 30em; + column-gap: 1em; + -moz-column-width: 30em; + -moz-column-gap: 1em; + -webkit-column-width: 30em; + -webkit-column-gap: 1em; + } + #named-character-references-table > 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; } + + @font-face { + font-family: 'Essays1743'; + src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743.ttf'); + } + @font-face { + font-family: 'Essays1743'; + font-weight: bold; + src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Bold.ttf'); + } + @font-face { + font-family: 'Essays1743'; + font-style: italic; + src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Italic.ttf'); + } + @font-face { + font-family: 'Essays1743'; + font-style: italic; + font-weight: bold; + src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-BoldItalic.ttf'); + } + + </style><style> + .domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; } + </style><link href="data:text/css," id="complete" rel="stylesheet" title="Complete specification"/><link href="data:text/css,.impl%20{%20display:%20none;%20}%0Ahtml%20{%20border:%20solid%20yellow;%20}%20.domintro:before%20{%20display:%20none;%20}" id="author" rel="alternate stylesheet" title="Author documentation only"/><link href="data:text/css,.impl%20{%20background:%20%23FFEEEE;%20}%20.domintro:before%20{%20background:%20%23FFEEEE;%20}" id="highlight" rel="alternate stylesheet" title="Highlight implementation requirements"/><link href="http://www.whatwg.org/specs/web-apps/current-work/status.css" rel="stylesheet"/></head><body class="draft" onload="init()"><header class="head" id="head"><p><a class="logo" href="http://www.whatwg.org/"><img alt="WHATWG" height="101" src="http://www.whatwg.org/images/logo" width="101"/></a></p> + <hgroup><h1 class="allcaps">HTML</h1> + <h2 class="no-num no-toc">Living Standard — Last Updated 8 August 2011</h2> + </hgroup><p class="copyright">© Copyright 2004-2011 Apple Computer, Inc., + Mozilla Foundation, and Opera Software ASA.</p> + <p class="copyright">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.8.11 </span>The <dfn id="canvas"><code>canvas</code></dfn> element</h4> + + <dl class="element"><dt>Categories</dt> + <dd><a href="#flow-content">Flow content</a>.</dd> + <dd><a href="#phrasing-content">Phrasing content</a>.</dd> + <dd><a href="#embedded-content">Embedded content</a>.</dd> + <dt>Contexts in which this element can be used:</dt> + <dd>Where <a href="#embedded-content">embedded content</a> is expected.</dd> + <dt>Content model:</dt> + <dd><a href="#transparent">Transparent</a>.</dd> + <dd><a href="#transparent">Transparent</a><!-- +--><!--FORK--><!-- +-->, but with no <a href="#interactive-content">interactive content</a> descendants except for <code><a href="#the-a-element">a</a></code> elements, <code><a href="#the-button-element">button</a></code> elements, <code><a href="#the-input-element">input</a></code> elements whose <code title="attr-input-type"><a href="#attr-input-type">type</a></code> attribute are in the <a href="#checkbox-state" title="attr-input-type-checkbox">Checkbox</a> or <a href="#radio-button-state" title="attr-input-type-radio">Radio Button</a> states, and <code><a href="#the-input-element">input</a></code> elements that are <a href="#concept-button" title="concept-button">buttons</a><!-- +--><!--FORK--><!-- +-->.</dd> <!-- and maybe <select>, I guess? I've left it in for now, since I guess authors might make accessible selects if they're simple enough, and it's not obvious how to distinguish the simple ones from the complex ones... --> + <dt>Content attributes:</dt> + <dd><a href="#global-attributes">Global attributes</a></dd> + <dd><code title="attr-canvas-width"><a href="#attr-canvas-width">width</a></code></dd> + <dd><code title="attr-canvas-height"><a href="#attr-canvas-height">height</a></code></dd> + <dt>DOM interface:</dt> + <dd> + <pre class="idl">interface <dfn id="htmlcanvaselement">HTMLCanvasElement</dfn> : <a href="#htmlelement">HTMLElement</a> { + attribute unsigned long <a href="#dom-canvas-width" title="dom-canvas-width">width</a>; + attribute unsigned long <a href="#dom-canvas-height" title="dom-canvas-height">height</a>; + + DOMString <a href="#dom-canvas-todataurl" title="dom-canvas-toDataURL">toDataURL</a>(in optional DOMString type, in any... args); + void <a href="#dom-canvas-toblob" title="dom-canvas-toBlob">toBlob</a>(in <span>FileCallback</span>? callback, in optional DOMString type, in any... args); + + object? <a href="#dom-canvas-getcontext" title="dom-canvas-getContext">getContext</a>(in DOMString contextId, in any... args); +};</pre> + </dd> + </dl><p>The <code><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, or other visual images on the fly.</p> + + <p>Authors should not use the <code><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><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><a href="#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements">h1</a></code>) and then styled using CSS and + supporting technologies such as XBL.</p> + + <p>When authors use the <code><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 bitmap canvas. This + content may be placed as content of the <code><a href="#the-canvas-element">canvas</a></code> + element. The contents of the <code><a href="#the-canvas-element">canvas</a></code> element, if any, + are the element's <a href="#fallback-content">fallback content</a>.</p> + + <p>In interactive visual media, if <a href="#concept-n-script" title="concept-n-script">scripting is enabled</a> for the + <code><a href="#the-canvas-element">canvas</a></code> element, and if support for <code><a href="#the-canvas-element">canvas</a></code> + elements has been enabled, the <code><a href="#the-canvas-element">canvas</a></code> element + <a href="#represents">represents</a> <a href="#embedded-content">embedded content</a> consisting of + a dynamically created image.</p> + + <p>In non-interactive, static, visual media, if the + <code><a href="#the-canvas-element">canvas</a></code> element has been previously painted on (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><a href="#the-canvas-element">canvas</a></code> element + <a href="#represents">represents</a> <a href="#embedded-content">embedded content</a> with the + current image and size. Otherwise, the element represents its + <a href="#fallback-content">fallback content</a> instead.</p> + + <p>In non-visual media, and in visual media if <a href="#concept-n-noscript" title="concept-n-noscript">scripting is disabled</a> for the + <code><a href="#the-canvas-element">canvas</a></code> element or if support for <code><a href="#the-canvas-element">canvas</a></code> + elements has been disabled, the <code><a href="#the-canvas-element">canvas</a></code> element + <a href="#represents">represents</a> its <a href="#fallback-content">fallback content</a> + instead.</p> + + <!-- CANVAS-FOCUS-FALLBACK --> + <p>When a <code><a href="#the-canvas-element">canvas</a></code> element <a href="#represents">represents</a> + <a href="#embedded-content">embedded content</a>, the user can still focus descendants + of the <code><a href="#the-canvas-element">canvas</a></code> element (in the <a href="#fallback-content">fallback + content</a>). When an element is focused, 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 focusable elements in the <a href="#fallback-content">fallback + content</a>. (Focus has no effect on mouse interaction + events.) <a href="#DOMEVENTS">[DOMEVENTS]</a></p> + + <p>The <code><a href="#the-canvas-element">canvas</a></code> element has two attributes to control the + size of the coordinate space: <dfn id="attr-canvas-width" title="attr-canvas-width"><code>width</code></dfn> and <dfn id="attr-canvas-height" title="attr-canvas-height"><code>height</code></dfn>. These + attributes, when specified, must have values that are <a href="#valid-non-negative-integer" title="valid non-negative integer">valid non-negative + integers</a>. <span class="impl">The <a href="#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.</span> The + <code title="attr-canvas-width"><a href="#attr-canvas-width">width</a></code> attribute defaults to + 300, and the <code title="attr-canvas-height"><a href="#attr-canvas-height">height</a></code> + attribute defaults to 150.</p> + + <p>The intrinsic dimensions of the <code><a href="#the-canvas-element">canvas</a></code> element equal + the size of the coordinate space, with the numbers interpreted in + CSS pixels. However, the element can be sized arbitrarily by a + style sheet. During rendering, the image is scaled to fit this layout + size.</p> + + <div class="impl"> + + <p>The size of the coordinate space does not necessarily represent + the size of the actual bitmap that the user agent will use + internally or during rendering. On high-definition displays, for + instance, the user agent may internally use a bitmap with two device + pixels per unit in the coordinate space, so that the rendering + remains at high quality throughout.</p> + + <p>When the <code><a href="#the-canvas-element">canvas</a></code> element is created, and subsequently + whenever the <code title="attr-canvas-width"><a href="#attr-canvas-width">width</a></code> and <code title="attr-canvas-height"><a href="#attr-canvas-height">height</a></code> attributes are set (whether + to a new value or to the previous value), the bitmap and any + associated contexts must be cleared back to their initial state and + reinitialized with the newly specified coordinate space + dimensions.</p> + + <p>When the canvas is initialized, its bitmap must be cleared to + transparent black.</p> + + <p>The <dfn id="dom-canvas-width" title="dom-canvas-width"><code>width</code></dfn> and + <dfn id="dom-canvas-height" title="dom-canvas-height"><code>height</code></dfn> IDL + attributes must <a href="#reflect">reflect</a> the respective content + attributes of the same name, with the same defaults.</p> + + </div> + + <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/><dl class="domintro"><dt><var title="">context</var> = <var title="">canvas</var> . <code title="dom-canvas-getContext"><a href="#dom-canvas-getcontext">getContext</a></code>(<var title="">contextId</var> [, ... ])</dt> + + <dd> + + <p>Returns an object that exposes an API for drawing on the + canvas. The first argument specifies the desired API. Subsequent + arguments are handled by that API.</p> + +<!--2DCONTEXT--> + + <p>This specification defines the "<code title="canvas-context-2d"><a href="#canvas-context-2d">2d</a></code>" context below. There is also + a specification that defines a "<code title="canvas-context-webgl">webgl</code>" context. <a href="#refsWEBGL">[WEBGL]</a></p> + +<!--2DCONTEXT--> + + <p>The list of defined contexts is given on the <a href="http://wiki.whatwg.org/wiki/CanvasContexts">WHATWG Wiki + CanvasContexts page</a>. <a href="#refsWHATWGWIKI">[WHATWGWIKI]</a> + + </p><p>Returns null if the given context ID is not supported or if the + canvas has already been initialized with some other (incompatible) + context type (e.g. trying to get a "<code title="canvas-context-2d"><a href="#canvas-context-2d">2d</a></code>" context after getting a + "<code title="canvas-context-webgl">webgl</code>" context).</p> + + </dd> + + </dl><div class="impl"> + + <p>A <code><a href="#the-canvas-element">canvas</a></code> element can have a <dfn id="primary-context">primary + context</dfn>, which is the first context to have been obtained for + that element. When created, a <code><a href="#the-canvas-element">canvas</a></code> element must not + have a <a href="#primary-context">primary context</a>.</p> + + + <p>The <dfn id="dom-canvas-getcontext" title="dom-canvas-getContext"><code>getContext(<var title="">contextId</var>, <var title="">args...</var>)</code></dfn> + method of the <code><a href="#the-canvas-element">canvas</a></code> element, when invoked, must run + the following steps:</p> + + <ol><li><p>Let <var title="">contextId</var> be the first argument to + the method.</p></li> + + <li> + + <p>If <var title="">contextId</var> is not the name of a context + supported by the user agent, return null and abort these + steps.</p> + + <p class="note">An example of this would be a user agent that + theoretically supports the "<code title="canvas-context-webgl">webgl</code>" 3D context, in the case + where the platform does not have hardware support for OpenGL and + the user agent does not have a software OpenGL implementation. + Despite the user agent recognising the "<code title="canvas-context-webgl">webgl</code>" name, it would return + null at this step because that context is not, in practice, + supported at the time of the call.</p> + + </li> + + <li><p>If the element has a <a href="#primary-context">primary context</a> and that + context's entry in the <a href="http://wiki.whatwg.org/wiki/CanvasContexts">WHATWG Wiki + CanvasContexts page</a> does not list <var title="">contextId</var> + as a context with which it is compatible, return null and abort + these steps. <a href="#refsWHATWGWIKI">[WHATWGWIKI]</a></p></li> + + <li><p>If the element does not have a <a href="#primary-context">primary context</a>, + let the element's <a href="#primary-context">primary context</a> be <var title="">contextId</var>.</p></li> + + <li><p>If the <code title="dom-canvas-getContext"><a href="#dom-canvas-getcontext">getContext()</a></code> method has + already been invoked on this element for the same <var title="">contextId</var>, return the same object as was returned + that time, and abort these steps. The additional arguments are + ignored.</p></li> + + <li><p><dfn id="getcontext-return" title="getContext-return">Return a new object for <var title="">contextId</var></dfn>, as defined by the specification + given for <var title="">contextId</var>'s entry in the <a href="http://wiki.whatwg.org/wiki/CanvasContexts">WHATWG Wiki + CanvasContexts page</a>. <a href="#refsWHATWGWIKI">[WHATWGWIKI]</a></p></li> + + </ol><p>New context types may be registered in the <a href="http://wiki.whatwg.org/wiki/CanvasContexts">WHATWG Wiki + CanvasContexts page</a>. <a href="#refsWHATWGWIKI">[WHATWGWIKI]</a></p> + + <p>Anyone is free to edit the WHATWG Wiki CanvasContexts page at any + time to add a new context type. These new context types must be + specified with the following information:</p> + + <dl><dt>Keyword</dt> + + <dd><p>The value of <var title="">contextID</var> that will return + the object for the new API.</p></dd> + + + <dt>Specification</dt> + + <dd><p>A link to a formal specification of the context type's + API. It could be another page on the Wiki, or a link to an external + page. If the type does not have a formal specification, an informal + description can be substituted until such time as a formal + specification is available.</p></dd> + + + <dt>Compatible with</dt> + + <dd><p>The list of context types that are compatible with this one + (i.e. that operate on the same underlying bitmap). This list must + be transitive and symmetric; if one context type is defined as + compatible with another, then all types it is compatible with must + be compatible with all types the other is compatible with.</p></dd> + + </dl><p>Vendors may also define experimental contexts using the syntax + <code><var title="">vendorname</var>-<var title="">context</var></code>, for example, + <code>moz-3d</code>. Such contexts should be registered in the + WHATWG Wiki CanvasContexts page.</p> + + </div> + + <hr/><dl class="domintro"><dt><var title="">url</var> = <var title="">canvas</var> . <code title="dom-canvas-toDataURL"><a href="#dom-canvas-todataurl">toDataURL</a></code>( [ <var title="">type</var>, ... ])</dt> + + <dd> + + <p>Returns a <a href="#data-protocol" title="data protocol"><code title="">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 title="">image/png</code>; that type is also used if the given + type isn't supported. The other arguments are specific to the + type, and control the way that the image is generated, as given in + the table below.</p> + + <p>When trying to use types other than "<code>image/png</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 title="">data:image/png,</code>" or "<code title="">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 title="">data:,</code>".)</p> + + </dd> + + <dt><var title="">canvas</var> . <code title="dom-canvas-toBlob"><a href="#dom-canvas-toblob">toBlob</a></code>(<var title="">callback</var> [, <var title="">type</var>, ... ])</dt> + + <dd> + + <p>Creates a <code><a href="#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 title="">image/png</code>; that type is also used if the given + type isn't supported. The other arguments are specific to the + type, and control the way that the image is generated, as given in + the table below.</p> + + </dd> + + </dl><div class="impl"> + + <p>The <dfn id="dom-canvas-todataurl" title="dom-canvas-toDataURL"><code>toDataURL()</code></dfn> method + must run the following steps:</p> + + <ol><li><p>If the canvas has no pixels (i.e. either its horizontal + dimension or its vertical dimension is zero) then return the string + "<code title="">data:,</code>" and abort these steps. (This is the + shortest <a href="#data-protocol" title="data protocol"><code title="">data:</code> + URL</a>; it represents the empty string in a <code title="">text/plain</code> resource.)</p></li> + + <li><p>Let <var title="">file</var> be <a href="#a-serialization-of-the-image-as-a-file">a serialization of the + image as a file</a>, using the method's arguments (if any) as + the <var title="">arguments</var>.</p></li> + + <li><p>Return a <a href="#data-protocol" title="data protocol"><code title="">data:</code> URL</a> representing <var title="">file</var>. <a href="#refsRFC2397">[RFC2397]</a></p> + + <!-- should we explicitly require the URL to be base64-encoded and + not have any parameters, to ensure the same exact URL is generated + in each browser? --> + + </li></ol><p>The <dfn id="dom-canvas-toblob" title="dom-canvas-toBlob"><code>toBlob()</code></dfn> method + must run the following steps:</p> + + <ol><li><p>Let <var title="">callback</var> be the first + argument.</p></li> + + <li><p>Let <var title="">arguments</var> be the second and + subsequent arguments to the method, if any.</p></li> + + <li><p>Let <var title="">file</var> be <a href="#a-serialization-of-the-image-as-a-file">a serialization of the + image as a file</a>, using <var title="">arguments</var>.</p></li> + + <li><p>Return, but continue running these steps + asynchronously.</p></li> + + <li><p>If <var title="">callback</var> is null, abort these + steps.</p></li> + + <li><p><a href="#queue-a-task">Queue a task</a> to invoke the + <code>FileCallback</code> <var title="">callback</var> with a + <code><a href="#blob">Blob</a></code> object representing <var title="">file</var> as + its argument. The <a href="#task-source">task source</a> for this task is the + <dfn id="canvas-blob-serialization-task-source">canvas blob serialization task source</dfn>. <a href="#refsFILESYSTEMAPI">[FILESYSTEMAPI]</a> <a href="#refsFILEAPI">[FILEAPI]</a> </p></li> + + </ol><p>When a user agent is to create <dfn id="a-serialization-of-the-image-as-a-file">a serialization of the image + as a file</dfn>, optionally with some given <var title="">arguments</var>, it must create an image file in the format + given by the first value of <var title="">arguments</var>, or, if + there are no <var title="">arguments</var>, in the PNG format. <a href="#refsPNG">[PNG]</a></p> + + <p>If <var title="">arguments</var> is not empty, the first value + must be interpreted as a <a href="#mime-type" title="MIME type">MIME type</a> + giving the format to use. If the type has any parameters, it must be + treated as not supported.</p> + + <p class="example">For example, the value "<code>image/png</code>" would + mean to generate a PNG image, the value "<code>image/jpeg</code>" + would mean to generate a JPEG image, and the value + "<code>image/svg+xml</code>" would mean to generate an SVG image + (which would probably require that the implementation actually keep + enough information to reliably render an SVG image from the canvas).</p> + + <p>User agents must support PNG ("<code>image/png</code>"). User + agents may support other types. If the user agent does not support + the requested type, it must create the file using the PNG format. <a href="#refsPNG">[PNG]</a></p> + + <p>User agents must <a href="#converted-to-ascii-lowercase" title="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 canvas image composited onto a solid + black background using the source-over operator.</p> + + <p>If the first argument in <var title="">arguments</var> gives a + type corresponding to one of the types given in the first column of + the following table, and the user agent supports that type, then the + subsequent arguments, if any, must be treated as described in the + second cell of that row.</p> + + </div> + + <table><thead><tr><th> Type </th><th> Other arguments </th><th> Reference + </th></tr></thead><tbody><tr><td> <code>image/jpeg</code> + </td><td> The second argument<span class="impl">, if it</span> is a + number in the range 0.0 to 1.0 inclusive<span class="impl">, must + be</span> treated as the desired quality level. <span class="impl">If it is not a number or is outside that range, the + user agent must use its default value, as if the argument had + been omitted.</span> + </td><td> <a href="#refsJPEG">[JPEG]</a> + </td></tr></tbody></table><div class="impl"> + + <p>For the purposes of these rules, an argument is considered to be + a number if it is converted to an IDL double value by the rules for + handling arguments of type <code title="">any</code> in the Web IDL + specification. <a href="#refsWEBIDL">[WEBIDL]</a></p> + + <p>Other arguments must be ignored and must not cause the user agent + to raise an exception. A future version of this specification will + probably define other parameters to be passed to these methods to + allow authors to more carefully control compression settings, image + metadata, etc.</p> + + </div> + + <!--2DCONTEXT--> + + <div data-component="HTML Canvas 2D Context (editor: Ian Hickson)"> + + <h5 id="2dcontext"><span class="secno">4.8.11.1 </span>The 2D context</h5> + + <!-- v2: we're on v4.1. suggestions for next version are marked v5, v6. --> + + + + <p>This specification defines the <dfn id="canvas-context-2d" title="canvas-context-2d"><code>2d</code></dfn> context type, whose + API is implemented using the <code><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> + interface.</p> + + <div class="impl"> + + <p>When the <code title="dom-canvas-getContext"><a href="#dom-canvas-getcontext">getContext()</a></code> + method of a <code><a href="#the-canvas-element">canvas</a></code> element is to <a href="#getcontext-return" title="getContext-return">return a new object for the <var title="">contextId</var></a> <code title="canvas-context-2d"><a href="#canvas-context-2d">2d</a></code>, the user agent must return a + new <code><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object. Any additional + arguments are ignored.</p> + + </div> + + <p>The 2D context represents a flat Cartesian surface whose origin + (0,0) is at the top left corner, with the coordinate space having + <var title="">x</var> values increasing when going right, and <var title="">y</var> values increasing when going down.</p> + + <pre class="idl">interface <dfn id="canvasrenderingcontext2d">CanvasRenderingContext2D</dfn> { + + // back-reference to the canvas + readonly attribute <a href="#htmlcanvaselement">HTMLCanvasElement</a> <a href="#dom-context-2d-canvas" title="dom-context-2d-canvas">canvas</a>; + + // state + void <a href="#dom-context-2d-save" title="dom-context-2d-save">save</a>(); // push state on state stack + void <a href="#dom-context-2d-restore" title="dom-context-2d-restore">restore</a>(); // pop state stack and restore state +<!-- + // v6 we've also received requests for: + attribute boolean <span title="dom-context-2d-forceHighQuality">forceHighQuality</span> // (default false) + // when enabled, it would prevent the UA from falling back on lower-quality but faster rendering routines + // useful e.g. for when an image manipulation app uses <canvas> both for UI previews and the actual work +--> + // transformations (default transform is the identity matrix) + void <a href="#dom-context-2d-scale" title="dom-context-2d-scale">scale</a>(in double x, in double y); + void <a href="#dom-context-2d-rotate" title="dom-context-2d-rotate">rotate</a>(in double angle); + void <a href="#dom-context-2d-translate" title="dom-context-2d-translate">translate</a>(in double x, in double y); + void <a href="#dom-context-2d-transform" title="dom-context-2d-transform">transform</a>(in double a, in double b, in double c, in double d, in double e, in double f); + void <a href="#dom-context-2d-settransform" title="dom-context-2d-setTransform">setTransform</a>(in double a, in double b, in double c, in double d, in double e, in double f); +<!-- + // v6 we've also received requests for: + void skew(...); + void reflect(...); // or mirror(...) +--> + // compositing + attribute double <a href="#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">globalAlpha</a>; // (default 1.0) + attribute DOMString <a href="#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">globalCompositeOperation</a>; // (default source-over) +<!-- + // v6 we've also received requests for: + - turning off antialiasing to avoid seams when patterns are painted next to each other + - might be better to overdraw? + - might be better to just draw at a higher res then downsample, like for 3d? + - nested layers + - the ability to composite an entire set of drawing operations with one shadow all at once + http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2008-August/015567.html +--> + // colors and styles + attribute any <a href="#dom-context-2d-strokestyle" title="dom-context-2d-strokeStyle">strokeStyle</a>; // (default black) + attribute any <a href="#dom-context-2d-fillstyle" title="dom-context-2d-fillStyle">fillStyle</a>; // (default black) + <a href="#canvasgradient">CanvasGradient</a> <a href="#dom-context-2d-createlineargradient" title="dom-context-2d-createLinearGradient">createLinearGradient</a>(in double x0, in double y0, in double x1, in double y1); + <a href="#canvasgradient">CanvasGradient</a> <a href="#dom-context-2d-createradialgradient" title="dom-context-2d-createRadialGradient">createRadialGradient</a>(in double x0, in double y0, in double r0, in double x1, in double y1, in double r1); + <a href="#canvaspattern">CanvasPattern</a> <a href="#dom-context-2d-createpattern" title="dom-context-2d-createPattern">createPattern</a>(in <a href="#htmlimageelement">HTMLImageElement</a> image, in DOMString repetition); + <a href="#canvaspattern">CanvasPattern</a> <a href="#dom-context-2d-createpattern" title="dom-context-2d-createPattern">createPattern</a>(in <a href="#htmlcanvaselement">HTMLCanvasElement</a> image, in DOMString repetition); + <a href="#canvaspattern">CanvasPattern</a> <a href="#dom-context-2d-createpattern" title="dom-context-2d-createPattern">createPattern</a>(in <a href="#htmlvideoelement">HTMLVideoElement</a> image, in DOMString repetition); + + // line caps/joins + attribute double <a href="#dom-context-2d-linewidth" title="dom-context-2d-lineWidth">lineWidth</a>; // (default 1) + attribute DOMString <a href="#dom-context-2d-linecap" title="dom-context-2d-lineCap">lineCap</a>; // "butt", "round", "square" (default "butt") + attribute DOMString <a href="#dom-context-2d-linejoin" title="dom-context-2d-lineJoin">lineJoin</a>; // "round", "bevel", "miter" (default "miter") + attribute double <a href="#dom-context-2d-miterlimit" title="dom-context-2d-miterLimit">miterLimit</a>; // (default 10) + + // shadows + attribute double <a href="#dom-context-2d-shadowoffsetx" title="dom-context-2d-shadowOffsetX">shadowOffsetX</a>; // (default 0) + attribute double <a href="#dom-context-2d-shadowoffsety" title="dom-context-2d-shadowOffsetY">shadowOffsetY</a>; // (default 0) + attribute double <a href="#dom-context-2d-shadowblur" title="dom-context-2d-shadowBlur">shadowBlur</a>; // (default 0) + attribute DOMString <a href="#dom-context-2d-shadowcolor" title="dom-context-2d-shadowColor">shadowColor</a>; // (default transparent black) + + // rects + void <a href="#dom-context-2d-clearrect" title="dom-context-2d-clearRect">clearRect</a>(in double x, in double y, in double w, in double h); + void <a href="#dom-context-2d-fillrect" title="dom-context-2d-fillRect">fillRect</a>(in double x, in double y, in double w, in double h); + void <a href="#dom-context-2d-strokerect" title="dom-context-2d-strokeRect">strokeRect</a>(in double x, in double y, in double w, in double h); + + // path API + void <a href="#dom-context-2d-beginpath" title="dom-context-2d-beginPath">beginPath</a>(); + void <a href="#dom-context-2d-closepath" title="dom-context-2d-closePath">closePath</a>(); + void <a href="#dom-context-2d-moveto" title="dom-context-2d-moveTo">moveTo</a>(in double x, in double y); + void <a href="#dom-context-2d-lineto" title="dom-context-2d-lineTo">lineTo</a>(in double x, in double y); + void <a href="#dom-context-2d-quadraticcurveto" title="dom-context-2d-quadraticCurveTo">quadraticCurveTo</a>(in double cpx, in double cpy, in double x, in double y); + void <a href="#dom-context-2d-beziercurveto" title="dom-context-2d-bezierCurveTo">bezierCurveTo</a>(in double cp1x, in double cp1y, in double cp2x, in double cp2y, in double x, in double y); + void <a href="#dom-context-2d-arcto" title="dom-context-2d-arcTo">arcTo</a>(in double x1, in double y1, in double x2, in double y2, in double radius); + void <a href="#dom-context-2d-rect" title="dom-context-2d-rect">rect</a>(in double x, in double y, in double w, in double h); + void <a href="#dom-context-2d-arc" title="dom-context-2d-arc">arc</a>(in double x, in double y, in double radius, in double startAngle, in double endAngle, in optional boolean anticlockwise); + void <a href="#dom-context-2d-fill" title="dom-context-2d-fill">fill</a>(); + void <a href="#dom-context-2d-stroke" title="dom-context-2d-stroke">stroke</a>(); + void <a href="#dom-context-2d-drawsystemfocusring" title="dom-context-2d-drawSystemFocusRing">drawSystemFocusRing</a>(in <a href="#element">Element</a> element); + boolean <a href="#dom-context-2d-drawcustomfocusring" title="dom-context-2d-drawCustomFocusRing">drawCustomFocusRing</a>(in <a href="#element">Element</a> element); + void <a href="#dom-context-2d-scrollpathintoview" title="dom-context-2d-scrollPathIntoView">scrollPathIntoView</a>(); + void <a href="#dom-context-2d-clip" title="dom-context-2d-clip">clip</a>(); + boolean <a href="#dom-context-2d-ispointinpath" title="dom-context-2d-isPointInPath">isPointInPath</a>(in double x, in double y); + + // text + attribute DOMString <a href="#dom-context-2d-font" title="dom-context-2d-font">font</a>; // (default 10px sans-serif) + attribute DOMString <a href="#dom-context-2d-textalign" title="dom-context-2d-textAlign">textAlign</a>; // "start", "end", "left", "right", "center" (default: "start") + attribute DOMString <a href="#dom-context-2d-textbaseline" title="dom-context-2d-textBaseline">textBaseline</a>; // "top", "hanging", "middle", "alphabetic", "ideographic", "bottom" (default: "alphabetic") + void <a href="#dom-context-2d-filltext" title="dom-context-2d-fillText">fillText</a>(in DOMString text, in double x, in double y, in optional double maxWidth); + void <a href="#dom-context-2d-stroketext" title="dom-context-2d-strokeText">strokeText</a>(in DOMString text, in double x, in double y, in optional double maxWidth);<!-- v6DVT + void <span title="dom-context-2d-fillVerticalText">fillVerticalText</span>(in DOMString text, in double x, in double y, in optional double maxHeight); + void <span title="dom-context-2d-strokeVerticalText">strokeVerticalText</span>(in DOMString text, in double x, in double y, in optional double maxHeight); --> + <a href="#textmetrics">TextMetrics</a> <a href="#dom-context-2d-measuretext" title="dom-context-2d-measureText">measureText</a>(in DOMString text); + + // drawing images + void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(in <a href="#htmlimageelement">HTMLImageElement</a> image, in double dx, in double dy); + void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(in <a href="#htmlimageelement">HTMLImageElement</a> image, in double dx, in double dy, in double dw, in double dh); + void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(in <a href="#htmlimageelement">HTMLImageElement</a> image, in double sx, in double sy, in double sw, in double sh, in double dx, in double dy, in double dw, in double dh); + void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(in <a href="#htmlcanvaselement">HTMLCanvasElement</a> image, in double dx, in double dy); + void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(in <a href="#htmlcanvaselement">HTMLCanvasElement</a> image, in double dx, in double dy, in double dw, in double dh); + void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(in <a href="#htmlcanvaselement">HTMLCanvasElement</a> image, in double sx, in double sy, in double sw, in double sh, in double dx, in double dy, in double dw, in double dh); + void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(in <a href="#htmlvideoelement">HTMLVideoElement</a> image, in double dx, in double dy); + void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(in <a href="#htmlvideoelement">HTMLVideoElement</a> image, in double dx, in double dy, in double dw, in double dh); + void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(in <a href="#htmlvideoelement">HTMLVideoElement</a> image, in double sx, in double sy, in double sw, in double sh, in double dx, in double dy, in double dw, in double dh); + + // pixel manipulation + <a href="#imagedata">ImageData</a> <a href="#dom-context-2d-createimagedata" title="dom-context-2d-createImageData">createImageData</a>(in double sw, in double sh); + <a href="#imagedata">ImageData</a> <a href="#dom-context-2d-createimagedata" title="dom-context-2d-createImageData">createImageData</a>(in <a href="#imagedata">ImageData</a> imagedata); + <a href="#imagedata">ImageData</a> <a href="#dom-context-2d-getimagedata" title="dom-context-2d-getImageData">getImageData</a>(in double sx, in double sy, in double sw, in double sh); + void <a href="#dom-context-2d-putimagedata" title="dom-context-2d-putImageData">putImageData</a>(in <a href="#imagedata">ImageData</a> imagedata, in double dx, in double dy); + void <a href="#dom-context-2d-putimagedata" title="dom-context-2d-putImageData">putImageData</a>(in <a href="#imagedata">ImageData</a> imagedata, in double dx, in double dy, in double dirtyX, in double dirtyY, in double dirtyWidth, in double dirtyHeight); +}; + +interface <dfn id="canvasgradient">CanvasGradient</dfn> { + // opaque object + void <a href="#dom-canvasgradient-addcolorstop" title="dom-canvasgradient-addColorStop">addColorStop</a>(in double offset, in DOMString color); +}; + +interface <dfn id="canvaspattern">CanvasPattern</dfn> { + // opaque object +}; + +interface <dfn id="textmetrics">TextMetrics</dfn> { + readonly attribute double <a href="#dom-textmetrics-width" title="dom-textmetrics-width">width</a>; +}; + +interface <dfn id="imagedata">ImageData</dfn> { + readonly attribute unsigned long <a href="#dom-imagedata-width" title="dom-imagedata-width">width</a>; + readonly attribute unsigned long <a href="#dom-imagedata-height" title="dom-imagedata-height">height</a>; + readonly attribute <a href="#canvaspixelarray">CanvasPixelArray</a> <a href="#dom-imagedata-data" title="dom-imagedata-data">data</a>; +}; + +interface <dfn id="canvaspixelarray">CanvasPixelArray</dfn> { + readonly attribute unsigned long <a href="#dom-canvaspixelarray-length" title="dom-canvaspixelarray-length">length</a>; + <a href="#dom-canvaspixelarray-get" title="dom-CanvasPixelArray-get">getter</a> octet (in unsigned long index); + <a href="#dom-canvaspixelarray-set" title="dom-CanvasPixelArray-set">setter</a> void (in unsigned long index, [Clamp] in octet value); +};</pre> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-canvas"><a href="#dom-context-2d-canvas">canvas</a></code></dt> + + <dd> + + <p>Returns the <code><a href="#the-canvas-element">canvas</a></code> element.</p> + + </dd> + + </dl><div class="impl"> + + <p>The <dfn id="dom-context-2d-canvas" title="dom-context-2d-canvas"><code>canvas</code></dfn> + attribute must return the <code><a href="#the-canvas-element">canvas</a></code> element that the + context paints on.</p> + + <p>Except where otherwise specified, for the 2D context interface, + any method call with a numeric argument whose value is infinite or a + NaN value must be ignored.</p> + + <!-- + Philip Taylor wrote: + > My experience with some 3d canvas code is that infinities come up in + > naturally harmless places, e.g. having a function that scales by x then + > translates by 1/x and wanting it to work when x=0 (which ought to draw + > nothing, since anything it draws is zero pixels wide), and it's a bit + > annoying to track down and fix those issues, so I'd probably like it if + > they were harmless in canvas methods. Opera appears to silently not draw + > anything if the transformation matrix is not finite, but Firefox throws + > exceptions when passing in non-finite arguments. + --> + + <p>Whenever the CSS value <code title="">currentColor</code> is used + as a color in this API, the "computed value of the 'color' property" + for the purposes of determining the computed value of the <code title="">currentColor</code> keyword is the computed value of the + 'color' property on the element in question 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 'color' property is + undefined for a particular case (e.g. because the element is not + <a href="#in-a-document">in a <code>Document</code></a>), then the "computed value + of the 'color' property" for the purposes of determining the + computed value of the <code title="">currentColor</code> keyword is + fully opaque black. <a href="#refsCSSCOLOR">[CSSCOLOR]</a></p> + + <p>In the case of <code title="dom-canvasgradient-addColorStop"><a href="#dom-canvasgradient-addcolorstop">addColorStop()</a></code> on + <code><a href="#canvasgradient">CanvasGradient</a></code>, the "computed value of the 'color' + property" for the purposes of determining the computed value of the + <code title="">currentColor</code> keyword is always fully opaque + black (there is no associated element). <a href="#refsCSSCOLOR">[CSSCOLOR]</a></p> + + <p class="note">This is because <code><a href="#canvasgradient">CanvasGradient</a></code> objects + are <code><a href="#the-canvas-element">canvas</a></code>-neutral — a + <code><a href="#canvasgradient">CanvasGradient</a></code> object created by one + <code><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> + + </div> + + + + <h6 id="the-canvas-state"><span class="secno">4.8.11.1.1 </span>The canvas state</h6> + + <p>Each context maintains a stack of drawing states. <dfn id="drawing-state" title="drawing state">Drawing states</dfn> consist of:</p> + + <ul class="brief"><li>The current <a href="#transformations" title="dom-context-2d-transformation">transformation matrix</a>.</li> + <li>The current <a href="#clipping-region">clipping region</a>.</li> + <li>The current values of the following attributes: <code title="dom-context-2d-strokeStyle"><a href="#dom-context-2d-strokestyle">strokeStyle</a></code>, <code title="dom-context-2d-fillStyle"><a href="#dom-context-2d-fillstyle">fillStyle</a></code>, <code title="dom-context-2d-globalAlpha"><a href="#dom-context-2d-globalalpha">globalAlpha</a></code>, <code title="dom-context-2d-lineWidth"><a href="#dom-context-2d-linewidth">lineWidth</a></code>, <code title="dom-context-2d-lineCap"><a href="#dom-context-2d-linecap">lineCap</a></code>, <code title="dom-context-2d-lineJoin"><a href="#dom-context-2d-linejoin">lineJoin</a></code>, <code title="dom-context-2d-miterLimit"><a href="#dom-context-2d-miterlimit">miterLimit</a></code>, <code title="dom-context-2d-shadowOffsetX"><a href="#dom-context-2d-shadowoffsetx">shadowOffsetX</a></code>, <code title="dom-context-2d-shadowOffsetY"><a href="#dom-context-2d-shadowoffsety">shadowOffsetY</a></code>, <code title="dom-context-2d-shadowBlur"><a href="#dom-context-2d-shadowblur">shadowBlur</a></code>, <code title="dom-context-2d-shadowColor"><a href="#dom-context-2d-shadowcolor">shadowColor</a></code>, <code title="dom-context-2d-globalCompositeOperation"><a href="#dom-context-2d-globalcompositeoperation">globalCompositeOperation</a></code>, <code title="dom-context-2d-font"><a href="#dom-context-2d-font">font</a></code>, <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code>, <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code>.</li> + </ul><p class="note">The current path and the current bitmap are not part + of the drawing state. The current path is persistent, and can only + be reset using the <code title="dom-context-2d-beginPath"><a href="#dom-context-2d-beginpath">beginPath()</a></code> method. The + current bitmap is a property of the canvas, not the context.</p> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-save"><a href="#dom-context-2d-save">save</a></code>()</dt> + + <dd> + + <p>Pushes the current state onto the stack.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-restore"><a href="#dom-context-2d-restore">restore</a></code>()</dt> + + <dd> + + <p>Pops the top state on the stack, restoring the context to that state.</p> + + </dd> + + </dl><div class="impl"> + + <p>The <dfn id="dom-context-2d-save" title="dom-context-2d-save"><code>save()</code></dfn> + method must push a copy of the current drawing state onto the + drawing state stack.</p> + + <p>The <dfn id="dom-context-2d-restore" title="dom-context-2d-restore"><code>restore()</code></dfn> method + must pop the top entry in the drawing state stack, and reset the + drawing state it describes. If there is no saved state, the method + must do nothing.</p> + + <!-- v6 +idea from Mihai: +> 5. Drawing states should be saveable with IDs, and for easier restoring. +> +> save(id) +> restore(id) +> +> If id is not provided, then save() works as defined now. The same for +> restore(). +> +> Currently, it's not trivial to save and restore a specific state. +...and from Philip: +> I think a more convenient syntax would be: +> var state = ctx.save(); +> ctx.restore(state); +> But how would it interact with normal calls to ctx.restore()? + --> + + </div> + + + <h6 id="transformations"><span class="secno">4.8.11.1.2 </span><dfn title="dom-context-2d-transformation">Transformations</dfn></h6> + + <p>The transformation matrix is applied to coordinates when creating + shapes and paths.</p> <!-- conformance criteria for actual drawing + are described in the various sections below --> + + <div class="impl"> + + <p>When the context is created, the transformation matrix must + initially be the identity transform. It may then be adjusted using + the transformation methods.</p> + + <p>The transformations must be performed in reverse order. For + instance, if a scale transformation that doubles the width is + applied, 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> + + </div> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-scale"><a href="#dom-context-2d-scale">scale</a></code>(<var title="">x</var>, <var title="">y</var>)</dt> + + <dd> + + <p>Changes the transformation matrix to apply a scaling transformation with the given characteristics.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-rotate"><a href="#dom-context-2d-rotate">rotate</a></code>(<var title="">angle</var>)</dt> + + <dd> + + <p>Changes the transformation matrix to apply a rotation transformation with the given characteristics. The angle is in radians.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-translate"><a href="#dom-context-2d-translate">translate</a></code>(<var title="">x</var>, <var title="">y</var>)</dt> + + <dd> + + <p>Changes the transformation matrix to apply a translation transformation with the given characteristics.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-transform"><a href="#dom-context-2d-transform">transform</a></code>(<var title="">a</var>, <var title="">b</var>, <var title="">c</var>, <var title="">d</var>, <var title="">e</var>, <var title="">f</var>)</dt> + + <dd> + + <p>Changes the transformation matrix to apply the matrix given by the arguments as described below.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-setTransform"><a href="#dom-context-2d-settransform">setTransform</a></code>(<var title="">a</var>, <var title="">b</var>, <var title="">c</var>, <var title="">d</var>, <var title="">e</var>, <var title="">f</var>)</dt> + + <dd> + + <p>Changes the transformation matrix <em>to</em> the matrix given by the arguments as described below.</p> + + </dd> + + </dl><div class="impl"> + + <p>The <dfn id="dom-context-2d-scale" title="dom-context-2d-scale"><code>scale(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must + add the scaling transformation described by the arguments to the + transformation matrix. The <var title="">x</var> argument represents + the scale factor in the horizontal direction and the <var title="">y</var> argument represents the scale factor in the + vertical direction. The factors are multiples.</p> + + <p>The <dfn id="dom-context-2d-rotate" title="dom-context-2d-rotate"><code>rotate(<var title="">angle</var>)</code></dfn> method must add the rotation + transformation described by the argument to the transformation + matrix. The <var title="">angle</var> argument represents a + clockwise rotation angle expressed in radians.</p> + + <p>The <dfn id="dom-context-2d-translate" title="dom-context-2d-translate"><code>translate(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must + add the translation transformation described by the arguments to the + transformation matrix. The <var title="">x</var> argument represents + the translation distance in the horizontal direction and the <var title="">y</var> argument represents the translation distance in the + vertical direction. The arguments are in coordinate space units.</p> + + <p>The <dfn id="dom-context-2d-transform" title="dom-context-2d-transform"><code>transform(<var title="">a</var>, <var title="">b</var>, <var title="">c</var>, <var title="">d</var>, <var title="">e</var>, <var title="">f</var>)</code></dfn> method must replace the current + transformation matrix with the result of multiplying the current + transformation matrix with the matrix described by:</p> + + </div> + + <table class="matrix"><tbody><tr><td><var title="">a</var></td> + <td><var title="">c</var></td> + <td><var title="">e</var></td> + </tr><tr><td><var title="">b</var></td> + <td><var title="">d</var></td> + <td><var title="">f</var></td> + </tr><tr><td>0</td> + <td>0</td> + <td>1</td> + </tr></tbody></table><p class="note">The arguments <var title="">a</var>, <var title="">b</var>, <var title="">c</var>, <var title="">d</var>, <var title="">e</var>, and <var title="">f</var> are sometimes called + <var title="">m11</var>, <var title="">m12</var>, <var title="">m21</var>, <var title="">m22</var>, <var title="">dx</var>, + and <var title="">dy</var> or <var title="">m11</var>, <var title="">m21</var>, <var title="">m12</var>, <var title="">m22</var>, <var title="">dx</var>, and <var title="">dy</var>. Care should be taken in particular with the order + of the second and third arguments (<var title="">b</var> and <var title="">c</var>) as their order varies from API to API and APIs + sometimes use the notation <var title="">m12</var>/<var title="">m21</var> and sometimes <var title="">m21</var>/<var title="">m12</var> for those positions.</p> + + <div class="impl"> + + <p>The <dfn id="dom-context-2d-settransform" title="dom-context-2d-setTransform"><code>setTransform(<var title="">a</var>, <var title="">b</var>, <var title="">c</var>, <var title="">d</var>, <var title="">e</var>, + <var title="">f</var>)</code></dfn> method must reset the current + transform to the identity matrix, and then invoke the <code><a href="#dom-context-2d-transform" title="dom-context-2d-transform">transform</a>(<var title="">a</var>, <var title="">b</var>, <var title="">c</var>, <var title="">d</var>, <var title="">e</var>, + <var title="">f</var>)</code> method with the same arguments.</p> + + </div> + + + <h6 id="compositing"><span class="secno">4.8.11.1.3 </span>Compositing</h6> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-globalAlpha"><a href="#dom-context-2d-globalalpha">globalAlpha</a></code> [ = <var title="">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 title="">context</var> . <code title="dom-context-2d-globalCompositeOperation"><a href="#dom-context-2d-globalcompositeoperation">globalCompositeOperation</a></code> [ = <var title="">value</var> ]</dt> + + <dd> + + <p>Returns the current composition operation, from the list below.</p> + + <p>Can be set, to change the composition operation. Unknown values + are ignored.</p> + + </dd> + + </dl><div class="impl"> + + <p>All drawing operations are affected by the global compositing + attributes, <code title="dom-context-2d-globalAlpha"><a href="#dom-context-2d-globalalpha">globalAlpha</a></code> and <code title="dom-context-2d-globalCompositeOperation"><a href="#dom-context-2d-globalcompositeoperation">globalCompositeOperation</a></code>.</p> + + <!-- conformance criteria for painting are described in the "drawing + model" section below --> + + <p>The <dfn id="dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha"><code>globalAlpha</code></dfn> + attribute gives an alpha value that is applied to shapes and images + before they are composited onto the canvas. 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, the attribute must retain its previous value. When the + context is created, the <code title="dom-context-2d-globalAlpha"><a href="#dom-context-2d-globalalpha">globalAlpha</a></code> attribute must + initially have the value 1.0.</p> + + <p>The <dfn id="dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation"><code>globalCompositeOperation</code></dfn> + attribute sets how shapes and images are drawn onto the existing + bitmap, once they have had <code title="dom-context-2d-globalAlpha"><a href="#dom-context-2d-globalalpha">globalAlpha</a></code> and the + current transformation matrix applied. It must be set to a value + from the following list. In the descriptions below, the source + image, <var title="">A</var>, is the shape or image being rendered, + and the destination image, <var title="">B</var>, is the current + state of the bitmap.</p> + + </div> + + <dl><dt><dfn id="gcop-source-atop" title="gcop-source-atop"><code>source-atop</code></dfn></dt> + + <dd><var title="">A</var> atop <var title="">B</var>. <span class="note">Display the + source image wherever both images are opaque. Display the + destination image wherever the destination image is opaque but the + source image is transparent. Display transparency elsewhere.</span></dd> + + <dt><dfn id="gcop-source-in" title="gcop-source-in"><code>source-in</code></dfn></dt> + + <dd><var title="">A</var> in <var title="">B</var>. <span class="note">Display the + source image wherever both the source image and destination image + are opaque. Display transparency elsewhere.</span></dd> + + <dt><dfn id="gcop-source-out" title="gcop-source-out"><code>source-out</code></dfn></dt> + + <dd><var title="">A</var> out <var title="">B</var>. <span class="note">Display the + source image wherever the source image is opaque and the + destination image is transparent. Display transparency + elsewhere.</span></dd> + + <dt><dfn id="gcop-source-over" title="gcop-source-over"><code>source-over</code></dfn> (default)</dt> + + <dd><var title="">A</var> over <var title="">B</var>. <span class="note">Display the + source image wherever the source image is opaque. Display the + destination image elsewhere.</span></dd> + + + <dt><dfn id="gcop-destination-atop" title="gcop-destination-atop"><code>destination-atop</code></dfn></dt> + + <dd><var title="">B</var> atop <var title="">A</var>. <span class="note">Same as <code title="gcop-source-atop"><a href="#gcop-source-atop">source-atop</a></code> but using the + destination image instead of the source image and vice versa.</span></dd> + + <dt><dfn id="gcop-destination-in" title="gcop-destination-in"><code>destination-in</code></dfn></dt> + + <dd><var title="">B</var> in <var title="">A</var>. <span class="note">Same as <code title="gcop-source-in"><a href="#gcop-source-in">source-in</a></code> but using the destination + image instead of the source image and vice versa.</span></dd> + + <dt><dfn id="gcop-destination-out" title="gcop-destination-out"><code>destination-out</code></dfn></dt> + + <dd><var title="">B</var> out <var title="">A</var>. <span class="note">Same as <code title="gcop-source-out"><a href="#gcop-source-out">source-out</a></code> but using the destination + image instead of the source image and vice versa.</span></dd> + + <dt><dfn id="gcop-destination-over" title="gcop-destination-over"><code>destination-over</code></dfn></dt> + + <dd><var title="">B</var> over <var title="">A</var>. <span class="note">Same as <code title="gcop-source-over"><a href="#gcop-source-over">source-over</a></code> but using the + destination image instead of the source image and vice versa.</span></dd> + + +<!-- no clear definition of this operator (doesn't correspond to a PorterDuff operator) + <dt><dfn title="gcop-darker"><code>darker</code></dfn></dt> + + <dd><span class="note">Display the sum of the source image and destination image, + with color values approaching 0 as a limit.</span></dd> +--> + + <dt><dfn id="gcop-lighter" title="gcop-lighter"><code>lighter</code></dfn></dt> + + <dd><var title="">A</var> plus <var title="">B</var>. <span class="note">Display the + sum of the source image and destination image, with color values + approaching 255 (100%) as a limit.</span></dd> + + + <dt><dfn id="gcop-copy" title="gcop-copy"><code>copy</code></dfn></dt> + + <dd><var title="">A</var> (<var title="">B</var> is + ignored). <span class="note">Display the source image instead of the destination + image.</span></dd> + + + <dt><dfn id="gcop-xor" title="gcop-xor"><code>xor</code></dfn></dt> + + <dd><var title="">A</var> xor <var title="">B</var>. <span class="note">Exclusive OR + of the source image and destination image.</span></dd> + + + <dt class="impl"><code><var title="">vendorName</var>-<var title="">operationName</var></code></dt> + + <dd class="impl">Vendor-specific extensions to the list of + composition operators should use this syntax.</dd> + + </dl><div class="impl"> + + <p>The operators in the above list must be treated as described by + the Porter-Duff operator given at the start of their description + (e.g. <var title="">A</var> over <var title="">B</var>). They are to + be applied as part of the <a href="#drawing-model">drawing model</a>, at which point the + <a href="#clipping-region">clipping region</a> is also applied. (Without a clipping + region, these operators act on the whole bitmap with every + operation.) <a href="#refsPORTERDUFF">[PORTERDUFF]</a></p> + + <p>These values are all case-sensitive — they must be used + exactly as shown. User agents must not recognize values that are not + a <a href="#case-sensitive">case-sensitive</a> match for one of the values given + above.</p> + + <p>On setting, if the user agent does not recognize the specified + value, it must be ignored, leaving the value of <code title="dom-context-2d-globalCompositeOperation"><a href="#dom-context-2d-globalcompositeoperation">globalCompositeOperation</a></code> + unaffected.</p> + + <p>When the context is created, the <code title="dom-context-2d-globalCompositeOperation"><a href="#dom-context-2d-globalcompositeoperation">globalCompositeOperation</a></code> + attribute must initially have the value + <code>source-over</code>.</p> + + </div> + + + <h6 id="colors-and-styles"><span class="secno">4.8.11.1.4 </span>Colors and styles</h6> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-strokeStyle"><a href="#dom-context-2d-strokestyle">strokeStyle</a></code> [ = <var title="">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><a href="#canvasgradient">CanvasGradient</a></code> or <code><a href="#canvaspattern">CanvasPattern</a></code> + object. Invalid values are ignored.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-fillStyle"><a href="#dom-context-2d-fillstyle">fillStyle</a></code> [ = <var title="">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><a href="#canvasgradient">CanvasGradient</a></code> or <code><a href="#canvaspattern">CanvasPattern</a></code> + object. Invalid values are ignored.</p> + + </dd> + + </dl><div class="impl"> + + <!-- v6 feature requests: + + * Getting and setting colours by component to bypass the CSS value parsing. + + Either: + context.fillStyle.red += 1; + + Or: + var array = context.fillStyle; + array[1] += 1; + context.fillStyle = array; + + * A more performant way of setting colours in general, e.g.: + + context.setFillColor(r,g,b,a) // already supported by webkit + + Or: + + context.fillStyle = 0xRRGGBBAA; // set a 32bit int directly + + * fill rule for deciding between winding and even-odd algorithms. + SVG has fill-rule: nonzero | evenodd + http://www.w3.org/TR/SVG/painting.html#FillProperties + + --> + + <p>The <dfn id="dom-context-2d-strokestyle" title="dom-context-2d-strokeStyle"><code>strokeStyle</code></dfn> + attribute represents the color or style to use for the lines around + shapes, and the <dfn id="dom-context-2d-fillstyle" title="dom-context-2d-fillStyle"><code>fillStyle</code></dfn> + attribute represents the color or style to use inside the + shapes.</p> + + <p>Both attributes can be either strings, + <code><a href="#canvasgradient">CanvasGradient</a></code>s, or <code><a href="#canvaspattern">CanvasPattern</a></code>s. On + setting, strings must be <a href="#parsed-as-a-css-color-value" title="parsed as a CSS <color> + value">parsed as CSS <color> values</a> and the color + assigned, and <code><a href="#canvasgradient">CanvasGradient</a></code> and + <code><a href="#canvaspattern">CanvasPattern</a></code> objects must be assigned themselves. <a href="#refsCSSCOLOR">[CSSCOLOR]</a> If the value is a string but + cannot be <a href="#parsed-as-a-css-color-value">parsed as a CSS <color> value</a>, or is + neither a string, a <code><a href="#canvasgradient">CanvasGradient</a></code>, nor a + <code><a href="#canvaspattern">CanvasPattern</a></code>, then it must be ignored, and the + attribute must retain its previous value.</p> + + <p>When set to a <code><a href="#canvaspattern">CanvasPattern</a></code> or + <code><a href="#canvasgradient">CanvasGradient</a></code> object, the assignment is + <a href="#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="#serialization-of-a-color" title="serialization of a color">serialization of the color</a> + must be returned. Otherwise, if it is not a color but a + <code><a href="#canvasgradient">CanvasGradient</a></code> or <code><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="serialization-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 in the range 0-9 a-f (U+0030 to U+0039 + and U+0061 to U+0066). Otherwise, the color value has alpha less + than 1.0, and the string is the color value in the CSS <code title="">rgba()</code> functional-notation format: the literal + string <code title="">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 digits 0-9, U+0030 + to U+0039, 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 digits in the range 0-9 + (U+0030 to U+0039) representing the fractional part of the alpha + value, and finally a U+0029 RIGHT PARENTHESIS.</p> <!-- if people + complain this is unreadable, expand it into a <dl> with two nested + <ol>s --> + + <p>When the context is created, the <code title="dom-context-2d-strokeStyle"><a href="#dom-context-2d-strokestyle">strokeStyle</a></code> and <code title="dom-context-2d-fillStyle"><a href="#dom-context-2d-fillstyle">fillStyle</a></code> attributes must + initially have the string value <code title="">#000000</code>.</p> + + </div> + + <hr/><p>There are two types of gradients, linear gradients and radial + gradients, both represented by objects implementing the opaque + <code><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. <span class="impl">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.</span></p> + + <dl class="domintro"><dt><var title="">gradient</var> . <code title="dom-canvasgradient-addColorStop"><a href="#dom-canvasgradient-addcolorstop">addColorStop</a></code>(<var title="">offset</var>, <var title="">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 <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception if the offset + is out of range. Throws a <code><a href="#syntax_err">SYNTAX_ERR</a></code> exception if the + color cannot be parsed.</p> + + </dd> + + <dt><var title="">gradient</var> = <var title="">context</var> . <code title="dom-context-2d-createLinearGradient"><a href="#dom-context-2d-createlineargradient">createLinearGradient</a></code>(<var title="">x0</var>, <var title="">y0</var>, <var title="">x1</var>, <var title="">y1</var>)</dt> + + <dd> + + <p>Returns a <code><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> + + <p>If any of the arguments are not finite numbers, throws a + <code><a href="#not_supported_err">NOT_SUPPORTED_ERR</a></code> exception.</p> + + </dd> + + <dt><var title="">gradient</var> = <var title="">context</var> . <code title="dom-context-2d-createRadialGradient"><a href="#dom-context-2d-createradialgradient">createRadialGradient</a></code>(<var title="">x0</var>, <var title="">y0</var>, <var title="">r0</var>, <var title="">x1</var>, <var title="">y1</var>, <var title="">r1</var>)</dt> + + <dd> + + <p>Returns a <code><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 any of the arguments are not finite numbers, throws a + <code><a href="#not_supported_err">NOT_SUPPORTED_ERR</a></code> exception. If either of the radii + are negative, throws an <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p> + + </dd> + + </dl><div class="impl"> + + <p>The <dfn id="dom-canvasgradient-addcolorstop" title="dom-canvasgradient-addColorStop"><code>addColorStop(<var title="">offset</var>, <var title="">color</var>)</code></dfn> + method on the <code><a href="#canvasgradient">CanvasGradient</a></code> interface adds a new stop + to a gradient. If the <var title="">offset</var> is less than 0, + greater than 1, infinite, or NaN, then an + <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception must be raised. If the <var title="">color</var> cannot be <a href="#parsed-as-a-css-color-value">parsed as a CSS <color> + value</a>, then a <code><a href="#syntax_err">SYNTAX_ERR</a></code> exception must be + raised. Otherwise, the gradient must have a new stop placed, at + offset <var title="">offset</var> relative to the whole gradient, + and with the color obtained by parsing <var title="">color</var> as + a CSS <color> value. If multiple stops are added at the same + offset on a gradient, 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" title="dom-context-2d-createLinearGradient"><code>createLinearGradient(<var title="">x0</var>, <var title="">y0</var>, <var title="">x1</var>, + <var title="">y1</var>)</code></dfn> method takes four arguments + that represent the start point (<var title="">x0</var>, <var title="">y0</var>) and end point (<var title="">x1</var>, <var title="">y1</var>) of the gradient. If any of the arguments to <code title="dom-context-2d-createLinearGradient"><a href="#dom-context-2d-createlineargradient">createLinearGradient()</a></code> + are infinite or NaN, the method must raise a + <code><a href="#not_supported_err">NOT_SUPPORTED_ERR</a></code> exception. Otherwise, the method must + return a linear <code><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" title="dom-context-2d-transformation">current transformation + matrix</a> when rendering.</p> + + <p>If <span title=""><var title="">x0</var> = <var title="">x1</var></span> and <span title=""><var title="">y0</var> = <var title="">y1</var></span>, then + the linear gradient must paint nothing.</p> + + <p>The <dfn id="dom-context-2d-createradialgradient" title="dom-context-2d-createRadialGradient"><code>createRadialGradient(<var title="">x0</var>, <var title="">y0</var>, <var title="">r0</var>, + <var title="">x1</var>, <var title="">y1</var>, <var title="">r1</var>)</code></dfn> method takes six arguments, the + first three representing the start circle with origin (<var title="">x0</var>, <var title="">y0</var>) and radius <var title="">r0</var>, and the last three representing the end circle + with origin (<var title="">x1</var>, <var title="">y1</var>) and + radius <var title="">r1</var>. The values are in coordinate space + units. If any of the arguments are infinite or NaN, a + <code><a href="#not_supported_err">NOT_SUPPORTED_ERR</a></code> exception must be raised. If either + of <var title="">r0</var> or <var title="">r1</var> are negative, an + <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception must be raised. Otherwise, + the method must return a radial <code><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 <span title=""><var title="">x<sub>0</sub></var> = <var title="">x<sub>1</sub></var></span> and <span title=""><var title="">y<sub>0</sub></var> = <var title="">y<sub>1</sub></var></span> and <span title=""><var title="">r<sub>0</sub></var> = <var title="">r<sub>1</sub></var></span>, then the radial gradient must + paint nothing. Abort these steps.</p></li> + + <li> + + <p>Let <span title="">x(<var title="">ω</var>) = (<var title="">x<sub>1</sub></var>-<var title="">x<sub>0</sub></var>)<var title="">ω</var> + <var title="">x<sub>0</sub></var></span></p> + + <p>Let <span title="">y(<var title="">ω</var>) = (<var title="">y<sub>1</sub></var>-<var title="">y<sub>0</sub></var>)<var title="">ω</var> + <var title="">y<sub>0</sub></var></span></p> + + <p>Let <span title="">r(<var title="">ω</var>) = (<var title="">r<sub>1</sub></var>-<var title="">r<sub>0</sub></var>)<var title="">ω</var> + <var title="">r<sub>0</sub></var></span></p> + + <p>Let the color at <var title="">ω</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 title="">ω</var> where <span title="">r(<var title="">ω</var>) > 0</span>, + starting with the value of <var title="">ω</var> nearest to + positive infinity and ending with the value of <var title="">ω</var> nearest to negative infinity, draw the + circumference of the circle with radius <span title="">r(<var title="">ω</var>)</span> at position (<span title="">x(<var title="">ω</var>)</span>, <span title="">y(<var title="">ω</var>)</span>), with the color at <var title="">ω</var>, but only painting on the parts of the + canvas 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 points in the radial gradient must be transformed as + described by the <a href="#transformations" title="dom-context-2d-transformation">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> + +<!-- + <p>Support for actually painting gradients is optional. Instead of + painting the gradients, user agents may instead just paint the first + stop's color. However, <code + title="dom-context-2d-createLinearGradient">createLinearGradient()</code> + and <code + title="dom-context-2d-createRadialGradient">createRadialGradient()</code> + must always return objects when passed valid arguments.</p> +--> + + </div> + + <hr/><p>Patterns are represented by objects implementing the opaque + <code><a href="#canvaspattern">CanvasPattern</a></code> interface.</p> + + <dl class="domintro"><dt><var title="">pattern</var> = <var title="">context</var> . <code title="dom-context-2d-createPattern"><a href="#dom-context-2d-createpattern">createPattern</a></code>(<var title="">image</var>, <var title="">repetition</var>)</dt> + + <dd> + + <p>Returns a <code><a href="#canvaspattern">CanvasPattern</a></code> object that uses the given image + and repeats in the direction(s) given by the <var title="">repetition</var> argument.</p> + + <p>The allowed values for <var title="">repetition</var> are <code title="">repeat</code> (both directions), <code title="">repeat-x</code> (horizontal only), <code title="">repeat-y</code> (vertical only), and <code title="">no-repeat</code> (neither). If the <var title="">repetition</var> argument is empty, the value <code title="">repeat</code> is used.</p> + + <p>If the image has no image data, throws an + <code><a href="#invalid_state_err">INVALID_STATE_ERR</a></code> exception. If the second argument + isn't one of the allowed values, throws a <code><a href="#syntax_err">SYNTAX_ERR</a></code> + exception. If the image isn't yet fully decoded, then the method + returns null.</p> + + </dd> + + </dl><div class="impl"> + + <p>To create objects of this type, the <dfn id="dom-context-2d-createpattern" title="dom-context-2d-createPattern"><code>createPattern(<var title="">image</var>, <var title="">repetition</var>)</code></dfn> + method is used. The first argument gives the image to use as the + pattern (either an <code><a href="#htmlimageelement">HTMLImageElement</a></code>, + <code><a href="#htmlcanvaselement">HTMLCanvasElement</a></code>, or <code><a href="#htmlvideoelement">HTMLVideoElement</a></code> + object). Modifying this image after calling the <code title="dom-context-2d-createPattern"><a href="#dom-context-2d-createpattern">createPattern()</a></code> method + must not affect the pattern. The second argument must be a string + with one of the following values: <code title="">repeat</code>, + <code title="">repeat-x</code>, <code title="">repeat-y</code>, + <code title="">no-repeat</code>. If the empty string is specified, + <code title="">repeat</code> must be assumed. If an unrecognized value + is given, then the user agent must raise a <code><a href="#syntax_err">SYNTAX_ERR</a></code> + exception. User agents must recognize the four values described above + exactly (e.g. they must not do case folding). Except as specified + below, the method must return a <code><a href="#canvaspattern">CanvasPattern</a></code> object + suitably initialized.</p> + + <p>The <var title="">image</var> argument is an instance of either + <code><a href="#htmlimageelement">HTMLImageElement</a></code>, <code><a href="#htmlcanvaselement">HTMLCanvasElement</a></code>, or + <code><a href="#htmlvideoelement">HTMLVideoElement</a></code>.</p> <!-- drawImage() has an equivalent + paragraph --> + + <p>If the <var title="">image</var> argument is an + <code><a href="#htmlimageelement">HTMLImageElement</a></code> object that is not <a href="#img-good" title="img-good">fully decodable</a>, or if the <var title="">image</var> argument is an <code><a href="#htmlvideoelement">HTMLVideoElement</a></code> + object whose <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> + attribute is either <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code> or <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, then the + implementation must return null.</p> <!-- drawImage() has an + equivalent paragraph --> + + <p>If the <var title="">image</var> argument is an + <code><a href="#htmlcanvaselement">HTMLCanvasElement</a></code> object with either a horizontal + dimension or a vertical dimension equal to zero, then the + implementation must raise an <code><a href="#invalid_state_err">INVALID_STATE_ERR</a></code> + exception.</p> + <!-- drawImage() has an equivalent paragraph --> + + <p>Patterns must be painted so that the top left of the first image + is anchored at the origin of the coordinate space, and images are + then repeated horizontally to the left and right (if the + <code>repeat-x</code> string was specified) or vertically up and + down (if the <code>repeat-y</code> string was specified) or in all + four directions all over the canvas (if the <code>repeat</code> + string was specified). The images are not scaled by this process; + one CSS pixel of the image must be painted on one coordinate space + unit. Of course, patterns must actually be painted only where the + stroking or filling effect requires that they be drawn, and are + affected by the current transformation matrix.</p> + + <p>If the original image data is a bitmap image, the value painted + at a point in the area of the repetitions 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 wrapping the + pixel's coordinates to the original image's dimensions. (That is, + the filter uses 'repeat' behavior, regardless of the value of + <var title="">repetition</var>.) + <!-- drawImage() has a similar paragraph with different rules --> + + </p><p>When the <code title="dom-context-2d-createPattern"><a href="#dom-context-2d-createpattern">createPattern()</a></code> method + is passed an animated image as its <var title="">image</var> + argument, the user agent must use the poster frame of the animation, + or, if there is no poster frame, the first frame of the + animation.</p> + <!-- drawImage() has an equivalent paragraph --> + + <p>When the <var title="">image</var> argument is an + <code><a href="#htmlvideoelement">HTMLVideoElement</a></code>, then the frame at the <a href="#current-playback-position">current + playback position</a> must be used as the source image, and the + source image's dimensions must be the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic width</a> and + <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</a> + of the <a href="#media-resource">media resource</a> (i.e. after any aspect-ratio + correction has been applied).</p> + <!-- drawImage() has an equivalent paragraph --> + + <!-- + Requests for v6 features: + * apply transforms to patterns, so you don't have to create + transformed patterns manually by rendering them to an off-screen + canvas then using that canvas as the pattern. + --> + + </div> + + + + <h6 id="line-styles"><span class="secno">4.8.11.1.5 </span>Line styles</h6> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-lineWidth"><a href="#dom-context-2d-linewidth">lineWidth</a></code> [ = <var title="">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 title="">context</var> . <code title="dom-context-2d-lineCap"><a href="#dom-context-2d-linecap">lineCap</a></code> [ = <var title="">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 title="">context</var> . <code title="dom-context-2d-lineJoin"><a href="#dom-context-2d-linejoin">lineJoin</a></code> [ = <var title="">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 title="">context</var> . <code title="dom-context-2d-miterLimit"><a href="#dom-context-2d-miterlimit">miterLimit</a></code> [ = <var title="">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> + + </dl><div class="impl"> + + <p>The <dfn id="dom-context-2d-linewidth" title="dom-context-2d-lineWidth"><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 context is created, the <code title="dom-context-2d-lineWidth"><a href="#dom-context-2d-linewidth">lineWidth</a></code> attribute must + initially have the value <code>1.0</code>.</p> + + <hr/><p>The <dfn id="dom-context-2d-linecap" title="dom-context-2d-lineCap"><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>. The <code>butt</code> + value means that the end of each line has a flat edge perpendicular + to the direction of the line (and that no additional line cap is + added). The <code>round</code> value means that a semi-circle with + the diameter equal to the width of the line must then be added on to + the end of the line. The <code>square</code> value means that a + rectangle with the length of the line width and the width of half + the line width, placed flat against the edge perpendicular to the + direction of the line, must be added at the end of each line.</p> + + <p>On getting, it must return the current value. On setting, if the + new value is one of the literal strings <code>butt</code>, + <code>round</code>, and <code>square</code>, then the current value + must be changed to the new value; other values must ignored, leaving + the value unchanged.</p> + + <p>When the context is created, the <code title="dom-context-2d-lineCap"><a href="#dom-context-2d-linecap">lineCap</a></code> attribute must + initially have the value <code>butt</code>.</p> + + <hr/><p>The <dfn id="dom-context-2d-linejoin" title="dom-context-2d-lineJoin"><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, if the + new value is one of the literal strings <code>bevel</code>, + <code>round</code>, and <code>miter</code>, then the current value + must be changed to the new value; other values must be ignored, + leaving the value unchanged.</p> + + <p>When the context is created, the <code title="dom-context-2d-lineJoin"><a href="#dom-context-2d-linejoin">lineJoin</a></code> attribute must + initially have the value <code>miter</code>.</p> + + <hr/><p>A join exists at any point in a subpath shared by two consecutive + lines. When a subpath is closed, then a join also exists at its + first point (equivalent to its last point) connecting the first and + last lines in the subpath.</p> + + <p>In addition to the point where the 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 filled triangle connecting these two opposite corners with a + straight line, with the third point of the triangle being the join + point, must be rendered at all joins. The <code title="dom-context-2d-lineJoin"><a href="#dom-context-2d-linejoin">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 a filled 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 + rendered at joins.</p> + + <p>The <code>miter</code> value means that a second filled triangle + must (if it can given the miter length) be rendered 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 to be exceeded, this second triangle must not + be rendered.</p> + + <p>The miter limit ratio can be explicitly set using the <dfn id="dom-context-2d-miterlimit" title="dom-context-2d-miterLimit"><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 context is created, the <code title="dom-context-2d-miterLimit"><a href="#dom-context-2d-miterlimit">miterLimit</a></code> attribute must + initially have the value <code>10.0</code>.</p> + + <!-- +v6: dashed lines have been requested. Philip Taylor provides these +notes on what would need to be defined for dashed lines: +> I don't think it's entirely trivial to add, to the detail that's +> necessary in a specification. The common graphics APIs (at least +> Cairo, Quartz and java.awt.Graphics, and any SVG implementation) all +> have dashes specified by passing an array of dash lengths (alternating +> on/off), so that should be alright as long as you define what units +> it's measured in and what happens when you specify an odd number of +> values and how errors are handled and what happens if you update the +> array later. But after that, what does it do when stroking multiple +> subpaths, in terms of offsetting the dashes? When you use strokeRect, +> where is offset 0? Does moveTo reset the offset? How does it interact +> with lineCap/lineJoin? All the potential issues need test cases too, +> and the implementations need to make sure they handle any edge cases +> that the underlying graphics library does differently. (SVG Tiny 1.2 +> appears to skip some of the problems by leaving things undefined and +> allowing whatever behavior the graphics library has.) + +Another request has been for hairline width lines, that remain +hairline width with transform. ack Shaun Morris. + --> + + </div> + + + <h6 id="shadows"><span class="secno">4.8.11.1.6 </span><dfn>Shadows</dfn></h6> + + <p>All drawing operations are affected by the four global shadow + attributes.</p> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-shadowColor"><a href="#dom-context-2d-shadowcolor">shadowColor</a></code> [ = <var title="">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 title="">context</var> . <code title="dom-context-2d-shadowOffsetX"><a href="#dom-context-2d-shadowoffsetx">shadowOffsetX</a></code> [ = <var title="">value</var> ]</dt> + <dt><var title="">context</var> . <code title="dom-context-2d-shadowOffsetY"><a href="#dom-context-2d-shadowoffsety">shadowOffsetY</a></code> [ = <var title="">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 title="">context</var> . <code title="dom-context-2d-shadowBlur"><a href="#dom-context-2d-shadowblur">shadowBlur</a></code> [ = <var title="">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><div class="impl"> + + <p>The <dfn id="dom-context-2d-shadowcolor" title="dom-context-2d-shadowColor"><code>shadowColor</code></dfn> + attribute sets the color of the shadow.</p> + + <p>When the context is created, the <code title="dom-context-2d-shadowColor"><a href="#dom-context-2d-shadowcolor">shadowColor</a></code> attribute + initially must be fully-transparent black.</p> + + <p>On getting, the <a href="#serialization-of-a-color" title="serialization of a + color">serialization of the color</a> must be returned.</p> + + <p>On setting, the new value must be <a href="#parsed-as-a-css-color-value">parsed as a CSS + <color> value</a> and the color assigned. If the value + cannot be parsed as a CSS <color> value then it must be + ignored, and the attribute must retain its previous value. <a href="#refsCSSCOLOR">[CSSCOLOR]</a></p> + + <p>The <dfn id="dom-context-2d-shadowoffsetx" title="dom-context-2d-shadowOffsetX"><code>shadowOffsetX</code></dfn> + and <dfn id="dom-context-2d-shadowoffsety" title="dom-context-2d-shadowOffsetY"><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 <code>0</code>.</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" title="dom-context-2d-shadowBlur"><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 title="dom-context-2d-shadowBlur"><a href="#dom-context-2d-shadowblur">shadowBlur</a></code> attribute must + initially have the value <code>0</code>.</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" title="when shadows are drawn">Shadows are only drawn + if</dfn> the opacity component of the alpha component of the color + of <code title="dom-context-2d-shadowColor"><a href="#dom-context-2d-shadowcolor">shadowColor</a></code> is + non-zero and either the <code title="dom-context-2d-shadowBlur"><a href="#dom-context-2d-shadowblur">shadowBlur</a></code> is non-zero, or + the <code title="dom-context-2d-shadowOffsetX"><a href="#dom-context-2d-shadowoffsetx">shadowOffsetX</a></code> + is non-zero, or the <code title="dom-context-2d-shadowOffsetY"><a href="#dom-context-2d-shadowoffsety">shadowOffsetY</a></code> is + non-zero.</p> + + <p class="critical">It is likely that this will change: browser + vendors have indicated an interest in changing the processing model + for shadows such that they only draw when the composition operator + is "source-over" (the default). <a href="http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2011-May/thread.html#31457">Read + more...</a></p> + + <p><a href="#when-shadows-are-drawn">When shadows are drawn</a>, they must be rendered as follows:</p> + + <ol><li> <p>Let <var title="">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 title="">B</var> be an infinite transparent black + bitmap, with a coordinate space and an origin identical to <var title="">A</var>.</p> </li> + + <li> <p>Copy the alpha channel of <var title="">A</var> to <var title="">B</var>, offset by <code title="dom-context-2d-shadowOffsetX"><a href="#dom-context-2d-shadowoffsetx">shadowOffsetX</a></code> in the + positive <var title="">x</var> direction, and <code title="dom-context-2d-shadowOffsetY"><a href="#dom-context-2d-shadowoffsety">shadowOffsetY</a></code> in the + positive <var title="">y</var> direction.</p> </li> + + <li> <p>If <code title="dom-context-2d-shadowBlur"><a href="#dom-context-2d-shadowblur">shadowBlur</a></code> is greater than + 0:</p> + + <ol><li> <p>Let <var title="">σ</var> be half the value of + <code title="dom-context-2d-shadowBlur"><a href="#dom-context-2d-shadowblur">shadowBlur</a></code>.</p></li> + + <li> <p>Perform a 2D Gaussian Blur on <var title="">B</var>, + using <var title="">σ</var> as the standard deviation.</p> + <!-- wish i could find a reference for this --> </li> + + </ol><p>User agents may limit values of <var title="">σ</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 title="">B</var> to the red, green, and blue components + (respectively) of the color of <code title="dom-context-2d-shadowColor"><a href="#dom-context-2d-shadowcolor">shadowColor</a></code>.</p> </li> + + <li> <p>Multiply the alpha component of every pixel in <var title="">B</var> by the alpha component of the color of <code title="dom-context-2d-shadowColor"><a href="#dom-context-2d-shadowcolor">shadowColor</a></code>.</p> </li> + + <li> <p>The shadow is in the bitmap <var title="">B</var>, and is + rendered as part of the <a href="#drawing-model">drawing model</a> described below.</p> </li> + + </ol></div> + + <p>If the current composition operation is <code title="gcop-copy"><a href="#gcop-copy">copy</a></code>, shadows effectively won't render + (since the shape will overwrite the shadow).</p> + + + <h6 id="simple-shapes-(rectangles)"><span class="secno">4.8.11.1.7 </span>Simple shapes (rectangles)</h6> + + <p>There are three methods that immediately draw rectangles to the + bitmap. They each take four arguments; the first two give the <var title="">x</var> and <var title="">y</var> coordinates of the top + left of the rectangle, and the second two give the width <var title="">w</var> and height <var title="">h</var> of the rectangle, + respectively.</p> + + <div class="impl"> + + <p>The <a href="#transformations" title="dom-context-2d-transformation">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 title="">(<var title="">x</var>, <var title="">y</var>)</span>, <span title="">(<span title=""><var title="">x</var>+<var title="">w</var></span>, <var title="">y</var>)</span>, + <span title="">(<span title=""><var title="">x</var>+<var title="">w</var></span>, + <span title=""><var title="">y</var>+<var title="">h</var></span>)</span>, + <span title="">(<var title="">x</var>, <span title=""><var title="">y</var>+<var title="">h</var></span>)</span>.</p> + + <p>Shapes are painted without affecting the current path, and are + subject to the <a href="#clipping-region" title="clipping region">clipping region</a>, + and, with the exception of <code title="dom-context-2d-clearRect"><a href="#dom-context-2d-clearrect">clearRect()</a></code>, also <a href="#shadows" title="shadows">shadow effects</a>, <a href="#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">global alpha</a>, and <a href="#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">global composition + operators</a>.</p> + + </div> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-clearRect"><a href="#dom-context-2d-clearrect">clearRect</a></code>(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</dt> + + <dd> + + <p>Clears all pixels on the canvas in the given rectangle to transparent black.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-fillRect"><a href="#dom-context-2d-fillrect">fillRect</a></code>(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</dt> + + <dd> + + <p>Paints the given rectangle onto the canvas, using the current fill style.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-strokeRect"><a href="#dom-context-2d-strokerect">strokeRect</a></code>(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</dt> + + <dd> + + <p>Paints the box that outlines the given rectangle onto the canvas, using the current stroke style.</p> + + </dd> + + </dl><div class="impl"> + + <p>The <dfn id="dom-context-2d-clearrect" title="dom-context-2d-clearRect"><code>clearRect(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</code></dfn> method must clear the pixels in the + specified rectangle that also intersect the current clipping region + to a fully transparent black, erasing any previous image. If either + height or width are zero, this method has no effect.</p> + + <p>The <dfn id="dom-context-2d-fillrect" title="dom-context-2d-fillRect"><code>fillRect(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</code></dfn> method must paint the specified + rectangular area using the <code title="dom-context-2d-fillStyle"><a href="#dom-context-2d-fillstyle">fillStyle</a></code>. If either height + or width are zero, this method has no effect.</p> + + <p>The <dfn id="dom-context-2d-strokerect" title="dom-context-2d-strokeRect"><code>strokeRect(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</code></dfn> method must stroke the specified + rectangle's path using the <code title="dom-context-2d-strokeStyle"><a href="#dom-context-2d-strokestyle">strokeStyle</a></code>, <code title="dom-context-2d-lineWidth"><a href="#dom-context-2d-linewidth">lineWidth</a></code>, <code title="dom-context-2d-lineJoin"><a href="#dom-context-2d-linejoin">lineJoin</a></code>, and (if + appropriate) <code title="dom-context-2d-miterLimit"><a href="#dom-context-2d-miterlimit">miterLimit</a></code> attributes. If + both height and width are zero, this method has no effect, since + there is no path to stroke (it's a point). If only one of the two is + zero, then the method will draw a line instead (the path for the + outline is just a straight line along the non-zero dimension).</p> + + </div> + + + <h6 id="complex-shapes-(paths)"><span class="secno">4.8.11.1.8 </span>Complex shapes (paths)</h6> + + <p>The context always has a current path. There is only one current + path, it is not part of the <a href="#drawing-state">drawing state</a>.</p> + + <p>A <dfn id="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 lines, 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 fewer than two points are ignored when + painting the path.</p> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-beginPath"><a href="#dom-context-2d-beginpath">beginPath</a></code>()</dt> + + <dd> + + <p>Resets the current path.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-moveTo"><a href="#dom-context-2d-moveto">moveTo</a></code>(<var title="">x</var>, <var title="">y</var>)</dt> + + <dd> + + <p>Creates a new subpath with the given point.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-closePath"><a href="#dom-context-2d-closepath">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 title="">context</var> . <code title="dom-context-2d-lineTo"><a href="#dom-context-2d-lineto">lineTo</a></code>(<var title="">x</var>, <var title="">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 title="">context</var> . <code title="dom-context-2d-quadraticCurveTo"><a href="#dom-context-2d-quadraticcurveto">quadraticCurveTo</a></code>(<var title="">cpx</var>, <var title="">cpy</var>, <var title="">x</var>, <var title="">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 title="">context</var> . <code title="dom-context-2d-bezierCurveTo"><a href="#dom-context-2d-beziercurveto">bezierCurveTo</a></code>(<var title="">cp1x</var>, <var title="">cp1y</var>, <var title="">cp2x</var>, <var title="">cp2y</var>, <var title="">x</var>, <var title="">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 title="">context</var> . <code title="dom-context-2d-arcTo"><a href="#dom-context-2d-arcto">arcTo</a></code>(<var title="">x1</var>, <var title="">y1</var>, <var title="">x2</var>, <var title="">y2</var>, <var title="">radius</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>Throws an <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception if the given + radius is negative.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-arc"><a href="#dom-context-2d-arc">arc</a></code>(<var title="">x</var>, <var title="">y</var>, <var title="">radius</var>, <var title="">startAngle</var>, <var title="">endAngle</var> [, <var title="">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 <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception if the given + radius is negative.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-rect"><a href="#dom-context-2d-rect">rect</a></code>(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</dt> + + <dd> + + <p>Adds a new closed subpath to the path, representing the given rectangle.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-fill"><a href="#dom-context-2d-fill">fill</a></code>()</dt> + + <dd> + + <p>Fills the subpaths with the current fill style.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-stroke"><a href="#dom-context-2d-stroke">stroke</a></code>()</dt> + + <dd> + + <p>Strokes the subpaths with the current stroke style.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-drawSystemFocusRing"><a href="#dom-context-2d-drawsystemfocusring">drawSystemFocusRing</a></code>(<var title="">element</var>)</dt> + + <dd> + + <p>If the given element is focused, draws a focus ring around the + current path, following the platform conventions for focus + rings.</p> + + </dd> + + <dt><var title="">shouldDraw</var> = <var title="">context</var> . <code title="dom-context-2d-drawCustomFocusRing"><a href="#dom-context-2d-drawcustomfocusring">drawCustomFocusRing</a></code>(<var title="">element</var>)</dt> + + <dd> + + <p>If the given element is focused, and the user has configured + his system to draw focus rings in a particular manner (for + example, high contrast focus rings), draws a focus ring around the + current path and returns false.</p> + + <p>Otherwise, returns true if the given element is focused, and + false otherwise. This can thus be used to determine when to draw a + focus ring (see <a href="#drawCustomFocusRingExample">the + example</a> below).</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-scrollPathIntoView"><a href="#dom-context-2d-scrollpathintoview">scrollPathIntoView</a></code>()</dt> + + <dd> + + <p>Scrolls the current path into view. This is especially useful + on devices with small screens, where the whole canvas might not be + visible at once.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-clip"><a href="#dom-context-2d-clip">clip</a></code>()</dt> + + <dd> + + <p>Further constrains the clipping region to the given path.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-isPointInPath"><a href="#dom-context-2d-ispointinpath">isPointInPath</a></code>(<var title="">x</var>, <var title="">y</var>)</dt> + + <dd> + + <p>Returns true if the given point is in the current path.</p> + + </dd> + + </dl><div class="impl"> + + <p>Initially, the context's path must have zero subpaths.</p> + + <p>The points and lines added to the path by these methods must be + transformed according to the <a href="#transformations" title="dom-context-2d-transformation">current transformation + matrix</a> as they are added.</p> + + + <p>The <dfn id="dom-context-2d-beginpath" title="dom-context-2d-beginPath"><code>beginPath()</code></dfn> + method must empty the list of subpaths so that the context once + again has zero subpaths.</p> + + + <p>The <dfn id="dom-context-2d-moveto" title="dom-context-2d-moveTo"><code>moveTo(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must + create a new subpath with the specified point as its first (and + only) point.</p> + + <p>When the user agent is to <dfn id="ensure-there-is-a-subpath">ensure there is a subpath</dfn> + for a coordinate (<var title="">x</var>, <var title="">y</var>), the + user agent must check to see if the context has any subpaths, and if + it does not, then the user agent must create a new subpath with the + point (<var title="">x</var>, <var title="">y</var>) as its first + (and only) point, as if the <code title="dom-context-2d-moveTo"><a href="#dom-context-2d-moveto">moveTo()</a></code> method had been + called.</p> + + + <p>The <dfn id="dom-context-2d-closepath" title="dom-context-2d-closePath"><code>closePath()</code></dfn> + method must do nothing if the context 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 title="dom-context-2d-moveTo"><a href="#dom-context-2d-moveto">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 context's paths.</p> + + + <p>The <dfn id="dom-context-2d-lineto" title="dom-context-2d-lineTo"><code>lineTo(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must + <a href="#ensure-there-is-a-subpath">ensure there is a subpath</a> for <span title="">(<var title="">x</var>, <var title="">y</var>)</span> if the context has + no subpaths. Otherwise, it must connect the last point in the + subpath to the given point (<var title="">x</var>, <var title="">y</var>) using a straight line, and must then add the given + point (<var title="">x</var>, <var title="">y</var>) to the + subpath.</p> + + + <p>The <dfn id="dom-context-2d-quadraticcurveto" title="dom-context-2d-quadraticCurveTo"><code>quadraticCurveTo(<var title="">cpx</var>, <var title="">cpy</var>, <var title="">x</var>, + <var title="">y</var>)</code></dfn> method must <a href="#ensure-there-is-a-subpath">ensure there + is a subpath</a> for <span title="">(<var title="">cpx</var>, + <var title="">cpy</var>)</span>, and then must connect the last + point in the subpath to the given point (<var title="">x</var>, <var title="">y</var>) using a quadratic Bézier curve with control + point (<var title="">cpx</var>, <var title="">cpy</var>), and must + then add the given point (<var title="">x</var>, <var title="">y</var>) to the subpath. <a href="#refsBEZIER">[BEZIER]</a></p> + + + <p>The <dfn id="dom-context-2d-beziercurveto" title="dom-context-2d-bezierCurveTo"><code>bezierCurveTo(<var title="">cp1x</var>, <var title="">cp1y</var>, <var title="">cp2x</var>, <var title="">cp2y</var>, <var title="">x</var>, <var title="">y</var>)</code></dfn> method must + <a href="#ensure-there-is-a-subpath">ensure there is a subpath</a> for <span title="">(<var title="">cp1x</var>, <var title="">cp1y</var>)</span>, and then must + connect the last point in the subpath to the given point (<var title="">x</var>, <var title="">y</var>) using a cubic Bézier + curve with control points (<var title="">cp1x</var>, <var title="">cp1y</var>) and (<var title="">cp2x</var>, <var title="">cp2y</var>). Then, it must add the point (<var title="">x</var>, <var title="">y</var>) to the subpath. <a href="#refsBEZIER">[BEZIER]</a></p> + + <hr/><p>The <dfn id="dom-context-2d-arcto" title="dom-context-2d-arcTo"><code>arcTo(<var title="">x1</var>, <var title="">y1</var>, <var title="">x2</var>, + <var title="">y2</var>, <var title="">radius</var>)</code></dfn> + method must first <a href="#ensure-there-is-a-subpath">ensure there is a subpath</a> for <span title="">(<var title="">x1</var>, <var title="">y1</var>)</span>. Then, the behavior depends on the + arguments and the last point in the subpath, as described below.</p> + + <p>Negative values for <var title="">radius</var> must cause the + implementation to raise an <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> + exception.</p> + + <p>Let the point (<var title="">x0</var>, <var title="">y0</var>) be + the last point in the subpath.</p> + + <p>If the point (<var title="">x0</var>, <var title="">y0</var>) is + equal to the point (<var title="">x1</var>, <var title="">y1</var>), + or if the point (<var title="">x1</var>, <var title="">y1</var>) is + equal to the point (<var title="">x2</var>, <var title="">y2</var>), + or if the radius <var title="">radius</var> is zero, then the method + must add the point (<var title="">x1</var>, <var title="">y1</var>) + to the subpath, and connect that point to the previous point (<var title="">x0</var>, <var title="">y0</var>) by a straight line.</p> + + <p>Otherwise, if the points (<var title="">x0</var>, <var title="">y0</var>), (<var title="">x1</var>, <var title="">y1</var>), and (<var title="">x2</var>, <var title="">y2</var>) all lie on a single straight line, then the + method must add the point (<var title="">x1</var>, <var title="">y1</var>) to the subpath, and connect that point to the + previous point (<var title="">x0</var>, <var title="">y0</var>) by a + straight line.</p> + + <p>Otherwise, let <var title="">The Arc</var> be the shortest arc + given by circumference of the circle that has radius <var title="">radius</var>, and that has one point tangent to the + half-infinite line that crosses the point (<var title="">x0</var>, + <var title="">y0</var>) and ends at the point (<var title="">x1</var>, <var title="">y1</var>), and that has a different + point tangent to the half-infinite line that ends at the point (<var title="">x1</var>, <var title="">y1</var>) and crosses the point + (<var title="">x2</var>, <var title="">y2</var>). The points at + which this circle touches these two lines are called the start and + end tangent points respectively. The method must connect the point + (<var title="">x0</var>, <var title="">y0</var>) to the start + tangent point by a straight line, adding the start tangent point to + the subpath, and then must connect the start tangent point to the + end tangent point by <var title="">The Arc</var>, adding the end + tangent point to the subpath.</p> + + <hr/><p>The <dfn id="dom-context-2d-arc" title="dom-context-2d-arc"><code>arc(<var title="">x</var>, <var title="">y</var>, <var title="">radius</var>, + <var title="">startAngle</var>, <var title="">endAngle</var>, <var title="">anticlockwise</var>)</code></dfn> method draws an arc. If + the context has any subpaths, then the method must add a straight + line from the last point in the subpath to the start point of the + arc. In any case, it must draw the arc between the start point of + the arc and the end point of the arc, and add the start and end + points of the arc to the subpath. The arc and its start and end + points are defined as follows:</p> + + <p>Consider a circle that has its origin at (<var title="">x</var>, + <var title="">y</var>) and that has radius <var title="">radius</var>. The points at <var title="">startAngle</var> + and <var title="">endAngle</var> along this circle's circumference, + measured in radians clockwise from the positive x-axis, are the + start and end points respectively.</p> + + <p>If the <var title="">anticlockwise</var> argument is omitted or + false and <span title=""><var title="">endAngle</var>-<var title="">startAngle</var></span> is equal to or greater than <span title="">2π</span>, or, if the <var title="">anticlockwise</var> + argument is <em>true</em> and <span title=""><var title="">startAngle</var>-<var title="">endAngle</var></span> is + equal to or greater than <span title="">2π</span>, then the arc + is the whole circumference of this circle.</p> + + <p>Otherwise, the arc is the path along the circumference of this + circle from the start point to the end point, going anti-clockwise + if the <var title="">anticlockwise</var> argument is true, and + clockwise otherwise. Since the points are on the circle, as opposed + to being simply angles from zero, the arc can never cover an angle + greater than <span title="">2π</span> radians. If the two points are the + same, or if the radius is zero, then the arc is defined as being of + zero length in both directions.</p> + + <p>Negative values for <var title="">radius</var> must cause the + implementation to raise an <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> + exception.</p> + + <hr/><p>The <dfn id="dom-context-2d-rect" title="dom-context-2d-rect"><code>rect(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</code></dfn> method must create a new subpath + containing just the four points (<var title="">x</var>, <var title="">y</var>), (<var title="">x</var>+<var title="">w</var>, + <var title="">y</var>), (<var title="">x</var>+<var title="">w</var>, <var title="">y</var>+<var title="">h</var>), + (<var title="">x</var>, <var title="">y</var>+<var title="">h</var>), with those four points connected by straight + lines, and must then mark the subpath as closed. It must then create + a new subpath with the point (<var title="">x</var>, <var title="">y</var>) as the only point in the subpath.</p> + + + <!-- v6 feature request: + * points as a primitive shape + http://home.comcast.net/~urbanjost/canvas/vogle4.html + --> + + + <p>The <dfn id="dom-context-2d-fill" title="dom-context-2d-fill"><code>fill()</code></dfn> + method must fill all the subpaths of the current path, using + <code title="dom-context-2d-fillStyle"><a href="#dom-context-2d-fillstyle">fillStyle</a></code>, and using + the non-zero winding number rule. Open subpaths must be implicitly + closed when being filled (without affecting the actual + subpaths).</p> + + <p class="note">Thus, if two overlapping but otherwise independent + subpaths have opposite windings, they cancel out and result in no + fill. If they have the same winding, that area just gets painted + once.</p> + + <p>The <dfn id="dom-context-2d-stroke" title="dom-context-2d-stroke"><code>stroke()</code></dfn> method + must calculate the strokes of all the subpaths of the current path, + using the <code title="dom-context-2d-lineWidth"><a href="#dom-context-2d-linewidth">lineWidth</a></code>, + <code title="dom-context-2d-lineCap"><a href="#dom-context-2d-linecap">lineCap</a></code>, <code title="dom-context-2d-lineJoin"><a href="#dom-context-2d-linejoin">lineJoin</a></code>, and (if + appropriate) <code title="dom-context-2d-miterLimit"><a href="#dom-context-2d-miterlimit">miterLimit</a></code> attributes, and + then fill the combined stroke area using the <code title="dom-context-2d-strokeStyle"><a href="#dom-context-2d-strokestyle">strokeStyle</a></code> + attribute.</p> + + <p class="note">Since the subpaths are all stroked as one, + overlapping parts of the paths in one stroke operation are treated + as if their union was what was painted.</p> + + <p>Paths, when filled or stroked, must be painted without affecting + the current path, and must be subject to <a href="#shadows" title="shadows">shadow effects</a>, <a href="#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">global alpha</a>, the <a href="#clipping-region" title="clipping region">clipping region</a>, and <a href="#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">global composition + operators</a>. (Transformations affect the path when the path is + created, not when it is painted, though the stroke <em>style</em> is + still affected by the transformation during painting.)</p> + + <p>Zero-length line segments must be pruned before stroking a + path. Empty subpaths must be ignored.</p> + + <hr/><p id="dom-context-2d-drawosfocusring">The <dfn id="dom-context-2d-drawsystemfocusring" title="dom-context-2d-drawSystemFocusRing"><code>drawSystemFocusRing(<var title="">element</var>)</code></dfn> method, when invoked, must run + the following steps:</p> + + <ol><li><p>If <var title="">element</var> is not focused or is not a + descendant of the element with whose context the method is + associated, then abort these steps.</p></li> + + <li> + + <p>If the user has requested the use of particular focus rings + (e.g. high-contrast focus rings), or if the <var title="">element</var> would have a focus ring drawn around it, + then draw a focus ring of the appropriate style along the path, + following platform conventions, and abort these steps.</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 title="dom-focus"><a href="#dom-focus">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" title="shadows">shadow effects</a>, the <a href="#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">global alpha</a>, or the <a href="#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">global composition + operators</a>, but <em>should</em> be subject to the <a href="#clipping-region" title="clipping region">clipping region</a>.</p> + + </li> + + <li> + + <p>Optionally, <a href="#inform">inform the user</a> that the + focus is at the location given by the path. User agents may wait + until the next time the <a href="#event-loop">event loop</a> reaches its + "update the rendering" step to optionally inform the user.</p> + + </li> + + </ol><p>The <dfn id="dom-context-2d-drawcustomfocusring" title="dom-context-2d-drawCustomFocusRing"><code>drawCustomFocusRing(<var title="">element</var>)</code></dfn> method, when invoked, must run + the following steps:</p> + + <ol><li><p>If <var title="">element</var> is not focused or is not a + descendant of the element with whose context the method is + associated, then return false and abort these steps.</p></li> + + <li> + + <p>If the user has requested the use of particular focus rings + (e.g. high-contrast focus rings), then draw a focus ring of the + appropriate style along the path, return false, and abort these + steps.</p> + + <p>The focus ring should not be subject to the <a href="#shadows" title="shadows">shadow effects</a>, the <a href="#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">global alpha</a>, or the <a href="#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">global composition + operators</a>, but <em>should</em> be subject to the <a href="#clipping-region" title="clipping region">clipping region</a>.</p> + + </li> + + <li> + + <p>Optionally, <a href="#inform">inform the user</a> that the + focus is at the location given by the path. User agents may wait + until the next time the <a href="#event-loop">event loop</a> reaches its + "update the rendering" step to optionally inform the user.</p> + + </li> + + <li><p>Return true.</p></li> + + </ol><p>The <dfn id="dom-context-2d-scrollpathintoview" title="dom-context-2d-scrollPathIntoView"><code>scrollPathIntoView()</code></dfn> + method, when invoked, must run the following steps:</p> + + <ol><li><p>Let <var title="">notional child</var> be a hypothetical + element that is a rendered child of the <code><a href="#the-canvas-element">canvas</a></code> element + whose dimensions are exactly the rectangle of the bounding box of + the current path.</p></li> + + <li><p><span title="scroll an element into view">Scroll <var title="">notional child</var> into view</span> with the <var title="">align to top flag</var> set.</p> + + </li><li><p>Optionally, <a href="#inform">inform the user</a> that the + caret and/or selection cover <var title="">the specified + rectangle</var> of the canvas. User agents may wait until the next + time the <a href="#event-loop">event loop</a> reaches its "update the rendering" + step to optionally inform the user.</p></li> + + </ol><p class="note" id="inform">"Inform the user", as used in this + section, could mean calling a system accessibility API, which would + notify assistive technologies such as magnification tools. To + properly drive magnification based on a focus change, a system + accessibility API driving a screen magnifier needs the bounds for + the newly focused object. The methods above are intended to enable + this by allowing the user agent to report the bounding box of the + path used to render the focus ring as the bounds of the <var title="">element</var> element passed as an argument, if that + element is focused, and the bounding box of the area to which the + user agent is scrolling as the bounding box of the current + selection.</p> + + <hr/><p>The <dfn id="dom-context-2d-clip" title="dom-context-2d-clip"><code>clip()</code></dfn> + method 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 current path, using the non-zero winding number + rule. 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 rectangle with the top left corner at (0,0) and the width and + height of the coordinate space.</p> + + <!-- v6 + Jordan OSETE suggests: + * support ways of extending the clipping region (union instead of intersection) + - also "add", "subtract", "replace", "intersect" and "xor" + * support ways of resetting the clipping region without save/restore + --> + + <hr/><p>The <dfn id="dom-context-2d-ispointinpath" title="dom-context-2d-isPointInPath"><code>isPointInPath(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must + return true if the point given by the <var title="">x</var> and <var title="">y</var> coordinates passed to the method, when treated as + coordinates in the canvas coordinate space unaffected by the current + transformation, is inside the current path as determined by the + non-zero winding number rule; and must return false + otherwise. Points on the path itself are considered to be inside the + path. If either of the arguments is infinite or NaN, then the method + must return false.</p> + + </div> + + + <div class="example" id="drawCustomFocusRingExample"> + + <p>This <code><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); + if (paint && context.drawCustomFocusRing(element)) { + context.strokeStyle = 'silver'; + context.stroke(); + } +</strong> 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; + 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> +<!-- http://software.hixie.ch/utilities/js/live-dom-viewer/saved/340 --> + + </div> + + + + + <h6 id="text-0"><span class="secno">4.8.11.1.9 </span>Text</h6> <!-- a v3 feature --> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-font"><a href="#dom-context-2d-font">font</a></code> [ = <var title="">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 'font' 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><a href="#the-canvas-element">canvas</a></code> element.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code> [ = <var title="">value</var> ]</dt> + + <dd> + + <p>Returns the current text alignment settings.</p> + + <p>Can be set, to change the alignment. The possible values are + <code title="">start</code>, <code title="">end</code>, <code title="">left</code>, <code title="">right</code>, and <code title="">center</code>. Other values are ignored. The default is + <code title="">start</code>.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> [ = <var title="">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 title="">alphabetic</code>.</p> + + </dd> + + <dt><var title="">context</var> . <code title="dom-context-2d-fillText"><a href="#dom-context-2d-filltext">fillText</a></code>(<var title="">text</var>, <var title="">x</var>, <var title="">y</var> [, <var title="">maxWidth</var> ] )</dt> + <dt><var title="">context</var> . <code title="dom-context-2d-strokeText"><a href="#dom-context-2d-stroketext">strokeText</a></code>(<var title="">text</var>, <var title="">x</var>, <var title="">y</var> [, <var title="">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 title="">metrics</var> = <var title="">context</var> . <code title="dom-context-2d-measureText"><a href="#dom-context-2d-measuretext">measureText</a></code>(<var title="">text</var>)</dt> + + <dd> + + <p>Returns a <code><a href="#textmetrics">TextMetrics</a></code> object with the metrics of the given text in the current font.</p> + + </dd> + + <dt><var title="">metrics</var> . <code title="dom-textmetrics-width"><a href="#dom-textmetrics-width">width</a></code></dt> + + <dd> + + <p>Returns the advance width of the text that was passed to the + <code title="dom-context-2d-measureText"><a href="#dom-context-2d-measuretext">measureText()</a></code> + method.</p> + + </dd> + + </dl><div class="impl"> + + <p>The <dfn id="dom-context-2d-font" title="dom-context-2d-font"><code>font</code></dfn> IDL + attribute, on setting, must be parsed the same way as the 'font' + property of CSS (but without supporting property-independent style + sheet syntax like 'inherit'), and the resulting font must be + assigned to the context, with the 'line-height' component forced to + 'normal', with the 'font-size' component converted to CSS pixels, + 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="#refsCSS">[CSS]</a></p> + + <p>Font names must be interpreted in the context of the + <code><a href="#the-canvas-element">canvas</a></code> element's stylesheets; any fonts embedded using + <code title="">@font-face</code> must therefore be available once + they are loaded. (If a font is referenced before it is fully loaded, + 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="#refsCSSFONTS">[CSSFONTS]</a></p> + + <p>Only vector fonts should be used by the user agent; if a user + agent were to use bitmap fonts then transformations would likely + make the font look very ugly.</p> + + <p>On getting, the <code title="dom-context-2d-font"><a href="#dom-context-2d-font">font</a></code> + attribute must return the <span title="serializing a CSS + value">serialized form</span> of the current font of the context + (with no 'line-height' component). <a href="#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 title="">context.font</code> would + evaluate to the string "<code title="">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 context is created, the font of the context must be set + to 10px sans-serif. When the 'font-size' component is set to lengths + using percentages, 'em' or 'ex' units, or the 'larger' or 'smaller' + keywords, these must be interpreted relative to the computed value + of the 'font-size' property of the corresponding <code><a href="#the-canvas-element">canvas</a></code> + element at the time that the attribute is set. When the + 'font-weight' component is set to the relative values 'bolder' and + 'lighter', these must be interpreted relative to the computed value + of the 'font-weight' property of the corresponding + <code><a href="#the-canvas-element">canvas</a></code> element at the time that the attribute is + set. If the computed values are undefined for a particular case + (e.g. because the <code><a href="#the-canvas-element">canvas</a></code> element is not <a href="#in-a-document">in a + <code>Document</code></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" title="dom-context-2d-textAlign"><code>textAlign</code></dfn> IDL + attribute, on getting, must return the current value. On setting, if + the value is one of <code title="">start</code>, <code title="">end</code>, <code title="">left</code>, <code title="">right</code>, or <code title="">center</code>, then the + value must be changed to the new value. Otherwise, the new value + must be ignored. When the context is created, the <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code> attribute must + initially have the value <code title="">start</code>.</p> + + <p>The <dfn id="dom-context-2d-textbaseline" title="dom-context-2d-textBaseline"><code>textBaseline</code></dfn> + IDL attribute, on getting, must return the current value. On + setting, if the value is one of <code title="dom-context-2d-textBaseline-top"><a href="#dom-context-2d-textbaseline-top">top</a></code>, <code title="dom-context-2d-textBaseline-hanging"><a href="#dom-context-2d-textbaseline-hanging">hanging</a></code>, <code title="dom-context-2d-textBaseline-middle"><a href="#dom-context-2d-textbaseline-middle">middle</a></code>, <code title="dom-context-2d-textBaseline-alphabetic"><a href="#dom-context-2d-textbaseline-alphabetic">alphabetic</a></code>, + <code title="dom-context-2d-textBaseline-ideographic"><a href="#dom-context-2d-textbaseline-ideographic">ideographic</a></code>, + or <code title="dom-context-2d-textBaseline-bottom"><a href="#dom-context-2d-textbaseline-bottom">bottom</a></code>, + then the value must be changed to the new value. Otherwise, the new + value must be ignored. When the context is created, the <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> attribute + must initially have the value <code title="">alphabetic</code>.</p> + + </div> + + <p>The <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">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="http://www.whatwg.org/specs/web-apps/current-work/http://images.whatwg.org/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" title="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" title="dom-context-2d-textBaseline-hanging"><code>hanging</code></dfn> + </dt><dd>The hanging baseline</dd> + + <dt><dfn id="dom-context-2d-textbaseline-middle" title="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" title="dom-context-2d-textBaseline-alphabetic"><code>alphabetic</code></dfn> + </dt><dd>The alphabetic baseline</dd> + + <dt><dfn id="dom-context-2d-textbaseline-ideographic" title="dom-context-2d-textBaseline-ideographic"><code>ideographic</code></dfn> + </dt><dd>The ideographic baseline</dd> + + <dt><dfn id="dom-context-2d-textbaseline-bottom" title="dom-context-2d-textBaseline-bottom"><code>bottom</code></dfn> + </dt><dd>The bottom of the em square</dd> + + </dl><div class="impl"> + + <p>The <dfn id="dom-context-2d-filltext" title="dom-context-2d-fillText"><code>fillText()</code></dfn> and + <dfn id="dom-context-2d-stroketext" title="dom-context-2d-strokeText"><code>strokeText()</code></dfn> + methods take three or four arguments, <var title="">text</var>, <var title="">x</var>, <var title="">y</var>, and optionally <var title="">maxWidth</var>, and render the given <var title="">text</var> at the given (<var title="">x</var>, <var title="">y</var>) coordinates ensuring that the text isn't wider + than <var title="">maxWidth</var> if specified, using the current + <code title="dom-context-2d-font"><a href="#dom-context-2d-font">font</a></code>, <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code>, and <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> + values. Specifically, when the methods are called, the user agent + must run the following steps:</p> + + <ol><li><p>If <var title="">maxWidth</var> is present but less than or + equal to zero, return without doing anything; abort these + steps.</p></li> + + <li><p>Let <var title="">font</var> be the current font of the + context, as given by the <code title="dom-context-2d-font"><a href="#dom-context-2d-font">font</a></code> attribute.</p></li> + + <li><p>Replace all the <a href="#space-character" title="space character">space + characters</a> in <var title="">text</var> with U+0020 SPACE + characters.</p></li> + + <li><p>Form a hypothetical infinitely wide CSS line box containing + a single inline box containing the text <var title="">text</var>, + with all the properties at their initial values except the 'font' + property of the inline box set to <var title="">font</var>, the + 'direction' property of the inline box set to <a href="#the-directionality">the + directionality</a> of the <code><a href="#the-canvas-element">canvas</a></code> element, and the + 'white-space' property set to 'pre'. <a href="#refsCSS">[CSS]</a></p></li> + + <!-- if you insert a step here, make sure to adjust the next step's + final words --> + + <li><p>If the <var title="">maxWidth</var> argument was specified + and the hypothetical width of the inline box in the hypothetical + line box is greater than <var title="">maxWidth</var> CSS pixels, + then change <var title="">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>Let the <var title="">anchor point</var> be a point on the + inline box, determined by the <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code> and <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> values, as + follows:</p> + + <p>Horizontal position:</p> + + <dl><dt> If <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code> is <code title="">left</code></dt> + <dt> If <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code> is <code title="">start</code> and <a href="#the-directionality">the directionality</a> of the + <code><a href="#the-canvas-element">canvas</a></code> element is 'ltr'</dt> + <dt> If <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code> is <code title="">end</code> and <a href="#the-directionality">the directionality</a> of the + <code><a href="#the-canvas-element">canvas</a></code> element is 'rtl'</dt> + + <dd>Let the <var title="">anchor point</var>'s horizontal + position be the left edge of the inline box.</dd> + + + <dt> If <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code> is <code title="">right</code></dt> + <dt> If <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code> is <code title="">end</code> and <a href="#the-directionality">the directionality</a> of the + <code><a href="#the-canvas-element">canvas</a></code> element is 'ltr'</dt> + <dt> If <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code> is <code title="">start</code> and <a href="#the-directionality">the directionality</a> of the + <code><a href="#the-canvas-element">canvas</a></code> element is 'rtl'</dt> + + <dd>Let the <var title="">anchor point</var>'s horizontal + position be the right edge of the inline box.</dd> + + + <dt> If <code title="dom-context-2d-textAlign"><a href="#dom-context-2d-textalign">textAlign</a></code> is <code title="">center</code></dt> + + <dd>Let the <var title="">anchor point</var>'s horizontal + position be half way between the left and right edges of the + inline box.</dd> + + </dl><p>Vertical position:</p> + + <dl><dt> If <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> is <code title="dom-context-2d-textBaseline-top"><a href="#dom-context-2d-textbaseline-top">top</a></code></dt> + + <dd>Let the <var title="">anchor point</var>'s vertical position + be the top of the em box of the first available font of the + inline box.</dd> + + + <dt> If <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> is <code title="dom-context-2d-textBaseline-hanging"><a href="#dom-context-2d-textbaseline-hanging">hanging</a></code></dt> + + <dd>Let the <var title="">anchor point</var>'s vertical position + be the hanging baseline of the first available font of the inline + box.</dd> + + + <dt> If <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> is <code title="dom-context-2d-textBaseline-middle"><a href="#dom-context-2d-textbaseline-middle">middle</a></code></dt> + + <dd>Let the <var title="">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 inline box.</dd> + + + <dt> If <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> is <code title="dom-context-2d-textBaseline-alphabetic"><a href="#dom-context-2d-textbaseline-alphabetic">alphabetic</a></code></dt> + + <dd>Let the <var title="">anchor point</var>'s vertical position + be the alphabetic baseline of the first available font of the inline + box.</dd> + + + <dt> If <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> is <code title="dom-context-2d-textBaseline-ideographic"><a href="#dom-context-2d-textbaseline-ideographic">ideographic</a></code></dt> + + <dd>Let the <var title="">anchor point</var>'s vertical position + be the ideographic baseline of the first available font of the inline + box.</dd> + + + <dt> If <code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> is <code title="dom-context-2d-textBaseline-bottom"><a href="#dom-context-2d-textbaseline-bottom">bottom</a></code></dt> + + <dd>Let the <var title="">anchor point</var>'s vertical position + be the bottom of the em box of the first available font of the + inline box.</dd> + + </dl></li> + + <li> + + <p>Paint the hypothetical inline box as the shape given by the + text's glyphs, as transformed by the <a href="#transformations" title="dom-context-2d-transformation">current transformation + matrix</a>, and anchored and sized so that before applying the + <a href="#transformations" title="dom-context-2d-transformation">current transformation + matrix</a>, the <var title="">anchor point</var> is at (<var title="">x</var>, <var title="">y</var>) and each CSS pixel is + mapped to one coordinate space unit.</p> + + <p>For <code title="dom-context-2d-fillText"><a href="#dom-context-2d-filltext">fillText()</a></code> + <code title="dom-context-2d-fillStyle"><a href="#dom-context-2d-fillstyle">fillStyle</a></code> must be + applied to the glyphs and <code title="dom-context-2d-strokeStyle"><a href="#dom-context-2d-strokestyle">strokeStyle</a></code> must be + ignored. For <code title="dom-context-2d-strokeText"><a href="#dom-context-2d-stroketext">strokeText()</a></code> the reverse + holds and <code title="dom-context-2d-strokeStyle"><a href="#dom-context-2d-strokestyle">strokeStyle</a></code> must be + applied to the glyph outlines and <code title="dom-context-2d-fillStyle"><a href="#dom-context-2d-fillstyle">fillStyle</a></code> must be + ignored.</p> + + <p>Text is painted without affecting the current path, and is + subject to <a href="#shadows" title="shadows">shadow effects</a>, <a href="#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">global alpha</a>, the <a href="#clipping-region" title="clipping region">clipping region</a>, and <a href="#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">global composition + operators</a>.</p> + + </li> + + </ol><!--v6DVT - this is commented out until CSS can get its act together +enough to actual specify vertical text rendering (how long have we +been waiting now?) + +WHEN EDITING THIS, FIX THE PARTS MARKED "XXX" BELOW + + <p>The <dfn + title="dom-context-2d-fillVerticalText"><code>fillVerticalText()</code></dfn> + and <dfn + title="dom-context-2d-strokeVerticalText"><code>strokeVerticalText()</code></dfn> + methods take three or four arguments, <var title="">text</var>, <var + title="">x</var>, <var title="">y</var>, and optionally <var + title="">maxHeight</var>, and render the given <var + title="">text</var> as vertical text at the given (<var + title="">x</var>, <var title="">y</var>) coordinates ensuring that + the text isn't taller than <var title="">maxHeight</var> if + specified, using the current <code + title="dom-context-2d-font">font</code> and <code + title="dom-context-2d-textAlign">textAlign</code> + values. Specifically, when the methods are called, the user agent + must run the following steps:</p> + + <ol> + + <li><p>If <var title="">maxHeight</var> is present but less than or + equal to zero, return without doing anything; abort these + steps.</p></li> + + <li><p>Let <var title="">font</var> be the current font of the + context, as given by the <code + title="dom-context-2d-font">font</code> attribute.</p></li> + + <li><p>Replace all the <span title="space character">space + characters</span> in <var title="">text</var> with U+0020 SPACE + characters.</p></li> + + <li><p>Form a <em class="XXX">whatever CSS ends up calling + vertical line boxes and inline boxes</em> containing the text <var + title="">text</var>, with all the properties at their initial + values except the 'font' property of the inline box set to <var + title="">font</var> and the 'direction' property of the inline + box set to <span>the directionality</span> of the <code>canvas</code> + element.</p></li> + + <!- - if you insert a step here, make sure to adjust the next step's + final words - -> + + <li><p>If the <var title="">maxHeight</var> argument was specified + and the hypothetical height of the <em class="XXX">box</em> + in the hypothetical line box is greater than <var + title="">maxHeight</var> CSS pixels, then change <var + title="">font</var> to have a more condensed font (if one is + available or if a reasonably readable one can be synthesized by + applying an appropriate scale factor to the font) or a smaller + font, and return to the previous step.</p></li> + + <li> + + <p>Let the <var title="">anchor point</var> be a point on the <em + class="XXX">inline box</var>, determined by the <code + title="dom-context-2d-textAlign">textAlign</code>, as follows:</p> + + <p>Vertical position:</p> + + <dl> + + <dt> If <code + title="dom-context-2d-textAlign">textAlign</code> is <code + title="">start</code></dt> + <dt> If <code + title="dom-context-2d-textAlign">textAlign</code> is <code + title="">left</code> and <span>the directionality</span> of the + <code>canvas</code> element is 'ltr'</dt> + <dt> If <code + title="dom-context-2d-textAlign">textAlign</code> is <code + title="">right</code> and <span>the directionality</span> of the + <code>canvas</code> element is 'rtl'</dt> + + <dd>Let the <var title="">anchor point</var>'s vertical + position be the top edge of the <em class="XXX">inline + box</em>.</dd> + + <dt> If <code + title="dom-context-2d-textAlign">textAlign</code> is <code + title="">end</code></dt> + <dt> If <code + title="dom-context-2d-textAlign">textAlign</code> is <code + title="">right</code> and <span>the directionality</span> of the + <code>canvas</code> element is 'ltr'</dt> + <dt> If <code + title="dom-context-2d-textAlign">textAlign</code> is <code + title="">left</code> and <span>the directionality</span> of the + <code>canvas</code> element is 'rtl'</dt> + + <dd>Let the <var title="">anchor point</var>'s vertical + position be the bottom edge of the <em class="XXX">inline + box</em>.</dd> + + + <dt> If <code + title="dom-context-2d-textAlign">textAlign</code> is <code + title="">center</code></dt> + + <dd>Let the <var title="">anchor point</var>'s vertical position + be half way between the top and bottom edges of the <em + class="XXX">inline box</em>.</dd> + + </dl> + + <p>Let the horizontal position be half way between the left and + right edges of the em box of the first available font of the <em + class="XXX">inline box</em>.</p> + + </li> + + <li> + + <p>Paint the hypothetical inline box as the shape given by the + text's glyphs, as transformed by the <span + title="dom-context-2d-transformation">current transformation + matrix</span>, and anchored and sized so that before applying the + <span title="dom-context-2d-transformation">current transformation + matrix</span>, the <var title="">anchor point</var> is at (<var + title="">x</var>, <var title="">y</var>) and each CSS pixel is + mapped to one coordinate space unit.</p> + + <p>For <code + title="dom-context-2d-fillVerticalText">fillVerticalText()</code> + <code title="dom-context-2d-fillStyle">fillStyle</code> must be + applied and <code + title="dom-context-2d-strokeStyle">strokeStyle</code> must be + ignored. For <code + title="dom-context-2d-strokeVerticalText">strokeVerticalText()</code> + the reverse holds and <code + title="dom-context-2d-strokeStyle">strokeStyle</code> must be + applied and <code + title="dom-context-2d-fillStyle">fillStyle</code> must be + ignored.</p> + + <p>Text is painted without affecting the current path, and is + subject to <span title="shadows">shadow effects</span>, <span + title="dom-context-2d-globalAlpha">global alpha</span>, the <span + title="clipping region">clipping region</span>, and <span + title="dom-context-2d-globalCompositeOperation">global composition + operators</span>.</p> + + </li> + + </ol> + +v6DVT (also check for '- -' bits in the part above) --><p>The <dfn id="dom-context-2d-measuretext" title="dom-context-2d-measureText"><code>measureText()</code></dfn> + method takes one argument, <var title="">text</var>. When the method + is invoked, the user agent must replace all the <a href="#space-character" title="space + character">space characters</a> in <var title="">text</var> with + U+0020 SPACE characters, and then must form a hypothetical + infinitely wide CSS line box containing a single inline box + containing the text <var title="">text</var>, with all the + properties at their initial values except the 'white-space' property + of the inline element set to 'pre' and the 'font' property of the + inline element set to the current font of the context as given by + the <code title="dom-context-2d-font"><a href="#dom-context-2d-font">font</a></code> attribute, and + must then return a new <code><a href="#textmetrics">TextMetrics</a></code> object with its + <code title="dom-textmetrics-width"><a href="#dom-textmetrics-width">width</a></code> attribute set to + the width of that inline box, in CSS pixels. <a href="#refsCSS">[CSS]</a></p> + + <p>The <code><a href="#textmetrics">TextMetrics</a></code> interface is used for the objects + returned from <code title="dom-context-2d-measureText"><a href="#dom-context-2d-measuretext">measureText()</a></code>. It has one + attribute, <dfn id="dom-textmetrics-width" title="dom-textmetrics-width"><code>width</code></dfn>, which is set + by the <code title="dom-context-2d-measureText"><a href="#dom-context-2d-measuretext">measureText()</a></code> + method.</p> + + <p class="note">Glyphs rendered using <code title="dom-context-2d-fillText"><a href="#dom-context-2d-filltext">fillText()</a></code> and <code title="dom-context-2d-strokeText"><a href="#dom-context-2d-stroketext">strokeText()</a></code> can spill out + of the box given by the font size (the em square size) and the width + returned by <code title="dom-context-2d-measureText"><a href="#dom-context-2d-measuretext">measureText()</a></code> (the text + width). This version of the specification does not provide a way to + obtain the bounding box dimensions of the text. If the text is to be + rendered and removed, care needs to be taken to replace the entire + area of the canvas that the clipping region covers, not just the box + given by the em square height and measured text width.</p> + + <!-- v6: Drawing text along a given path --> + <!-- v6: Adding text to a path --> + <!-- see also: http://www.w3.org/TR/SVG11/text.html#TextpathLayoutRules --> + <!-- see also: http://developer.mozilla.org/en/docs/Drawing_text_using_a_canvas --> + + </div> + + <p class="note">A future version of the 2D context API may 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="images"><span class="secno">4.8.11.1.10 </span>Images</h6> + + <p>To draw images onto the canvas, the <dfn id="dom-context-2d-drawimage" title="dom-context-2d-drawImage"><code>drawImage</code></dfn> method + can be used.</p> + + <p>This method can be invoked with three different sets of arguments:</p> + + <ul class="brief"><li><code title="">drawImage(<var title="">image</var>, <var title="">dx</var>, <var title="">dy</var>)</code> + </li><li><code title="">drawImage(<var title="">image</var>, <var title="">dx</var>, <var title="">dy</var>, <var title="">dw</var>, <var title="">dh</var>)</code> + </li><li><code title="">drawImage(<var title="">image</var>, <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, <var title="">sh</var>, <var title="">dx</var>, <var title="">dy</var>, <var title="">dw</var>, <var title="">dh</var>)</code> + </li></ul><!-- v3: drawImage() of an ImageData object might make sense (when resizing as well as filtering) - ack Charles Pritchard --><p>Each of those three can take either an + <code><a href="#htmlimageelement">HTMLImageElement</a></code>, an <code><a href="#htmlcanvaselement">HTMLCanvasElement</a></code>, or + an <code><a href="#htmlvideoelement">HTMLVideoElement</a></code> for the <var title="">image</var> + argument.</p> + + <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-drawImage"><a href="#dom-context-2d-drawimage">drawImage</a></code>(<var title="">image</var>, <var title="">dx</var>, <var title="">dy</var>)</dt> + <dt><var title="">context</var> . <code title="dom-context-2d-drawImage"><a href="#dom-context-2d-drawimage">drawImage</a></code>(<var title="">image</var>, <var title="">dx</var>, <var title="">dy</var>, <var title="">dw</var>, <var title="">dh</var>)</dt> + <dt><var title="">context</var> . <code title="dom-context-2d-drawImage"><a href="#dom-context-2d-drawimage">drawImage</a></code>(<var title="">image</var>, <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, <var title="">sh</var>, <var title="">dx</var>, <var title="">dy</var>, <var title="">dw</var>, <var title="">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="http://www.whatwg.org/specs/web-apps/current-work/http://images.whatwg.org/drawImage.png" width="356"/></p> + + <p>If the first argument isn't an <code><a href="#the-img-element">img</a></code>, + <code><a href="#the-canvas-element">canvas</a></code>, or <code><a href="#the-video-element">video</a></code> element, throws a + <code><a href="#type_mismatch_err">TYPE_MISMATCH_ERR</a></code> exception. If the image has no + image data, throws an <code><a href="#invalid_state_err">INVALID_STATE_ERR</a></code> exception. If + the one of the source rectangle dimensions is zero, throws an + <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception. If the image isn't yet + fully decoded, then nothing is drawn.</p> + + </dd> + + </dl><div class="impl"> + + <p>If not specified, the <var title="">dw</var> and <var title="">dh</var> arguments must default to the values of <var title="">sw</var> and <var title="">sh</var>, interpreted such that + one CSS pixel in the image is treated as one unit in the canvas + coordinate space. If the <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, and <var title="">sh</var> arguments are omitted, they must default to 0, 0, + the image's intrinsic width in image pixels, and the image's + intrinsic height in image pixels, respectively. If the image has no + intrinsic dimensions, the <i>concrete object size</i> must be used + instead, as determined using the CSS "<a href="http://dev.w3.org/csswg/css3-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 contraints, the object's intrinsic properties being those + of the <var title="">image</var> argument, and the <i>default object + size</i> being the size of the <code><a href="#the-canvas-element">canvas</a></code> element. <a href="#refsCSSIMAGES">[CSSIMAGES]</a></p> + + <p>The <var title="">image</var> argument is an instance of either + <code><a href="#htmlimageelement">HTMLImageElement</a></code>, <code><a href="#htmlcanvaselement">HTMLCanvasElement</a></code>, or + <code><a href="#htmlvideoelement">HTMLVideoElement</a></code>.</p> <!-- createPattern() has an + equivalent paragraph --> + + <p>If the <var title="">image</var> argument is an + <code><a href="#htmlimageelement">HTMLImageElement</a></code> object that is not <a href="#img-good" title="img-good">fully decodable</a>, or if the <var title="">image</var> argument is an <code><a href="#htmlvideoelement">HTMLVideoElement</a></code> + object whose <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> + attribute is either <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code> or <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, then the + implementation must return without drawing anything.</p> <!-- + createPattern() has an equivalent paragraph --> + + <p>If the <var title="">image</var> argument is an + <code><a href="#htmlcanvaselement">HTMLCanvasElement</a></code> object with either a horizontal + dimension or a vertical dimension equal to zero, then the + implementation must raise an <code><a href="#invalid_state_err">INVALID_STATE_ERR</a></code> + exception.</p> + <!-- createPattern() has an equivalent paragraph --> + + <p>The source rectangle is the rectangle whose corners are the four + points (<var title="">sx</var>, <var title="">sy</var>), (<span title=""><var title="">sx</var>+<var title="">sw</var></span>, <var title="">sy</var>), (<span title=""><var title="">sx</var>+<var title="">sw</var></span>, <span title=""><var title="">sy</var>+<var title="">sh</var></span>), (<var title="">sx</var>, <span title=""><var title="">sy</var>+<var title="">sh</var></span>).</p> + + <p>If one of the <var title="">sw</var> or <var title="">sh</var> + arguments is zero, the implementation must raise an + <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p> + + <p>The destination rectangle is the rectangle whose corners are the + four points (<var title="">dx</var>, <var title="">dy</var>), + (<span title=""><var title="">dx</var>+<var title="">dw</var></span>, <var title="">dy</var>), (<span title=""><var title="">dx</var>+<var title="">dw</var></span>, <span title=""><var title="">dy</var>+<var title="">dh</var></span>), (<var title="">dx</var>, <span title=""><var title="">dy</var>+<var title="">dh</var></span>).</p> + + <p>When <code title="dom-context-2d-drawImage"><a href="#dom-context-2d-drawimage">drawImage()</a></code> is + invoked, the region of the image specified by the source rectangle + must be painted on the region of the canvas specified by the + destination rectangle, after applying the <a href="#transformations" title="dom-context-2d-transformation">current transformation + matrix</a> to the points of the destination rectangle.</p> + + <p>The original image data of the source image must be used, not the + image as it is rendered (e.g. <code title="attr-dim-width"><a href="#attr-dim-width">width</a></code> and <code title="attr-dim-height"><a href="#attr-dim-height">height</a></code> attributes on the source + element have no effect). The image data must be processed in the + original direction, even if the dimensions given are negative. <!-- + remove that last sentence if it causes confusion. Someone once + suggested that 5,5,-2,-2 was different than 3,3,2,2; this is trying + to clarify that this is no the case. --></p> + + <p class="note">This specification does not define the algorithm to + use when scaling the image, if necessary.</p> + + <p class="note">When a canvas is drawn onto itself, the <a href="#drawing-model">drawing + model</a> requires the source to be copied before the image is drawn + back onto the canvas, so it is possible to copy parts of a canvas + onto overlapping parts of itself.</p> + + <p>If the original image data is a bitmap image, 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.)</p> + <!-- see CORE-32111 and: + http://krijnhoetmer.nl/irc-logs/whatwg/20100818#l-737 + http://www.w3.org/Bugs/Public/show_bug.cgi?id=10799#c11 + --> + <!-- createPattern() has a similar paragraph with different rules --> + + <p>When the <code title="dom-context-2d-drawImage"><a href="#dom-context-2d-drawimage">drawImage()</a></code> method + is passed an animated image as its <var title="">image</var> + argument, the user agent must use the poster frame of the animation, + or, if there is no poster frame, the first frame of the + animation.</p> + <!-- createPattern() has an equivalent paragraph --> + + <p>When the <var title="">image</var> argument is an + <code><a href="#htmlvideoelement">HTMLVideoElement</a></code>, then the frame at the <a href="#current-playback-position">current + playback position</a> must be used as the source image, and the + source image's dimensions must be the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic width</a> and + <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</a> + of the <a href="#media-resource">media resource</a> (i.e. after any aspect-ratio + correction has been applied).</p> + <!-- createPattern() has an equivalent paragraph --> + + <p>Images are painted without affecting the current path, and are + subject to <a href="#shadows" title="shadows">shadow effects</a>, <a href="#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">global alpha</a>, the <a href="#clipping-region" title="clipping region">clipping region</a>, and <a href="#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">global composition + operators</a>.</p> + + </div> + + + + <h6 id="pixel-manipulation"><span class="secno">4.8.11.1.11 </span><dfn>Pixel manipulation</dfn></h6> + + <dl class="domintro"><dt><var title="">imagedata</var> = <var title="">context</var> . <code title="dom-context-2d-createImageData"><a href="#dom-context-2d-createimagedata">createImageData</a></code>(<var title="">sw</var>, <var title="">sh</var>)</dt> + + <dd> + + <p>Returns an <code><a href="#imagedata">ImageData</a></code> object with the given + dimensions in CSS pixels (which might map to a different number of + actual device pixels exposed by the object itself). All the pixels + in the returned object are transparent black.</p> + + </dd> + + <dt><var title="">imagedata</var> = <var title="">context</var> . <code title="dom-context-2d-createImageData"><a href="#dom-context-2d-createimagedata">createImageData</a></code>(<var title="">imagedata</var>)</dt> + + <dd> + + <p>Returns an <code><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 title="">imagedata</var> = <var title="">context</var> . <code title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">getImageData</a></code>(<var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, <var title="">sh</var>)</dt> + + <dd> + + <p>Returns an <code><a href="#imagedata">ImageData</a></code> object containing the image + data for the given rectangle of the canvas.</p> + + <p>Throws a <code><a href="#not_supported_err">NOT_SUPPORTED_ERR</a></code> exception if any of the + arguments are not finite. Throws an <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> + exception if the either of the width or height arguments are + zero.</p> + + </dd> + + <dt><var title="">imagedata</var> . <code title="dom-imagedata-width"><a href="#dom-imagedata-width">width</a></code></dt> + <dt><var title="">imagedata</var> . <code title="dom-imagedata-height"><a href="#dom-imagedata-height">height</a></code></dt> + + <dd> + + <p>Returns the actual dimensions of the data in the <code><a href="#imagedata">ImageData</a></code> object, in device pixels.</p> + + </dd> + + <dt><var title="">imagedata</var> . <code title="dom-imagedata-data"><a href="#dom-imagedata-data">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 title="">context</var> . <code title="dom-context-2d-putImageData"><a href="#dom-context-2d-putimagedata">putImageData</a></code>(<var title="">imagedata</var>, <var title="">dx</var>, <var title="">dy</var> [, <var title="">dirtyX</var>, <var title="">dirtyY</var>, <var title="">dirtyWidth</var>, <var title="">dirtyHeight</var> ])</dt> + + <dd> + + <p>Paints the data from the given <code><a href="#imagedata">ImageData</a></code> object + onto the canvas. If a dirty rectangle is provided, only the pixels + from that rectangle are painted.</p> + + <p>The <code title="dom-context-2d-globalAlpha"><a href="#dom-context-2d-globalalpha">globalAlpha</a></code> + and <code title="dom-context-2d-globalCompositeOperation"><a href="#dom-context-2d-globalcompositeoperation">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>If the first argument is null, throws a + <code><a href="#type_mismatch_err">TYPE_MISMATCH_ERR</a></code> exception. Throws a + <code><a href="#not_supported_err">NOT_SUPPORTED_ERR</a></code> exception if any of the other + arguments are not finite.</p> + + </dd> + + </dl><div class="impl"> + + <p>The <dfn id="dom-context-2d-createimagedata" title="dom-context-2d-createImageData"><code>createImageData()</code></dfn> + method is used to instantiate new blank <code><a href="#imagedata">ImageData</a></code> + objects. When the method is invoked with two arguments <var title="">sw</var> and <var title="">sh</var>, it must return an + <code><a href="#imagedata">ImageData</a></code> object representing a rectangle with a width + in CSS pixels equal to the absolute magnitude of <var title="">sw</var> and a height in CSS pixels equal to the absolute + magnitude of <var title="">sh</var>. When invoked with a single <var title="">imagedata</var> argument, it must return an + <code><a href="#imagedata">ImageData</a></code> object representing a rectangle with the same + dimensions as the <code><a href="#imagedata">ImageData</a></code> object passed as the + argument. The <code><a href="#imagedata">ImageData</a></code> object returned must be filled + with transparent black.</p> + + <p>The <dfn id="dom-context-2d-getimagedata" title="dom-context-2d-getImageData"><code>getImageData(<var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, + <var title="">sh</var>)</code></dfn> method must return an + <code><a href="#imagedata">ImageData</a></code> object representing the underlying pixel data + for the area of the canvas denoted by the rectangle whose corners are + the four points (<var title="">sx</var>, <var title="">sy</var>), + (<span title=""><var title="">sx</var>+<var title="">sw</var></span>, <var title="">sy</var>), (<span title=""><var title="">sx</var>+<var title="">sw</var></span>, <span title=""><var title="">sy</var>+<var title="">sh</var></span>), (<var title="">sx</var>, <span title=""><var title="">sy</var>+<var title="">sh</var></span>), in canvas + coordinate space units. Pixels outside the canvas must be returned + as transparent black. Pixels must be returned as non-premultiplied + alpha values.</p> + + <p>If any of the arguments to <code title="dom-context-2d-createImageData"><a href="#dom-context-2d-createimagedata">createImageData()</a></code> or + <code title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">getImageData()</a></code> + are infinite or NaN, the method must instead raise a + <code><a href="#not_supported_err">NOT_SUPPORTED_ERR</a></code> exception. If either the <var title="">sw</var> or <var title="">sh</var> arguments are zero, + the method must instead raise an <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> + exception.</p> + + <p><code><a href="#imagedata">ImageData</a></code> objects must be initialized so that their + <dfn id="dom-imagedata-width" title="dom-imagedata-width"><code>width</code></dfn> attribute + is set to <var title="">w</var>, the number of physical device + pixels per row in the image data, their <dfn id="dom-imagedata-height" title="dom-imagedata-height"><code>height</code></dfn> attribute is + set to <var title="">h</var>, the number of rows in the image data, + and their <dfn id="dom-imagedata-data" title="dom-imagedata-data"><code>data</code></dfn> + attribute is initialized to a <code><a href="#canvaspixelarray">CanvasPixelArray</a></code> object + holding the image data. At least one pixel's worth of image data + must be returned.</p> + + <p>The <code><a href="#canvaspixelarray">CanvasPixelArray</a></code> object provides ordered, + indexed access to the color components of each pixel of the image + data. The data must be 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 device 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 <code><a href="#canvaspixelarray">CanvasPixelArray</a></code> object thus represents <var title="">h</var>×<var title="">w</var>×4 integers. The + <dfn id="dom-canvaspixelarray-length" title="dom-canvaspixelarray-length"><code>length</code></dfn> + attribute of a <code><a href="#canvaspixelarray">CanvasPixelArray</a></code> object must return this + number.</p> + + <p>The object's <a href="#supported-property-indices">supported property indices</a> are the + numbers in the range 0 .. <span title=""><var title="">h</var>×<var title="">w</var>×4-1</span>.</p> + + <p>To <dfn id="dom-canvaspixelarray-get" title="dom-CanvasPixelArray-get">determine the value of + an indexed property</dfn> <var title="">index</var>, the user agent + must return the value of the <var title="">index</var>th component + in the array.</p> + + <p>To <dfn id="dom-canvaspixelarray-set" title="dom-CanvasPixelArray-set">set the value of an + existing indexed property</dfn> <var title="">index</var> to value + <var title="">value</var>, the value of the <var title="">index</var>th component in the array must be set to <var title="">value</var>.</p> + + <p class="note">The width and height (<var title="">w</var> and <var title="">h</var>) might be different from the <var title="">sw</var> + and <var title="">sh</var> arguments to the above methods, e.g. if + the canvas is backed by a high-resolution bitmap, or if the <var title="">sw</var> and <var title="">sh</var> arguments are + negative.</p> + + <p>The <dfn id="dom-context-2d-putimagedata" title="dom-context-2d-putImageData"><code>putImageData(<var title="">imagedata</var>, <var title="">dx</var>, <var title="">dy</var>, <var title="">dirtyX</var>, <var title="">dirtyY</var>, <var title="">dirtyWidth</var>, <var title="">dirtyHeight</var>)</code></dfn> method writes data from + <code><a href="#imagedata">ImageData</a></code> structures back to the canvas.</p> + + <p>If any of the arguments to the method are infinite or NaN, the + method must raise a <code><a href="#not_supported_err">NOT_SUPPORTED_ERR</a></code> exception.</p> + + <p>When the last four arguments are omitted, they must be assumed to + have the values 0, 0, the <code title="dom-imagedata-width"><a href="#dom-imagedata-width">width</a></code> member of the <var title="">imagedata</var> structure, and the <code title="dom-imagedata-height"><a href="#dom-imagedata-height">height</a></code> member of the <var title="">imagedata</var> structure, respectively.</p> + + <p>When invoked with arguments that do not, per the last few + paragraphs, cause an exception to be raised, the <code title="dom-context-2d-putImageData"><a href="#dom-context-2d-putimagedata">putImageData()</a></code> method + must act as follows:</p> + + <ol><li> + + <p>Let <var title="">dx<sub>device</sub></var> be the x-coordinate + of the device pixel in the underlying pixel data of the canvas + corresponding to the <var title="">dx</var> coordinate in the + canvas coordinate space.</p> + + <p>Let <var title="">dy<sub>device</sub></var> be the y-coordinate + of the device pixel in the underlying pixel data of the canvas + corresponding to the <var title="">dy</var> coordinate in the + canvas coordinate space.</p> + + </li> + + <li> + + <p>If <var title="">dirtyWidth</var> is negative, let <var title="">dirtyX</var> be <span title=""><var title="">dirtyX</var>+<var title="">dirtyWidth</var></span>, and let <var title="">dirtyWidth</var> be equal to the absolute magnitude of + <var title="">dirtyWidth</var>.</p> + + <p>If <var title="">dirtyHeight</var> is negative, let <var title="">dirtyY</var> be <span title=""><var title="">dirtyY</var>+<var title="">dirtyHeight</var></span>, and let <var title="">dirtyHeight</var> be equal to the absolute magnitude of + <var title="">dirtyHeight</var>.</p> + + </li> + + <li> + + <p>If <var title="">dirtyX</var> is negative, let <var title="">dirtyWidth</var> be <span title=""><var title="">dirtyWidth</var>+<var title="">dirtyX</var></span>, and + let <var title="">dirtyX</var> be zero.</p> + + <p>If <var title="">dirtyY</var> is negative, let <var title="">dirtyHeight</var> be <span title=""><var title="">dirtyHeight</var>+<var title="">dirtyY</var></span>, and + let <var title="">dirtyY</var> be zero.</p> + + </li> + + <li> + + <p>If <span title=""><var title="">dirtyX</var>+<var title="">dirtyWidth</var></span> is greater than the <code title="dom-imagedata-width"><a href="#dom-imagedata-width">width</a></code> attribute of the <var title="">imagedata</var> argument, let <var title="">dirtyWidth</var> be the value of that <code title="dom-imagedata-width"><a href="#dom-imagedata-width">width</a></code> attribute, minus the + value of <var title="">dirtyX</var>.</p> + + <p>If <span title=""><var title="">dirtyY</var>+<var title="">dirtyHeight</var></span> is greater than the <code title="dom-imagedata-height"><a href="#dom-imagedata-height">height</a></code> attribute of the <var title="">imagedata</var> argument, let <var title="">dirtyHeight</var> be the value of that <code title="dom-imagedata-height"><a href="#dom-imagedata-height">height</a></code> attribute, minus the + value of <var title="">dirtyY</var>.</p> + + </li> + + <li> + + <p>If, after those changes, either <var title="">dirtyWidth</var> + or <var title="">dirtyHeight</var> is negative or zero, stop these + steps without affecting the canvas.</p> + + </li> + + <li><p>Otherwise, for all integer values of <var title="">x</var> + and <var title="">y</var> where <span title=""><var title="">dirtyX</var> ≤ <var title="">x</var> < <span title=""><var title="">dirtyX</var>+<var title="">dirtyWidth</var></span></span> + and <span title=""><var title="">dirtyY</var> ≤ <var title="">y</var> < <span title=""><var title="">dirtyY</var>+<var title="">dirtyHeight</var></span></span>, copy the four channels of + the pixel with coordinate (<var title="">x</var>, <var title="">y</var>) in the <var title="">imagedata</var> data + structure to the pixel with coordinate (<span title=""><var title="">dx<sub>device</sub></var>+<var title="">x</var></span>, + <span title=""><var title="">dy<sub>device</sub></var>+<var title="">y</var></span>) in the underlying pixel data of the + canvas.</p></li> + + </ol><p>The handling of pixel rounding when the specified coordinates do + not exactly map to the device coordinate space is not defined by + this specification, except that the following must result in no + visible changes to the rendering:</p> + + <pre>context.putImageData(context.getImageData(x, y, w, h), p, q);</pre> + + <p>...for any value of <var title="">x</var>, <var title="">y</var>, + <var title="">w</var>, and <var title="">h</var> and where <var title="">p</var> is the smaller of <var title="">x</var> and the sum + of <var title="">x</var> and <var title="">w</var>, and <var title="">q</var> is the smaller of <var title="">y</var> and the sum + of <var title="">y</var> and <var title="">h</var>; and except that + the following two calls:</p> + + <pre>context.createImageData(w, h); +context.getImageData(0, 0, w, h);</pre> + + <p>...must return <code><a href="#imagedata">ImageData</a></code> objects with the same + dimensions, for any value of <var title="">w</var> and <var title="">h</var>. In other words, while user agents may round the + arguments of these methods so that they map to device pixel + boundaries, any rounding performed must be performed consistently + for all of the <code title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">createImageData()</a></code>, <code title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">getImageData()</a></code> and <code title="dom-context-2d-putImageData"><a href="#dom-context-2d-putimagedata">putImageData()</a></code> + operations.</p> + + <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 title="dom-context-2d-putImageData"><a href="#dom-context-2d-putimagedata">putImageData()</a></code> might be + returned to an equivalent <code title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">getImageData()</a></code> as + different values.</p> + + <p>The current path, <a href="#transformations" title="dom-context-2d-transformation">transformation matrix</a>, + <a href="#shadows" title="shadows">shadow attributes</a>, <a href="#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">global alpha</a>, the <a href="#clipping-region" title="clipping region">clipping region</a>, and <a href="#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">global composition + operator</a> must not affect the <code title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">getImageData()</a></code> and <code title="dom-context-2d-putImageData"><a href="#dom-context-2d-putimagedata">putImageData()</a></code> + methods.</p> + + </div> + + <div class="example"> + + <p>The data returned by <code title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">getImageData()</a></code> is at the + resolution of the canvas backing store, which is likely to not be + one device pixel to each CSS pixel if the display used is a high + resolution display.</p> + + <p>In the following example, the script generates an + <code><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 title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">getImageData()</a></code> and <code title="dom-context-2d-putImageData"><a href="#dom-context-2d-putimagedata">putImageData()</a></code> to + implement an edge detection filter.</p> + + <pre><!DOCTYPE HTML> +<html> + <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 + // notice that we are using input.width and input.height here + // as they might not be the same as canvas.width and canvas.height + // (in particular, they might be different on high-res displays) + 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> + + + <div class="impl"> + + <h6 id="drawing-model"><span class="secno">4.8.11.1.12 </span><dfn>Drawing model</dfn></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 title="">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><a href="#when-shadows-are-drawn">When shadows are drawn</a>, render the shadow from + image <var title="">A</var>, using the current shadow styles, + creating image <var title="">B</var>.</p></li> + + <li><p><a href="#when-shadows-are-drawn">When shadows are drawn</a>, multiply the alpha + component of every pixel in <var title="">B</var> by <code title="dom-context-2d-globalAlpha"><a href="#dom-context-2d-globalalpha">globalAlpha</a></code>.</p></li> + + <li><p><a href="#when-shadows-are-drawn">When shadows are drawn</a>, composite <var title="">B</var> within the <a href="#clipping-region">clipping region</a> over the + current canvas bitmap using the current composition + operator.</p></li> + + <li><p>Multiply the alpha component of every pixel in <var title="">A</var> by <code title="dom-context-2d-globalAlpha"><a href="#dom-context-2d-globalalpha">globalAlpha</a></code>.</p></li> + + <li><p>Composite <var title="">A</var> within the <a href="#clipping-region">clipping + region</a> over the current canvas bitmap using the current + composition operator.</p></li> + + </ol></div> + + + <h6 id="best-practices"><span class="secno">4.8.11.1.13 </span>Best practices</h6> + + <p><i>This section is non-normative.</i></p> + + <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>To indicate which focusable part of the canvas is currently + focused, authors should use the <code title="dom-context-2d-drawSystemFocusRing"><a href="#dom-context-2d-drawsystemfocusring">drawSystemFocusRing()</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 focused, so that + it can simply be called whenever drawing the element, without + checking whether the element is focused or not first.</p> + + <p>Authors should avoid implementing text editing controls using the + <code><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 field 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><a href="#the-input-element">input</a></code> element, the <code><a href="#the-textarea-element">textarea</a></code> element, or + the <code title="attr-contenteditable"><a href="#attr-contenteditable">contenteditable</a></code> + attribute.</p> + + + <h6 id="examples"><span class="secno">4.8.11.1.14 </span>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><!--data-component--> + + <!--2DCONTEXT--> + + <div class="impl"> + + <h5 id="color-spaces-and-color-correction"><span class="secno">4.8.11.2 </span>Color spaces and color correction</h5> + + <p>The <code><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 the canvas, to convert + the image to the color space used by the canvas (e.g. using the 2D + Context's <code title="dom-context-2d-drawImage"><a href="#dom-context-2d-drawimage">drawImage()</a></code> + method with an <code><a href="#htmlimageelement">HTMLImageElement</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 title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">getImageData()</a></code> + method.</p> + + <p>The <code title="dom-canvas-toDataURL"><a href="#dom-canvas-todataurl">toDataURL()</a></code> method + must not include color space information in the resource + returned. Where the output format allows it, the color of pixels in + resources created by <code title="dom-canvas-toDataURL"><a href="#dom-canvas-todataurl">toDataURL()</a></code> must match those + returned by the <code title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">getImageData()</a></code> + method.</p> + + <p>In user agents that support CSS, the color space used by a + <code><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><a href="#the-img-element">img</a></code> element would use the same colors as one painted on + a <code><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 title="dom-canvas-toDataURL"><a href="#dom-canvas-todataurl">toDataURL()</a></code> method) must be + rendered with no color correction.</p> + + <p class="note">Thus, in the 2D context, calling the <code title="dom-context-2d-drawImage"><a href="#dom-context-2d-drawimage">drawImage()</a></code> method to render + the output of the <code title="dom-canvas-toDataURL"><a href="#dom-canvas-todataurl">toDataURL()</a></code> method to the + canvas, given the appropriate dimensions, has no visible effect.</p> + + </div> + + + <div class="impl"> + + <h5 id="security-with-canvas-elements"><span class="secno">4.8.11.3 </span>Security with <code><a href="#the-canvas-element">canvas</a></code> elements</h5> + + <p><strong>Information leakage</strong> can occur if scripts from + one <a href="#origin">origin</a> can access information (e.g. read pixels) + from images from another origin (one that isn't the <a href="#same-origin" title="same origin">same</a>).</p> + + <p>To mitigate this, <code><a href="#the-canvas-element">canvas</a></code> elements are defined to + have a flag indicating whether they are <i>origin-clean</i>. All + <code><a href="#the-canvas-element">canvas</a></code> elements must start with their + <i>origin-clean</i> set to true. The flag must be set to false if + any of the following actions occur:</p> + + <ul><li><p>The element's 2D context's <code title="dom-context-2d-drawImage"><a href="#dom-context-2d-drawimage">drawImage()</a></code> method is + called with an <code><a href="#htmlimageelement">HTMLImageElement</a></code> or an + <code><a href="#htmlvideoelement">HTMLVideoElement</a></code> whose <a href="#origin">origin</a> is not the + <a href="#same-origin" title="same origin">same</a> as that of the + <code><a href="#document">Document</a></code> object that owns the <code><a href="#the-canvas-element">canvas</a></code> + element.</p></li> + + <li><p>The element's 2D context's <code title="dom-context-2d-drawImage"><a href="#dom-context-2d-drawimage">drawImage()</a></code> method is + called with an <code><a href="#htmlcanvaselement">HTMLCanvasElement</a></code> whose + <i>origin-clean</i> flag is false.</p></li> + + <li><p>The element's 2D context's <code title="dom-context-2d-fillStyle"><a href="#dom-context-2d-fillstyle">fillStyle</a></code> attribute is set + to a <code><a href="#canvaspattern">CanvasPattern</a></code> object that was created from an + <code><a href="#htmlimageelement">HTMLImageElement</a></code> or an <code><a href="#htmlvideoelement">HTMLVideoElement</a></code> + whose <a href="#origin">origin</a> was not the <a href="#same-origin" title="same + origin">same</a> as that of the <code><a href="#document">Document</a></code> object + that owns the <code><a href="#the-canvas-element">canvas</a></code> element when the pattern was + created.</p></li> + + <li><p>The element's 2D context's <code title="dom-context-2d-fillStyle"><a href="#dom-context-2d-fillstyle">fillStyle</a></code> attribute is set + to a <code><a href="#canvaspattern">CanvasPattern</a></code> object that was created from an + <code><a href="#htmlcanvaselement">HTMLCanvasElement</a></code> whose <i>origin-clean</i> flag was + false when the pattern was created.</p></li> + + <li><p>The element's 2D context's <code title="dom-context-2d-strokeStyle"><a href="#dom-context-2d-strokestyle">strokeStyle</a></code> attribute is + set to a <code><a href="#canvaspattern">CanvasPattern</a></code> object that was created from an + <code><a href="#htmlimageelement">HTMLImageElement</a></code> or an <code><a href="#htmlvideoelement">HTMLVideoElement</a></code> + whose <a href="#origin">origin</a> was not the <a href="#same-origin" title="same + origin">same</a> as that of the <code><a href="#document">Document</a></code> object + that owns the <code><a href="#the-canvas-element">canvas</a></code> element when the pattern was + created.</p></li> + + <li><p>The element's 2D context's <code title="dom-context-2d-strokeStyle"><a href="#dom-context-2d-strokestyle">strokeStyle</a></code> attribute is + set to a <code><a href="#canvaspattern">CanvasPattern</a></code> object that was created from an + <code><a href="#htmlcanvaselement">HTMLCanvasElement</a></code> whose <i>origin-clean</i> flag was + false when the pattern was created.</p></li> + + <li><p>The element's 2D context's <code title="dom-context-2d-fillText"><a href="#dom-context-2d-filltext">fillText()</a></code> or <code title="dom-context-2d-fillText"><a href="#dom-context-2d-filltext">strokeText()</a></code> methods are + invoked and consider using a font that has an <a href="#origin">origin</a> + that is not the <a href="#same-origin" title="same origin">same</a> as that of + the <code><a href="#document">Document</a></code> object that owns the <code><a href="#the-canvas-element">canvas</a></code> + element. (The font doesn't even have to be used; all that matters + is whether the font was considered for any of the glyphs + drawn.)</p></li> <!-- because fonts could consider sensitive + material, I guess; and because that sensitivity could extend to + whether or not a particular glyph is in the font in the first + place. --> + + </ul><p>Whenever the <code title="dom-canvas-toDataURL"><a href="#dom-canvas-todataurl">toDataURL()</a></code> method of a + <code><a href="#the-canvas-element">canvas</a></code> element whose <i>origin-clean</i> flag is set to + false is called, the method must raise a <code><a href="#security_err">SECURITY_ERR</a></code> + exception.</p> + + <p>Whenever the <code title="dom-context-2d-getImageData"><a href="#dom-context-2d-getimagedata">getImageData()</a></code> method of + the 2D context of a <code><a href="#the-canvas-element">canvas</a></code> element whose + <i>origin-clean</i> flag is set to false is called with otherwise + correct arguments, the method must raise a <code><a href="#security_err">SECURITY_ERR</a></code> + exception.</p> + + <p>Whenever the <code title="dom-context-2d-measureText"><a href="#dom-context-2d-measuretext">measureText()</a></code> method of + the 2D context of a <code><a href="#the-canvas-element">canvas</a></code> element ends up using a font + that has an <a href="#origin">origin</a> that is not the <a href="#same-origin" title="same + origin">same</a> as that of the <code><a href="#document">Document</a></code> object that + owns the <code><a href="#the-canvas-element">canvas</a></code> element, the method must raise a + <code><a href="#security_err">SECURITY_ERR</a></code> exception.</p> + + <p class="note">Even resetting the canvas state by changing its + <code title="attr-canvas-width"><a href="#attr-canvas-width">width</a></code> or <code title="attr-canvas-height"><a href="#attr-canvas-height">height</a></code> attributes doesn't reset + the <i>origin-clean</i> flag.</p> + + </div> + + + + </body></html> |