Skip to content

Commit

Permalink
Remove addPathByStrokingPath, addText, addPathByStrokingText from Path2D
Browse files Browse the repository at this point in the history 
The following methods on the Path2D interface have not been implemented
in any major user agent.
 - addPathByStrokingPath
 - addText
 - addPathByStrokingText

Remove these methods and the associated DrawingStyle interface.

Path2D.addPath has not been removed as is currently shipping /
implemented in the following engines:

WebKit - Shipped Path2D.addPath.
Firefox - Shipped Path2D.addPath.
Blink - Implemented Path2D.addPath behind a flag.
Edge - Not yet implemented.
  • Loading branch information
@bfgeek @domenic
bfgeek authored and domenic committed Dec 15, 2015
1 parent 1b918cf commit e1d04f4
Show file tree
Hide file tree
Showing 3 changed files with 2 additions and 313 deletions.
Binary file removed images/Qp-overlap-outline.png
View file
Binary file not shown.
Binary file removed images/Qp-overlap.png
View file
Binary file not shown.
315 changes: 2 additions & 313 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61484,21 +61484,12 @@ interface <dfn>ImageData</dfn> {
readonly attribute <span data-x="idl-Uint8ClampedArray">Uint8ClampedArray</span> <span data-x="dom-imagedata-data">data</span>;
};

[<span data-x="dom-DrawingStyle">Constructor</span>(optional <span>Element</span> scope), Exposed=(Window,Worker)]
interface <dfn>DrawingStyle</dfn> { };
<span>DrawingStyle</span> implements <span>CanvasDrawingStyles</span>;

[<span data-x="dom-Path2D">Constructor</span>,
<span data-x="dom-Path2D-copy">Constructor</span>(<span>Path2D</span> path),
<span data-x="dom-Path2D-merge">Constructor</span>(sequence&lt;<span>Path2D</span>&gt; paths, optional <span>CanvasFillRule</span> fillRule = "<span data-x="dom-context-2d-fillRule-nonzero">nonzero</span>"),
<span data-x="dom-Path2D-withdata">Constructor</span>(DOMString d), Exposed=(Window,Worker)]
interface <dfn>Path2D</dfn> {
void <span data-x="dom-Path2D-addPath">addPath</span>(<span>Path2D</span> path, optional <span>DOMMatrix</span>? transformation = null);
void <span data-x="dom-Path2D-addPathByStrokingPath">addPathByStrokingPath</span>(<span>Path2D</span> path, <span>CanvasDrawingStyles</span> styles, optional <span>DOMMatrix</span>? transformation = null);
void <span data-x="dom-Path2D-addText">addText</span>(DOMString text, <span>CanvasDrawingStyles</span> styles, <span>DOMMatrix</span>? transformation, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
void <span data-x="dom-Path2D-addPathByStrokingText">addPathByStrokingText</span>(DOMString text, <span>CanvasDrawingStyles</span> styles, <span>DOMMatrix</span>? transformation, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
void <span data-x="dom-Path2D-addText">addText</span>(DOMString text, <span>CanvasDrawingStyles</span> styles, <span>DOMMatrix</span>? transformation, <span>Path2D</span> path, optional unrestricted double maxWidth);
void <span data-x="dom-Path2D-addPathByStrokingText">addPathByStrokingText</span>(DOMString text, <span>CanvasDrawingStyles</span> styles, <span>DOMMatrix</span>? transformation, <span>Path2D</span> path, optional unrestricted double maxWidth);
};
<span>Path2D</span> implements <span>CanvasPathMethods</span>;</pre>

Expand Down Expand Up @@ -62180,42 +62171,6 @@ idea from Mihai:
</div>


<h6><code>DrawingStyle</code> objects</h6>

<p>All the line styles (line width, caps, joins, and dash patterns) and text styles (fonts)
described in the next two sections apply to <code>CanvasRenderingContext2D</code> objects and to
<code>DrawingStyle</code> objects. This section defines the constructor used to obtain a
<code>DrawingStyle</code> object. This object is then used by methods on <code>Path2D</code>
objects to control how text and paths are rasterised and stroked.</p>

<dl class="domintro">

<dt><var>styles</var> = new <code data-x="dom-DrawingStyle">DrawingStyle</code>( [ <var>element</var> ] )</dt>

<dd>

<p>Creates a new <code>DrawingStyle</code> object, optionally using a specific element for
resolving relative keywords and sizes in font specifications.</p>

</dd>

</dl>

<div w-nodev>

<p>Each <code>DrawingStyle</code> object can have a <dfn>styles scope object</dfn>.</p>

<p>The <dfn><code data-x="dom-DrawingStyle">DrawingStyle()</code></dfn> constructor, when invoked,
must return a newly created <code>DrawingStyle</code> object. If the constructor was passed an
argument, then the <code>DrawingStyle</code> object's <span>styles scope object</span> is that
element. Otherwise, if the constructor lives in a window, the object's <span>styles scope
object</span> is <span data-x="concept-document-window">the <code>Window</code> object's newest
<code>Document</code> object</span>. Otherwise, the constructor lives in a worker, and the
<span>styles scope object</span> is the worker.</p>

</div>


<h6>Line styles</h6>

<dl class="domintro">
Expand Down Expand Up @@ -62740,8 +62695,7 @@ transform. ack Shaun Morris. -->
<code>CanvasRenderingContext2D</code> objects, if the object lives in a window, the object's
<span>font style source object</span> is <span data-x="concept-document-window">the
<code>Window</code> object's newest <code>Document</code> object</span>; otherwise the object
lives in a worker and the <span>font style source object</span> is the worker. For
<code>DrawingStyle</code> objects, it's the <span>styles scope object</span>.</p>
lives in a worker and the <span>font style source object</span> is the worker.</p>

<p>The <dfn><code data-x="dom-context-2d-font">font</code></dfn> IDL attribute, on setting, must
be <span data-x="parse something according to a CSS grammar">parsed as a CSS &lt;'font'> value</span> (but without supporting property-independent
Expand Down Expand Up @@ -63715,32 +63669,11 @@ try {
</dd>

<dt><var>path</var> . <code subdfn data-x="dom-Path2D-addPath">addPath</code>(<var>path</var> [, <var>transform</var> ] )</dt>
<dt><var>path</var> . <code subdfn data-x="dom-Path2D-addPathByStrokingPath">addPathByStrokingPath</code>(<var>path</var>, <var>styles</var> [, <var>transform</var> ] )</dt>

<dd>

<p>Adds to the path the path given by the argument.</p>

<p>In the case of the stroking variants, the line styles are taken from the <var>styles</var> argument, which can be either a <code>DrawingStyle</code> object or a
<code>CanvasRenderingContext2D</code> object.</p>

</dd>

<dt><var>path</var> . <code subdfn data-x="dom-Path2D-addText">addText</code>(<var>text</var>, <var>styles</var>, <var>transform</var>, <var>x</var>, <var>y</var> [, <var>maxWidth</var> ] )</dt>
<dt><var>path</var> . <code data-x="dom-Path2D-addText">addText</code>(<var>text</var>, <var>styles</var>, <var>transform</var>, <var>path</var> [, <var>maxWidth</var> ] )</dt>
<dt><var>path</var> . <code subdfn data-x="dom-Path2D-addPathByStrokingText">addPathByStrokingText</code>(<var>text</var>, <var>styles</var>, <var>transform</var>, <var>x</var>, <var>y</var> [, <var>maxWidth</var> ] )</dt>
<dt><var>path</var> . <code data-x="dom-Path2D-addPathByStrokingText">addPathByStrokingText</code>(<var>text</var>, <var>styles</var>, <var>transform</var>, <var>path</var> [, <var>maxWidth</var> ] )</dt>

<dd>

<p>Adds to the path a series of subpaths corresponding to the given text. If the arguments give
a coordinate, the text is drawn horizontally at the given coordinates. If the arguments give a
path, the text is drawn along the path. If a maximum width is provided, the text will be scaled
to fit that width if necessary.</p>

<p>The font, and in the case of the stroking variants, the line styles, are taken from the <var>styles</var> argument, which can be either a <code>DrawingStyle</code> object or a
<code>CanvasRenderingContext2D</code> object.</p>

</dd>

</dl>
Expand Down Expand Up @@ -63864,251 +63797,6 @@ try {

</ol>

<hr>

<p>The <dfn><code data-x="dom-Path2D-addPathByStrokingPath">addPathByStrokingPath(<var>b</var>, <var>styles</var>, <var>transform</var>)</code></dfn>
method, when invoked on a <code>Path2D</code> object <var>a</var>, must run the
following steps:</p>

<ol>

<li><p>If the <code>Path2D</code> object <var>b</var> has no subpaths, abort these
steps.</p></li>

<li><p>Create a copy of all the subpaths in <var>b</var>. Let this copy be known as <var>c</var>.</p></li>

<li><p>Transform all the coordinates and lines in <var>c</var> by transformation matrix
<var>transform</var>, if it is not null.</p></li>

<li><p>Let a new list of subpaths <var>d</var> be the result of <span data-x="trace a
path">tracing</span> <var>c</var>, using the <var>styles</var> argument for the
line styles.</p>

<li><p>Let (<var>x</var>, <var>y</var>) be the last point in the last subpath
of <var>d</var>.</p></li>

<li><p>Add all the subpaths in <var>d</var> to <var>a</var>.</p></li>

<li><p>Create a new subpath in <var>a</var> with (<var>x</var>, <var>y</var>) as the only point in the subpath.</p></li>

</ol>

<hr>

<p>The <dfn><code data-x="dom-Path2D-addText">addText()</code></dfn> and <dfn><code data-x="dom-Path2D-addPathByStrokingText">addPathByStrokingText()</code></dfn> methods each
come in two variants: one rendering text at a given coordinate, and one rendering text along a
given path. In both cases, the methods take a <code>CanvasDrawingStyles</code> object argument for
the text and (if appropriate) line styles to use, a <code>DOMMatrix</code> object <var>transform</var> (which can be null), and a maximum width can optionally be provided.</p>

<p>When one of the <code data-x="dom-Path2D-addText">addText()</code> and <code
data-x="dom-Path2D-addPathByStrokingText">addPathByStrokingText()</code> variants that take as
argument an (<var>x</var>, <var>y</var>) coordinate is invoked, the method
must run the following algorithm:</p>

<ol>

<li><p>Run the <span>text preparation algorithm</span>, passing it <var>text</var>, the
<code>CanvasDrawingStyles</code> object argument, and, if the <var>maxWidth</var>
argument was provided, that argument. Let <var>glyphs</var> be the result.</p>

<li><p>Move all the shapes in <var>glyphs</var> to the right by <var>x</var>
CSS pixels and down by <var>y</var> CSS pixels.</p></li>

<li><p>Let <var>glyph paths</var> be a list of <span data-x="concept-path">paths</span>
describing the shapes given in <var>glyphs</var>, with each CSS pixel in the coordinate
space of <var>glyphs</var> mapped to one coordinate space unit in <var>glyph
paths</var>. Subpaths in <var>glyph paths</var> must wind clockwise, regardless of how
the user agent's font subsystem renders fonts and regardless of how the fonts themselves are
defined.</p>

<li><p>Transform all the coordinates and lines in <var>glyph paths</var> by the
transformation matrix <var>transform</var>, if it is not null.</p></li>

<li><p>If the method is <code
data-x="dom-Path2D-addPathByStrokingText">addPathByStrokingText()</code>, replace <var>glyph paths</var> by the result of <span data-x="trace a path">tracing</span> each
<span data-x="concept-path">path</span> in <var>glyph paths</var>, using the
<code>CanvasDrawingStyles</code> object argument for the line styles.</p>

<li id="mergeGlyphs">

<p>Let <var>merged path</var> be a <span data-x="concept-path">path</span> that
consists of a set of non-overlapping subpaths that exactly outline the points from which, in any
of the <span data-x="concept-path">paths</span> in <var>glyph paths</var>, the number
of times a half-infinite straight line drawn from that point crosses that path is odd.</p>

<p>The subpaths in <var>merged path</var> must be oriented such that for any point,
the number of times a half-infinite straight line drawn from that point crosses a subpath is
even if and only if the number of times a half-infinite straight line drawn from that same point
crosses a subpath going in one direction is equal to the number of times it crosses a subpath
going in the other direction.</p>

<div class="example">

<p>For example, suppose <var>text</var> consists of two overlapping glyphs "Q" and
"p" (maybe the "Q" has a flourish that crosses into the tail of the "p"). The <var>glyph paths</var> therefore consist of two paths, each with two subpaths: one for the
outside of the letter shape, and one for the inside of the letter shape. There are points that,
according to the even-odd fill rule, are filled in both shapes simultaneously: where they
overlap. As such, the subpaths from the two glyphs actually cross each other.</p>

<p><img src="images/Qp-overlap.png" alt=""></p> <!-- this image repeats the previous paragraph,
so alternative text would be redundant -->
<!--
c.clearRect(0, 0, 640, 480);
c.save();
try {
c.font = '100px Zapfino';
c.fillStyle = 'blue';
c.fillText('Q', 200, 200);
c.fillStyle = 'fuchsia';
c.fillText('p', 337, 200);
} finally {
c.restore();
}
-->

<p>The resulting <var>merged path</var> in such a situation would have just one path
for these two letters, with a total of just three subpaths (one big outer outline, one for the
inside of the "Q", and one for inside of the "p"). This single path would have no subpaths that
cross each other.</p>

<p><img src="images/Qp-overlap-outline.png" alt=""></p> <!-- this image again repeats the
previous paragraph, so alternative text would be redundant -->
<!-- this is just an edge-detected version of the previous image -->

</div>

</li>

<li><p>Add all the subpaths in <var>merged path</var> to the <code>Path2D</code>
object.</p></li>

<li><p>Set the <code>Path2D</code> object's <span>need new subpath</span> flag.</p></li>

</ol>

<p>When one of the <code data-x="dom-Path2D-addText">addText()</code> and <code
data-x="dom-Path2D-addPathByStrokingText">addPathByStrokingText()</code> variants that take as
argument a <code>Path2D</code> object is invoked, the method must run the following algorithm:</p>

<ol>

<li><p>Let <var>target</var> be the <code>Path2D</code> object on which the method was
invoked.</p></li>

<li><p>Let <var>path</var> be the <code>Path2D</code> object that was provided in the
method's arguments.</p></li>

<li><p>Run the <span>text preparation algorithm</span>, passing it <var>text</var>, the
<code>CanvasDrawingStyles</code> object argument, and, if the <var>maxWidth</var>
argument was provided, that argument. Let <var>glyphs</var> be the resulting array, and
<var>physical alignment</var> be the resulting alignment value.</p>

<li><p>Let <var>width</var> be the aggregate length of all the subpaths in <var>path</var>, including the distances from the last point of each closed subpath to the
first point of that subpath.</p></li>

<li><p>Define <var>L</var> to be a linear coordinate line for of all the subpaths in
<var>path</var>, with additional lines drawn between the last point and the first point
of each closed subpath, such that the first point of the first subpath is defined as point 0, and
the last point of the last subpath, if the last subpath is not closed, or the second occurrence
first point of that subpath, if it is closed, is defined as point <var>width</var>.</p></li>

<li>

<p>Let <var>offset</var> be determined according to the appropriate step below:</p>

<dl class="switch">

<dt>If <var>physical alignment</var> is <i>left</i></dt> <dd>Let <var>offset</var> be zero.</dd>

<dt>If <var>physical alignment</var> is <i>right</i></dt> <dd>Let <var>offset</var> be <var>width</var>.</dd>

<dt>If <var>physical alignment</var> is <i>center</i></dt> <dd>Let <var>offset</var> be half of <var>width</var>.</dd>

</dl>

</li>

<li><p>Move all the shapes in <var>glyphs</var> to the right by <var>offset</var> CSS pixels.</p></li>

<li><p>Let <var>transformed path list</var> be an empty list of paths.</p></li>

<li>

<p>For each glyph <var>glyph</var> in the <var>glyphs</var> array, run these
substeps:</p>

<ol>

<li><p>Let <var>dx</var> be the <var>x</var>-coordinate of the horizontal
center of the bounding box of the shape described by <var>glyph</var>, in CSS
pixels.</p></li>

<li><p>If <var>dx</var> is negative or greater than <var>width</var>, skip
the remainder of these substeps for this glyph.</p></li>

<li><p>Recast <var>dx</var> to coordinate spaces units in <var>path</var>.
(This just changes the dimensionality of <var>dx</var>, not its numeric value.)</p>
<!-- hide this step if people get confused by the pedancy -->

<li><p>Find the point <var>p</var> on <var>path</var> (or implied closing
lines in <var>path</var>) that corresponds to the position <var>dx</var> on
the coordinate line <var>L</var>.</p>

<li><p>Let <var>&theta;</var> be the clockwise angle from the positive x-axis to the
side of the line that is tangential to <var>path</var> at the point <var>p</var> that is going in the same direction as the line at point <var>p</var>.</p></li>

<li><p>Rotate the shape described by <var>glyph</var> clockwise by <var>&theta;</var> about the point that is at the <var>dx</var> coordinate
horizontally and the zero coordinate vertically.</p></li>

<li><p>Let (<var>x</var>, <var>y</var>) be the coordinate of the point <var>p</var>.</p></li>

<li><p>Move the shape described by <var>glyph</var> to the right by <var>x</var> and down by <var>y</var>.</p></li>

<li><p>Let <var>glyph subpaths</var> be a list of subpaths describing the shape given
in <var>glyph</var>, with each CSS pixel in the coordinate space of <var>glyph</var> mapped to one coordinate space unit in <var>glyph subpaths</var>.
Subpaths in <var>glyph subpaths</var> must wind clockwise, regardless of how the user
agent's font subsystem renders fonts and regardless of how the fonts themselves are
defined.</p>

<li><p>Transform all the coordinates and lines in <var>glyph subpaths</var> by the
transformation matrix <var>transform</var>, if it is not null.</p></li>

<li><p>If the method is <code
data-x="dom-Path2D-addPathByStrokingText">addPathByStrokingText()</code>, replace <var>glyph subpaths</var> by the result of <span data-x="trace a path">tracing</span> <var>glyph subpaths</var>, using the <code>CanvasDrawingStyles</code> object argument for
the line styles.</p>

<li><p>Add all the subpaths in <var>glyph subpaths</var> to <var>transformed path list</var>.</p></li>

</ol>

</li>

<li>

<p>Let <var>merged path</var> be a <span data-x="concept-path">path</span> that
consists of a set of non-overlapping subpaths that exactly outline the points from which, in any
of the <span data-x="concept-path">paths</span> in <var>transformed path list</var>,
the number of times a half-infinite straight line drawn from that point crosses that path is
odd.</p>

<p>The subpaths in <var>merged path</var> must be oriented such that for any point,
the number of times a half-infinite straight line drawn from that point crosses a subpath is
even if and only if the number of times a half-infinite straight line drawn from that same point
crosses a subpath going in one direction is equal to the number of times it crosses a subpath
going in the other direction.</p>

<p class="note">See <a href="#mergeGlyphs">the equivalent step in the earlier algorithm</a> for
an example of this step. It's even more likely that there will be overlap with this method,
since neighboring glyphs are likely to be rotated relative to each other.</p>

</li>

<li><p>Add all the subpaths in <var>merged path</var> to <var>target</var>.</p></li>

<li><p>Set the <code>Path2D</code> object's <span>need new subpath</span> flag.</p></li>

</ol>

</div>


Expand Down Expand Up @@ -117978,6 +117666,7 @@ INSERT INTERFACES HERE
Ian Clelland,
Ian Davis,
Ian Fette,
Ian Kilpatrick,
Ido Green,
Ignacio Javier,
Igor Oliveira,
Expand Down

0 comments on commit e1d04f4

Please sign in to comment.