1. Introduction
A marker is a graphical object that is painted at particular positions along a path, line, polyline or polygon element, together known as the markable elements. There are four ways markers can be placed on these elements:
- The marker-start and marker-end properties can be used to place markers at the first and last vertex, and the marker-mid property can be used to place markers at every other vertex (aside from the first and last). The marker-start and marker-end can be used for example to add arrowheads to paths. Markers placed using these properties are known as vertex markers.
- The marker-segment property can be used to place markers at the center of every path segment. These markers are known as segment markers.
- The marker-pattern property can be used to define a regular repeating pattern of markers to place along the length of the path. Markers placed with marker-pattern are known as repeating markers.
- A child marker element with a position attribute can be used to place a marker at a particular location along the path. Such markers are known as positioned markers.
There are probably better terms to use than "vertex" and "segment" markers. At least, "vertex" would go more naturally with "edge", but we should use more natural sounding names.
The graphics for a marker are defined by a marker element. The marker-start, marker-end, marker-mid, marker-segment and marker-pattern properties, together known as the marker properties, reference marker elements.
Markers can be animated, and as with use elements, the animated effects will show on all current uses of the markers within the document.
Markers on a given element are painted in the following order, from bottom to top:
-
any marker specified by marker-start
-
alternating marker-mid and marker-segment markers, in order of their position along the path
-
any repeating markers, in order of their position along the path
-
any positioned markers, in document order of the marker element children
2. The marker element
| Name: | marker |
|---|---|
| Categories: | Container element |
| Contexts: | none |
| Content model: | Any number of the following statements, in order: |
| Attributes: | |
| DOM Interfaces: | SVGMarkerElement |
The marker element defines the graphics that are to be used for drawing markers on a markable element.
Attribute definitions:
-
Name Value Initial value Animatable markerUnits strokeWidth | userSpaceOnUse strokeWidth yes -
The markerUnits attribute defines the coordinate system for attributes markerWidth, markerHeight and the contents of the marker. Values have the following meanings:
- strokeWidth
- markerWidth, markerHeight and the contents of the marker represent values in a coordinate system which has a single unit equal the size in user units of the current stroke width (see the stroke-width property) in place for the graphic object referencing the marker.
- userSpaceOnUse
- markerWidth, markerHeight and the contents of the marker represent values in the current user coordinate system in place for the graphic object referencing the marker (i.e., the user coordinate system for the element referencing the marker element via a marker).
-
Name Value Initial value Animatable markerWidth, markerHeight <length> | <percentage> | <number> 3 yes - The markerWidth and markerHeight attributes represent the size of the viewport into which the marker is to be fitted according to the viewBox and preserveAspectRatio attributes. A value of zero for either attribute results in nothing being rendered for the marker. A negative value for either attribute is an error (see Error processing).
-
Name Value Initial value Animatable refX <length> | <percentage> | <number> | left | center | right 0 yes refY <length> | <percentage> | <number> | top | center | bottom 0 yes -
New in SVG 2: geometric keywords (matches use in symbol).
We will add top/center/bottom, left/center/right keywords to refX/refY on marker/symbol. Resolved at LondonF2F. Values inspired by background-position.
The refX and refY attributes define the reference point of the marker which is to be placed exactly at the marker’s position on the markable element. They are interpreted as being in the coordinate system of the marker contents, after application of the viewBox and preserveAspectRatio attributes.
-
Name Value Initial value Animatable orient auto | auto-start-reverse | <angle> | <number> 0 yes (non-additive) -
The orient attribute indicates how the marker is rotated when it is placed at its position on the markable element. Values have the following meaning:
- auto
-
A value of auto indicates that the marker is oriented such that its positive x-axis is pointing in the direction of the path at the point it is placed.
This needs to reference a definition for how directionality of a given start/mid/end vertex is calculated. Part of that (which should be moved somewhere more appropriate) is in the path element implementation notes. Some wording from SVG 1.1 appears to have been lost, compare with this.
Here’s an example that is a bit unclear currently:<svg> <marker id="m" orient="auto" overflow="visible"> <rect x="-1" y="-0.5" width="1" height="1" fill="green"/> </marker> <path d="M50,0C50,50 50,100 50,100" marker-end="url(#m)" stroke-width="100" stroke="red"/> </svg>
The second control point and the endpoint coincide, should this mean that the direction of the endpoint is a) unknown [aka default to 0 degrees] or b) that you have to look at the previous segment(s)/command(s) until a direction can be established?If the marker is a segment marker, then the direction the marker is oriented is, if considering the incoming and outgoing directions as unit vectors, in the direction of the sum of these two vectors. If this sum is zero, then the marker is oriented in the incoming direction.
If the marker is on the first or last vertex of a closed subpath, then the incoming direction taken from the final path segment and the outgoing direction is taken from:
- auto-start-reverse
-
A value of auto-start-reverse means the same as auto except that for a marker placed by marker-start, the orientation is 180° different from the orientation as determined by auto.
This allows a single arrowhead marker to be defined that can be used for both the start and end of a path, point in the right directions.
- <angle>
- <number>
-
An <angle> value represents the angle the marker’s positive x-axis makes with the positive x-axis in the user space of the markable element, and a <number> value with no unit represents an angle in degrees. For example, if a value of 0 is given, then the marker will be drawn such that its x-axis will align with the x-axis of the user space of the graphic object referencing the marker. A value of 90deg will result in the marker being drawn with its positive x-axis in the direction of the positive y-axis of the markable element’s user space.
The orientation occurs after the marker has been fitted into its viewport. See the Details on how markers are rendered section below for an illustrative example.
-
Name Value Initial value Animatable position <length> | <percentage> | <number> as if not specified yes -
If the marker element is a child of a markable element, then the presence of a attribute indicates that the marker is a positioned marker and that it will be painted at the specified distance along the path. If the value is negative or greater than the length of the path, then no marker will be painted. If this attribute is specified on a marker that is not a child of a markable element, then it has no effect beyond being exposed in the DOM.
Should a negative or greater than path length value be an "in error" / "unsupported" value?
-
Name Value Initial value Animatable href URL [URL] as if not specified yes -
When a marker element is being used as a positioned marker, the href attribute indicates that the marker referenced by the attribute is to be used as the definition of the marker. The graphical content of the referencing marker element and any of its attributes that affect marker processing are ignored. Authors must not place any child graphical content in the referencing marker or specify the viewBox, preserveAspectRatio, refX, refY, markerUnits, markerWidth, markerHeight or orient attributes on it.
We should say something about referencing marker elements that have an href with the marker properties. I suspect we should just allow this. Whether we want to allow the full element-referencing thing that you can do with gradients, with selective overriding of attributes, I’m not sure.
-
Name Value Initial value Animatable viewBox see prose see prose see prose -
The viewBox attribute is defined be SVG. See ‘The viewBox attribute’ [SVG11].
-
Name Value Initial value Animatable preserveAspectRatio see prose see prose see prose -
The preserveAspectRatio attribute is defined be SVG. See ‘The preserveAspectRatio attribute’ [SVG11].
The contents of the marker are relative to a new coordinate system. The markerUnits attribute determines an initial scale factor for transforming the graphics in the marker into the user coordinate system for the referencing element. An additional set of transformations might occur if there is a viewBox attribute, in which case the coordinate system for the contents of the marker will be transformed due to the processing of attributes viewBox and preserveAspectRatio. If there is no viewBox attribute, then the assumed default value for the viewBox attribute has the origin of the viewBox coincident with the origin of the viewport and the width/height of the viewBox the same as the width/height of the viewport.
The user agent style sheet sets the overflow property for marker elements to hidden, which causes a rectangular clipping path to be created at the bounds of marker’s viewport. Unless the overflow property is overridden, any graphics within the marker which goes outside of the marker’s viewport will be clipped.
Properties inherit into the marker element from its ancestors; properties do not inherit from the element referencing the marker element.
Note: By using the context-stroke value for the fill or stroke on elements in its definition, a single marker can be designed to match the style of the element referencing the marker.
marker elements are only rendered directly when they are used as children of a markable element and have a position attribute specified. This causes the marker to be painted as a positioned marker. All other marker elements are not rendered directly and must be referenced by one of the marker properties to be rendered. The display property does not apply to the marker element; thus, marker elements are not directly rendered even if the display property is set to a value other than none, and marker elements are available for referencing even when the display property on the marker element or any of its ancestors is set to none. marker elements that are used as positioned markers can simultaneously be referenced by the marker properties to be used as segment markers and repeating markers.
Event attributes and event listeners attached to the contents of a marker element are not processed; only the rendering aspects of marker elements are processed.
Make interaction work on positioned markers.
The following example shows the use of positioned markers to place symbols at particular distances along a path.
<svg xmlns="http://www.w3.org/2000/svg"
width="600" height="200" viewBox="0 0 600 200">
<defs>
<marker id="Square" markerWidth="10" markerHeight="10"
refX="5" refY="5" orient="auto">
<path d="M 5,1 L 9,5 5,9 1,5 z" fill="#6a9100"/>
</marker>
<marker id="Circle" markerWidth="10" markerHeight="10"
refX="5" refY="5" orient="auto">
<circle cx="5" cy="5" r="2" fill="dodgerblue"/>
</marker>
</defs>
<path d="M 100,50 C 100,250 500,-50 300,150"
fill="none" stroke="deeppink" stroke-width="3">
<marker href="#Square" position="0"/>
<marker href="#Square" position="100%"/>
<marker href="#Circle" position="50px"/>
<marker href="#Circle" position="calc(100% - 50px)"/>
<marker refX="5" refY="5" position="50%">
<!-- the cross -->
<path d="M 3,3 L 7,7 M 3,7 L 7,3"
fill="none" stroke="black" stroke-width="2"/>
</marker>
</path>
</svg>
Child marker elements are used to position two square and two circular markers. The cross marker is defined inline and does not need an ID.
3. Referencing marker elements
A number of marker properties allow specifying a marker using a <marker-ref> value.
where:
Values have the following meaning
- <url>
- Indicates that the marker element referenced by the <url> value will be used. If the URL reference is not valid (e.g., it points to an object that is undefined or the object is not a marker element), then the marker reference is also not valid.
- child
- Indicates that the last child marker element of the element where the property is specified will be used. If there is no such element, then the reference is not valid.
- <child-selector>
- Indicates that the first matching descendent marker specified by the <child-selector>, applied in the context of the element where the property is specified, will be used. If no element matches any of the selectors contained in the <child-selector>>, or the first match is not a marker, then the reference is not valid.
4. Vertex markers: the marker-start, marker-mid and marker-end properties
| Name: | marker-start, marker-mid, marker-end |
|---|---|
| Value: | none | <marker-ref> |
| Initial: | none |
| Applies to: | markable elements |
| Inherited: | yes |
| Percentages: | n/a |
| Media: | visual |
| Computed value: | as specified, but with <url> values (that are part of a <marker-ref>) made absolute |
| Animatable: | yes |
The marker-start and marker-end properties are used to specify the marker that will be drawn at the first and last vertices of the given markable element, respectively. marker-mid is used to specify the marker that will be drawn at all other vertices (i.e., every vertex except the first and last). Possible values for marker-start, marker-mid and marker-end are:
- none
- Indicates that no marker symbol will be drawn at the given vertex or vertices.
- <marker-ref>
- Indicates that the marker element referenced by the <marker-ref> value will be drawn at the given vertex or vertices. If the reference is not valid, then no marker will be drawn at the given vertex or vertices.
For polygon elements, the last vertex is the same as the first vertex, and for path elements that end with a closed subpath, the last vertex is the same as the first vertex of that final subpath. In this case, if the value of marker-end is not none, then it is possible that two markers will be rendered on that final vertex.
Note: marker-start and marker-end refer to the first and last vertex of the entire path, not each subpath.
The following example shows a triangular marker symbol used as a vertex marker to form an arrowhead at the end of two paths.
<svg xmlns="http://www.w3.org/2000/svg"
width="275" height="200" viewBox="0 0 275 200">
<defs>
<marker id="Triangle" viewBox="0 0 10 10" refX="1" refY="5"
markerUnits="strokeWidth" markerWidth="4" markerHeight="3"
orient="auto">
<path d="M 0 0 L 10 5 L 0 10 z" fill="context-stroke"/>
</marker>
</defs>
<g fill="none" stroke-width="10" marker-end="url(#Triangle)">
<path stroke="crimson" d="M 100,75 C 125,50 150,50 175,75"/>
<path stroke="olivedrab" d="M 175,125 C 150,150 125,150 100,125"/>
</g>
</svg>
The triangle is placed at the end of the path and oriented automatically so that it points in the right direction. The use of context-stroke ensures the fill of the triangle matches the stroke of each path.
5. Segment markers: the marker-segment property
| Name: | marker-segment |
|---|---|
| Value: | none | <marker-ref> |
| Initial: | none |
| Applies to: | markable elements |
| Inherited: | yes |
| Percentages: | n/a |
| Media: | visual |
| Computed value: | as specified, but with <url> values (that are part of a <marker-ref>) made absolute |
| Animatable: | yes |
Note: New in SVG 2. Added to allow automatically placing marker symbols on path edges, as is common in for example line graphs.
The marker-segment property is used to specify the marker that will be drawn at the center of each length path segment. Possible values are:
- none
- Indicates that no marker symbol will be drawn at the given vertex or vertices.
- <marker-ref>
- Indicates that the marker element referenced by the <marker-ref> value will be drawn at the center of each path segment. If the reference is not valid, then no marker will be drawn at the path segment centers.
The following example shows the use of both vertex markers and segment markers to construct a line graph.
<svg xmlns="http://www.w3.org/2000/svg" width="400" height="200">
<marker id="Circle" markerWidth="8" markerHeight="8" refX="4" refY="4"
markerUnits="userSpaceOnUse">
<circle cx="4" cy="4" r="3" fill="deeppink"/>
</marker>
<marker id="Cross" markerWidth="10" markerHeight="10" refX="0" refY="0"
viewBox="-5 -5 10 10" markerUnits="userSpaceOnUse"
fill="none">
<path d="M -4,-4 L 4,4 M -4,4 L 4,-4" stroke="white" stroke-width="4"/>
<path d="M -4,-4 L 4,4 M -4,4 L 4,-4" stroke="black" stroke-width="2"/>
</marker>
<!-- grid lines -->
<path stroke="#888" d="M 40,20 360,20 M 40,40 360,40 M 40,60 360,60
M 40,80 360,80 M 40,100 360,100 M 40,120 360,120
M 40,140 360,140 M 40,160 360,160 M 40,180 360,180"/>
<!-- the graph line -->
<polyline points="50,100 100,20 150,50 200,130 250,80 300,170 350,100"
fill="none" stroke="deeppink" stroke-width="2"
marker="url(#Circle)" marker-segment="url(#Cross)"/>
</svg>
Segment markers are used to place crosses at the center of each line segment in the line graph.
6. Repeating markers: the marker-pattern property
| Name: | marker-pattern |
|---|---|
| Value: | <marker-gap>? <marker-ref-group> [ <marker-gap> <marker-gap> ]* <marker-gap>? |
| Initial: | none |
| Applies to: | markable elements |
| Inherited: | yes |
| Percentages: | n/a |
| Media: | visual |
| Computed value: | as specified, but with <url> values (that are part of a <marker-ref>) made absolute |
| Animatable: | yes |
where:
<marker-gap> = <length> | <percentage> | <number>
<marker-ref-group> = none | <marker-ref>+
Note: New in SVG 2. Added to allow markers to be placed along a path at positions unrelated to the segments used to form the path.
The marker-pattern property is used to specify a pattern of markers and gaps to be repeated along the length of the markable element. Values have the following meanings:
- none
- Indicates that no marker will be painted at the current position along the path.
- <marker-gap>
- Indicates the length of a gap in the repeated pattern of markers.
- <marker-ref>
- A reference to a marker that will be placed at the current position along the path. If the reference is not valid, then no marker for that <marker-ref> will be painted.
If a value other than none is given, and the sum of the <length>s, <percentage>s and <number>s is not positive, then it is an invalid value.
Unlike vertex markers, the orientation of an ''orient="auto"'' repeating marker that happens to lie on a vertex does not take into account the incoming and outgoing directions. Instead, it is simply oriented such that its positive x-axis is aligned with the direction of the path at its position.
The following example shows the use of the marker-pattern property to specify a repeating pattern of two different markers spaced along a path.
<svg xmlns="http://www.w3.org/2000/svg" width="600" height="200">
<marker id="DoubleDash" markerWidth="8" markerHeight="12" refX="0" refY="0"
viewBox="-4 -6 8 12" markerUnits="userSpaceOnUse" orient="auto">
<rect x="-3" y="-5" width="2" height="10"/>
<rect x="1" y="-5" width="2" height="10"/>
</marker>
<marker id="SingleDash" markerWidth="4" markerHeight="12" refX="0" refY="0"
viewBox="-2 -6 4 12" markerUnits="userSpaceOnUse" orient="auto">
<rect x="-1" y="-5" width="2" height="10"/>
</marker>
<path d="M 50,100 S 100,132 150,86 200,173 250,76 300,81
350,136 400,87 450,166 500,87 550,96"
stroke="deeppink" stroke-width="2" fill="none"
marker-pattern="40 url(#DoubleDash) 40 url(#SingleDash)"/>
</svg>
Markers specified with the marker-pattern property are placed along the path at fixed distances, not relative to the path vertices.
7. Marker shorthand: the marker property
| Name: | marker |
|---|---|
| Value: | |
| Initial: | none |
| Applies to: | markable elements |
| Inherited: | no |
| Percentages: | see individual properties |
| Media: | visual |
| Computed value: | see individual properties |
| Animatable: | see individual properties |
The marker property sets values for the marker-start, marker-mid, marker-end, marker-segment and marker-pattern properties. Values for have the following meanings:
- none | <marker-ref>
- Sets marker-start, marker-mid and marker-end to the specified value, and sets marker-segment and marker-pattern to none.
- [ none | <marker-ref> ]{2}
- Sets marker-start and marker-end to the two values specified, and sets marker-mid, marker-segment and marker-pattern to none.
- [ none | <marker-ref> ]{3}
- Sets marker-start, marker-mid and marker-end to the three values specified, and sets marker-segment and marker-pattern to none.
- [ none | <marker-ref> ]{4}
- Sets marker-start, marker-segment, marker-mid and marker-end to the four <marker-ref> values specified, and sets marker-pattern to none.
- [ none | <marker-ref> ]{1,4} / marker-pattern
- Sets marker-start, marker-segment, marker-mid and marker-end to the four <marker-ref> values specified before the slash, and sets marker-pattern to the value after the slash.
- anything else
- Sets marker-start, marker-segment, marker-mid and marker-end to none, and sets marker-pattern to the specified value.
8. Knocking out the stroke: the marker-knockout-left and marker-knockout-right properties
The marker knockout properties are still under heavy development and are subject to change. Feedback on how authors might prefer to specify marker knockout shapes is welcome.
| Name: | marker-knockout-left, marker-knockout-right |
|---|---|
| Value: | <knockout-offset> | <knockout-shape> [ at <knockout-offset> ]? |
| Initial: | 0 |
| Applies to: | marker |
| Inherited: | no |
| Percentages: | see prose |
| Media: | visual |
| Computed value: | as specified |
| Animatable: | yes |
where:
<knockout-offset> = <length> | <percentage> | <number>
<knockout-shape> =[ <length> | <percentage> | <number> ] inverted? circle |
[ <length> | <percentage> | <number> ]{2} inverted? ellipse |
[ <length> | <percentage> | <number> ]{1,2} inverted? [ rectangle | triangle ]
Note: New in SVG 2. Added to allow authors to specify parts of a stroke that should be clipped away when a marker is placed on a path. This helps with arrowheads, where the stroke must not be visible behind the pointy end, and with hollow markers as seen in metro maps, where the center of a marker is transparent and the stroke should not show through.
When specified on a marker element, the marker-knockout-left and marker-knockout-right properties together specify a shape to clip away when when painting the stroke of an element that uses the marker. marker-knockout-left specifies the left side of the shape and marker-knockout-right the right side. These two sides are joined together with straight lines.
The <knockout-offset> part of the value, if specified, is the offset from the marker position, outwards, along the tangent, that the knockout shape side is placed at. This is the knockout shape side position. If it is omitted, then the offset is assumed to be zero. The value can be negative. Percentage values refer to the width of the marker contents viewport.
The <knockout-shape> part of the value, if specified, is the left or right side of the knockout shape. Values have the following meanings:
- [ <length> | <percentage> | <number> ]{2} inverted? ellipse
-
The knockout shape side is an arc. The lengths or percentages specified are the x-radius and y-radius of the ellipse from which the arc is taken. A length is interpreted as being in the marker contents coordinate system. If the first value is a percentage, then it refers to the width of the marker contents viewport, and if the second value is a percentage then it refers to the height of the marker contents viewport.
If the inverted keyword is not specified, then the arc is constructed by placing the center of the ellipse at the knockout shape side position. First we consider only the 180° arc of the ellipse which points in the direction of the start of the start of the path, if this is the left knockout shape side, or the end of the path if this is the right knockout shape side. If the y-radius is less than or equal to half of the stroke width of the path the marker is on, then this 180° arc is the final knockout shape side. Otherwise, we intersect the arc with the two lines that are offset, by half of the stroke width, from the tangent to the marker orientation. The resulting arc with its start and end points on these two lines is the final knockout shape side.
If the inverted keyword is specified, then the arc is constructed by placing the center of the ellipse at a distance of two times its x-radius along the tangent to the marker orientation, in the direction of the start of the path if this is the left knockout shape side, or the end of the path if this is the right knockout shape side. We consider only the 180° arc of the ellipse that is pointing in the opposite direction. If the y-radius is less or equal to half of the stroke width of the path the marker is on, then this 180° arc is the final knockout shape side. Otherwise, we intersect the arc with the two lines that are offset, by half of the stroke width, from the tangent to the marker orientation. The resulting arc with its side and end points on these two lines is the final knockout shape side.
- [ <length> | <percentage> | <number> ] inverted? circle
-
The knockout shape side is an arc. The shape is computed in the same way as the ellipse shape, but with both radii of the ellipse being the specified length or percentage, and with a percentage referring to the size of the marker contents viewport.
- [ <length> | <percentage> | <number> ]{1,2} inverted? rectangle
-
The knockout shape side comprises one or two rectangles. These rectangles are aligned such that their top and bottom edges are parallel to the tangent to the marker orientation. The length or percentage is a width and the second, if specified, is a height. Percentage values here refer to the width and height of the marker contents viewport, respectively.
If the inverted keyword is not specified, then the knockout shape side is a single rectangle. The width of the rectangle is the specified width value. The height of the rectangle is the maximum of the stroke width of the path on which the marker exists and the specified height value, if it is specified. If it is not specified, then the height of the rectangle is just the stroke width. The rectangle is posisioned such that the center of its right hand edge is positioned at the knockout shape side position and the extent of its width is in the direction of the start of the path, if this is the left knockout shape side, or the end of the path if this is the right knockout shape side.
If the inverted keyword is specified, then the knockout shape side comprises two rectangles. If the specified height is greater than or equal to the stroke width, then the height of these rectangles is zero; otherwise, their heights are half of the difference between the stroke width and the specified height. The top edge of one of the rectangles is half of the stroke width away from the marker orientation tangent line, with its bottom edge closer to the tangent line. The other rectangle has its bottom edge half of the stroke width away from the tangent line and its top edge closer to the tangent line. The right edges of the rectangles are aligned with each other and also with the line perpendicular to the marker orientation tangent line. The extent of the widths of the rectangles is in the direction of the start of the path, if this is the left knockout shape side, or the end of the path if this is the right knockout shape side.
- [ <length> | <percentage> | <number> ]{1,2} inverted? [ rectangle | triangle ]
-
The knockout shape side comprises one or two rectangles. These rectangles are aligned such that their top and bottom edges are parallel to the tangent to the marker orientation. The length or percentage is a width and the second, if specified, is a height. Percentage values here refer to the width and height of the marker contents viewport, respectively.
If the inverted keyword is not specified, then the knockout shape side is a single rectangle. The width of the rectangle is the specified width value. The height of the rectangle is the maximum of the stroke width of the path on which the marker exists and the specified height value, if it is specified. If it is not specified, then the height of the rectangle is just the stroke width. The rectangle is positioned such that the center of its right hand edge is positioned at the knockout shape side position and the extent of its width is in the direction of the start of the path, if this is the left knockout shape side, or the end of the path if this is the right knockout shape side.
If the inverted keyword is specified, then the knockout shape side comprises two rectangles. If the specified height is greater than or equal to the stroke width, then the height of these rectangles is zero; otherwise, their heights are half of the difference between the stroke width and the specified height. The top edge of one of the rectangles is half of the stroke width away from the marker orientation tangent line, with its bottom edge closer to the tangent line. The other rectangle has its bottom edge half of the stroke width away from the tangent line and its top edge closer to the tangent line. The right edges of the rectangles are aligned with each other and also with the line perpendicular to the marker orientation tangent line. The extent of the widths of the rectangles is in the direction of the start of the path, if this is the left knockout shape side, or the end of the path if this is the right knockout shape side.
- [ <length> | <percentage> | <number> ]{1,2} inverted? triangle
A diagram showing the construction of these shapes would be helpful.
Need to define how the two shape sides are joined together. It’s taking the top and bottom points from both shapes, drawing vertical lines to the edge of the stroke shape, then drawing two horizontal lines to join them together.
The two knockout shape sides must not intersect, although they may touch. If they do intersect, then no knockout is performed for that marker when painting the stroke.
Note: For example, using 8px inverted triangle at -4px for marker-knockout-left and 8px triangle for marker-knockout-right is allowed, as the two straight lines that form the left shape side do not intersect with either of the two straight lines that form the right shape side. However, using 8px triangle at -4px for both properties would obviously cause an intersection, and so would not be allowed.
An illustration of the use of inverted and non-inverted circle, rectangle and triangle knockout shapes, at both 0px and 10px offsets. The value beneath each pink stroke is used for both marker-knockout-left and marker-knockout-right. (The marker itself here has no content and does not render anything.)
While this is nice for straight line segments, if the path is curved at the marker position then it might be preferable to have the knockout shapes aligned with the tangent at the knockout shape side position, rather than with the marker orientation. Especially if the knockout is being used as a fancy dash pattern. Then we would likely want to join the left and right sides of the shape with a curved shape (along the stroke) and not just a rectangle. If we allow this, then computing that shape is going to be hard, and will mean that determining whether the left and right sides of the knockout shape intersect, and determining what the intersections of all of the knockout shapes on a path are, is also going to be hard. Perhaps that can be handled by extending dashing line caps with these shapes rather than here? Regardless of whether it is handled by marker knockouts or new line caps, it’s going to be non-trivial to compute the right shapes.
Another thing to note is that knockouts here are like setting up a clipping path to remove parts of the stroke when it’s painted. That means that if the stroke intersects itself over the knockout areas, it’s going to be knocked out of all bits of the stroke that go through those areas. That may or may not be fine depending on your use cases.
9. Details on how markers are rendered
Markers are drawn after the given object is filled and stroked.
For each marker that is drawn, a temporary new user coordinate system is established so that the marker will be positioned and sized correctly, as follows:
- The axes of the temporary new user coordinate system are aligned according to the orient attribute on the marker element and the slope of the curve at the given vertex. (Note: if there is a discontinuity at a vertex, the slope is the average of the slopes of the two segments of the curve that join at the given vertex. If a slope cannot be determined, the slope is assumed to be zero.)
- A temporary new coordinate system is established by attribute markerUnits. If markerUnits equals strokeWidth, then the temporary new user coordinate system is the result of scaling the current user coordinate system by the current value of property stroke-width. If markerUnits equals userSpaceOnUse, then no extra scale transformation is applied.
- An additional set of transformations might occur if the marker element includes a viewBox attribute, in which case additional transformations are set up to produce the necessary result due to attributes viewBox and preserveAspectRatio.
- If the overflow property on the marker element indicates that the marker needs to be clipped to its viewport, then an implicit clipping path is established at the bounds of the viewport.
The rendering effect of a marker is as if the contents of the referenced marker element were deeply cloned into a separate non-exposed DOM tree for each instance of the marker. Because the cloned DOM tree is non-exposed, the SVG DOM does not show the cloned instance of the marker.
For user agents that support Styling with CSS, the conceptual deep cloning of the referenced marker element into a non-exposed DOM tree also copies any property values resulting from the CSS cascade ([CSS21], chapter 6) and property inheritance on the referenced element and its contents. CSS 2.1 selectors can be applied to the original (i.e., referenced) elements because they are part of the formal document structure. CSS 2.1 selectors cannot be applied to the (conceptually) cloned DOM tree because its contents are not part of the formal document structure.
For illustrative purposes, we’ll repeat the marker example shown earlier:
<?xml version="1.0" standalone="no"?>
<svg width="4in" height="2in"
viewBox="0 0 4000 2000"
xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="Triangle"
viewBox="0 0 10 10" refX="0" refY="5"
markerUnits="strokeWidth"
markerWidth="4" markerHeight="3"
orient="auto">
<path d="M 0 0 L 10 5 L 0 10 z" />
</marker>
</defs>
<rect x="10" y="10" width="3980" height="1980"
fill="none" stroke="blue" stroke-width="10" />
<desc>Placing an arrowhead at the end of a path.
</desc>
<path d="M 1000 750 L 2000 750 L 2500 1250"
fill="none" stroke="black" stroke-width="100"
marker-end="url(#Triangle)" />
</svg>
The rendering effect of the above file will be visually identical to the following:
<?xml version="1.0" standalone="no"?>
<svg width="4in" height="2in"
viewBox="0 0 4000 2000"
xmlns="http://www.w3.org/2000/svg">
<desc>File which produces the same effect
as the marker example file, but without
using markers.
</desc>
<rect x="10" y="10" width="3980" height="1980"
fill="none" stroke="blue" stroke-width="10" />
<!-- The path draws as before, but without the marker properties -->
<path d="M 1000 750 L 2000 750 L 2500 1250"
fill="none" stroke="black" stroke-width="100" />
<!-- The following logic simulates drawing a marker
at final vertex of the path. -->
<!-- First off, move the origin of the user coordinate system
so that the origin is now aligned with the end point of the path. -->
<g transform="translate(2500,1250)" >
<!-- Rotate the coordinate system 45 degrees because
the marker specified orient="auto" and the final segment
of the path is going in the direction of 45 degrees. -->
<g transform="rotate(45)" >
<!-- Scale the coordinate system to match the coordinate system
indicated by the 'markerUnits' attributes, which in this case has
a value of 'strokeWidth'. Therefore, scale the coordinate system
by the current value of the 'stroke-width' property, which is 100. -->
<g transform="scale(100)" >
<!-- Translate the coordinate system by
(-refX*viewBoxToMarkerUnitsScaleX, -refY*viewBoxToMarkerUnitsScaleY)
in order that (refX,refY) within the marker will align with the vertex.
In this case, we use the default value for preserveAspectRatio
('xMidYMid meet'), which means find a uniform scale factor
(i.e., viewBoxToMarkerUnitsScaleX=viewBoxToMarkerUnitsScaleY)
such that the viewBox fits entirely within the viewport ('meet') and
is center-aligned ('xMidYMid'). In this case, the uniform scale factor
is markerHeight/viewBoxHeight=3/10=.3. Therefore, translate by
(-refX*.3,-refY*.3)=(0*.3,-5*.3)=(0,-1.5). -->
<g transform="translate(0,-1.5)" >
<!-- There is an implicit clipping path because the user agent style
sheet says that the 'overflow' property for markers has the value
'hidden'. To achieve this, create a clipping path at the bounds
of the viewport. Note that in this case the viewport extends
0.5 units to the left and right of the viewBox due to
a uniform scale factor, different ratios for markerWidth/viewBoxWidth
and markerHeight/viewBoxHeight, and 'xMidYMid' alignment -->
<clipPath id="cp1" >
<rect x="-0.5" y="0" width="4" height="3" />
</clipPath>
<g clip-path="url(#cp1)" >
<!-- Scale the coordinate system by the uniform scale factor
markerHeight/viewBoxHeight=3/10=.3 to set the coordinate
system to viewBox units. -->
<g transform="scale(.3)" >
<!-- This 'g' element carries all property values that result from
cascading and inheritance of properties on the original 'marker' element.
In this example, neither fill nor stroke was specified on the 'marker'
element or any ancestors of the 'marker', so the initial values of
"black" and "none" are used, respectively. -->
<g fill="black" stroke="none" >
<!-- Expand out the contents of the 'marker' element. -->
<path d="M 0 0 L 10 5 L 0 10 z" />
</g>
</g>
</g>
</g>
</g>
</g>
</g>
</svg>
