Copyright © 2004-2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
SVG is language for describing vector graphics. SVG vector effects is a way of elaborating the vector geometry prior to rasterisation and rendering. This alows the authored geometry to be kept simple, while the rendered result is more compex.
This document introduces the features used by SVG Vector Effects.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.
This document is the first public working draft of this specification. It is derived from chapter 9 of the SVG 1.2 Full specification, which is no longer developed. There is an accompanying SVG Vector Effects 1.2, Part 1: Primer that lists the ways SVG Vector Effects may be used.
This document has been produced by the W3C SVG Working Group as part of the W3C Graphics Activity within the Interaction Domain.
We explicitly invite comments on this specification. Please send them to public-svg-filters@w3.org (archives). For comments on the core SVG language, use www-svg@w3.org: the public email list for issues related to vector graphics on the Web (archives). Acceptance of the archiving policy is requested automatically upon first post to either list. To subscribe to these lists send an email to public-svg-filters-request@w3.org or www-svg-request@w3.org with the word subscribe in the subject line.
The latest information regarding patent disclosures related to this document is available on the Web. As of this publication, the SVG Working Group are not aware of any royalty-bearing patents they believe to be essential to SVG.
Publication of this document does not imply endorsement by the W3C membership. A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/. W3C publications may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite a W3C Working Draft as anything other than a work in progress."
This draft of SVG Vector Effects is essentially the normative portions of chapter 9 of the SVG 1.2 Full specification. Clarifications have been made in response to feedback from reviewers and implementors.
It is probably best to read the SVG Vector Effects Primer before reading this specification. That document, which is non normative, explains what Vector Effects do, why they are needed, and the sort of visual effect produced.
The main purpose of this document is to encourage public feedback. The best way to give feedback is by sending an email to public-svg-wf@w3.org. Please include some kind of keyword that identifies the area of the specification the comment is referring to in the subject line of your message (e.g "Section X.Y - the 'vsStrokePath' element"). If you have comments on multiple areas of this document, then it is probably best to split those comments into multiple email messages.
The public are welcome to comment on any aspect in this document, but there are a few areas in which the SVG Working Group are explicitly requesting feedback. These areas are noted in place within this document.
Note that even though this specification references parts of SVG 1.1 it does not require a complete SVG 1.1 implementation.
This document is normative.
This document contains explicit conformance criteria that may overlap with some RNG definitions in requirements. If there is any conflict between the two, the explicit conformance criteria are the definitive reference.
The vectorEffect element defines a transformation of a primitive shape's outline that happens before it is drawn. The transformation is described as a series of vector effect primitive processing nodes, where input(s) and the output of every node can be considered to be SVG path data. Any primitive shape or path element can reference a vector effect through the vector-effect property. Alternatively, vector effects can be used as a drawing element; in such case its input is considered to be empty (and the vePath element must be used to get input data).
Attribute definitions:
The lacuna value is "userSpaceOnUse". The output of the last vector effect node is considered to be the result of the complete vector effect. That path is used when shape's outline is normally used (inside clipPath, for text flows and text on a path, and when referenced by a vePath element).
Animatable: no.
The value "normal" means that results of the individual fill operations are composited with each other (using the Porter-Duff srcOver operator). The value "clip" means that painting operations should be processed last to first and after every painting operation, a clipping should be applied that excludes (clips out) the path just painted from the paintable region. The effect is that areas that were painted already won't be painted over. The lacuna value is "normal".
Animatable: no.
This is the default vectorEffect, which corresponds to the default SVG painting behavior:
<vectorEffect> <veFill/> <veStroke/> <veMarker/> </vectorEffect>
The following vector effect will result in no rendering (i.e., neither the fill, the stroke, nor the markers are rendered).
<vectorEffect/>
The following common attributes are available on multiple vector effect primitives, so are described here.
Attribute definitions:
The result attribute specifies the location, if necessary, of the output from the current vector effect primitive. It is analogous to the result attribute on filter effect primitives. If not specified, the value is empty, and the result is only passed to the following primitive.
Animatable: no.
Whether or not each attribute should be animatable needs to be discussed. This applies to the whole specification
The in and in2 attributes define the input locations for the current vector effect primitive. The value of "SourcePath" means that the outline of the shape that references this effect is used. Any other values refer to the output of another node within this vectorEffect identified by the value of its result attribute. If this attribute is omitted, for the first primitive the value "SourcePath" is used, and the output of the previous primitive is used for all other nodes. The path used for "SourcePath"is always pre-transformed to be in the correct coordinate space depending on the value of the vectorEffectUnits attribute value.
Animatable: no.
The transform and transformPath attributes supply coordinate space transformations for some vector effect elements. The difference between them is that the transform attribute defines the coordinate space where a particular operation occurs so that the input is transformed into that coordinate space, the vector effect operation applied and then the inverse transform applied to the result. In contrast, transformPath is simply applied to the input of the particular operation. The default value is empty.
Animatable: yes.
The veStrokePath element produces an outline of the input path's stroke. It is calculated using the given stroke parameters. The lacuna values come from the corresponding computed property values of the source element. Width attribute percentages are interpreted relative to the source element stroke-width property.
Attribute definitions:
The stroke-dasharray attribute takes the same values as the stroke-dasharray property.
Whether these attributes should allow the value "inherit", which does nothing here, needs to be discussed.
Animatable: yes.
The stroke-dashoffset attribute takes the same values as the stroke-dashoffset property.
Animatable: yes.
The stroke-linecap attribute takes the same values as the stroke-linecap property.
Animatable: yes.
The stroke-linejoin attribute takes the same values as the stroke-linejoin property.
Animatable: yes.
The stroke-miterlimit attribute takes the same values as the stroke-miterlimit property.
Animatable: yes.
The stroke-width attribute takes the same values as the stroke-width property.
Animatable: yes.
What about stroke-opacity?
The veSetback element performs a path "setback" operation: it breaks the path into individual segments and shortens both ends of every segment by the distance specified by setback-offset.
Attribute definition:
The setback-offset attribute is a list of four lengths, interpreted as follows:
If the list contains less than four lengths, the missing ones are taken to be zero (i.e. no offset).
Animatable: yes.
The veAffine element transforms a path using the specified transformation matrix.
The veReverse element reverses the direction of the path. The path is adjusted such that all of the vertices on the path are put in reverse order (i.e., if there are N vertices numbered 0 to N-1, then vertex K is moved to position N-K-1) with adjustments to the path commands and control points to produce the same shape as the original path. In effect, it is as if the path segments have been played backward.
There are a variety of effects that rendering results from a veReverse operation. They include swapping the begin and end markers and a 180 degree orientation change for automatically oriented markers. There are potentially different results when rendering compound paths.
The veJoin element joins two paths together by a concatenation operation on the path data commands for the two paths (the path referenced by in2 is concatenated to the end of the path referenced by in).
Attribute definitions:
If the connect attribute has a value of "none", the path segments are concatenated without change. A value of "line" means that, if an "M" command starts the second path, it is replaced with an "L" command with the same parameters. The lacuna value is "none"
Animatable: no.
The veUnion element produces an outline of the union of two shapes. The geometric effect is equivalent to the result of a geometric computation of additive clipping paths (i.e., logical OR'ing of the silhouettes produced by each of the shapes).
The veIntersect element produces an outline of the intersection of two shapes. The geometric effect is equivalent to the result of a geometric computation of nested clipping paths.
The veExclude element produces an outline of the exclusion of the second shape, provided by in2, from the first shape, provided by in. The geometric effect of veExclude is equivalent to a geometric "clip out" computation where the resulting path geometry is the geometric clip of the first shape against a composite shape consisting of a veJoin of: (a) a very large rectangle (i.e., a rectangle whose bounding box is outside the bounds of the first shape) and (b) the second shape after a veReverse operation.
The veFill element fills a shape using the paint given by the fill property and the opacity value given by the fill-opacity property. For the fill property, values of "currentStroke" and "currentFill" correspond to the computed value of stroke and fill on the source element. For the fill-opacity property, values of "currentStrokeOpacity" and "currentFillOpacity" correspond to the computed value of stroke-opacity and fill-opacity on the source element. The output of the veFill element is the same as its input.
Attribute definitions:
The fill attribute takes the same values as the fill property, plus the two keywords currentPaint and currentFill.
Animatable: yes.
The attribute takes the same values as the fill-opacity property.
Animatable: yes.
fill-rule needed or not? (suspect not)
The veStroke element creates a shape that represents the path of the shape's stroke (taking into account the stroke properties on the source element) and then fills the stroke using the paint server given by the fill property and the opacity value given by the fill-opacity property.
Attribute definitions:
The fill attribute takes the same values as the fill property, plus the two keywords currentPaint and currentFill.
Animatable: yes.
The attribute takes the same values as the fill-opacity property.
Animatable: yes.
For the fill property, values of "currentStroke" and "currentFill" mean the computed value of stroke and fill on the source element. For the fill-opacity property, values of "currentStrokeOpacity" and "currentFillOpacity" mean the computed value of stroke-opacity and fill-opacity on the source element. The output of the veStroke element is the same as its input.
Note that the veStroke element has fill and fill-opacity attributes and not stroke and stroke-opacity attributes. This is because the conceptual model for stroking within vector effects is that you first perform an implicit veStrokePath operation to create a new shape, and then you paint the region of (i.e., you "fill") that new shape.
The veMarker element draws markers along the input path. Its output is the same as its input.
Attribute definitions:
The marker-start, marker-end and marker-mid attributes take the same values as the corresponding marker properties.
Animatable: yes.
The shorthand 'marker' is not allowed, because otherwise there could be two sets of markers, and precedence would be problematic when the individual marker attributes were also specified.
The veMarkerPath element behaves like veMarker but instead of drawing, it produces its output by taking the union of the paths of all the markers.
Note that because of the geometric flattening, multicolored markers will become a single object with a single fill. Together with a fill of currentStroke, this allows the commonly-requested feature of markers which take the color of the path on which they are used.
Attribute definitions:
The marker-start, marker-end and marker-mid attributes take the same values as the corresponding marker properties.
Animatable: yes.
The vePath element does not take input and its result is the path taken from the shape(s) which it references. The path references come from child vePathRef elements. Individual paths are transformed according to the transformPath attribtue on vePathRef and then joined together in the same manner as veJoin.
The vePathRef element is a child node for the vePath element that references an individual path. It is an error for this element to reference anything but a primitive shape, a path or a text element.
Attribute definitions:
If the connect attribute has a value of "none", the path segments are concatenated without change. A value of "line" means that, if an "M" command starts the second path, it is replaced with an "L" command with the same parameters. The lacuna value is "none".
Animatable: no.
The attribute specifies whether the input path should be reversed (an implicit veReverse). The lacuna value is "false".
Animatable: no.
The vector-effect property specifies the vector effect to use when drawing an object. Vector effects are applied before any of the other compositing operations: filters, masks and clips.
| Value: | 'default' | 'non-scaling-stroke' | 'inherit' | <uri> |
| Initial: | 'default' |
| Applies to: | graphical elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Animatable: | yes |
The value 'default' corresponds to the following vector effect:
<vectorEffect>
<veFill/>
<veStroke/>
<veMarker/>
</vectorEffect>
It is the default rendering behaviour from SVG 1.1.
The value 'non-scaling-stroke' is a keyword for a predefined vector effect that causes an object's stroke-width to be unaffected by transformations and zooming. That is:
<vectorEffect>
<veFill/>
<veStrokePath in="SourcePath"/>
<veFill transform="ref(host)" fill="currentStroke"/>
<veMarker in="SourcePath" transform="ref(host)"/>
</vectorEffect>
The URI value references a vectorEffect element that should be used as the vector effect.
The value "non-scaling-stroke" is designed so that it can be implemented without the entire vector effect engine. For example, profiles of SVG may restrict the values of vector-effect to be "default" or "non-scaling-stroke". In effect this requires no processing of vector effects, rather it is always the default rendering order with a different set of transformations.
la la la la la la