- From: poot <cvsmail@w3.org>
- Date: Fri, 09 Mar 2012 19:31:43 -0500
- To: public-html-diffs@w3.org
2Dapi; hixie: Make it possible to draw Path primitives to the canvas.
(whatwg r7024)
http://dev.w3.org/cvsweb/html5/2dcontext/Overview.html?r1=1.127&r2=1.128&f=h
http://html5.org/tools/web-apps-tracker?from=7023&to=7024
===================================================================
RCS file: /sources/public/html5/2dcontext/Overview.html,v
retrieving revision 1.127
retrieving revision 1.128
diff -u -d -r1.127 -r1.128
--- Overview.html 9 Mar 2012 23:58:54 -0000 1.127
+++ Overview.html 10 Mar 2012 00:31:30 -0000 1.128
@@ -320,7 +320,7 @@
<h1>HTML Canvas 2D Context</h1>
<h2 class="no-num no-toc" id="generatedID"></h2>
- <h2 class="no-num no-toc" id="editor-s-draft-9-march-2012">Editor's Draft 9 March 2012</h2>
+ <h2 class="no-num no-toc" id="editor-s-draft-10-march-2012">Editor's Draft 10 March 2012</h2>
<dl><dt>Latest Published Version:</dt>
<dd><a href="http://www.w3.org/TR/2dcontext/">http://www.w3.org/TR/2dcontext/</a></dd>
<dt>Latest Editor's Draft:</dt>
@@ -456,7 +456,7 @@
Group</a> is the W3C working group responsible for this
specification's progress along the W3C Recommendation
track.
- This specification is the 9 March 2012 Editor's Draft.
+ This specification is the 10 March 2012 Editor's Draft.
</p><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><p>Work on this specification is also done at the <a href="http://www.whatwg.org/">WHATWG</a>. The W3C HTML working group
actively pursues convergence with the WHATWG, as required by the <a href="http://www.w3.org/2007/03/HTML-WG-charter">W3C HTML working
group charter</a>.</p><!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><p>This specification is an extension to the HTML5 language. All
@@ -537,15 +537,22 @@
void <a href="#dom-context-2d-fillrect" title="dom-context-2d-fillRect">fillRect</a>(double x, double y, double w, double h);
void <a href="#dom-context-2d-strokerect" title="dom-context-2d-strokeRect">strokeRect</a>(double x, double y, double w, double h);
- // current default path API (see also <a href="#canvaspathmethods">CanvasPathMethods</a>)
+ // path API (see also <a href="#canvaspathmethods">CanvasPathMethods</a>)
void <a href="#dom-context-2d-beginpath" title="dom-context-2d-beginPath">beginPath</a>();
void <a href="#dom-context-2d-fill" title="dom-context-2d-fill">fill</a>();
+ void <a href="#dom-context-2d-fill" title="dom-context-2d-fill">fill</a>(<a href="#path">Path</a> path);
void <a href="#dom-context-2d-stroke" title="dom-context-2d-stroke">stroke</a>();
+ void <a href="#dom-context-2d-stroke" title="dom-context-2d-stroke">stroke</a>(<a href="#path">Path</a> path);
void <a href="#dom-context-2d-drawsystemfocusring" title="dom-context-2d-drawSystemFocusRing">drawSystemFocusRing</a>(<span>Element</span> element);
+ void <a href="#dom-context-2d-drawsystemfocusring" title="dom-context-2d-drawSystemFocusRing">drawSystemFocusRing</a>(<a href="#path">Path</a> path, <span>Element</span> element);
boolean <a href="#dom-context-2d-drawcustomfocusring" title="dom-context-2d-drawCustomFocusRing">drawCustomFocusRing</a>(<span>Element</span> element);
+ boolean <a href="#dom-context-2d-drawcustomfocusring" title="dom-context-2d-drawCustomFocusRing">drawCustomFocusRing</a>(<a href="#path">Path</a> path, <span>Element</span> element);
void <a href="#dom-context-2d-scrollpathintoview" title="dom-context-2d-scrollPathIntoView">scrollPathIntoView</a>();
+ void <a href="#dom-context-2d-scrollpathintoview" title="dom-context-2d-scrollPathIntoView">scrollPathIntoView</a>(<a href="#path">Path</a> path);
void <a href="#dom-context-2d-clip" title="dom-context-2d-clip">clip</a>();
+ void <a href="#dom-context-2d-clip" title="dom-context-2d-clip">clip</a>(<a href="#path">Path</a> path);
boolean <a href="#dom-context-2d-ispointinpath" title="dom-context-2d-isPointInPath">isPointInPath</a>(double x, double y);
+ boolean <a href="#dom-context-2d-ispointinpath" title="dom-context-2d-isPointInPath">isPointInPath</a>(<a href="#path">Path</a> path, double x, double y);
// text (see also the <a href="#canvastext">CanvasText</a> interface)
void <a href="#dom-context-2d-filltext" title="dom-context-2d-fillText">fillText</a>(DOMString text, double x, double y, optional double maxWidth);
@@ -2363,39 +2370,46 @@
</dd>
<dt><var title="">context</var> . <code title="dom-context-2d-fill"><a href="#dom-context-2d-fill">fill</a></code>()</dt>
+ <dt><var title="">context</var> . <code title="dom-context-2d-fill"><a href="#dom-context-2d-fill">fill</a></code>(<var title="">path</var>)</dt>
<dd>
- <p>Fills the subpaths of the current default path with the current fill style.</p>
+ <p>Fills the subpaths of the current default path or the given path 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>
+ <dt><var title="">context</var> . <code title="dom-context-2d-stroke"><a href="#dom-context-2d-stroke">stroke</a></code>(<var title="">path</var>)</dt>
<dd>
- <p>Strokes the subpaths of the currnet default path with the current stroke style.</p>
+ <p>Strokes the subpaths of the current default path or the given path 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>
+ <dt><var title="">context</var> . <code title="dom-context-2d-drawSystemFocusRing"><a href="#dom-context-2d-drawsystemfocusring">drawSystemFocusRing</a></code>(<var title="">path</var>, <var title="">element</var>)</dt>
<dd>
<p>If the given element is focused, draws a focus ring around the
- current default path, following the platform conventions for focus
- rings.</p>
+ current default path or hte given 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>
+ <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="">path</var>, <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 default path and returns false.</p>
+ current default path or the given 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
@@ -2404,7 +2418,9 @@
</dd>
+
<dt><var title="">context</var> . <code title="dom-context-2d-scrollPathIntoView"><a href="#dom-context-2d-scrollpathintoview">scrollPathIntoView</a></code>()</dt>
+ <dt><var title="">context</var> . <code title="dom-context-2d-scrollPathIntoView"><a href="#dom-context-2d-scrollpathintoview">scrollPathIntoView</a></code>(<var title="">path</var>)</dt>
<dd>
@@ -2414,7 +2430,9 @@
</dd>
+
<dt><var title="">context</var> . <code title="dom-context-2d-clip"><a href="#dom-context-2d-clip">clip</a></code>()</dt>
+ <dt><var title="">context</var> . <code title="dom-context-2d-clip"><a href="#dom-context-2d-clip">clip</a></code>(<var title="">path</var>)</dt>
<dd>
@@ -2423,7 +2441,9 @@
</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>
+ <dt><var title="">context</var> . <code title="dom-context-2d-isPointInPath"><a href="#dom-context-2d-ispointinpath">isPointInPath</a></code>(<var title="">path</var>, <var title="">x</var>, <var title="">y</var>)</dt>
<dd>
@@ -2438,10 +2458,23 @@
method must empty the list of subpaths in the context's current
default path so that the it once again has zero subpaths.</p>
+ <p>Where the following method definitions use the term <i>intended
+ path</i>, it means the <code><a href="#path">Path</a></code> argument, if one was
+ provided, or the current default path otherwise.</p>
+
+ <p>When the intended path is a <code><a href="#path">Path</a></code> object, the
+ coordinates of its subpaths must be transformed according to the
+ <code><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object's <a href="#transformations" title="dom-context-2d-transformation">current transformation
+ matrix</a> when used by these methods (without affecting the
+ <code><a href="#path">Path</a></code> object itself). When the intended path is the
+ current default path, it is not affected by the transform, (This is
+ because transformations already affect the current default path when
+ it is constructed, so applying it when it is painted as well would
+ result in a double transformation.)</p>
+
<p>The <dfn id="dom-context-2d-fill" title="dom-context-2d-fill"><code>fill()</code></dfn>
- method must fill all the subpaths of the current default 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
+ method must fill all the subpaths of the intended 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>
@@ -2451,8 +2484,9 @@
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
- default 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
+ must calculate the strokes of all the subpaths of the intended 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>
@@ -2460,14 +2494,18 @@
overlapping parts of the paths in one stroke operation are treated
as if their union was what was painted.</p>
+ <p class="note">The stroke <em>style</em> is affected by the
+ transformation during painting, even if the intended path is the
+ current default path.</p>
+
<p>Paths, when filled or stroked, must be painted without affecting
- the current default 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>
+ the current default path or any <code><a href="#path">Path</a></code> objects, 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>. (The effect of transformations is described above
+ and varies based on which path is being used.)</p>
- <p>Zero-length line segments must be pruned before stroking a
- path. Empty subpaths must be ignored.</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>
@@ -2480,9 +2518,8 @@
<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 current
- default path, following platform conventions, and abort these
- steps.</p>
+ then draw a focus ring of the appropriate style along the intended
+ 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
@@ -2495,18 +2532,21 @@
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>
+ <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>. (The
+ effect of transformations is described above and varies based on
+ which path is being used.)</p>
</li>
<li>
<p>Optionally, <a href="#inform">inform the user</a> that the
- focus is at the location given by the current default path. User
- agents may wait until the next time the <span>event loop</span>
- reaches its "update the rendering" step to optionally inform the
- user.</p>
+ focus is at the location given by the intended path. User agents
+ may wait until the next time the <span>event loop</span> reaches
+ its "update the rendering" step to optionally inform the user.</p>
</li>
@@ -2521,21 +2561,24 @@
<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 current default path, return false,
- and abort these steps.</p>
+ appropriate style along the intended 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>
+ <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>. (The
+ effect of transformations is described above and varies based on
+ which path is being used.)</p>
</li>
<li>
<p>Optionally, <a href="#inform">inform the user</a> that the
- focus is at the location given by the current default path. User
- agents may wait until the next time the <span>event loop</span>
- reaches its "update the rendering" step to optionally inform the
- user.</p>
+ focus is at the location given by the intended path. User agents
+ may wait until the next time the <span>event loop</span> reaches
+ its "update the rendering" step to optionally inform the user.</p>
</li>
@@ -2544,10 +2587,13 @@
</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
+ <ol><li><p>Let <var title="">the specified rectangle</var> be the
+ rectangle of the bounding box of the intended path.</li>
+
+ <li><p>Let <var title="">notional child</var> be a hypothetical
element that is a rendered child of the <code>canvas</code> element
- whose dimensions are exactly the rectangle of the bounding box of
- the current default path.</li>
+ whose dimensions are those of <var title="">the specified
+ rectangle</var>.</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>
@@ -2572,9 +2618,9 @@
<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 default 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
+ described by the intended 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
@@ -2587,8 +2633,8 @@
<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 default path as determined by
- the non-zero winding number rule; and must return false otherwise.
+ transformation, is inside the intended path as determined by the
+ non-zero winding number rule; and must return false otherwise.
Points on the path itself must be considered to be inside the path.
If either of the arguments is infinite or NaN, then the method must
return false.</p>
Received on Saturday, 10 March 2012 00:31:46 UTC