Implementation Requirements

This appendix is normative.

Introduction

The following are notes about implementation requirements corresponding to various features in the SVG language.

Unsupported elements, attributes, properties, attribute values and property values

Conforming SVG user agents must treat unknown attributes, attribute values, styling properties, styling property values, and descendant elements as follows:

Within an SVG document fragment, any subtree that is rooted by an unknown element (including those in the SVG or XML Events namespaces) or a known element that occurs in unexpected location, is not rendered. The nodes in the subtree are not processed beyond including the relevant DOM objects in the document tree. Those DOM objects will still implement the DOM interfaces appropriate for the element type, however.
For known elements in the SVG or XML Events namespaces, unknown attributes that have no namespace and known attributes with unsupported values are treated as if they hadn't been specified when rendering.
Attributes put in the SVG namespace on any element are processed as unknown attributes.
For unknown attributes in the XLink or XML Events namespaces, or known attributes in the XLink or XML Events namespaces with unsupported values, the user agent must process the element with regards to, respectively, linking or event handling, as if the attributes had not been specified.
The user agent must not stop processing or rendering under any of the above situations, but at user option it may alert, log, or otherwise provide a notification that unsupported content was encountered.

In Example ignored-fill below, the 'fill' property on the 'circle' element is ignored due to the above rules. Since 'fill' is an inherited property, the circle's fill is indeed green, and not black.

When unsupported content is encountered, an SVG user agent which provides access to an error console should report the incidence of unsupported content, the location where it was encountered, and other appropriate messages that may help the author, to the error console.

Error processing

A conforming SVG user agent must process errors in the following manner.

There are various scenarios where an SVG document fragment must be considered technically in error:

When the content is not well-formed according to the version of XML used (either the XML 1.0 [XML10] or XML 1.1 specifications [XML11])
When the content is not namespace-well-formed according to the Namespaces in XML 1.0 specification [XML-NS10] or the Namespaces in XML 1.1 specification [XML-NS] (depending on the version of XML used as per the previous bullet)
Other situations that are described as being in error in this specification

A document can go in and out of error over time. For example, document changes from the SVG uDOM or from animation can cause a document to become in error and a further change can cause the document to become correct again.

When a document is in error the SVG user agent must provide a highly perceivable indication of error. Additionally, an SVG user agent which provides access to an error console should report the error, the location where it was encountered, and other appropriate messages that may help the author, to the error console.

Because of situations where a block of scripting changes might cause a given SVG document fragment to go into and out of error, error processing shall occur only at times when document presentation (e.g., rendering to the display device) is updated.

Namespace, version, baseProfile, requiredFeatures and requiredExtensions

SVG user agents must only consider elements explicitly placed in the SVG namespace as being SVG elements. For example, when parsing a document, SVG user agents must only consider elements explicitly placed in the SVG namespace by XML namespace declarations in the document to be SVG elements. Similarly, any element created with the Document::createElementNS uDOM method must have had the SVG namespace passed as the namespaceURI parameter for it to be considered considered to be an SVG element.

SVG content can use attributes 'requiredFeatures' and 'requiredExtensions' to provide explicit indication of the minimal features that must be supported by the SVG user agent in order to render the SVG content correctly. SVG content can also use the 'version' attribute in conjunction with 'baseProfile' to provide explicit indication of the minimal features that must be supported. For example, if 'version' is '1.2' and 'baseProfile' is 'tiny', then these attributes indicate that the content requires a SVG user agent that minimally supports the SVG Tiny 1.2 specification. If an SVG user agent does not support the minimal required feature set, then the user agent should alert or otherwise provide a highly visible notification to the user that it may not be able to render the content correctly.

However, SVG content that provides a specified value for 'version' but does not provide a specified value for 'baseProfile' simply indicates to the user agent the specification level (1.0, 1.1, 1.2) to which the content conforms. If 'version' is specified but not 'baseProfile', the SVG content does not provide sufficient information to the user agent to determine the minimum feature set that is required to render the content; the user agent can only know that the author might be using SVG language features that were not defined in earlier versions of the language. Therefore, if the SVG content specifies a version of the SVG language unknown to the user agent, then the user agent should alert or otherwise provide a highly perceivable notification to the user that it may not be able to render the content correctly.

When SVG content specifies SVG language versions, profiles, features or extensions not supported by the currently installed user agent, the user agent may notify the user how to update the SVG user agent should a newer version be available which does support these features.

Note that the intent of the version number is to indicate the minimum implementation version for the content; an SVG user agent which encounters content with a version number unknown to the user agent must still render those elements and attributes that it does support, and must not render elements or document fragments with root elements which it does not support.

Clamping of color and opacity Values

This section describes the behaviour of SVG user agents.

Some numeric attribute and property values have restricted ranges, such as color component values. When out-of-range color or opacity values are provided, the user agent should defer any error checking until after presentation time, as composited actions might produce intermediate values which are out-of-range but final values which are within range.

Color values are not in error if they are out-of-range, even if final computations produce an out-of-range color value at presentation time. User agents should clamp color values to the nearest color value (possibly determined by simple clipping) which the system should process as late as possible (e.g., presentation time), although it is acceptable for SVG user agents to clamp color values as early as parse time. Thus, implementation dependencies might preclude consistent behavior across different systems when out-of-range color values are used.

Opacity values out-of-range are not in error and should be clamped to the range 0 to 1 at the time which opacity values have to be processed (e.g., at presentation time or when it is necessary to perform intermediate filter effect calculations).

'path' element implementation notes

A conforming SVG user agent must implement path rendering as follows:

Directionality and zero-length path segments:
- Certain line-capping and line-joining situations require that a path segment have directionality at its start and end points. Zero-length path segments have no directionality. In these cases, the following algorithm must be used to establish directionality: to determine the directionality of the start point of a zero-length path segment, go backwards in the path data specification within the current subpath until you find a segment which has directionality at its end point (e.g., a path segment with non-zero length) and use its ending direction; otherwise, temporarily consider the start point to lack directionality. Similarly, to determine the directionality of the end point of a zero-length path segment, go forwards in the path data specification within the current subpath until you find a segment which has directionality at its start point (e.g., a path segment with non-zero length) and use its starting direction; otherwise, temporarily consider the end point to lack directionality. If the start point has directionality but the end point doesn't, then the end point uses the start point's directionality. If the end point has directionality but the start point doesn't, then the start point uses the end point's directionality. Otherwise, set the directionality for the path segment's start and end points to align with the positive x-axis in user space.
- If 'stroke-linecap' is set to butt and the given path segment has zero length, the linecap for that segment must not be drawn; however, the linecap for zero-length path segments when 'stroke-linecap' is set to either round or square must be drawn. (This allows round and square dots to be drawn on the canvas.)
The S/s commands indicate that the first control point of the given cubic Bézier segment is calculated by reflecting the previous path segments second control point relative to the current point. The exact math must be as follows. If the current point is (curx, cury) and the second control point of the previous path segment is (oldx2, oldy2), then the reflected point (i.e., (newx1, newy1), the first control point of the current path segment) is:
```
(newx1, newy1) = (curx - (oldx2 - curx), cury - (oldy2 - cury))
               = (2 * curx - oldx2, 2 * cury - oldy2)
```

Text selection implementation notes

This specification does not mandate any particular scheme for visual feedback for text selection, but a conforming SVG user agent should provide such feedback as is consistent with system norms.

The following implementation notes describe the algorithm that must be used for deciding which characters are selected during a text selection operation. A conforming SVG user agent must implement the behavior specified by this algorithm.

As the text selection operation occurs (e.g., while the user clicks and drags the mouse to identify the selection), the user agent determines a start selection position and an end selection position, each of which represents a position in the text string between two characters. After determining start selection position and end selection position, the user agent selects the appropriate characters, where the resulting text selection must consist of either:

no selection or
a start character, an end character (possibly the same character), and all of the characters within the same text content element whose position in the DOM is logically between the start character and end character.

On systems with pointer devices, to determine the start selection position, the SVG user agent should determine which boundary between characters corresponding to rendered glyphs is the best target (e.g., closest) based on the current pointer location at the time of the event that initiates the selection operation (e.g., the mouse down event). The user agent should then track the completion of the selection operation (e.g., the mouse drag, followed ultimately by the mouse up). At the end of the selection operation, the user agent should determine which boundary between characters is the best target (e.g., closest) for the end selection position.

If no character reordering has occurred due to bidirectionality, then the selection must consist of all characters between the start selection position and end selection position. For example, if a 'text' element contains the string "abcdef" and the start selection position and end selection positions are 0 and 3 respectively (assuming the left side of the "a" is position zero), then the selection shall consist of "abc".

When the user agent is implementing selection of bidirectional text, and when the selection starts (or ends) between characters which are not contiguous in logical order, then there may be multiple potential combinations of characters that can be considered part of the selection. The algorithms to choose among the combinations of potential selection options shall choose the selection option which most closely matches the text string's visual rendering order.

When multiple characters map inseparably to a given set of one or more glyphs, the user agent may either disallow the selection to start in the middle of the glyph set or may attempt to allocate portions of the area taken up by the glyph set to the characters that correspond to the glyph.

For systems which support selection, the user agent must provide a mechanism for selecting text with a full range of available UI devices (e.g. keyboard, mouse, pen, or any other pointer device) as a default, even when the given text is part of a link. One implementation option for platforms which support selection via a pointer device such as a mouse is for the user agent to provide for a small additional region around character cells which initiates text selection operations but does not initiate event handlers or links. Additionally, the user agent must allow scripted or programmatic DOM access to all text content, and specifically any selected or focused content, at all times.

Printing implementation notes

In conforming SVG user agents which support both zooming on display devices and printing, the default printing option should produce printed output that reflects the display device's current view of the current SVG document fragment (assuming there is no media-specific styling), taking into account any zooming and panning done by the user, the current state of animation, and any document changes due to DOM and scripting. Thus, if the user zooms into a particular area of a map on the display device and then requests a hardcopy, the hardcopy should show the same view of the map as appears on the display device. If a user pauses an animation and prints, the hardcopy should show the same graphics as the currently paused picture on the display device. If scripting has added or removed elements from the document, then the hardcopy should reflect the same changes that would be reflected on the display.

When an SVG document is rendered on a static-only device such as a printer which does not support SVG's animation and scripting and facilities, then the user agent shall ignore any animation and scripting elements in the document and render the remaining graphics elements according to the rules in this specification.