- From: SVG Working Group repository <cam+svgwgrepo@mcc.id.au>
- Date: Mon, 11 Nov 2013 20:43:40 -0800
- To: public-svg-wg@w3.org
details: https://svgwg.org/hg/svg2/rev/c1162571f066
branches:
changeset: 548:c1162571f066
user: Cameron McCormack <cam@mcc.id.au>
date: Tue Nov 12 15:39:23 2013 +1100
description:
Add new "B" and "b" bearing path commands. (ACTION-3125)
diffstat:
master/images/paths/bearing01.svg | 13 ++
master/paths.html | 232 ++++++++++++++++++++++++++++++++++---
2 files changed, 221 insertions(+), 24 deletions(-)
diffs (561 lines):
diff --git a/master/images/paths/bearing01.svg b/master/images/paths/bearing01.svg
new file mode 100644
--- /dev/null
+++ b/master/images/paths/bearing01.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg"
+ width="300" height="100" viewBox="0 0 300 100">
+
+ <path fill="#eee"
+ stroke="deeppink" stroke-width="8px" stroke-linejoin="round"
+ d="M 150,10
+ l 38.02379873562253,27.62590685774624
+ l -14.52379873562252,44.69965626587222
+ l -47,0
+ l -14.52379873562254,-44.69965626587221
+ z"/>
+
+</svg>
diff --git a/master/paths.html b/master/paths.html
--- a/master/paths.html
+++ b/master/paths.html
@@ -33,20 +33,21 @@ Compositing</a>.)</p>
an analogy with drawing on paper, the current point can be
thought of as the location of the pen. The position of the pen
can be changed, and the outline of a shape (open or closed) can
be traced by dragging the pen in either straight lines or
curves.</p>
<p>Paths represent the geometry of the outline of an object,
defined in terms of <em>moveto</em> (set a new current point),
-<em>lineto</em> (draw a straight line), <em>curveto</em> (draw
+<em>bearing</em> (set a new orientation), <em>lineto</em>
+(draw a straight line), <em>curveto</em> (draw
a curve using a cubic Bézier), <em>arc</em> (elliptical
or circular arc) and <em>closepath</em> (close the current
-shape by drawing a line to the last <em>moveto</em>) elements.
+shape by drawing a line to the last <em>moveto</em>) commands.
Compound paths (i.e., a path with multiple subpaths) are
possible to allow effects such as "donut holes" in objects.</p>
<p>This chapter describes the syntax, behavior and DOM
interfaces for SVG paths. Various implementation notes for SVG
paths can be found in <a
href="implnote.html#PathElementImplementationNotes"><span
class="element-name">'path'</span> element implementation
@@ -172,17 +173,17 @@ what their shape is as a path. (The equ
</table>
</div>
<h3 id="PathDataGeneralInformation">General information about path data</h3>
<p>A path is defined by including a <a>'path'</a>
element which contains a <span class='attr-value'>d="(path data)"</span>
attribute, where the <a>'d'</a> attribute contains the
-<em>moveto</em>, <em>line</em>, <em>curve</em> (both cubic and
+<em>moveto</em>, <em>bearing</em>, <em>lineto</em>, <em>curveto</em> (both cubic and
quadratic Béziers), <em>arc</em> and <em>closepath</em>
instructions.</p>
<p><span class="example-ref">Example triangle01</span>
specifies a path in the shape of a triangle. (The
<strong>M</strong> indicates a <em>moveto</em>, the
<strong>L</strong>s indicate <em>lineto</em>s, and the
<strong>z</strong> indicates a <em>closepath</em>).</p>
@@ -231,19 +232,19 @@ attempts to minimize the size of path da
"M100 100L200 200").</li>
<li>The command letter can be eliminated on subsequent
commands if the same command is used multiple times in a row
(e.g., you can drop the second "L" in "M 100 200 L 200 100 L
-100 -200" and use "M 100 200 L 200 100 -100 -200"
instead).</li>
- <li>Relative versions of all commands are available
- (uppercase means absolute coordinates, lowercase means
- relative coordinates).</li>
+ <li>For most commands there are absolute and relative
+ versions available (uppercase means absolute coordinates,
+ lowercase means relative coordinates).</li>
<li>Alternate forms of <em>lineto</em> are available to
optimize the special cases of horizontal and vertical lines
(absolute and relative).</li>
<li>Alternate forms of <em>curve</em> are available to
optimize the special cases where some of the control points
on the current segment can be determined automatically from
@@ -259,23 +260,43 @@ characters are allowed [<a href='refs.ht
(For example, the following is an
invalid numeric value in a path data stream: "13,000.56".
Instead, say: "13000.56".)</p>
<p>For the relative versions of the commands, all coordinate
values are relative to the current point at the start of the
command.</p>
-<p>In the tables below, the following notation is used:</p>
+<div class="ready-for-wg-review">
+
+<p>Relative path commands are also influenced by the
+current bearing, which is an angle set by the <em>bearing</em>
+commands. This allows for paths to be specified using a
+style of "turtle graphics", where straight line and curved
+path segments are placed with their starting point at a
+tangent (or at some other angle) to the current bearing.</p>
+
+</div>
+
+<p>In the tables below, the following notation is used to
+describe the syntax of a given path command:</p>
<ul>
<li>(): grouping of parameters</li>
<li>+: 1 or more of the given parameter(s) is required</li>
</ul>
+<div class="ready-for-wg-review">
+
+<p>In the description of the path commands, <var>cpx</var> and
+<var>cpy</var> represent the coordinates of the current point,
+and <var>cb</var> represents the current bearing.</p>
+
+</div>
+
<p>The following sections list the commands.</p>
<h3 id="PathDataMovetoCommands">The <strong>"moveto"</strong> commands</h3>
<p>The "moveto" commands (<strong>M</strong> or
<strong>m</strong>) establish a new current point. The effect
is as if the "pen" were lifted and moved to a new location. A
path data segment (if there is one) must begin with a "moveto"
@@ -291,32 +312,41 @@ is not the first command) represent the
<th>Description</th>
</tr>
<tr>
<td><strong>M</strong> (absolute)<br />
<strong>m</strong> (relative)</td>
<td>moveto</td>
<td>(x y)+</td>
<td>
- Start a new sub-path at the given (x,y) coordinate.
+ Start a new sub-path at the given (x,y) coordinates.
<strong>M</strong> (uppercase) indicates that absolute
coordinates will follow; <strong>m</strong> (lowercase)
indicates that relative coordinates will follow. If a moveto is
followed by multiple pairs of coordinates, the subsequent pairs
are treated as implicit lineto commands. Hence, implicit lineto
commands will be relative if the moveto is relative, and
absolute if the moveto is absolute. If a relative moveto
(<strong>m</strong>) appears as the first element of the path,
then it is treated as a pair of absolute coordinates. In this
case, subsequent pairs of coordinates are treated as relative
even though the initial moveto is interpreted as an absolute moveto.
</td>
</tr>
</table>
-
+
+<div class="ready-for-wg-review">
+
+<p>When a relative <strong>m</strong> command is used, the
+position moved to is (<var>cpx</var> + <var>x</var> cos <var>cb</var>
++ <var>y</var> sin <var>cb</var>, <var>cpy</var> +
+<var>x</var> sin <var>cb</var> + <var>y</var> cos <var>cb</var>).</p>
+
+</div>
+
<h3 id="PathDataClosePathCommand">The <strong>"closepath"</strong> command</h3>
<p>The "closepath" (<strong>Z</strong> or <strong>z</strong>)
ends the current subpath and causes an automatic straight line
to be drawn from the current point to the initial point of the
current subpath. If a "closepath" is followed immediately by a
"moveto", then the "moveto" identifies the start point of the
next subpath. If a "closepath" is followed immediately by any
@@ -331,34 +361,41 @@ of the subpath is "joined" with the star
segment of the subpath using the current value of <a>'stroke-linejoin'</a>.
If you instead "manually" close the subpath via a "lineto"
command, the start of the first segment and the end of the last
segment are not joined but instead are each capped using the
current value of <a>'stroke-linecap'</a>.
At the end of the command, the new current point is set to the
initial point of the current subpath.</p>
+<div class="ready-for-wg-review">
+
+<p>The current bearing does not affect a <strong>z</strong> command.</p>
+
+</div>
+
<table class="PathDataTable">
<tr>
<th>Command</th>
<th>Name</th>
<th>Parameters</th>
<th>Description</th>
</tr>
<tr>
<td><strong>Z</strong> or<br />
<strong>z</strong></td>
<td>closepath</td>
<td>(none)</td>
<td>Close the current subpath by drawing a straight line from the
- current point to current subpath's initial point. Since the Z and z
+ current point to current subpath's initial point. Since the
+ <strong>Z</strong> and <strong>z</strong>
commands take no parameters, they have an identical effect.</td>
</tr>
</table>
-
+
<h3 id="PathDataLinetoCommands">The <strong>"lineto"</strong> commands</h3>
<p>The various "lineto" commands draw straight lines from the
current point to a new point:</p>
<table class="PathDataTable">
<tr>
<th>Command</th>
@@ -380,41 +417,72 @@ current point to a new point:</p>
At the end of the command, the new current point is set to
the final set of coordinates provided.</td>
</tr>
<tr>
<td><strong>H</strong> (absolute)<br />
<strong>h</strong> (relative)</td>
<td>horizontal lineto</td>
<td>x+</td>
- <td>Draws a horizontal line from the current point (cpx,
- cpy) to (x, cpy). <strong>H</strong> (uppercase) indicates
+ <td>Draws a horizontal line from the current point.
+ <strong>H</strong> (uppercase) indicates
that absolute coordinates will follow; <strong>h</strong>
(lowercase) indicates that relative coordinates will
follow. Multiple x values can be provided (although usually
- this doesn't make sense). At the end of the command, the
- new current point becomes (x, cpy) for the final value of
- x.</td>
+ this doesn't make sense). An <strong>H</strong> or <strong>h</strong>
+ command is equivalent to an <strong>L</strong> or <strong>l</strong>
+ command with 0 specified for the y coordinate.
+ At the end of the command, the new current point is
+ taken from the final coordinate value.</td>
</tr>
<tr>
<td><strong>V</strong> (absolute)<br />
<strong>v</strong> (relative)</td>
<td>vertical lineto</td>
<td>y+</td>
- <td>Draws a vertical line from the current point (cpx, cpy)
- to (cpx, y). <strong>V</strong> (uppercase) indicates that
+ <td>Draws a vertical line from the current point.
+ <strong>V</strong> (uppercase) indicates that
absolute coordinates will follow; <strong>v</strong>
(lowercase) indicates that relative coordinates will
follow. Multiple y values can be provided (although usually
- this doesn't make sense). At the end of the command, the
- new current point becomes (cpx, y) for the final value of
- y.</td>
+ this doesn't make sense). A <strong>V</strong> or <strong>v</strong>
+ command is equivalent to an <strong>L</strong> or <strong>l</strong>
+ command with 0 specified for the x coordinate.
+ At the end of the command, the new current point is
+ taken from the final coordinate value.</td>
</tr>
</table>
+<div class="ready-for-wg-review">
+
+<p>When a relative <strong>l</strong> command is used, the
+end point of the line is (<var>cpx</var> + <var>x</var> cos <var>cb</var>
++ <var>y</var> sin <var>cb</var>, <var>cpy</var> +
+<var>x</var> sin <var>cb</var> + <var>y</var> cos <var>cb</var>).</p>
+
+<p>When a relative <strong>h</strong> command is used,
+the end point of the line is (<var>cpx</var> + <var>x</var> cos <var>cb</var>,
+<var>cpy</var> + <var>x</var> sin <var>cb</var>). This means
+that an <strong>h</strong> command with a positive <var>x</var>
+value draws a line in the direction of the current bearing. When
+the current bearing is 0, this is a horizontal line in the direction
+of the positive x-axis.</p>
+
+<div class="note">
+ <p>When there is a non-zero bearing, a mnemonic for the <strong>h</strong>
+ command could be "<u>h</u>ead this distance at the current bearing",
+ rather than "draw a <u>h</u>orizontal line".</p>
+</div>
+
+<p>When a relative <strong>v</strong> command is used,
+the end point of the line is (<var>cpx</var> + <var>y</var> sin <var>cb</var>,
+<var>cpy</var> + <var>y</var> cos <var>cb</var>).</p>
+
+</div>
+
<h3 id="PathDataCurveCommands">The curve commands</h3>
<p>These three groups of commands draw curves:</p>
<ul>
<li><a href="paths.html#PathDataCubicBezierCommands">Cubic
Bézier commands</a> (<strong>C</strong>,
<strong>c</strong>, <strong>S</strong> and
@@ -480,16 +548,28 @@ current point to a new point:</p>
indicates that relative coordinates will follow. Multiple
sets of coordinates may be specified to draw a
polybézier. At the end of the command, the new
current point becomes the final (x,y) coordinate pair used
in the polybézier.</td>
</tr>
</table>
+<div class="ready-for-wg-review">
+
+<p>When a relative <strong>c</strong> or <strong>s</strong>
+command is used, each of the relative coordinate pairs
+is computed as for those in an <strong>m</strong> command.
+For example, the final control point of the curve of
+both commands is (<var>cpx</var> + <var>x</var> cos <var>cb</var>
++ <var>y</var> sin <var>cb</var>, <var>cpy</var> +
+<var>x</var> sin <var>cb</var> + <var>y</var> cos <var>cb</var>).</p>
+
+</div>
+
<p><span class="example-ref">Example cubic01</span> shows some
simple uses of cubic Bézier commands within a path. The
example uses an internal CSS style sheet to assign styling
properties. Note that the control point for the "S" command is
computed automatically as the reflection of the control point
for the previous "C" command relative to the start point of the
"S" command.</p>
@@ -548,16 +628,28 @@ this example as SVG (SVG-enabled browser
absolute coordinates will follow; <strong>t</strong>
(lowercase) indicates that relative coordinates will
follow. At the end of the command, the new current point
becomes the final (x,y) coordinate pair used in the
polybézier.</td>
</tr>
</table>
+<div class="ready-for-wg-review">
+
+<p>When a relative <strong>q</strong> or <strong>t</strong>
+command is used, each of the relative coordinate pairs
+is computed as for those in an <strong>m</strong> command.
+For example, the final control point of the curve of
+both commands is (<var>cpx</var> + <var>x</var> cos <var>cb</var>
++ <var>y</var> sin <var>cb</var>, <var>cpy</var> +
+<var>x</var> sin <var>cb</var> + <var>y</var> cos <var>cb</var>).</p>
+
+</div>
+
<p><span class="example-ref">Example quad01</span> shows some
simple uses of quadratic Bézier commands within a path.
Note that the control point for the "T" command is computed
automatically as the reflection of the control point for the
previous "Q" command relative to the start point of the "T"
command.</p>
<edit:example href='images/paths/quad01.svg' name='quad01' description='quadratic Bézier commands in path data' image='yes' link='yes'/>
@@ -610,16 +702,28 @@ command.</p>
<strong>cy</strong>) of the ellipse is calculated
automatically to satisfy the constraints imposed by the
other parameters. <strong>large-arc-flag</strong> and
<strong>sweep-flag</strong> contribute to the automatic
calculations and help determine how the arc is drawn.</td>
</tr>
</table>
+<div class="ready-for-wg-review">
+
+<p>When a relative <strong>a</strong> command is used, the end point
+of the arc is (<var>cpx</var> + <var>x</var> cos <var>cb</var>
++ <var>y</var> sin <var>cb</var>, <var>cpy</var> +
+<var>x</var> sin <var>cb</var> + <var>y</var> cos <var>cb</var>).
+The effective value of the x-axis-rotation parameter is
+also affected by the current bearing: it is computed as
+<var>x-axis-rotation</var> + <var>cb</var>.</p>
+
+</div>
+
<p><span class="example-ref">Example arcs01</span> shows some
simple uses of arc commands within a path.</p>
<edit:example href='images/paths/arcs01.svg' name='arcs01' description='arc commands in path data' image='yes' link='yes'/>
<p>The elliptical arc command draws a section of an ellipse
which meets the following constraints:</p>
@@ -681,16 +785,91 @@ src="images/paths/arcs02.png" width="426
<p class="view-as-svg"><a href="images/paths/arcs02.svg">View
this example as SVG (SVG-enabled browsers only)</a></p>
<p>Refer to <a
href="implnote.html#ArcImplementationNotes">Elliptical arc
implementation notes</a> for detailed implementation notes for
the path data elliptical arc commands.</p>
+<div class="ready-for-wg-review">
+
+<h3 id="PathDataBearingCommands">The bearing commands</h3>
+
+<p>The bearing commands (<strong>B</strong> or <strong>b</strong>)
+set the current bearing, which influences the orientation of
+subsequent relative path commands:</p>
+
+<table class="PathDataTable">
+ <tr>
+ <th>Command</th>
+ <th>Name</th>
+ <th>Parameters</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><strong>B</strong> (absolute)<br/>
+ <strong>b</strong> (relative)</td>
+ <td>bearing</td>
+ <td>angle+</td>
+ <td>Sets the current bearing. The parameter is an angle
+ in degrees, where 0 indicates the direction of the positive
+ x-axis. <strong>B</strong> (uppercase) sets
+ the current bearing to the specified angle; <strong>b</strong>
+ (lowercase) sets the current bearing to be the angle of the
+ tangent at the end of the preceding path command plus the
+ specified angle. The current point is unaffected.
+ Although multiple parameters may be specified, this usually
+ will not be useful, as they could be combined into a single
+ angle value.</td>
+ </tr>
+</table>
+
+<p>At the beginning of a path, the current bearing is 0, which
+points in the direction of the positive x-axis. The current
+bearing remains unchanged until a <strong>B</strong> or
+<strong>b</strong> command is encountered. Since the relative
+<strong>b</strong> command sets the current bearing relative
+to the tangent at the end of the preceding path command,
+it is possible to set the bearing to that tangent by using
+"b 0".</p>
+
+<div class="example">
+ <p>The example below shows how bearing commands can be used
+ to draw a regular pentagon.</p>
+
+ <pre class="xml"><![CDATA[<svg xmlns="http://www.w3.org/2000/svg"
+ width="300" height="100" viewBox="0 0 300 100">
+
+ <path fill="#eee"
+ stroke="deeppink" stroke-width="8px" stroke-linejoin="round"
+ d="M 150,10
+ B 36 h 47
+ b 72 h 47
+ b 72 h 47
+ b 72 h 47 z"/>
+
+</svg>]]></pre>
+
+ <div class="figure">
+ <img class="bordered" src="images/paths/bearing01.svg"
+ alt="Image showing the use of the bearing command."/>
+ <p class="caption">Bearing commands can be used to position
+ the end points of the sides of a regular polygon without
+ having to use trigonometry to calculate them based on the
+ polygon's interior angles.</p>
+ </div>
+</div>
+
+<div class="issue">
+ <p>What should we do about the SVGPathSeg objects for these new path commands?</p>
+</div>
+
+</div>
+
<h3 id="PathDataBNF">The grammar for path data</h3>
<p>The following notation is used in the Backus-Naur Form (BNF)
description of the grammar for path data:</p>
<ul>
<li>*: 0 or more</li>
<li>+: 1 or more</li>
@@ -718,16 +897,17 @@ drawto-command:
| lineto
| horizontal-lineto
| vertical-lineto
| curveto
| smooth-curveto
| quadratic-bezier-curveto
| smooth-quadratic-bezier-curveto
| elliptical-arc
+ | bearing
moveto:
( "M" | "m" ) wsp* moveto-argument-sequence
moveto-argument-sequence:
coordinate-pair
| coordinate-pair comma-wsp? lineto-argument-sequence
closepath:
("Z" | "z")
lineto:
@@ -775,17 +955,22 @@ smooth-quadratic-bezier-curveto-argument
elliptical-arc:
( "A" | "a" ) wsp* elliptical-arc-argument-sequence
elliptical-arc-argument-sequence:
elliptical-arc-argument
| elliptical-arc-argument comma-wsp? elliptical-arc-argument-sequence
elliptical-arc-argument:
number comma-wsp? number comma-wsp?
number comma-wsp flag comma-wsp? flag comma-wsp? coordinate-pair
-coordinate-pair:
+bearing:
+ ( "B" | "b") wsp* bearing-argument-sequence
+<div class="ready-for-wg-review">bearing-argument-sequence:
+ number
+ | number comma-wsp? bearing-argument-sequence</div><!--
+-->coordinate-pair:
coordinate comma-wsp? coordinate
coordinate:
number
nonnegative-number:
integer-constant
| floating-point-constant
number:
sign? integer-constant
@@ -853,17 +1038,17 @@ agents employ algorithms that produce as
possible; however, to accommodate implementation differences
and to help distance calculations produce results that
approximate author intent, the <a>'pathLength'</a> attribute can be used
to provide the author's computation of the total length of the
path so that the user agent can scale distance-along-a-path
computations by the ratio of <a>'pathLength'</a> to the user agent's own
computed value for total path length.</p>
-<p>A "moveto" operation within a <a>'path'</a> element is defined to have
+<p>A "moveto" or "bearing" operation within a <a>'path'</a> element is defined to have
zero length. Only the various "lineto", "curveto" and "arcto"
commands contribute to path length calculations.</p>
</edit:with>
<h2 id="DOMInterfaces">DOM interfaces</h2>
<h3 id="InterfaceSVGPathSeg">Interface SVGPathSeg</h3>
@@ -904,17 +1089,16 @@ single command within a path data specif
<dt id="__svg__SVGPathSeg__PATHSEG_UNKNOWN" class="constant first-child"><b>PATHSEG_UNKNOWN</b><span class="idl-type-parenthetical"> (unsigned short)</span></dt>
<dd class="constant">
<div>
The unit type is not one of predefined types. It is invalid to attempt
to define a new value of this type or to attempt to switch an existing
value to this type.
-
</div>
</dd>
<dt id="__svg__SVGPathSeg__PATHSEG_CLOSEPATH" class="constant"><b>PATHSEG_CLOSEPATH</b><span class="idl-type-parenthetical"> (unsigned short)</span></dt>
<dd class="constant">
<div>
Corresponds to a "closepath" (z) path data command.
Received on Tuesday, 12 November 2013 04:44:04 UTC