C Implementation Requirements

This appendix is normative.

C.1 Introduction

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

C.2 Unsupported elements, attributes, properties, attribute values and property values

User Agents shall ignore unknown attributes, attribute values, styling properties, styling property values, and descendant elements as follows:

• Unknown elements, including unknown elements in the SVG namespace, and their descendant elements are not rendered. The processing model for unknown elements is equivalent to an <svg:g> element with the 'display' property set to 'none'.
• For known elements in the SVG namespace, unknown attributes that have no namespace and known attributes with unsupported values are treated as if they hadn't been specified when rendering. Unsupported values are defined in the definitions section. Unsupported values for known attributes must also cause a highly perceivable warning in the user agent.
• 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 treat the attributes as if they were not specified.
• User agents must implement the CSS2 rules for unknown styling properties and known styling properties that have unsupported values.

C.3 Error processing

There are various scenarios where an SVG document fragment is technically in error:

• When the content does not conform to the XML 1.0 specification [XML10], such as the use of incorrect XML syntax
• 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 DOM 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 User Agent shall provide a highly perceivable indication of error. The following error handling behavior represents a recommended approach that User Agents may choose to implement:

• The document should be rendered up to, but not including, the first element which has an error. Exceptions:
  • If a 'path' element is the first element which has an error and the only errors are in the path data specification, then render the 'path' up to the point of the path data error. For related information, see 'path' element implementation notes.
  • If a 'polyline' or 'polygon' element is the first element which has an error and the only errors are within the points attribute, then render the 'polyline' or 'polygon' up to the segment with the error.
  This approach will provide a visual clue to the user or developer about where the error might be in the document.
• If the document has animations, the animations should stop at the point at which an error is encountered and the visual presentation of the document should reflect the animated status of the document at the point the error was encountered.
• For visual rendering situations, an example of an indication of error would be to render a translucent colored pattern such as a checkerboard on top of the area where the SVG content is rendered.
• If the user agent has access to an error reporting capability such as status bar, it is recommended that the user agent provide whatever additional detail it can to enable the user or developer to quickly find the source of the error. For example, the user agent might provide an error message along with a line number and character number at which the error was encountered.

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. In particular, error processing shall be disabled whenever redraw has been suspended via DOM calls to suspendRedraw().

C.3.1 Example

This example shows the differences between erroneous and unsupported values. The first rectangle is conformant. The next two rectangles have unsupported values for the known attribute width. These values are not specifically listed as errors in the specification, but do not conform to the syntax for length. In both these cases the attribute should be ignored for rendering and the default value of zero should be used for the width. The last (fourth) rectangle in the example contains a value for 'width' that is explicitly listed as in error, thus at this point the document goes into error.

C.4 Namespace, version, baseProfile, requiredFeatures and requiredExtensions

The outermost <svg> element must be defined in the SVG namespace (e.g., <svg xmlns="http://www.w3.org/2000/svg">); otherwise the document is in error.

The attributes 'version', 'baseProfile', 'requiredFeatures' and 'requiredExtensions' identify the minimal functional requirements of an SVG user agent in order to render the content successfully. If these attributes identify a version, a profile, features or extensions, and the features are not supported by the user agent, then the user agent should alert or otherwise notify the user that the version of the file is not supported and suggest an alternate processing option (e.g., installing an updated version of the user agent) if such an option exists.

C.5 Clamping values which are restricted to a particular range

Some numeric attribute and property values have restricted ranges, such as color component values. When out-of-range values are provided, the user agent shall 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. It is recommended that user agents clamp color values to the nearest color value (possibly determined by simple clipping) which the system can process as late as possible (e.g., presentation time), although it is acceptable for 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).

C.6 '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 is 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, do not draw the linecap for that segment; however, do draw the linecap for zero-length path segments when 'stroke-linecap' is set to either round or square. (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 is 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)
  

• A non-positive radius value is an error.
• Unrecognized contents within a path data stream (i.e., contents that are not part of the path data grammar) is an error.

C.7 Text selection implementation notes

The following implementation notes describe the algorithm for deciding which characters are selected during a text selection operation.

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 consists of either:

• no selection or
• a start character, an end character (possibly the same character), and all of the characters within the same 'text' 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 determines 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 then tracks 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 determines 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 consists 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 will 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 might 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 can either disallow the selection to start in the middle of the glyph set or can 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 pointer devices such as a mouse, the user agent is required to provide a mechanism for selecting text even when the given text has associated event handlers or links, which might block text selection due to event processing precedence rules (see Pointer events). One implementation option: For platforms which support a pointer device such as a mouse, the user agent may provide for a small additional region around character cells which initiates text selection operations but does not initiate event handlers or links.

C.8 Printing implementation notes

For user agents which support both zooming on display devices and printing, it is recommended that the default printing option 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.