Abstract

This specification defines the features and syntax for Scalable
Vector Graphics (SVG) Version 2. SVG is a language based on XML for describing
two-dimensional vector and mixed vector/raster graphics. SVG content is stylable,
scalable to different display resolutions, and can be viewed stand-alone,
mixed with HTML content, or embedded using XML namespaces within other XML languages.
SVG also supports dynamic changes; script can be used to create interactive documents,
and animations can be performed using declarative animation features or by using script.

Status of This Document

This section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of current W3C
publications and the latest revision of this technical report can be found in
the W3C technical reports index at https://www.w3.org/TR/.

This document is the 25 November 2016 Editor’s Draft of SVG 2. This version of SVG
builds upon SVG 1.1 Second Edition
by improving the usability of the language and by adding new features commonly
requested by authors. The Changes appendix lists all
of the changes that have been made since SVG 1.1 Second Edition.

Comments on this Editor’s Draft are welcome.
Comments can be sent to www-svg@w3.org,
the public email list for issues related to vector graphics on the Web. This list is
archived and
senders must agree to have their message publicly archived from their
first posting. To subscribe send an email to
www-svg-request@w3.org with
the word subscribe in the subject line.

The specification includes a number of annotations that the Working Group is
using to record links to meeting minutes and resolutions where specific decisions
about SVG features have been made. Different coloring is also used to mark the
maturity of different sections of the specification:

a red background indicates a section that is either unchanged since SVG
1.1 (and which therefore still requires review and possible rewriting for
SVG 2), or a section that is new but still requires substantial work

a yellow background indicates a section from SVG 1.1 that has been reviewed
and rewritten if necessary, or a new section that is complete and ready
for the rest of the Working Group to review

a white background indicates a section, either from SVG 1.1 or new for
SVG 2, that has been reviewed by the Working Group and which is ready
for wider review

Publication as a Working Draft does not imply endorsement by the W3C Membership.
This is a draft document and may be updated, replaced or obsoleted by other documents
at any time. It is inappropriate to cite this document as other than work in progress.

A list of current W3C Recommendations and other technical documents can be found at
https://www.w3.org/TR/. W3C publications
may be updated, replaced, or obsoleted by other documents at any time.

All features in this specification depend upon implementation in browsers
or authoring tools. If a feature is not certain to be implemented, we define
that feature as "at risk". At-risk features will be removed from the current
specification, and may be included in future versions of the specification. If
an at-risk feature is particularly important to authors of SVG, those authors
are encouraged to give feedback to implementers regarding its priority. The
following features are at risk, and may be dropped during the CR period:

Acknowledgments

The SVG Working Group would like to thank the following people for
contributing to this specification with patches or by participating in discussions
that resulted in changes to the document:
David Dailey,
Eric Eastwood,
Jarek Foksa,
Daniel Holbert,
Paul LeBeau,
Robert Longson,
Henri Manson,
Ms2ger,
Kari Pihkala,
Philip Rogers,
David Zbarsky.

In addition, the SVG Working Group would like to acknowledge the
contributions of the editors and authors of the previous versions
of SVG – as much of the text in this document derives from these
earlier specifications – including:

Finally, the SVG Working Group would like to acknowledge the
great many people outside of the SVG Working Group who help with the
process of developing the SVG specifications. These people are too
numerous to list individually. They include but are not limited to
the early implementers of the SVG 1.0 and 1.1 languages (including
viewers, authoring tools, and server-side transcoders), developers of
SVG content, people who have contributed on the www-svg@w3.org and
svg-developers@yahoogroups.com email lists, other Working Groups at the
W3C, and the W3C Team. SVG 1.1 is truly a cooperative effort between
the SVG Working Group, the rest of the W3C, and the public and benefits
greatly from the pioneering work of early implementers and content
developers, feedback from the public, and help from the W3C team.

Contents

1.1. About SVG

SVG is a language for describing two-dimensional graphics.
As a standalone format or when mixed with other XML, it uses the
XML syntax [xml].
SVG code used inside HTML documents uses the HTML syntax [HTML].
SVG allows for three types of graphic objects: vector graphic
shapes (e.g., paths consisting of straight lines and curves),
images and text. Graphical objects can be grouped, styled,
transformed and composited.
The feature set includes nested transformations, clipping
paths, alpha masks, filter effects and template objects.

SVG drawings can be interactive
and dynamic. Animations
can be defined and triggered
either declaratively (i.e., by embedding SVG animation elements
in SVG content) or via scripting.

Sophisticated applications of SVG are possible by use of a
supplemental scripting language which accesses
SVG Document Object Model (DOM), which
provides complete access to all elements, attributes and
properties. A rich set of event handlers
can be assigned to any SVG graphical object.
Within a web page, the same scripts can work on both HTML and SVG elements.
Scripting.

SVG is useful for rich graphical presentation of information, including a number
of accessibility features that, used correctly,
ensure the content can be used by the widest possible audience. But a direct
link to source data, where possible,
is helpful for many people to understand the content provided.

1.2. Compatibility with other standards efforts

SVG leverages and integrates with other W3C specifications
and standards efforts, as described in the following:

SVG can be integrated with HTML either by using SVG in HTML or by using HTML in SVG, in both cases either by inclusion or reference.

SVG is an application of XML and is compatible with XML 1.0 and with the Namespaces in XML specification. However, when SVG content is included in HTML document, the HTML syntax applies and may not be compatible with XML. See SVG Integration for details.

SVG includes a complete Document Object Model (DOM) and
extends DOM4.
The SVG DOM has a high level of compatibility and consistency
with the HTML DOM.
Additionally, the SVG DOM supports and
incorporates many of the facilities described in
the CSS object model and event handling
[dom-level-2-style]
[uievents].

SVG incorporates some features and approaches that are
part of SMIL 3, including
the ‘switch’ element and the ‘systemLanguage’
attribute.

SVG is compatible with W3C work on internationalization.
References (W3C and otherwise) include: [UNICODE]
and [charmod].

1.3. Normative Terminology

Within this specification, the key words "MUST", "MUST NOT",
"REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as
described in Key words for use in RFCs to Indicate Requirement Levels
[rfc2119].
However, for readability, these words do not appear in all
uppercase letters in this specification.

At times, this specification recommends good practice for
authors and user agents.

2.1. Overview

Graphics defined with SVG have many different applications.
As a result, not all software that uses SVG will have the same features.
Conformance to the SVG specification is therefore not a binary matter;
sofware may be conforming within a restricted feature set.

Furthermore, SVG is designed to be integrated into other types of documents;
depending on the type of integration, only a limited feature-set may be appropriate.
There are various ways that an SVG document fragment can be
referenced by or included in other documents and thereby
be processed by a user agent. SVG documents can also be viewed directly,
as the primary document.
Each different method by which an SVG document fragment
can be used implies a certain set of requirements on how the SVG document
fragment must be processed.

This chapter therefore defines a number of
processing modes
that encompass the different combinations of features
which may be enabled or disabled in the document.
In addition, it specifies normative requirements for which processing mode
must be used when SVG documents reference or embed other SVG documents.
The same set of processing modes may be used by reference in other specifications
to describe how SVG documents should be processed.

This document does not place normative requirements on
other specifications that can reference or include SVG documents, such as
HTML and various CSS specifications. The intention is for these other
specifications to normatively point to the appropriate processing mode
from this document.

2.2. Processing modes

This section defines a standard set of processing modes
for SVG documents. Each processing mode specifies whether certain high level
SVG features are enabled.

2.2.1. Features

The features that can be enabled or disabled depending
on the processing mode are as follows:

declarative animation

Declarative animation includes both the animation elements in SVG –
‘animate’, ‘animateMotion’,
‘animateTransform’ and ‘set’ – and CSS Transitions and Animations
(see the Animation appendix for details).
When declarative animations are disabled in an SVG document, any
animation elements or CSS Transitions or Animations must not be applied or run.

This is not the same as pausing the document's animated
state at 0s document time; if an animation is defined to begin at 0s,
it still will not be applied.

references to external resources

References to external resources are URLs references
or network access requests
made by markup, style properties, script or other Web platform features
used in the document, except for:

When external references are disabled in an SVG document, any attempt to
fetch a document through an external reference must instead be treated as
if a network error occurred and no data was received.

When external references are enabled,
user agents that support external file requests from the Internet
must adhere to the restrictions on cross-origin resource fetching,
as outlined in the Linking chapter.

script execution

Script execution is the execution of any SVG ‘script’ elements,
script found in event attributes (such as ‘onclick’ on
SVG elements), or any other script defined by other Web platform features
used in the document, such as any HTML ‘script’ elements.
When script execution is disabled in an SVG document, no script in the
document must be run.

interaction

Interaction refers to the delivery of DOM Events or the invocation of
any user agent specific UI behaviors such as text selection, focus changing,
link traversal, or animation or transition triggering that is done in
response to user input such as mouse or keyboard activity. When
interaction is disabled in an SVG document, any user input events that would
be targetted at the document or any elements within the document must have
no effect.

2.2.2. Dynamic interactive mode

This processing mode imposes no restrictions on any
feature of the SVG language.

Dynamic Interactive Features

script execution

yes

external references

yes

declarative animation

yes

interactivity

yes

2.2.3. Animated mode

This processing mode is intended for circumstances where
an SVG document is to be used as an animated image that is allowed
to resolve external references, but which is not intended to be used
as an interactive document.

Animated Features

script execution

no

external references

yes

declarative animation

yes

interactivity

no

2.2.4. Secure animated mode

This processing mode is intended for circumstances where
an SVG document is to be used as an animated image that is not allowed
to resolve external references, and which is not intended to be used
as an interactive document. This mode might be used where image support
has traditionally been limited to raster images (such as JPEG, PNG and
GIF).

Secure Animated Features

script execution

no

external references

no

declarative animation

yes

interactivity

no

2.2.5. Static mode

This processing mode is intended for circumstances where
an SVG document is to be used as a non-animated image that is allowed
to resolve external references, but which is not intended to be used
as an interactive document.
For example,
an SVG viewer that processes graphics for inclusion in print documents
would likely use static mode.

Static Features

script execution

no

external references

yes

declarative animation

no

interactivity

no

2.2.6. Secure static mode

This processing mode is intended for circumstances where
an SVG document is to be used as a non-animated image that is not allowed
to resolve external references, and which is not intended to be used
as an interactive document. This mode might be used where image support
has traditionally been limited to non-animated raster images (such as JPEG
and PNG.)

Secure Static Features

script execution

no

external references

no

declarative animation

no

interactivity

no

2.3. Processing modes for SVG sub-resource documents

When an SVG document is viewed directly,
it is expected to be displayed using the most comprehensive
processing mode supported by the user agent.
However, when an SVG is processed
as a sub-resource or embedded document,
the following restrictions must apply:

The same processing modes are expected to be used
for other cases where SVG is used in place of a raster image,
such as an HTML ‘img’ element or
in any CSS property that takes an
<image> data type.
This is consistent with HTML's requirement
that image sources must reference
"a non-interactive, optionally animated, image resource that is neither paged nor scripted"
[HTML]

SVG documents referenced by the
an HTML ‘iframe’ element in an SVG document must use the
same processing mode as the embedding document,
subject to any restrictions defined by the
sandbox attribute
on the embedding ‘iframe’.

Note that animations do not run while processing the sub-resource document,
for both performance reasons and because there is currently no context
defined for resource documents to reference their timeline against.
However, when elements from a sub-resource document are cloned
into the current document because of a ‘use’ element reference
or paint-server cross-reference,
the cloned element instances may be animated
in the current document's timeline,
as described in Animations in use-element shadow trees,
and may trigger the loading of additional sub-resource files.

Graphical effects references

When SVG documents are loaded
through any style property references that target specific elements in the document
(as opposed to SVG as an image format),
they must be processed in secure static mode.

Note that animations do not run in sub-resource documents,
for both performance reasons and because there is currently no context
defined for resource documents to reference their timeline against.

Some style properties may reference either specific elements
or entire image files;
the processing mode is more restrictive in the first case.
For example, a reference to an SVG ‘mask’ element
will not be animated,
but an entire SVG file used as an image mask can be.

These restrictions are included in the
OpenType specification for processing documents from the "SVG"
table.
OpenType also applies additional restrictions,
in the form of a user agent style sheet
that prevents rendering of text and foreign objects
[OPENTYPE].

SVG document fragments that are included inline in a host document
must use a processing mode that matches that of the host document.
SVG document fragments included as
children of an SVG ‘foreignObject’ element must use the
processing mode of the surrounding SVG document;
non-SVG foreign content must be processed with equivalent restrictions.

For example, if an SVG document is being used in
secure animated mode due to being referenced
by an HTML ‘img’
or SVG ‘image’ element,
then any content within a ‘foreignObject’ element
must have scripts, interactivity, and external file references disabled,
but should have declarative animation enabled.

2.3.1. Examples

Below are various methods of embedding SVG in an HTML page by
reference,
along with the expected processing mode
and allowed features for each.

Each cell in the "Live Example" row should display a yellow
smiley face.
In each example below, clicking on the eyes tests link
traversal,
and clicking on the face tests declarative interactivity
and script execution.
The link should replace the image with a blue
square (clicking it will revert it to the original image).
The declarative interactivity
uses the ‘set’ element to change the face from shades of yellow to shades of green,
and uses CSS pseudoclasses to add a stroke to the interactive elements.
The script should fill in the smile.
Time-based (as opposed to interactivity-based) declarative animation is supported if the left eye is winking (using the ‘animate’ element)
and if the eyes are dark blue with regular flashes of light blue (using CSS keyframe animation).

The expected processing modes and features outlined here
are subject to any future changes in the corresponding HTML or CSS specification.

Embedding method

object without sandboxing

iframe with sandbox=""

img

CSS background

Expected processing mode

dynamic interactive

dynamic interactive, with restrictions

secure animated

secure animated

Declarative, time-based animation (winking left eye, color-change in both eyes)

Link navigation within the same browsing context, to the same domain (image changes when clicking eyes)

allowed

allowed

disabled

disabled

Scripted interaction (smile widens when clicking face)

allowed

disabled (because of sandboxing)

disabled

disabled

Live example

This browser does not support embedded SVG images.

This browser does not support embedded SVG images.

2.4. Document Conformance Classes

SVG is defined in terms of a document object model (DOM),
rather than a particular file format or document type.
For SVG content, therefore,
conformance with this specification is defined by whether
the content is or can generate a conforming DOM.
Additional conformance classes depend on whether the content
is also valid and well-formed XML [xml].

SVG document fragments can be included within parent XML documents using
the XML namespace facilities described in
Namespaces in XML [xml-names].
Note, however, that since a conforming SVG DOM subtree must have an
‘svg’ element as its root, the use of an individual non-‘svg’
element from the SVG namespace is disallowed. Thus, the SVG part of the
following document is not conforming:

The SVG language and these conformance criteria provide no designated
size limits on any aspect of SVG content. There are no maximum values on
the number of elements, the amount of character data, or the number of
characters in attribute values.

2.4.2. Conforming SVG Markup Fragments

A document or part of a document is a conforming SVG markup fragment
if it can be parsed without error (other than network errors)
by the appropriate parser for the document MIME type
to form a conforming SVG DOM subtree,
and in addition if:

2.4.4. Conforming XML-Compatible SVG DOM Subtrees

If the DOM subtree cannot be serialized to conforming XML without altering it,
such as when an ‘id’ value is not a valid XML name, or when a
Comment node's data contains the substring "--", then the subtree is not
a conforming XML-compatible SVG DOM subtree.

2.5. Software Conformance Classes

For software, the requirements for conformance depend
on the category of program:

SVG generators

Any software that creates or makes available SVG content,
either as markup or as a DOM
(as is the case with client-side JavaScript libraries).

SVG authoring tools

Any software that provides an interface for human content creators
to manipulate graphics or code that will be used to generate SVG.
SVG authoring tools are implicitly also SVG generators.

SVG servers

Any network or file server that makes available SVG content
in response to requests from other software.
SVG servers are implicitly also SVG generators.

SVG interpreters

Any software that parses or processes SVG documents or markup fragments.
An SVG interpreter is an SVG user agent
for the purpose of any sections of this specification that
relate to the parsing or processing steps undertaken by the interpreter.

SVG viewers

Any software that creates a rendered graphical representation
after parsing or processing an SVG document or SVG markup fragment.
SVG viewers are implicitly also SVG interpreters.
An SVG viewer is always an SVG user agent for the purpose of this specification.

SVG user agent

An SVG user agent is a user agent that is able to retrieve and
render SVG content.

user agent

The general definition of a user agent is an application
that retrieves and renders Web content, including text,
graphics, sounds, video, images, and other content types. A
user agent may require additional user agents that handle
some types of content. For instance, a browser may run a
separate program or plug-in to render sound or video. User
agents include graphical desktop browsers, multimedia
players, text browsers, voice browsers, and assistive
technologies such as screen readers, screen magnifiers,
speech synthesizers, onscreen keyboards, and voice input
software.

In general terms,
a "user agent" may or may not have the ability to retrieve
and render SVG content;
however, unless the context requires an alternative interpretation,
all references to a "user agent" in this specification
are assumed to be references to an SVG user agent that
retrieves and renders SVG content.

Many programs will fall under multiple software classes.
For example, a graphical editor that can import and display SVG files,
allow the user to modify them,
and then export the modified graphic to file,
is an SVG interpreter,
an SVG viewer,
an SVG authoring tool,
and an SVG generator.

2.5.3. Conforming SVG Servers

A conforming SVG server must meet all the requirements of a conforming SVG generator. In addition, conforming SVG servers using HTTP or other protocols
that use Internet Media types must serve SVG stand-alone files with the media
type "image/svg+xml".

Also, if the SVG file is compressed with gzip or deflate, conforming SVG
Servers must indicate this with the appropriate header, according to what the
protocol supports. Specifically, for content compressed by the server
immediately prior to transfer, the server must use the "Transfer-Encoding: gzip"
or "Transfer-Encoding: deflate" headers as appropriate, and for content
stored in a compressed format on the server (e.g. with the file extension "svgz"),
the server must use the "Content-Encoding: gzip" or
"Content-Encoding: deflate" headers as appropriate.

Compression of stored content (the "entity," in HTTP
terms) is distinct from automatic compression of the message body, as
defined in HTTP/1.1 TE/
Transfer Encoding
([rfc2616], sections 14.39 and 14.41).

2.5.4. Conforming SVG Interpreters

An SVG interpreter is a program which can parse and process
SVG document fragments. Examples of SVG interpreters are
server-side transcoding tools or optimizers (e.g., a tool which converts SVG
content into modified SVG content) or analysis tools (e.g., a
tool which extracts the text content from SVG content,
or a validity checker).
A transcoder from SVG into another graphics
representation, such as an SVG-to-raster transcoder, represents
a viewer, and thus viewer conformance criteria also apply.

To modulate the tradeoff of a numerical precision in use cases of the technical drawing and mapping, and the performance of user agent.

Owner:

heycam, stakagi

An SVG viewer is a program which can parse and process an
SVG document fragment and render the contents of the document
onto some sort of graphical output medium such as a display, printer, or engraver.
Thus, an SVG viewer is also an SVG interpreter
(in that it can parse and process SVG document fragments),
but with the additional requirement of correct rendering.

A conforming SVG viewer
must be a conforming SVG interpreter, and
must be able to support rendering output in at least one of the
processing modes defined in this chapter:

Areas of an image of SVG content may have opacity less than 100%.
The viewer must at least support Simple Alpha Compositing
of the image of the SVG content onto the target canvas, as described in the
Compositing and Blending Specification
[compositing-1].

The viewer must support data URL references
containing base64-encoded or URL-encoded content,
in conformance with
the "data:" URL scheme
[rfc2397],
wherever a URI reference to another document is permitted within
SVG content.
When the encoded document is of MIME type image/svg+xml,
it must be a well-formed, complete SVG document in order to be processed.

Even if the viewer only supports secure processing modes,
it is still required to support these image formats,
in order to process data URL references.

Resampling of image data must be consistent with the
specification of property image-rendering.

Whenever possible in the parent environment,
the viewer must use information about physical device resolution
and expected viewing conditions in order to accurately
determine the initial scale
in conformance with the rules described in CSS 2.1
([CSS2], section 4.3.2).
In situations where this
information is impossible to determine,
the viewer or the parent environment must make a reasonable approximation
for common target devices.

All visual rendering must be accurate to within one
device pixel or point of the mathematically correct result
at the initial 1:1 zoom ratio. It is suggested that viewers
attempt to keep a high degree of accuracy when zooming.

If printing devices are supported, SVG content must be
printable at printer resolutions with the same graphics
features available as required for display (e.g., the
specified colors must be rendered on color printers).

On systems which support accurate sRGB
[SRGB] color, all
sRGB color computations and all resulting color values must
be accurate to within one sRGB color component value, where
sRGB color component values range from 0 to 255.

SVG implementations must correctly support
gzip-encoded
[rfc1952] and
deflate-encoded
[rfc1951] data streams,
for any content type (including SVG, script files, images).
SVG implementations that support HTTP must support these
encodings according to the
HTTP 1.1
specification [rfc2616];
in particular, the client must specify with an "Accept-Encoding:"
request header [HTTP-ACCEPT-ENCODING]
those encodings that it accepts, including at minimum gzip
and deflate, and then decompress any
gzip-encoded and
deflate-encoded
data streams that are downloaded from the server. When an SVG
viewer retrieves compressed content (e.g., an .svgz file) over
HTTP, if the "Content-Encoding" and "Transfer-Encoding" response
headers are missing or specify a value that does not match the
compression method that has been applied to the content, then
the SVG viewer must not render the content and must treat the
document as being in error.

The viewer must use at least single-precision floating point for intermediate calculations on any numerical operations for conversion of coordinates. However, in order to prevent the rounding error on coordinate transformation, at least double-precision floating point computation must be used on CTM generation processing. Such minimum typical computation way is expressed with following formulas.

Furthermore, when it has nested viewport coordinate sytstems, the ScreenCTM which is a transformation matrix produced by nested CTM for transforming user coordinates into the coordinates of an output device also must be generated by double-precision floating point computation.

If the user agent includes an HTML or XHTML viewing
capability or can apply CSS/XSL styling properties to XML
documents, then a conforming SVG viewer must support
resources of MIME type "image/svg+xml" wherever raster image
external resources can be used, such as in the HTML or XHTML
‘img’ element and in CSS/XSL
properties that can refer to raster image resources (e.g.,
‘background-image’).

2.5.6. Conforming High-Quality SVG Viewer

In order for a conforming SVG viewer to be considered
a conforming high-quality SVG viewer, it must
support the following additional features:

Professional-quality results with good processing and
rendering performance and smooth, flicker-free
animations.

On low-resolution devices such as display devices at
150dpi or less, support for smooth edges on lines, curves and
text. (Smoothing is often accomplished using anti-aliasing
techniques.)

Color management via ICC profile support (i.e., the
ability to support colors defined using ICC profiles).

Resampling of image data must conform to the requirements
for conforming high-quality SVG viewers as specified in the
description of property image-rendering.

At least double-precision floating point computation on
coordinate system transformation numerical calculations.

3.1. Introduction

Implementations of SVG must implement the rendering model as described in this
chapter, as modified in the appendix on conformance
requirementswhich describes
situations where an implementation may deviate.
In practice variability is allowed based on limitations of the output device
(e.g. only a limited range of colors might be supported) and because of practical
limitations in implementing a precise mathematical model (e.g. for realistic
performance curves are approximated by straight lines, the approximation need
only be sufficiently precise to match the conformance requirements).

The appendix on conformance
requirements describes the extent to which an actual
implementation may deviate from this description. In practice
an actual implementation may
deviate slightly because of
limitations of the output device (e.g. only a limited range of
colors might be supported) and because of practical limitations
in implementing a precise mathematical model (e.g. for
realistic performance curves are approximated by straight
lines, the approximation need only be sufficiently precise to
match the conformance requirements).

3.2. The rendering tree

The components of the final rendered representation of an SVG document
do not have a one-to-one relationship with the underlying
elements in the document model.
The appearance of the graphic instead reflects a parallel structure,
the rendering tree,
in which some elements are excluded and others are repeated.

Many elements in the SVG namespace do not directly represent
a component of the graphical document.
Instead, they define graphical effects, metadata,
content to be used to represent other elements,
or alternatives to be displayed under certain conditions.
In dynamic documents, certain components of the graphic
may be rendered or not, depending on interaction or animation.
These non-rendered elements are not directly included
in the rendering tree.

Because SVG supports the reuse of graphical sub-components,
some elements are rendered multiple times.
The individual renderings may have context-dependent styling
and may be rasterized at different scales or transformations.

3.2.1. Definitions

rendering tree

The rendering tree is the set of elements being rendered
in an SVG document fragment.
It is generated from the document tree
by excluding non-rendered elements
and inserting additional fragments for re-used graphics.
Graphics are painted and composited in rendering-tree order,
subject to stacking and re-ordering based on the
z-index and paint-order properties.
Note that elements that have no visual paint may still be in the rendering tree.

Graphical components that are included in the rendering tree
but do not have a single direct equivalent element
in the document model.
They may be represented through shadow DOM elements
(as in graphics re-used with a ‘use’ element),
or as image fragments generated as part of a graphical effect
(as in patterns or masks).

A renderable element may or may not be rendered
in a given document or point in time.

3.2.2. Rendered versus non-rendered elements

At any given time, every SVG element
(or element instance in a use-element shadow tree)
is either rendered or non-rendered.
Whether an element is currently rendered or not affects
not only its visual display but also interactivity
and geometric calculations.

Non-rendered elements are not represented in the document accessibility tree.
Nonetheless, they remain part of the document model, and
participate in style inheritance and cascade.

3.2.3. Controlling visibility: the effect of the ‘display’ and ‘visibility’
properties

SVG uses two properties to toggle the visible display of
elements that are normally rendered:
display and visibility.
Although they have a similar visible effect in static documents,
they are conceptually distinct.

The display property affects the direct processing
of a given element, but it does not prevent it from
being referenced by other elements.
For example, setting
display: none on a ‘path’ element
will prevent that element from getting rendered directly onto the
canvas, but the ‘path’ element can still be referenced by a
‘textPath’ element and its geometry will be used
in text-on-a-path processing.

When applied to a graphics element or ‘use’ element,
setting visibility to hidden
or collapse
results in the element not being painted.
It is, however, still part of the rendering tree.
It may be sensitive to pointer events
(depending on the value of pointer-events),
may receive focus (depending on the value of ‘tabindex’),
contributes to bounding box calculations and clipping paths,
and does affect text layout.

Shadow DOM elements are rendered in the same way as normal elements,
as if the host element (e.g., the ‘use’ element)
was a container and the shadow content was its descendents.
Style and geometry properties on the shadow DOM elements
are resolved independently from those on their corresponding element
in the source document.
The display property has its normal effect on shadow elements,
except for special rules that apply to the ‘symbol’ element.

Unless properties on the host element create a stacking context,
z-index values on shadow DOM elements
can change their rendering order relative to elements in the main DOM.
For blending purposes, the ‘use’ element forms a non-isolated group.

In contrast,
graphical effects elements generate a self-contained SVG fragment
which is rendered independently as a stacking context
and an isolated group.
The canvas for this fragment is scaled
The graphical effect element's child content
is rendered and composited into this canvas.
The flattened canvas as a whole is treated as a vector image
when compositing and blending with other paint layers

The display property on any child content of a graphical effects element
has its normal effect when set to none,
excluding that subtree from being used in rendering.
However, the graphical effect is not altered
by a value of display: none
on the graphical effect element or an ancestor.

3.3. The painters model

SVG uses a "painters model" of rendering. Paint
is applied in successive operations to the output device such
that each operation paints onto some area of the output device,
possibly obscuring paint that has previously been layed down.
After each object or group is painted, it becomes part of the background
for the next painting operation.
SVG 2 supports advanced blending modes and compositing operations that
control how each painting operation interacts with the background.
The rules governing these painting operations are outlined in the
Compositing and Blending Specification.

3.4. Rendering order

Elements in SVG are positioned in three dimensions. In addition to their
position on the x and y axis of the SVG viewport, SVG elements are also
positioned on the z axis. The position on the z-axis defines the order that
they are painted.

Along the z axis, elements are grouped into stacking contexts, each stacking
context has an associated stack level.
A stack level may contain one or more child nodes - either child
stack levels, graphics elements, or ‘g’ elements.
graphics elements and ‘g’ elements within single
stack level are painted in document order - that is, they are painted
in the order that they are defined in the document.

Each stack level is assigned an integer value that defines it's
position on the z axis relative to other stack levels within the same
stacking context. Lower values are painted first, and so
elements in a stack level with a higher value will paint over one
with a lower value.

3.4.1. Controlling element rendering order: the ‘z-index’ property

The z-index property allows an element to be assigned to a
stack level.

The rules governing behavior for SVG elements with the z-index
property specified are outlined below:

CSS specifies a
property named z-index. The CSS rules
that define the effect of the ‘z-index’ property
were written specifically for the CSS box model, and those rules do not make
sense as they stand for most SVG elements (most SVG elements do not participate
in or establish a CSS box model layout). This section specifies how
implementations must handle the z-index property on elements in the SVG
namespace.

Contrary to the rules in CSS 2.1, the z-index property applies to all SVG
elements regardless of the value of the position property, with one exception:
as for boxes in CSS 2.1, outer ‘svg’ elements must be positioned for z-index
to apply to them.

This integer is the stack level of the element in the current
stacking context. The element also establishes a new local
stacking context for its descendants.

auto

The stack level of the element in the current stacking context
is the same as its parent element, unless its parent established
a new stacking context, in which case its stack level is 0. The
element does not establish a new local stacking context.

In this example there are three stack levels: -1, 0 (the default) and 1. The red
and yellow rects are in stack level -1, the lime and aqua rects are in stack
level 0 (the default), and the blue rect is in stack level 1. Going from lowest
stack level to highest, and painting the elements in each stack level in
document order, the painting order is: red, yellow, lime, aqua, blue.

3.4.2. Establishing a stacking context in SVG

A new stacking context must be established at an SVG element for its descendants if:

it is the root element

the z-index property applies to the element and its computed
value is an integer

the element is an inner ‘svg’ element and the computed value of its
overflow property is a value other than visible

the element is subject to explicit clipping:

the clip property applies to the element and it has a
computed value other than auto

the clip-path property applies to the element and it has a
computed value other than none

the opacity property applies to the element and it has a
computed value other than 1

the mask property applies to the element and it has a computed
value other than none

the filter property applies to the element and it has a
computed value other than none

a property defined in another specification is
applied and that property is defined to establish a stacking context in SVG

Stacking contexts and stack levels are conceptual tools used to describe the
order in which elements must be painted one on top of the other when the
document is rendered, and for determining which element is highest when
determining the target of a pointer event. Stacking contexts and stack levels do
not affect the position of elements in the DOM tree, and their presence or
absence does not affect an element's position, size or orientation in the
canvas' X-Y plane - only the order in which it is painted.

Stacking contexts can contain further stacking contexts. A stacking context is
atomic from the point of view of its parent stacking context; elements in
ancestor stacking contexts may not come between any of its elements.

Each element belongs to one stacking context. Each element in a given stacking
context has an integer stack level. Elements with a higher stack level must be
placed in front of elements with lower stack levels in the same stacking
context. Elements may have negative stack levels. Elements with the same stack
level in a stacking context must be stacked according to document order.

With the exception of the ‘foreignObject’ element, the back to front
stacking order for a stacking context created by an SVG element is:

the background and borders of the element forming the stacking
context, if any

child stacking contexts created by descendants with negative stack
levels, primarily ordered by most negative first, then by tree order

descendants with 'z-index: auto' or
'z-index: 0', in tree order

child stacking contexts created by descendants with positive stack levels,
primarily ordered by lowest index first, then by tree order

Since the ‘foreignObject’ element creates a "fixed position containing block" in
CSS terms, the normative rules for the stacking order of the stacking context
created by ‘foreignObject’ elements are the rules in Appendix E of CSS 2.1.

In the following example, the z-index property on the ‘g’
element is set to zero. This creates a new stacking context to contain the
‘g’ element's children without moving the ‘g’ to a different
level in the document's root stacking context:

The example's root stacking context contains two stack levels: -1 and 0. The red
‘rect’ is in level -1, and the ‘g’ element and aqua ‘rect’ are in level 0. Inside
stack level 0, the ‘g’ element's z-index property creates a new nested stacking
context at the ‘g’ for the ‘g’ element's children. In this child stacking
context there are two stack levels: 0 and 1. The yellow ‘rect’ is in level 0 (the
default), and the lime ‘rect’ is in level 1.

Painting of this example starts with the stack levels of the root stacking
context. First the red rect is painted in level -1, then in level 0 the ‘g’
element is painted followed by the aqua rect. When the ‘g’ element is painted,
the child stacking context that its z-index created and all of that context's
stack levels are also painted. In this child stacking context, first the yellow
rect in level 0 is painted, followed by the lime rect in level 1. It's only
after the ‘g’ and the stacking context that it creates has been painted that the
aqua rect is painted. Note that this means that although the z-index of 1 for
the lime rect is a higher value than the (implicit) z-index of 0 for the aqua
rect, the containment provided by the ‘g’'s child stacking context results in the
aqua rect painting over the lime rect. The painting order is therefore: red,
yellow, lime, aqua.

3.6. How groups are rendered

Grouping elements, such as the ‘g’ element (see container elements
) create a compositing group.
Similarly, a ‘use’ element creates a compositing group for its shadow content.
The Compositing and Blending
specification normatively describes how to render compositing groups.
In SVG, effects may be applied to a group. For example, opacity, filters
or masking. These effects are applied to the rendered result of the group
immediately before any transforms on the group are applied, which are applied
immediately before the group is blended and composited with the
group backdrop. Applying any such effects to a group makes that
group isolated.

Thus, rendering a compositing group follows the following steps:
If the group is isolated:

3.6.1. Object and group opacity: the
effect of the ‘opacity’ property

The opacity property specifies how opaque a given
graphical element or container element will be when it is
painted to the canvas. When applied to a container element,
this is known as group opacity, and when applied to
an individual rendering element, it is known as object
opacity. The principle for these two operations however
is the same.

These four opacity properties are involved in intermediate rendering operations.
Object and group opacity however can be thought of as a post-processing operation.
Conceptually, the object or group to which opacity applies
is rendered into an RGBA offscreen image. The offscreen image as whole is then blended
into the canvas with the specified opacity value used uniformly
across the offscreen image.
Thus, the presence of opacity causes the group to be
isolated.

Each group of red and green circles is first rendered
to an offscreen image before being blended with the background
blue rectangle as a whole, with the given opacity values.

In the example, the top row of circles have differing opacities,
ranging from 1.0 to 0.2. The bottom row illustrates five ‘g’ elements,
each of which contains overlapping red and green circles, as follows:

The first group shows the opaque case for reference. The group has
opacity of 1, as do the circles.

The second group shows group opacity when the elements in the group are
opaque.

The third and fourth group show that opacity is not commutative. In the
third group (which has opacity of 1), a semi-transparent green circle is
drawn on top of a semi-transparent red circle, whereas in the fourth group a
semi-transparent red circle is drawn on top of a semi-transparent green
circle. Note that area where the two circles intersect display different
colors. The third group shows more green color in the intersection area,
whereas the fourth group shows more red color.

The fifth group shows the multiplicative effect of opacity settings.
Both the circles and the group itself have opacity settings of .5. The
result is that the portion of the red circle which does not overlap with the
green circle (i.e., the top/right of the red circle) will blend into the
blue rectangle with accumulative opacity of .25 (i.e., .5*.5), which, after
blending into the blue rectangle, results in a blended color which is 25%
red and 75% blue.

3.7. Types of graphics elements

SVG supports three fundamental types of graphics elements
that can be rendered onto the canvas:

Raster images, which represent an array of values that
specify the paint color and opacity (often termed alpha) at a
series of points on a rectangular grid. (SVG requires support
for specified raster image formats under
conformance requirements.)

3.7.1. Painting shapes and text

Shapes and text can be filled (i.e., apply paint to the
interior of the shape) and stroked (i.e., apply paint
along the outline of the shape).

For certain types of shapes, marker
symbols (which themselves can consist of any combination of shapes,
text and images) can be drawn at positions along the
shape boundary. Each marker symbol
is painted as if its graphical content were expanded into the
SVG document tree just after the shape object which is using
the given marker symbol. The graphical contents of a marker
symbol are rendered using the same methods as graphics
elements. Marker symbols are not applicable to text.

The order in which fill, stroke and markers are painted is determined
by the paint-order property. The default is that
fill is painted first, then the stroke, and then the
marker symbols. The marker symbols are rendered in order along
the outline of the shape, from the start of the shape to the
end of the shape.

The fill and stroke operations are entirely independent;
for instance, each fill or stroke operation has its own opacity setting.

SVG supports numerous built-in types of paint which can
be used in fill and stroke operations. These are described in
Paint Servers.

3.7.2. Painting raster images

When a raster image is rendered, the original samples are
"resampled" using standard algorithms to produce samples at the
positions required on the output device. Resampling
requirements are discussed under
conformance requirements.

As in HTML [HTML, 10.4.2],
all animated images with the same absolute URL and the same image
data are expected to be rendered synchronised to the same timeline as a group,
with the timeline starting at the time of the least recent addition to the
group.

When a user agent is to restart the animation for an img element showing an
animated image, all animated images with the same absolute URL and the same
image data in that img element's node document are expected to restart their
animation from the beginning.

3.8. Filtering painted regions

In this case the result must be as though the paint
operations had been applied to an intermediate canvas
initialized to transparent black, of a size determined by the
rules given in Filter Effects then
filtered by the processes defined in
Filter Effects.

3.9. Clipping and masking

SVG supports the following clipping/masking features:

clipping paths, which either uses
any combination of ‘path’, ‘text’ and
basic shapes or basic shapes to serve as
the outline of a (in the absence of anti-aliasing) 1-bit
mask, where everything on the "inside" of the outline is
allowed to show through but everything on the outside is
masked out

masks, which are
container elements
which can contain graphics elements
or other container elements which define a set of graphics
that is to be used as a semi-transparent mask for compositing
foreground objects into the current background.

Both, clipping and masking, are specified in the module CSS Masking
[css-masking-1].

3.10. Parent compositing

SVG document fragments can be semi-opaque.

In accordance with the Compositing and Blending specification,
the ‘svg’ element always creates an isolated group.
When an SVG document is a top-level document,
meaning it is not embedded in another document,
the root ‘svg’ element
is considered to be the page group and is composited with
a backdrop of white with 100% opacity.
In all other cases, the SVG document or document fragment is composited into the parent
document with opacity preserved.

The overflow property has the same parameter values and has the
same meaning as defined in CSS 2.1
([CSS2], section 11.1.1);
however, the following additional points apply:

If the overflow property has a value of 'visible',
the property has no effect (i.e., a clipping rectangle is not created).

For those elements to which the overflow property can apply.
If the overflow property has the value
hidden or scroll, a clip,
the exact size of the SVG viewport is applied.

When scroll is specified on an
‘svg’ element and if the user agent uses a scrolling mechanism that
is visible on the screen (such as a scroll bar or a panner), that mechanism
should be displayed for the SVG viewport whether or not any of its content is clipped.

Within SVG content, the value auto implies
that all rendered content for child elements must be
visible, either through a scrolling
mechanism, or by rendering with no clip.
For elements where the value of scroll results
in a scrolling mechanism being used by the user agent, then a value of
auto may be treated as
scroll. If the user agent has no scrolling
mechanism, the content would not be clipped, or the value 'scroll' is treated
as hidden, then the value
auto must be treated as
visible

Although the initial value for overflow is auto. In the User Agent style sheet,
overflow is overriden for the ‘svg’ element when it is not the root
element of a stand-alone document, the ‘pattern’ element, ‘hatch’
element, and the ‘marker’ element to be hidden by default.

4.1. Definitions

initial value

The initial value of an attribute or property is the value used when
that attribute or property is not specified, or when it has an
invalid value.
This value is to be used for the purposes of rendering, calculating
animation values,
and when accessing the attribute or property via DOM interfaces.

invalid value

An invalid value specified for a property, either in a style sheet
or a presentation attribute, is one that is either not allowed according
to the grammar defining the property's values, or is allowed by the grammar but
subsequently disallowed in prose. A CSS declaration with an invalid value is
ignored; see Declarations
and properties ([CSS2], section 4.1.8).

4.2. Attribute syntax

In this specification, attributes are defined with an attribute definition
table, which looks like this:

Note that this allows CSS comments and escapes to be used
in such attributes. For example, a value of '10\px/**/'
would successfully parse as '10px' in
the ‘x’ presentation attribute of the ‘rect’ element.

When an attribute defined as a URL is parsed, this is
done by invoking the
URL parser with
the attribute's value as input and the document's URL as
base [URL].

The Initial value column gives the initial value for the attribute.
When an attribute fails to parse according to the specified CSS Value Definition Syntax,
ABNF or EBNF grammar, or if parsing according to the URL Standard
or by the prose describing how to parse the attribute indicates failure,
the attribute is assumed to have been specified as the given initial value.

The initial value of a presentation attribute is its
corresponding property's initial value. Since the use of an invalid value
in a presentation attribute will be treated as if the initial value
was specified, this value can override values that come from lower priority
style sheet rules, such as those from the user agent style sheet.

For example, although the user agent style sheet sets the value of the
overflow property to hidden
for ‘svg’ elements, specifying an invalid presentation attribute such
as overflow="invalid" will result
in a rule setting overflow to visible,
overriding the user agent style sheet value.

4.3. Real number precision

Unless stated otherwise, numeric values in SVG attributes and in
properties that are defined to have an effect on SVG elements must
support at least all finite single-precision values supported by the host
architecture.

It is recommended that higher precision floating point
storage and computation be performed on operations such as
coordinate system transformations to provide the best
possible precision and to prevent round-off errors.

This attribute is deprecated and may be removed in a
future version of this specification. Authors are advised to use
Element.classList intead.

The dataset IDL attribute
provides access to custom data attributes
on the element. Its behavior is the same as the corresponding IDL
member on the HTMLElement interface.

The ownerSVGElement IDL attribute
represents the nearest ancestor ‘svg’ element. On getting
ownerSVGElement,
the nearest ancestor ‘svg’ element is returned; if the current
element is the outermost svg element, then null is returned.

The viewportElement IDL attribute
represents the element that provides the SVG viewport for the current element. On getting
viewport,
the nearest ancestor element that establishes an SVG viewport is returned; if the current
element is the outermost svg element, then null is returned.

The tabIndex IDL attribute and
the focus and
blur methods are used to control
focus on SVG elements in the document. Their behavior is the same as the
corresponding IDL members on the HTMLElement interface.

As in HTML documents, the use of the
blur method is discouraged. Authors
are recommended to focus another element instead.

Authors are strongly suggested not to use the
blur method or any
other technique to hide the focus ring from keyboard users, such as
using a CSS rule to override the outline property.
Removal of the focus ring leads to serious accessibility issues for users who
navigate and interact with interactive content using the keyboard.

The transform IDL attribute
reflects the computed value of the transform property and its
corresponding ‘transform’ presentation attribute.

The getBBox method is used
to compute the bounding box of the current element. When the getBBox(options)
method is called, the bounding box algorithm
is invoked for the current element,
with fill, stroke, markers
and clipped members of the options dictionary argument
used to control which parts of the element are included in the bounding box,
using the element's local coordinate system as the coordinate system to return the
bounding box in. A newly created DOMRect object that defines the
computed bounding box is returned.

The getCTM method is used to
get the matrix that transforms the current element's coordinate system to
its SVG viewport's coordinate system. When getCTM() is called, the following
steps are run:

ctm is a matrix that transforms the coordinate
space of the current element (including its transform
property) to the coordinate space of its closest ancestor
viewport-establishing element (also including its transform
property).

Return a newly created, detachedDOMMatrix object that represents the same matrix as ctm.

The getScreenCTM method
is used to get the matrix that transforms the current element's coordinate
system to the coordinate system of the SVG viewport for the SVG document fragment.
When getScreenCTM() is called, the following steps are run:

If the current element is not in the document, then return null.

Let ctm be a matrix that transforms the coordinate
space of the current element (including its transform property)
to the coordinate space of the document's viewport.

any transforms from the SVG viewport's coordinate space
to the document's viewport, i.e. taking into account the positions of
all of the CSS boxes from the outermost svg element's box
to the initial containing block when the SVG document fragment
is inline in an HTML document

Return a newly created, detachedDOMMatrix object that represents the same matrix as ctm.

This method would have been more aptly named as getClientCTM,
but the name getScreenCTM is kept for historical reasons.

4.4.3. Interface SVGGeometryElement

Interface SVGGeometryElement represents SVG elements whose rendering
is defined by geometry with an equivalent path,
and which can be filled and stroked.
This includes paths and the basic shapes.

The isPointInFill and
isPointInStroke methods
determine whether a given point is within the fill or stroke shape of an element.
Normal hit testing rules apply; the value of the pointer-events
property on the element determines whether a point is considered to be
within the fill or stroke. The point argument is interpreted
as a point in the local coordiante system of the element.

4.5. DOM interfaces for basic data types

4.5.1. Interface SVGNumber

An SVGNumber object can be designated as read only,
which means that attempts to modify the object will result in an exception
being thrown, as described below.
SVGNumber objects reflected through the animVal IDL attribute are always
read only.

An SVGNumber object can be associated
with a particular element. The associated element is used to
determine which element's content attribute to update if the object reflects
an attribute. Unless otherwise described, an SVGNumber object is not
associated with any element.

4.5.2. Interface SVGLength

An SVGLength object can be designated as read only,
which means that attempts to modify the object will result in an exception
being thrown, as described below.
SVGLength objects reflected through the animVal IDL attribute are always
read only.

An SVGLength object can be associated
with a particular element, as well as being designated with a directionality:
horizontal, vertical or unspecified. The associated element and the directionality of the
length are used to resolve percentage values to user units and is also used to
determine which element's content attribute to update if the object reflects
an attribute. Unless otherwise
described, an SVGLength object is not associated with any element and
has unspecified directionality.

The use of numeric length unit type constants is an anti-pattern and
new constant values will not be introduced for any other units or length types supported by
SVGLength. If other types of lengths are supported and used, the SVGLength
uses the SVG_LENGTHTYPE_UNKNOWN
unit type. See below for details on how the other properties of an SVGLength
operate with these types of lengths.

The unitType IDL attribute represents
the type of value that the SVGLength's value is.
On getting unitType, the following steps
are run:

Return the result of converting value to an absolute length,
using viewport size and font size as percentage and font size
bases. If the conversion is not possible due to the lack of an
associated element, return 0.

Append to string an implementation
specific string that, if parsed as a <number> using CSS syntax,
would return the number value closest to factor, given the
implementation's supported real number precision.

If value is a <percentage> then append to
string a single U+0025 PERCENT SIGN character.

Otherwise, if value is a <length>,
then append to string the canonical spelling of
value's unit.

Return string.

Otherwise, return an implementation specific string that,
if parsed as a <length>, would return the closest
length value to value, given the
implementation's supported real number precision.

4.5.3. Interface SVGAngle

An SVGAngle object can be designated as read only,
which means that attempts to modify the object will result in an exception
being thrown, as described below. An SVGAngle reflected through the
animVal attribute is always read only.

An SVGAngle object can be associated
with a particular element. The associated element is used to
determine which element's content attribute to update if the object reflects
an attribute. Unless otherwise described, an SVGAngle object is not
associated with any element.

The use of numeric angle unit type constants is an anti-pattern and
new constant values will not be introduced for any other units or angle types supported by
SVGAngle. If other types of angles are supported and used, the SVGAngle
uses the SVG_ANGLETYPE_UNKNOWN
unit type. See below for details on how the other properties of an SVGAngle
operate with these types of angles.

The unitType IDL attribute represents
the type of value that the SVGAngle's value is.
On getting unitType, the following steps
are run:

If the SVGAngle's value is a unitless
<number> or a <length> with a
deg,
rad or
grad unit, then return the corresponding constant
value from the angle unit type table above.

Let factor be value's numeric factor,
if it is an <angle>,
or value itself it is a <number>.

Append to string an implementation
specific string that, if parsed as a <number> using CSS syntax,
would return the number value closest to factor, given the
implementation's supported real number precision.

If value is an <angle>,
then append to string the canonical spelling of
value's unit.

where Name is a descriptive name for the list element's
("Number", "Length", "Point", "Transform" or "String") and Type is the IDL type of the
list's elements (SVGNumber, SVGLength, DOMPoint, SVGTransform or DOMString).

The SVGTransformList interface takes the above form but has
two additional methods on it.

A list interface object maintains an internal list of elements,
which is referred to in the text below simply as "the list".
The IDL attributes and methods are used to inspect and manipulate elements
of the list. The list can also be changed in response to
changes to the reflected content attribute and to animation of
the content attribute (or, for SVGTransformList objects,
in response to changes to the computed value of the transform
property).

A list interface object can be designated as
read only, which means that attempts to modify the object will result
in an exception being thrown, as described below. list interface objects
reflected through the animVal IDL attribute are always read only.

A list interface object
is synchronized by running
the following steps:

Let value be the base value of the
reflected content attribute (using the attribute's initial value
if it is not present or invalid).

Let length be the number of items in the list.

Let new length be the number of values in value.
If value is the keyword none
(as supported by the transform property), new length
is 0.

4.6. DOM interfaces for reflecting SVG attributes

In SVG 1.1 SE, the animVal attribute of the SVG DOM interfaces represented the
current animated value of the reflected attribute. In this version of SVG,
animVal no longer representes the current animated value and is instead an
alias of baseVal.

Some IDL attributes reflect the value of a content attribute
or a property. The way this reflection is done depends on the type of the IDL attribute:

Let keyword be the content attribute's keyword
value corresponding to number, or the empty string
if number is 0.

This means that if the enumeration value is
set to the "unknown" value, the content attribute will be
set to the empty string.

Set the content attribute to keyword.

boolean

Set the content attribute to "true" if value is true,
and "false" otherwise.

float

double

Set the content attribute to an implementation specific string
that, if parsed as a <number> using CSS syntax,
would return the number value closest to value, given
the implementation's supported real number precision.

Let components be a list of four values, being the values of the
x,
y,
width and
height
members of value.

Let serialized components be a list of four strings,
where each is an implementation specific string that, if parsed
as a <number> using CSS syntax, would return the number
value closest to the corresponding value in components, given
the implementation's supported real number precision.

Set the content attribute to a string consisting of the strings in
serialized components joined and separated by single
U+0020 SPACE characters.

The string is an implementation specific string that, if parsed
as a <number> using CSS syntax, would return the number
value closest to the SVGNumber object's
value member, given
the implementation's supported real number precision.

For SVGAnimatedEnumeration objects that reflect an
animatable attribute that takes only a keyword value, the
baseVal and
animVal IDL attributes
represents the current non-animated value of the reflected attribute.
For orientType,
they represent the type of the current non-animated value of the
reflected ‘orient’ attribute. On getting
baseVal or
animVal, the
following steps are run:

Let value be the value of the reflected attribute
(using the attribute's initial value if it is not present
or invalid).

Return the numeric type value
for value, according to the reflecting IDL attribute's
definition.

For SVGAnimatedInteger objects that reflect
an animatable attribute that takes a single integer value, the
baseVal and
animVal IDL attributes
represent the current non-animated value of the reflected attribute.
For those that reflect one integer of an attribute that takes an
integer followed by an optional second integer, they represent the
current non-animated value of one of the two integers. On getting
baseVal or
animVal, the
following steps are run:

Let value be the value of the reflected attribute
(using the attribute's initial value if it is not present
or invalid).

If the reflected attribute is defined to take an integer
followed by an optional second integer, then:

If this SVGAnimatedInteger object reflects the
first integer, then return the first value in value.

Otherwise, this SVGAnimatedInteger object reflects the
second integer. Return the second value in value if it has been
explicitly specified, and if not, return the implicit value
as described in the definition of the attribute.

For example, the definition of ‘order’
says that the implicit second integer is the same as the explicit
first integer.

Otherwise, the reflected attribute is defined to take a single
integer value. Return value.

If the reflected attribute is defined to take an integer
followed by an optional second integer, then:

Let current be the value of the reflected attribute
(using the attribute's initial value if it is not present
or invalid).

Let first be the first integer in current.

Let second be the second integer in current
if it has been explicitly specified, and if not, the implicit value
as described in the definition of the attribute.

If this SVGAnimatedInteger object reflects the
first integer, then set first to value.
Otherwise, set second to value.

Append first to new.

Append second to new.

Otherwise, the reflected attribute is defined to take a single
integer value. Append value to new.

Set the content attribute to a string consisting of each integer
in new serialized to an implementation specific string that,
if parsed as an <number> using CSS syntax, would return that
integer, joined and separated by a single U+0020 SPACE character.

For SVGAnimatedNumber objects that reflect
an animatable attribute that takes a single number value, the
baseVal and
animVal IDL attributes
represent the current non-animated value of the reflected attribute.
For those that reflect one number of an attribute that takes a
number followed by an optional second number, they represent the
current non-animated value of one of the two numbers. On getting
baseVal or
animVal, the
following steps are run:

Let value be the value of the reflected attribute
(using the attribute's initial value if it is not present
or invalid).

If the reflected attribute is defined to take an number
followed by an optional second number, then:

If this SVGAnimatedNumber object reflects the
first number, then return the first value in value.

Otherwise, this SVGAnimatedNumber object reflects the
second number. Return the second value in value if it has been
explicitly specified, and if not, return the implicit value
as described in the definition of the attribute.

For example, the definition of ‘kernelUnitLength’
says that the implicit second number is the same as the explicit
first number.

Otherwise, the reflected attribute is defined to take a single
number value. Return value.

If the reflected attribute is defined to take an number
followed by an optional second number, then:

Let current be the value of the reflected attribute
(using the attribute's initial value if it is not present
or invalid).

Let first be the first number in current.

Let second be the second number in current
if it has been explicitly specified, and if not, the implicit value
as described in the definition of the attribute.

If this SVGAnimatedNumber object reflects the
first number, then set first to value.
Otherwise, set second to value.

Append first to new.

Append second to new.

Otherwise, the reflected attribute is defined to take a single
number value. Append value to new.

Set the content attribute to a string consisting of each number
in new serialized to an implementation specific string that,
if parsed as an <number> using CSS syntax, would return the
value closest to the number (given the implementation's supported
Precisionreal number precision),
joined and separated by a single U+0020 SPACE character.

The baseVal
and animVal IDL attributes
represent the current non-animated value of the reflected attribute.
On getting baseVal
or animVal,
the following steps are run:

If the reflected attribute is not present, then:

If the SVGAnimatedString object is defined to additionally
reflect a second, deprecated attribute, and that attribute is present,
then return its value.

Otherwise, if the reflected attribute has an initial value,
then return it.

Otherwise, return the empty string.

Otherwise, the reflected attribute is present. Return its value.

For the href
member on the SVGURIReference interface, this will result in
the deprecated ‘xlink:href’ attribute being returned if it is
present and the ‘href’ attribute is not,
and in the ‘href’ attribute being
returned in all other cases.

If the reflected attribute is not present,
the SVGAnimatedString object is defined to additionally reflect
a second, deprecated attribute, and that deprecated attribute is present,
then set that deprecated attribute to the specified value.

Otherwise, set the reflected attribute to the specified value.

For the href
member on the SVGURIReference interface, this will result in
the deprecated ‘xlink:href’ attribute being set if it is
present and the ‘href’ attribute is not,
and in the ‘href’ attribute being
set in all other cases.

4.6.8. Interface SVGAnimatedRect

An SVGAnimatedRect object is used to reflect an
animatable attribute that takes a rectangle value as specified
by an x, y, width and height.

The baseVal
and animVal IDL attributes
represent the current non-animated value of the reflected attribute.
On getting baseVal or
animVal,
an SVGNumberList object is returned that reflects the base value
of the reflected attribute.

The baseVal
or animVal IDL attributes
represent the current non-animated value of the reflected attribute.
On getting baseVal or
animVal,
an SVGLengthList object is returned that reflects the base value
of the reflected attribute.

The href IDL attribute
represents the value of the ‘href’
attribute, and, on elements that are defined to support it,
the deprecated ‘xlink:href’ attribute. On getting
href, an
SVGAnimatedString object is returned that:

reflects the ‘href’ attribute, and

if the element is defined to support the deprecated
‘xlink:href’ attribute, additionally reflects that deprecated attribute.

The SVGAnimatedString interface is defined
to reflect, through its baseVal
and animVal members, the deprecated
‘xlink:href’ attribute, if that attribute is
present and the ‘href’ is not, and to
reflect the ‘href’ attribute in all
other circumstances. Animation elements
treat attributeName='xlink:href'
as being an alias for targetting the ‘href’ attribute.

An SVG document fragment can stand by itself as a self-contained
file or resource, in which case the SVG document fragment is an SVG document, or it can be embedded inline as a fragment within a parent
HTML or XML document.

The following example shows simple SVG
content embedded inline as a fragment within a parent XML document.
Note the use of XML namespaces to indicate that the ‘svg’ and
‘ellipse’ elements belong to the SVG namespace:

5.1.2. Namespace

When SVG is parsed as a XML, for compliance with the
Namespaces in XML Recommendation
[xml-names], an SVG namespace
declaration must be provided so that all SVG elements are identified
as belonging to the SVG namespace.

When using the HTML syntax, the namespace is provided automatically by the HTML parser.

As the example shows there's no need to have an ‘xmlns’
attribute declaring that the element is in the SVG namespace when using the HTML parser.
The HTML parser will automatically create the SVG elements in the proper namespace.

This section should talk about how a document's behavior
is defined in terms of the DOM, and also explain how the HTML parser can
create SVG fragments.

The SVG 2 namespace is http://www.w3.org/2000/svg,
which is the same as for earlier versions of SVG.

The following are possible ways to
provide a namespace declaration when SVG is parsed as XML. An ‘xmlns’
attribute without a namespace prefix could be specified on an
‘svg’ element, which means that SVG is the default namespace
for all elements within the scope of the element with the ‘xmlns’ attribute:

If a namespace prefix is specified on the ‘xmlns’
attribute (e.g., xmlns:svg="http://www.w3.org/2000/svg"),
then the corresponding namespace is not the default namespace, so an
explicit namespace prefix must be assigned to the elements:

5.1.3. Definitions

The structural elements are those which define the primary
structure of an SVG document. Specifically, the following
elements are structural elements:
‘defs’, ‘g’, ‘svg’, ‘symbol’ and ‘use’.

structurally external element

Elements that define its structure by reference to an external resource.
Specifically, the following elements are structurally external elements when
they have an ‘href’ attribute:
‘audio’, ‘foreignObject’, ‘iframe’, ‘image’, ‘script’, ‘use’ and ‘video’.

current SVG document fragment

The document sub-tree which starts with the outermost
ancestor ‘svg’ element of a given SVG
element, with the requirement that all container elements
between the outermost ‘svg’ and the given element are
all elements in the SVG namespace.

A document sub-tree which starts with an ‘svg’
element which is either the root element of the document or whose parent
element is not in the SVG namespace.
An SVG document fragment can consist of a stand-alone SVG document,
or a fragment of a parent document enclosed by an ‘svg’
element.
Howevere, an ‘svg’ element that is a direct child of another SVG-namespaced element
is not the root of an SVG document fragment.

The x and y attributes specify the
top-left corner of the rectangular region into which an
embedded ‘svg’ element is placed. On an outermost svg element,
these attributes have no effect.

For outermost svg elements,
the width and height attributes specify
the intrinsic size of the SVG document fragment.
For embedded ‘svg’ elements, they specify the size
of the rectangular region into which the ‘svg’ element
is placed.
In either case, a computed style of auto
is treated equivalent to 100%.

Attribute definitions:

Name

Value

Initial value

Animatable

zoomAndPan

disable | magnify

magnify

no

Specifies whether the user agent should supply a means to zoom
and pan the SVG content. See the definition of ‘zoomAndPan’
for details.

If an SVG document is likely to be referenced as a component
of another document, the author will often want to include a
‘viewBox’ attribute on the outermost svg element of the
referenced document. This attribute provides a convenient way to design
SVG documents to scale-to-fit into an arbitrary SVG viewport.

Treating unknown elements as a generic container element, resulting in the
rendering of their child trees, and assigning the SVGUnknownElement interface to
unknown elements are both at risk, with no known implementations.

Unknown elements are all elements that are in the SVG namespace that are not
defined by this specification or any SVG module. The SVGUnknownElement
interface must be used for unknown elements.

Unknown elements in the SVG namespace are renderable elements and container elements.
They must render as if the unknown element
were replaced with a ‘g’ element or ‘tspan’, according to context.
Any global attribute or property that is valid on any SVG graphics element
is also valid on unknown elements, and must be processed as normal.
This includes conditional processing attributes, ARIA attributes, data attributes,
and the ‘lang’, ‘id’, ‘class’, ‘tabindex’ and ‘style’.
Styles specified on unknown elements must be inherited by
their child elements according to the normal rules for inheritance for each style property.

Known and unknown elements in other namespaces that occur as a child of any
SVG element except ‘foreignObject’, must not render unless
explicitly stated otherwise in this specification.

Known elements in the SVG namespace that occur in places where SVG's content
model doesn't explicitly allow it must not render unless
explicitly stated otherwise in this specification.

5.4. Defining content for reuse, and the ‘defs’ element

5.4.1. Overview

SVG allows a graphical object to be defined for later reuse.
To do this, SVG makes extensive use of the URL reference
construct [rfc3987].
For example, to fill a rectangle with a linear gradient, a
‘linearGradient’ element may be defined with an
‘id’ property that may be referenced in the value for
the rectangle's fill property, as in the following:

Some types of element, such as gradients, will not by themselves produce a graphical result. They can therefore be placed anywhere convenient. However, sometimes it is desired to define a graphical object and prevent it from being directly rendered. it is only there to be referenced elsewhere. To do this, and to allow convenient grouping defined content, SVG provides the ‘defs’ element.

It is recommended that, where possible, referenced elements be defined
prior to the elements that use them, in document order.
Collecting all referenced elements
inside of a single ‘defs’ element
near the top of the file
can make the markup easier to read and understand.

The ‘defs’ element is a container element for
referenced elements. For understandability and
accessibility reasons, it is recommended
that, whenever possible, referenced elements be defined inside
of a ‘defs’.

The content model for ‘defs’ is the same as for the
‘g’ element; thus, any element that can be a child of a
‘g’ can also be a child of a ‘defs’, and vice versa.

Elements that are descendants of a ‘defs’ are not rendered directly;
the display value for the ‘defs’ element
must always be set to none
by the user agent style sheet,
and this declaration must have importance over any other CSS rule or presentation attribute.
Note, however, that the descendants of a ‘defs’ are
always present in the source tree and thus can always be
referenced by other elements; thus, the value of the display
property on the ‘defs’ element does not
prevent those elements from being referenced by other elements.

5.5. The ‘symbol’ element

The ‘symbol’ element is used to define graphical templates
which can be instantiated by a ‘use’ element but which are not rendered
directly.

A ‘symbol’ establishes a nested coordinate system
for the graphics it contains.
When a symbol is instantiated
as the referenced element of a ‘use’ element,
it is therefore rendered very similarly to a nested ‘svg’ element.

The x, y, width, and height geometry properties
have the same effect as on an ‘svg’ element,
when the ‘symbol’ is instantiated by a ‘use’ element.
In particular, if width and height
compute to auto
(and are not over-ridden by values on the instantiating ‘use’ element),
then they will be treated as a value of 100%.

New in SVG 2.
Allowing geometry properties to be specified on a symbol
provides a more consistent rendering model,
and allows authors to set a default size for each symbol
(which may still be over-ridden by attributes on the ‘use’ element).

We will add top/center/bottom, left/center/right keywords to
refX/refY on marker/symbol. Resolved at
London
F2F. Values inspired by
'background-position'.
Status: Done.

The ‘refX’ and ‘refY’ attributes define the
reference point of the symbol which is to be placed exactly at
the symbol's x,y positioning coordinate,
as defined by the cumulative effect of the x and y
properties and any transformations on the ‘symbol’
and its host‘use’ element.

Keyword values have the same meaning as for the
‘refX’ and ‘refY’ attributes on the ‘marker’ element,
resolving to 0%, 50%, or 100% in the applicable direction.

Unlike other positioning attributes,
‘refX’ and ‘refY’
are interpreted as being in the coordinate system of the
symbol contents, after application of the ‘viewBox’
and ‘preserveAspectRatio’ attributes.
If one or both of the attributes is not specified,
no adjustment is made in the corresponding dimension,
and the top or left side of the symbol's rectangular viewport region
(regardless of the ‘viewBox’ coordinates)
is positioned at the x,y point.

For backwards compatibility,
the behavior when ‘refX’ and ‘refY’
are not specified on a ‘symbol’
is different from when they are specified with a value of 0,
and therefore different from the behavior
when equivalent attributes are not specified on a ‘marker’.

5.5.2. Notes on symbols

The use of ‘symbol’ elements for graphics that are used multiple
times in the same document adds structure and semantics.
Closely related to the ‘symbol’ element are the
‘marker’ and ‘pattern’ elements;
all three define a container of graphical content
that can be rendered repeatedly at various positions and scales in the SVG.
However, while re-used graphics in a pattern and marker
provide a graphical effect on another element,
the content in a ‘symbol’ will be embedded
as fully interactive content, within a use-element shadow tree.

The user agent style sheet sets
the overflow property for ‘symbol’ elements to
hidden, which causes a rectangular clipping
path to be created at the bounds of symbol's SVG viewport. Unless the
overflow property is overridden, any graphics within the symbol which
goes outside of the symbol's SVG viewport will be clipped.

‘symbol’ elements must never be rendered directly;
their only usage is as something that can be referenced
using the ‘use’ element.
The user agent must set the
display property on the ‘symbol’ element
to none,
as part of the user agent style sheet,
and this declaration must have importance over any other CSS rule or presentation attribute.

The ‘use’ element
references another element, a copy of which
is rendered in place of the ‘use’ in the document.
The referenced element may be a container element,
in which case a copy of
the complete SVG document subtree rooted at that element is used.

The cloned content inherits styles from the ‘use’ element
and can be the target of user events.
However, these cloned element instances remain linked to the referenced source
and reflect DOM mutations in the original.
In addition, all style rules that apply in the scope of the referenced element
also apply in the scope of the cloned shadow tree.

The x, y, width and height
geometric properties specify the positioning of the referenced element.
The width and height attributes
only have an effect if the referenced element
defines a viewport (i.e., if it is a ‘svg’ or ‘symbol’);
if so, a value other than auto
for the ‘use’ element overrides the value
of the corresponding geometric property on that element.

A negative value for width or height
must be treated as an illegal value.
If width or height is zero,
and the properties have an effect on the referenced element,
then rendering of that element will be disabled.

The x and y properties
affect the user coordinate system for the element.
See the Layout section for implementation details.

New in SVG 2.
An ‘href’ without a fragment allows an entire SVG document to be referenced
without having to ensure that it has an ID on its root element.

User agents may restrict external resource documents for security
reasons. In particular, this specification does not allow cross-origin resource requests in ‘use’.
A future version of this or another specification may provide a method of securely enabling cross-origin re-use
of assets.

Elements in the shadow tree are rendered as if
the ‘use’ element was a container and they were its children.
However, the SVG Document Object Model (DOM) only contains
the ‘use’ element and its attributes.
The SVG DOM does not include the
element instances as children of the ‘use’ element.

User agents that support scripting and the document object model
must implement the use-element shadow tree as described in this section
and in conformance with the Shadow DOM specification [SHADOWDOM],
or its future replacement.
In contrast, user agents that do not support
the dynamic interactive processing mode
may not need to implement all the details of the shadow DOM.
However, all user agents must ensure that the layout
and style inheritance for the re-used graphics,
and any multimedia
and declarative animations if applicable,
are rendered in the same way as if the shadow DOM was implemented.

The following definitions apply when discussing ‘use’ elements
and their shadow trees:

referenced element

The element specified by the ‘href’ (or ‘xlink:href’) attribute on the ‘use’ element, or the root element of a document referenced by that attribute if the URL provided does not include a target fragment that links to a specific element ‘id’.

referenced document subtree

referenced graphics

The referenced element, and all of its descendent nodes.

shadow root

A ShadowRoot object,
a type of DocumentFragment node which is associated with a host Element,
and which contains the content that will be used to render that host.
A shadow root should be implemented in conformance with the Shadow DOM specification [SHADOWDOM],
or its future replacement.

shadow host

host

An element that has an associated shadow root;
usage is consistent the definition of host in the DOM standard.

shadow tree

A node tree whose root is a shadow root;
usage is consistent the definition of shadow tree in the DOM standard.

use-element shadow tree

A shadow tree whose host is a ‘use’ element,
which contains element instances generated by cloning the referenced graphics.

element instance

instance

An element in the use-element shadow tree,
which is generated by cloning a corresponding element in the referenced document subtree.

instance root

The element instance for the referenced element;
it is always a direct child of the ‘use’ element's shadow root.

corresponding element

For each element instance,
the element in the referenced document subtree from which it is cloned.

corresponding use element

For each element instance,
the ‘use’ element which causes it to be rendered in the document.
This is the instance's shadow root's host ‘use’ element
if that element is not itself an element instance within a ‘use’ element shadow tree,
or is that element's corresponding use element otherwise,
recursively exiting shadow trees as many times as necessary
to reach a ‘use’ element that was not itself generated
as part of the shadow tree of another ‘use’ element.

When the user agent successfully resolves a ‘use’ element
to identify a referenced element,
the user agent must create a
use-element shadow tree whose host is the ‘use’ element itself.
The shadow tree must be created even if
the ‘use’ element is not rendered
because it is a descendent of a never-rendered element,
because of conditional processing,
or because of the display property being set to none
on it or an ancestor element.

Previous versions of SVG restricted the contents
of the shadow tree to SVG graphics elements.
This specification allows any valid SVG document subtree
to be cloned.
Cloning non-graphical content, however,
will not usually have any visible effect.

The user agent must ensure that
all mutations to the referenced document subtree are reflected in the shadow tree.
This includes changes to elements, attributes, and text and other nodes.
In addition, changes to the stylesheets in effect for the referenced graphics
must be reflected in changes to the stylesheets in the shadow tree's scope,
as described futher in the section on style inheritance.

If either the ‘use’ element or the referenced element is altered
in a way that causes the ‘use’ element's URL reference to become unresolved again,
then the entire shadow tree for that use element is discarded.

When a ‘use’ references
another element which is another ‘use’ or whose content contains a
‘use’ element, then the shadow DOM
cloning approach described above is recursive. However, a set
of references that directly or indirectly reference a element
to create a circular dependency is an invalid circular reference.
The ‘use’ element or element instance
whose shadow tree would create the circular reference
is in error and must not be rendered by the user agent.

5.6.2. Layout of re-used graphics

The value of the x, y, width and height properties
on a ‘use’ element
are used to position the re-used graphics
and to set the viewport size
if the referenced element defines a nested viewport.
The effect of these properties on a ‘use’ element
is notably different from their effect on a graphics element,
or from their effect in CSS box layout.

The x and y properties define
an additional transformation
(translate(x,y),
where x
and y represent the computed value of the corresponding property)
to be applied to the ‘use’ element,
after any transformations specified with other properties
(i.e., appended to the right-side of the transformation list).

For historical reasons,
the supplemental transformation is applied to the ‘use’ element itself,
rather than solely to the re-used content in the shadow tree.
This affects the coordinate system used for
any masks, clipping paths, or filters
applied to the ‘use’ element
and calculated in userSpaceOnUse units.

To apply userSpaceOnUse graphical effects in an un-transformed coordinate space,
while also using the x and y to position the graphics,
authors can nest the ‘use’ element inside a ‘g’,
and apply the graphical effects to the ‘g’ element.

The width and height properties
on the ‘use’ element
override the values for the corresponding properties
on a referenced ‘svg’ or ‘symbol’ element
when determining the used value for that property on the instance root element.
However, if the computed value for the property on the ‘use’ element is auto,
then the property is computed as normal for the element instance.

These properties can therefore be used to scale a graphic
that defines its own coordinate system,
each time it is re-used.
Because auto is the initial value,
if dimensions are not explicitly set on the ‘use’ element,
the values set on the ‘svg’ or ‘symbol’ will be used as defaults.

In all other ways,
rendering and layout of elements within the
use-element shadow tree
occurs as if the ‘use’ element was a container for its shadow content.
In particular, unless elements within the shadow tree establish a new viewport,
they must be drawn in the coordinate system in which the ‘use’ element is defined
(including any cumulative transformations).
This affects the interpretation of percentage lengths,
and also graphical effects with userSpaceOnUse units.

5.6.3. Style Scoping and Inheritance

The use-element shadow tree, like other shadow trees,
exhibits style encapsulation,
as defined in the CSS Scoping module [css-scoping-1].
This means that elements in the shadow tree inherit styles
from its host‘use’ element,
but that style rules defined in the outer document
do not match the elements in the shadow tree.
Instead, the shadow tree maintains its own list of stylesheets,
whose CSS rules are matched against elements in the shadow tree.

When the referenced element
is from the same document as the ‘use’ element,
the same document stylesheets will apply in
both the original document and the shadow tree document fragment.
Any changes to the stylesheets in the main document
also affect the shadow tree;
the StyleSheetList object accessed through the
document and shadow root document fragment's
styleSheets properties must be identical.
If a ‘style’ element is duplicated
as part of the referenced document subtree,
then the styleSheet property on the element instance
points to the same object as for the corresponding element.

When the referenced element
is from an external document,
the stylesheet objects generated when processing that document
apply to the shadow tree, and are read-only.
All URL references in the stylesheet,
including fragment-only references,
must be made absolute, relative to the URL of the document
that contains the referenced element.
User agents may re-use the same stylesheet objects for any shadow trees
that reference that same external document.

Style rules that are scoped to the shadow tree
cannot normally affect any elements in the main document.
Similarly, style rules in the main document can only
affect the shadow tree elements by changing inherited values.
However, CSS Scoping
defines special selectors for styling the host element from within the shadow tree,
or for adjusting styles within the shadow tree
in response to changes in the host's context
[css-scoping-1].

CSS media queries within a shadow tree's scope
are evaluated using the same device features and dimensions
as the corresponding "light" document
(that is, the document that contains the corresponding use element
for the shadow tree, after recursively exiting all nested shadow trees).

In most cases,
the element instance in the shadow tree will match the same style rules
as its corresponding element in the original document.
However, if a CSS rule uses a complex selector
to match an element based on its ancestors or siblings,
and those ancestors or siblings are not cloned as part of the shadow tree,
then that rule would no longer match the element instance.
Similarly, child-indexed pseudo-classes
such as nth-of-type and nth-child
may apply to one element but not the other.
This represents a change
from how style cloning was defined in previous versions of SVG.

The following example demonstrates both the consistent and changed style-matching rules.
The circle on the left is re-used to draw the circle on the right.
The original circle has styles set in various ways:

stroke-width (20) is set in a presentation attribute on the circle itself.

stroke-opacity (0.7) is set via a CSS rule with a simple selector matching the circle tag name.

stroke color (green) is set using a complex CSS selector, matching the circle as a descendent of an element with class special.

fill color is not set directly on the circle, so is inherited from the style set on the containing ‘g’ element (blue).

In the SVG 1.1 style-cloning model,
the specified style values
would be cloned from the original element to the element instance.
The re-used circle would have the same styles as the original,
except that the fill value would be inherited from the ‘use’ (orange)
instead of from the ‘g’ (blue).

In the shadow DOM model required by SVG 2,
the styles for the re-used circle are calculated as follows:

the stroke-width (20) presentation attribute is cloned to the element instance.

the CSS rule setting stroke-opacity (0.7) is part of the CSS stylesheet cloned into the shadow tree; it matches the circle tag name of the element instance, so is applied.

the CSS rule with the complex selector is also part of the cloned stylesheet, but it does not match the element instance of the circle, which is not a descendent of an element with class special; instead, stroke color on the circle is inherited from the host ‘use’ element (purple).

fill color is still not set directly, so is once again inherited from the host ‘use’ element.

The re-used circle therefore differs from the original in both fill color (because it inherits from a different element) and stroke color (because the complex selector no longer matches).

<svg xmlns="http://www.w3.org/2000/svg"
xmlns:xlink="http://www.w3.org/1999/xlink"
width="200" height="100" viewBox="0 0 200 100">
<title>Style inheritance and the use element</title>
<desc>
Two circles, one of which is a re-styled clone of the other.
This file demonstrates one of the cases where
the shadow-DOM style matching rules in SVG 2
have a different effect than the SVG 1.1 style cloning rules.
The original circle on the left
should have blue fill
and green stroke.
In a conforming SVG 1.1 user agent,
the re-used circle on the right
should have orange fill and green stroke.
In a conforming SVG 2 user agent,
the re-used circle should have orange fill and purple stroke.
In all cases,
the stroke should be partially transparent
and 20 units wide,
relative to a total circle diameter of 100 units.
</desc>
<style type="text/css">
circle { stroke-opacity: 0.7; }
.special circle { stroke: green; }
use { stroke: purple;
fill: orange; }
</style>
<g class="special" style="fill: blue">
<circle id="c" cy="50" cx="50" r="40"
stroke-width="20" />
</g>
<use xlink:href="#c" x="100" />
</svg>

Previous versions of SVG
were not clear about how dynamic pseudo-classes
(such as :hover)
should apply to element instances.
The shadow tree model requires that all such pseudo-classes
are matched independently to the
element instance or to its corresponding element,
depending on which element the user is interacting with.

Specifying 'visibility:hidden' on a ‘use’ element does not guarantee
that the referenced content will not be rendered.
Unlike the display or the opacity properties,
the visibility property does not appy directly to container elements,
and therefore does not apply directly to the ‘use’ element.
Because visibility is normally inherited,
hiding the use element will often hide the child content,
but not necessarily.
If any graphics elements in the shadow tree have
'visibility:visible' specified, then that
element will be visible even if the ‘use’ element specifies 'visibility:hidden'.

The "dark" class is set on the group containing the ‘use’ elements,
so all parts of the re-used graphics inherit the hidden visibility setting,
except for the subtrees with class "eyes", where it is reset to visible.
Upon hovering or focusing the graphic, the hiding effect is removed.

The example also demonstrates inheritance of other style properties
(fill and stroke)
specified on the ‘use’ elements,
and how these are also not used if any elements within the symbol
specify explicit values (e.g., the pink noses and ears and the white tails).

The instance must not play any audio
if the ‘use’ element is not rendered.

If user-agent provided playback controls are included
for the corresponding element
(or would be included, if the element was rendered),
then they must be included for all instances in the document,
and a user action on any instance must control playback on them all.

Scripted animations created by directly manipulating
attributes on elements in the referenced graphics
(including the ‘style’ attribute or its IDL property)
will be propagated to the element instances
in the shadow tree in the same manner as any other DOM manipulations.

Animation effects applied using CSS
will be duplicated along with other stylesheet rules,
following the procedure specified in the
Style Scoping and Inheritance section.

The user agent must create such a ShadowAnimation
for all Web Animations API animations in effect
(including pending and frozen animations)
at the time the shadow tree is generated,
and for any new animations applied while the shadow tree exists.
The user agent must not create ShadowAnimation objects
for CSS animations or animation elements
(as these are duplicated separately).

For each animation element [svg-animation]
that targets an element in the
referenced document subtree,
the user agent must ensure that an equivalent animation element
is in effect in the use-element shadow tree.
If the animation element itself is part of the referenced document subtree,
then this happens as a matter of course through the creation
of an element instance for the animation element.
Otherwise, the user agent must generate an element instance
for the animation element
that has the same effect as if it was a node in the shadow tree.
The effective document order for these generated animation elements
must be the same as the document order for their corresponding elements.

Each animation element or instance must only affect a target element
in the same node tree (shadow or light),
regardless of whether the targetting is implicit (the parent element)
or explicit (a URL cross-reference to an element ‘id’).
In this way, the one-to-one relationship between animation elements
and target elements is preserved.

The ‘id’ attribute is cloned, like any other attribute,
from the corresponding element to the element instance;
This does not conflict with the requirement for ‘id’ to be unique,
because the clone and the original are in distinct node trees.

All animation elements, in the document or in the shadow trees,
which are timed to begin or end in response to an event
on another element identified by its ‘id’ attribute,
must also begin or end when any instance of an element with that ‘id’
receives the same event.
This is consistent with how event listeners on a
referenced element also listen to events on instances of that element,
as described in the section on
Event handling in use-element shadow trees.
This behavior does not apply to animation begin or end times
defined only by an event and not by an ‘id’
(and therefore implicitly listening for the event on the target element);
in that case, each animation element is only triggered by its own target.

At the time an instance of an animation element
is generated within a shadow tree,
if there is an active animation associated with the corresponding element
(including a frozen animation),
and the timing event that initiated that animation would also have initiated the instance if it existed,
then the animation for the element instance must be initiated,
with its begin time
adjusted backwards in the document timeline
to match the timing of the corresponding element.

In many cases,
the requirements of this section mean that
the element instance and its corresponding element
will animate synchronously.
This will be the case if the animation is purely time-based,
or if it begins and ends in response to user interaction
on an element referenced by its ‘id’.
However, if the animation is triggered by a user interaction event
on the targetted element (implicitly),
then only the element or element instance that receives the interaction event
will display the animation.

This is a change from previous versions of SVG,
which required all animations on the corresponding element to be mirrored,
regardless of user interaction,
but which did not offer clear guidance for responding to
user interactions with the element instances.
The change ensures that interactive animations declared with animation elements
behave in the same manner as interactive CSS styles and CSS animations.

In order to create animations
that apply to all instances when any instance or the original element
receives an event,
specify the element ‘id’ explicitly:

<set href="#target" begin="mouseover" ... />
<!-- only affects the element that is moused over -->
<set href="#target" begin="target.mouseover" ... />
<!-- affects all instances of the element with the id 'target',
in all light and shadow node trees,
when any of them are moused over -->

5.6.6. Event handling in use-element shadow trees

Element in a use-element shadow tree
can both listen for and be the target of DOM events.
Event retargetting provides encapsulation,
so that the details of the shadow DOM structure
are masked when an event bubbles out of the shadow tree and into the light.

Event retargeting is new in SVG 2.
It provides consistency with the Shadow DOM specification,
with existing implementations,
and with the expectations of authors who are only concerned with elements in the main DOM.

In general, the event path for a use-element shadow tree
is constructed from the ancestors of the event target element
up to the shadow root,
then the host‘use’ element
and its event path through to the document window.
This means that, in the capture phase,
an event propagates from the window through the regular document tree
to the ‘use’ element
and then to the shadow root object
and down through the shadow tree
(or recursively through multiple shadow trees)
to the event target element.
In the bubbling phase, the event passes in the opposite direction,
from the shadow tree elements to the shadow root,
then to the ‘use’ element and its ancestors.

The event retargeting algorithm ensures that
from the perspective of event listeners
on the ‘use’ element or its ancestors,
all events targetted to element instances in the shadow tree
instead have a target of the ‘use’ element itself.
If the event has both a target
and a relatedTarget,
and both of these properties would be retargeted
to point to the same ‘use’ element,
then the event is not propagated at all outside of the shadow tree.
This would occur, for example,
if focus moved from one element inside the shadow tree to another.
Certain other event types are constrained to
not propagate outside of the shadow tree in which they were created.

5.7. Conditional processing

5.7.1. Conditional processing overview

SVG contains a ‘switch’ element along with
attributes ‘requiredExtensions’ and ‘systemLanguage’ to provide an
ability to specify alternate viewing depending on the
capabilities of a given user agent or the user's language.

Attributes ‘requiredExtensions’ and ‘systemLanguage’ act as tests and
evaluate to either true or false. The ‘switch’ renders the first of
its children for which all of these attributes test true. If
the given attribute is not specified, then a true value is
assumed.

When an element is excluded because of conditional processing,
it is treated as if it had a used value of none for the display property.
Similar to the display property, conditional processing
attributes only affect the direct rendering of elements and do
not prevent elements from being successfully referenced by
other elements (such as via a ‘use’).

conditional processing will
have no effect on never-rendered elements;
in particular, conditional processing does not affect the processing of a ‘style’ or ‘script’ element.

conditional processing of child content of a never-rendered container element
(e.g., a ‘pattern’ or a ‘mask’)
will affect whether that child content contributes to the graphical effect.

Previous versions of SVG included a third conditional processing attribute,
requiredFeatures.
This was intended to allow authors to provide fallback behavior for user agents
that only implemented parts of the SVG specification.
Unfortunately, poor specification and implementation of this attribute made it unreliable
as a test of feature support.

5.7.2. Definitions

conditional processing attribute

A conditional processing attribute is one that controls whether
or not the element on which it appears is processed. Most elements,
but not all, may have conditional processing attributes specified
on them. See Conditional processing
for details. The conditional processing attributes defined in
SVG 2 are ‘requiredExtensions’ and ‘systemLanguage’.

The ‘switch’ element evaluates
the ‘requiredExtensions’ and
‘systemLanguage’ attributes on its direct child elements in
order, and then processes and renders the first child for which these
attributes evaluate to true. All others will be bypassed and therefore
not rendered. If the child element is a container element such as a
‘g’, then the entire subtree is either processed/rendered or
bypassed/not rendered.

In SVG, when evaluating the ‘systemLanguage’ attribute, the order of
evaluation of descendant elements of the ‘switch’ element must be as if the
'allowReorder'
attribute, defined in the SMIL specification [SMIL]
always has a value of 'yes'.

Note that the values of properties display and
visibility have no effect on ‘switch’ element
processing. In particular, setting display to
none on a child of a ‘switch’ element
has no effect on true/false testing associated with ‘switch’
element processing.

The ‘switch’ element does not affect the processing of
‘script’ and ‘style’ elements.

5.7.4. The ‘requiredExtensions’ attribute

The ‘requiredExtensions’
attribute defines a list of required language extensions.
Language extensions are capabilities within a user agent that
go beyond the feature set defined in this specification. Each
extension is identified by an URL reference.

The value is a list of URL references which
identify the required extensions, with the individual
values separated by white space. Determines whether all of
the named extensions are supported by the user
agent. If all of the given extensions are supported, then
the attribute evaluates to true; otherwise, the current
element and its children are skipped and thus will not be
rendered.

If a given URL
reference contains white space within itself, that white
space must be escaped.

If the attribute is not present, then it implicitly evaluates to "true". If a null string or empty string value is
given to attribute ‘requiredExtensions’, the attribute
evaluates to "false".

‘requiredExtensions’ is often
used in conjunction with the ‘switch’ element. If the ‘requiredExtensions’ is used in other
situations, then it represents a simple switch on the given
element whether to render the element or not.

The URL names for the extension should include versioning
information, such as "http://example.org/SVGExtensionXYZ/1.0",
so that script writers can distinguish between different
versions of a given extension.

Evaluates to "true" if one of the languages indicated by
user preferences exactly equals one of the languages given in
the value of this parameter, or if one of the languages
indicated by user preferences exactly equals a prefix of one of
the languages given in the value of this parameter such that
the first tag character following the prefix is "-".

Evaluates to "false" otherwise.

If the attribute is not present, then it implicitly evaluates to "true".
If a null string or empty string value is
given to attribute ‘systemLanguage’, the attribute evaluates to
"false".

Note: This use of a prefix matching rule does not imply that
language tags are assigned to languages in such a way that it
is always true that if a user understands a language with a
certain tag, then this user will also understand all languages
with tags for which this tag is a prefix.

The prefix rule simply allows the use of prefix tags if this
is the case.

Implementation note: When making the choice of linguistic
preference available to the user, implementers should take into
account the fact that users are not familiar with the details
of language matching as described above, and should provide
appropriate guidance. As an example, users may assume that on
selecting "en-gb", they will be served any kind of English
document if British English is not available. The user
interface for setting user preferences should guide the user to
add "en" to get the best matching behavior.

Multiple languages may be listed for content that is
intended for multiple audiences. For example, content that is
presented simultaneously in the original Maori and English
versions, would call for:

<text systemLanguage="mi, en"><!-- content goes here --></text>

However, just because multiple languages are present within
the object on which the ‘systemLanguage’ test
attribute is placed, this does not mean that it is intended for
multiple linguistic audiences. An example would be a beginner's
language primer, such as "A First Lesson in Latin," which is
clearly intended to be used by an English-literate audience. In
this case, the ‘systemLanguage’ test attribute
should only include "en".

Authoring note: Authors should realize that if several
alternative language objects are enclosed in a ‘switch’, and none of them
matches, this may lead to situations where no content is
displayed. It is thus recommended to include a "catch-all"
choice at the end of such a ‘switch’ which is acceptable in
all cases.

‘systemLanguage’ is often used
in conjunction with the ‘switch’ element. If the ‘systemLanguage’ is used in other
situations, then it represents a simple switch on the given
element whether to render the element or not.

5.8. The ‘desc’
and ‘title’ elements

5.8.1. Definition

descriptive element

An element which provides supplementary descriptive information about
its parent. Specifically, the following elements are descriptive elements:
‘desc’, ‘metadata’ and ‘title’.

Multilingual descriptive text selection, based on the ‘lang’ attribute, was added to allow internationalization
of the ‘desc’ and ‘title’ elements.

New in SVG 2. Adding 'lang' resolved at Rigi Kaltbad face-to-face.
Removed text that limited number of 'desc' and 'title' elements. Status: Done.

Multiple sibling ‘desc’ or ‘title’ elements must have
different languages,
as defined using a ‘lang’ attribute (or xml:lang attribute) on the descriptive element or an ancestor.
The user agent must select the element of each type whose language best
matches language preferences set by the user.
A descriptive element with an empty-string language tag
(indicating no language, for example a text alternative consisting of emoji symbols)
is a lowest-priority match for any user, ranked below all user-specified language preferences.
If multiple equally valid matches exist, the first match should be used.
If no match exists for either 'title' or 'desc', the first element of that type must be selected.

The following example shows alternative language titles on a re-used star icon,
inline in an HTML document.
The example assumes that the HTML document as a whole has a correctly-declared language of en (English without a specified country code).

The first title element inherits the language of the document (en); the others have explicitly-declared languages for each element.
If the user's preferred language (out of those provided) is American English, the icon title is the American spelling "Favorite".
If the user's preferred language is Dutch, the icon title is "Favoriet".
If the user's preference list includes generic English ranked higher than Dutch, the title is "Favourite" with British spelling.
If the user does not understand either Dutch or English, the title will be the star symbol character—which is not ideal (most screen readers will read it as a localized version of "black star"), but better than no text alternative at all.

Authors should be aware that SVG 1.1-supporting user agents
that have not yet implemented multi-lingual descriptive text
will normally select the first element of each type, regardless of user preferences.
SVG 1.1 user agents may also fail to recognize a title element that is not the first child of its parent,
or a desc element that has previous siblings that are not other descriptive elements.

The use of more than one ‘title’ or ‘desc’ element to
provide localised information is at risk, with no known implementations.

User agents must make the text content of selected 'title' and 'desc' elements available to platform accessibility APIs as part of the name and description computation for the parent element, as defined in the SVG Accessibility API Mappings [SVG-AAM] specification.

Inclusion of any 'title' or 'desc' elements as a direct child of a rendered element indicates that the rendered element is of semantic importance in the graphic.
Authors should not, and SVG generators must not, include empty 'title' or 'desc' elements with no text content or whitespace-only text content,
as this will result in a nameless object being presented to assistive technology users.

If an individual graphic element has no meaning on its own,
alternative text should instead be provided for the nearest container element that describes a meaningful object.
Authors should use grouping (‘g’) elements to structure their drawing elements into meaningful objects, and name those groups with ‘title’.
Conversely, if a container object is used simply to apply styles or layout,
and neither defines an object nor provides meaningful grouping structure,
it does not need alternative text.

Descriptive text elements whose parent is not rendered may be used by authors or authoring tools as reference information; authors are warned that this data is not normally available to end users viewing the graphic through assistive technologies. Nonetheless, a non-rendered element may be referenced as part of the accessible name or description of a rendered element (as defined in SVG-AAM), and the recursive computation will use descriptive child elements of the referenced element.

Description and title elements may contain marked-up text
from other namespaces, using standard XML mechanisms to indicate the namespace.
However, authors should not rely on such markup to provide meaning to alternative text;
only the plain text content is currently required to be exposed to assistive technologies.

The HTML parser treats all markup within ‘title’ and ‘desc’
the same way it treats markkup in an HTML fragment;
most elements will be assigned to the HTML namespace.

User agents may use markup within ‘title’
to influence the visual presentation of titles (such as tooltips),
but are not required to do so.

The ‘title’ child element represents a short text alternative for the
element.

On a link, this could be the title or a description of the target resource; on an
image or drawing object, it could be a short description of the
graphic; on interactive content, it could be a label for, or instructions for, use
of the element; and so forth.

Authors should not provide redundant information in a ‘title’ element
if there is also a visible label for the drawing element (e.g., using a ‘text’ element).
Instead, the visual label should be associated with the drawing element
using an ‘aria-labelledby’ attribute.

Interactive user agents should make the plain text content of ‘title’ elements available in response to user interaction, in a manner consistent with platform conventions;
existing user agents commonly render ‘title’ elements as
a tooltip on hovering the parent element.

Authors should provide a ‘title’ child element to the root svg
element within a stand-alone SVG document. Since users often consult documents
out of context, authors should provide context-rich titles. Thus, instead of a
title such as "Introduction", which doesn't provide much contextual background,
authors should supply a title such as "Introduction to Medieval Bee-Keeping"
instead. For reasons of accessibility, user agents should always make the
content of the ‘title’ child element to the root svg element available to
users.
However, this is typically done through other means than the tooltips used for nested SVG and graphics elements, e.g., by displaying in a browser tab.

The ‘desc’ element represents more detailed textual
information for the element such as a description. This is typically exposed to assistive
technologies to provide more detailed information, such as a description of the visual appearance of a graphic or help to explain the functionality of a complex widget. It is not typically available to other users, so should not be used for essential instructions.

Authors may associate detailed information, including visible text, with part of the graphic
using ‘aria-describedby’ attribute
(on the described element or a parent container),
with the value being an ID reference to one or more SVG or HTML elements containing the description.
The ‘aria-describedby’ attribute takes precedence
over the child ‘desc’ when providing a description.
If an element has both visible description and a child ‘desc’ element providing supplementary information,
authors should explicitly include the ‘id’ of the element itself in its own ‘aria-describedby’ list, in order to concatenate the two descriptions together.

5.9. The ‘metadata’ element

Metadata which is included with SVG content should be
specified within ‘metadata’
elements. The contents of the ‘metadata’ should be elements from
other XML namespaces, with these elements from these namespaces
expressed in a manner conforming with the Namespaces in XML Recommendation
[xml-names].

SVG 2 removes the recommendation to structure metadata
elements in any particular way.

Metadata content is not directly rendered;
the display value for the ‘metadata’ element
must always be set to none
by the user agent style sheet,
and this declaration must have importance over any other CSS rule or presentation attribute.

Here is an example of how metadata can be included in an SVG
document. The example uses the Dublin Core version 1.1 schema.
(Other XML-compatible metadata languages, including ones not
based on RDF, can be used also.)

Note that the base element will affect all URL values in the document, including e.g. paint server references or ‘use’ element references.
However, when processing URL references
to identify a specific target element,
the user agent must always compare the generated absolute URL against the current document base URL
to determine whether it is a same-document URL reference.
In this way, target-fragment only references to elements in the same document remain valid,
regardless of any changes to the document base URL.

5.11. Foreign namespaces and private data

SVG allows inclusion of elements from foreign namespaces
anywhere within the SVG content.
In general, the SVG user agent
must include the unknown foreign-namespaced elements in the DOM
but will ignore and exclude them for rendering purposes.

Additionally, SVG allows inclusion of attributes from
foreign namespaces on any SVG element.
The SVG user agent must
include unknown attributes in the DOM but should otherwise ignore
unknown attributes.

Authors should be aware that unknown namespaced elements and attributes
will not be parsed as such by the HTML parser.
Instead, the namespace prefix will be included in the tag or attribute name,
elements will be placed in the parent element namespace and attributes in the default namespace.

To add custom attributes in a way that will result in consistent parsing
in both XML and HTML documents,
authors may use the ‘data-*’ attributes.
These can be added to SVG ‘metadata’ elements
if the information they encode is not associated with any other element in the document.

SVG's ability to include foreign namespaces can be used for
the following purposes:

Application-specific information so that authoring
applications can include model-level data in the SVG content
to serve their "roundtripping" purposes (i.e., the ability to
write, then read a file without loss of higher-level
information).

Supplemental data for extensibility. For example, suppose
there is an extension which extrudes 2D graphics
into three dimensions according to certain parameters;
these parameters may be included in the SVG content
by inserting elements from the extension's
namespace.

For example, a business graphics authoring application
might want to include some private data within an SVG document
so that it could properly reassemble the chart (a pie chart in
this case) upon reading it back in:

5.12.2. Attributes common to all elements: ‘id’

Must reflect the element's
ID [DOM].
The ‘id’ attribute must be unique within the node tree,
must not be an empty string,
and must not contain any whitespace characters.

Additional requirements apply in order for
the ‘id’ attribute to be valid in XML documents,
as defined in the specification for the relevant version of XML.
A stand-alone SVG document uses XML 1.0 syntax [xml],
which specifies that valid ‘id’ values are XML name tokens.
Valid XML 1.0 names only include designated characters (letters, digits, and a few punctuation marks),
and do not start with a digit, a full stop (.) character, or a hyphen-minus (-) character.

If these attributes are omitted from an element, then the language of this element is the same as the language of its parent element, if any.

The ‘lang’ attribute in the XML namespace may be used on SVG elements in XML documents.
If both the ‘lang’ attribute in no namespace and the ‘lang’ attribute
in the XML namespace are specified on the same element, they must have exactly the same value when compared in an ASCII case-insensitive manner.

If both the ‘lang’ attribute in no namespace and the ‘lang’ attribute in the
XML namespace are set on an element, user agents must use the ‘lang’ attribute in the XML namespace, and
the ‘lang’ attribute in no namespace must be ignored for the purposes of determining the element's language.

The ‘lang’ attribute specifies the primary language for the element's contents and
for any of the element's attributes that contain text. Its value must be a valid BCP 47 language tag,
or the empty string. Setting the attribute to the empty string indicates that the primary language is unknown.
[BCP47].

5.12.4. The ‘xml:space’ attribute

SVG 2 Requirement:

Deprecate the use of ‘xml:space’ to affect text layout and use the ‘white-space’ property instead.

Deprecated XML attribute to specify whether white space
is preserved in character data. The only possible values
are the strings 'default' and 'preserve', without
white space. Refer to the
Extensible Markup Language (XML) 1.0
Recommendation [xml] and to the
discussion white space
handling in SVG.

5.12.5. The ‘tabindex’ attribute

This content attribute allows authors to control whether an element is focusable, whether it is supposed to be reachable
using sequential focus navigation, and what is to be the relative
order of the element for the purposes of sequential focus
navigation.

The name "tab index" comes from the common use of the
"tab" key to navigate through the focusable elements. The term
"tabbing" refers to moving forward through the focusable elements
that can be reached using sequential focus navigation.

The WAI-ARIA role that an SVG element has assigned to it is the first valid
role found in the list of tokens generated when the role attribute
is split on spaces.
A valid role is a recognized, non-abstract role that is allowed for the element type.

5.13.3. State and property attributes (all aria- attributes)

These attributes, if specified, must have a value that is the WAI-ARIA value
type in the "Value" field of the definition for the state or property, mapped to
the appropriate SVG value type according to
Mapping WAI-ARIA Value types to languages
using the SVG mapping ([wai-aria], section 10.2).

The attributes are animatable;
if animation is used to change the state of the graphic,
or to change its content in a way that alters the correct alternative text description,
the same method of animation should be used to update the corresponding
ARIA state or property attribute.

WAI-ARIA State and Property attributes can be used on any element. They are
not always meaningful, however, and in such cases user agents might not perform
any processing aside from including them in the DOM. State and property attributes are
processed according to the ARIA and
SVG Accessibility API Mappings specification
specifications. [wai-aria] [svg-aam-1.0]

5.13.4. Implicit and Allowed ARIA Semantics

The following table defines the default implicit ARIA
semantics that apply to SVG elements. Each
language feature (element) in a cell in the first
column implies the ARIA semantics (role, states, and/or properties)
given in the cell in the second column of the same row. The third column defines restrictions as to what WAI-ARIA semantic (role, state, or property) may or may not apply.

For many graphics elements, an implicit role is only assigned
if the author provides information that indicates semantic importance.
The complete inclusion criteria for the accessibility tree
are defined by the SVG Accessibility API Mappings specification for user agents [svg-aam-1.0].
For authors, the preferred means of indicating semantic importance is to provide an accessible name for the element.
This can be done through a direct child ‘title’ element,
or through the ‘aria-label’ or ‘aria-labelledby’ attributes.
Authors should use one of these methods to provide an accessible name
for any content that is essential to the comprehension of the SVG,
and especially for any interactive content.

link role
if the element has a valid href or xlink:href attribute.
For a elements that are not links, the default semantics are the same as
tspan if the a element is a descendent of text,
or the same as g otherwise.

5.14. DOM interfaces

5.14.1. Extensions to the Document interface

The DOM Core specification defines a Document interface, which this specification extends.

In the case where an SVG document is embedded by reference,
such as when an HTML document has an ‘object’
element whose ‘data’ attribute references an SVG
document (i.e., a document whose MIME type is "image/svg+xml"
and whose root element is thus an ‘svg’ element), there will exist
two distinct DOM hierarchies. The first DOM hierarchy will be for the
referencing document (e.g., an XHTML document). The second DOM hierarchy
will be for the referenced SVG document.

The
x,
y,
width and
height IDL attributes
reflect the computed values of the x, y, width and
height properties and their corresponding
presentation attributes, respectively.

The currentScale and
currentTranslate IDL
attributes represent the transform applied to the document in
response to user magnification and panning operations, as described under
Magnification and panning.

The document's magnification and panning
transform is a 2x3 matrix of the form
[currentScale 0 0 currentScale currentTranslate.x currentTranslate.y].
The value of the ‘transform’ property does not affect
currentScale or
currentTranslate.

Running these steps when the outermost svg element
changes will ensure that if the document element is replaced with a different
‘svg’ element, that its currentTranslate
will be immediately updated to reflect the translation component of
the document's magnification and panning transform.

Note that the value of the ‘zoomAndPan’ attribute
on the outermost svg element only controls whether the document's
magnification and panning transform can be updated through user interaction.
Regardless of the value of that attribute, the current scale and translation
can be changed by modifying currentScale
and currentTranslate.

The suspendRedraw,
unsuspendRedraw,
unsuspendRedrawAll
and forceRedraw
methods are all deprecated and defined to have no effect. When
the suspendRedraw method is called, it must return 1.

The getIntersectionList,
getEnclosureList,
checkIntersection and
checkEnclosure methods are
used to perform geometry operations on graphics elements to find
those whose (or check whether their) graphical content lies partially or
completely within a given rectangle.

To find the intersecting
or enclosed descendants of a given element element
with a given rectangle rectangle using ancestor
as the element in whose coordinate space rectangle is
to be interpreted, the following steps are run:

If any element in elements is not also in descendants,
then return false.

Return true.

The deselectAll method is
used to remove any selections from the document. When deselectAll() is called,
all ranges
from the document's selection
are removed and the selection's
direction is set to
forwards. [DOM][EDITING]
This method is deprecated, as it duplicates functionality from the Selection API.

This is equivalent to calling document.getSelection().removeAllRanges()
on the document that this ‘svg’ element is in.

The
createSVGNumber,
createSVGLength,
createSVGAngle,
createSVGPoint,
createSVGMatrix,
createSVGRect and
createSVGTransform
methods are all factory functions used to create a new datatype object
of a particular type. When one of these methods is called, a new
object is returned according to the following table:

The
x,
y,
width and
height IDL attributes
reflect the computed values of the x, y, width and
height properties and their corresponding
presentation attributes, respectively.

The instanceRoot and
animatedInstanceRoot
IDL attributes both point to the instance root,
the SVGElementInstance that is a direct child
of this element's shadow root
(u.instanceRoot is equivalent to getting u.shadowRoot.firstChild).
If this element does not have a shadow tree
(for example, because its URI is invalid
or because it has been disabled by conditional processing),
then getting these attributes returns null.

5.14.12. Interface SVGElementInstance

In previous versions of SVG,
SVG element instances were defined as non-element objects
that were valid event targets but not full DOM nodes.
This specification re-defines the use-element shadow tree
to be consistent with the Shadow DOM specification,
which means that instances are actual SVGElement objects.
This interface adds the missing functionality for backwards compatibility.
However, authors should be aware that compatibility is not perfect,
and design their scripts accordingly.
Also note that these properties will not be available
on HTML-namespaced element objects in the shadow tree.

When the referenced element is in an external file,
the presence of this pointer
implies that the entire DOM of the external file
must be maintained in memory.
However, as currently specified, the external DOM is read-only.
It therefore offers limited functionality and a potentially large performance impact.
Pending feedback from implementers,
authors should consider the use of correspondingElement
with external file references to be at-risk.

A ShadowAnimation is read-only.
Any attempt to set any of the inherited IDL properties,
or call any of the Animation methods that change its state,
must throw a NoModificationAllowedError.
However, the user agent must ensure that
any changes to the properties or state
of the sourceAnimation are reflected
in changes to the ShadowAnimation.

5.14.14. Interface SVGSwitchElement

5.14.15. Interface GetSVGDocument

This interface provides access to an SVG document embedded by reference
in another DOM-based language. The expectation is that the interface is
implemented on DOM objects that allow such SVG document references.

This interface is deprecated and may be dropped from future versions of
the SVG specification. To access the SVG document inside an
‘iframe’ or
‘object’ element,
authors are suggested to use the contentDocument
attribute on the HTMLIFrameElement or HTMLObjectElement
interface, respectively.

The getSVGDocument method
is used to return a referenced SVG document. When getSVGDocument() is called,
it must return the Document object referenced by the embedding element
that implements the GetSVGDocument interface; if there is no document,
null is returned.

Note that this does no check to see whether the referenced
document is indeed an SVG document. Instead, any document is returned.

6.1. Styling SVG content using CSS

Elements in an SVG document can be styled using CSS.
Most visual characteristics and some aspects of element
geometry are controlled using CSS properties.
For example, the fill property controls the paint used to
fill the inside of a shape, and the width and
height properties are used to control the size
of a ‘rect’ element.

SVG user agents must support all of the CSS styling
mechanisms described in this chapter.

In SVG 1.1, support for inline style sheets
using the ‘style’ element and
‘style’ was not required. In SVG 2,
these are required.

The style sheet's text content is never directly rendered;
the display value for the ‘style’ element
must always be set to none
by the user agent style sheet,
and this declaration must have importance over any other CSS rule or presentation attribute.

6.3. External style sheets: the effect of the HTML ‘link’ element

An HTML
‘link’ element in an SVG document (that is,
an element in the HTML namespace with local name "link")
with its ‘rel’
attribute set to 'stylesheet' must be processed
as defined in the HTML specification and cause external style sheets to be
loaded and applied to the document. Such elements in HTML documents outside
of an inline SVG fragment must also apply to the SVG content.

Because the element is required to be in the HTML namespace, it
is not possible for an HTML
‘link’ element to be parsed as
part of an inline SVG fragment in a text/html document. However, when
parsing an SVG document using XML syntax, XML namespace declarations
can be used to place the element in the HTML namespace.

Note that an alternative way to reference external style sheets
without using the HTML
‘link’ element is to use an @import
rule in an inline style sheet. For example:

6.4. Style sheets in HTML documents

When an SVG ‘style’ or an HTML
‘style’ element is used in an HTML
document, those style sheets must apply to all HTML and
inline SVG content in the document. Similarly, any HTML
‘style’ element used in an SVG
document must also apply its style sheet to the document.

6.5. Element-specific styling: the ‘class’ and ‘style’ attributes

As with HTML, SVG supports the ‘class’ and ‘style’
attributes on all elements to support element-specific styling.

6.6. Presentation attributes

Some styling properties can be specified not only in style sheets
and ‘style’ attributes, but also in
presentation attributes.
These are attributes whose name matches (or is similar to) a given CSS property
and whose value is parsed as a value of that property. Presentation
attributes contribute to the
author level
of the cascade, following all other author-level style sheets,
and have specificity 0.

Not all style properties that can affect SVG rendering have a corresponding
presentation attribute.
Other attributes (which happen to share the name of a style property) must not be parsed as a
presentation attribute and must not affect CSS cascading and inheritance.
Also, only elements in the SVG namespace support presentation attributes.
Most SVG presentation attributes may be specified on any element in the SVG namespace
where there is not a name clash with an existing attribute.
However, the geometry properties only have equivalent presentation attributes
on designated elements.
Attributes of the same name on other elements must not affect CSS cascading and inheritance.

Except as noted in the table for the transform presentation attributes,
the presentation attribute name is the same as the property name, in lower-case letters.

Since presentation attributes are only available
on elements in the SVG namespace, an HTML video element is
classified as a graphics element, for example, but does not support
any presentation attributes.

Note that
‘cx’,
‘cy’,
‘r’,
‘x’,
‘y’,
‘width’ and
‘height’ attributes are not
always presentation attributes.
For example, the ‘x’ attribute on ‘text’ and ‘tspan’
is not a presentation attribute for the x property,
and the ‘r’ attribute on a ‘radialGradient’
is not a presentation attribute for the r property.

In the future, any new properties that apply
to SVG content will not gain presentation attributes. Therefore,
authors are suggested to use styling properties, either through
inline ‘style’ properties or style sheets,
rather than presentation attributes, for styling SVG content.

Animation of presentation attributes is equivalent to
animating the corresponding property.

In addition,
all interactive user agents are required
to apply distinctive styles to
the :focus pseudo-class
(normally using the outline property)
and the ::selection pseudo-element
(using an appropriate highlighting technique,
such as redrawing the selected glyphs with inverse colors).

An !important rule in a user agent stylesheet
over-rides all user and author styles
[css-cascade-4].
The display value for never-rendered elements
and for ‘symbol’ elements
can therefore not be changed.
A symbol must only be rendered if it is the direct child
of a shadow root whose host is a ‘use’ element
(and must always be rendered if the host ‘use’ element is rendered).
The other elements, and their child content, are never rendered directly.

CSS Transforms defines that the initial value for
transform-origin is 50% 50%.
Since elements in SVG must, by default, transform around their origin at (0, 0),
transform-origin is overridden and set to a default value of
0 0 for all SVG elements
(except for root ‘svg’ elements and ‘svg’ elements that are the child of a
‘foreignObject’ element or an element in a non-SVG namespace; these elements
must transform around their center).
[css-transforms-1]

The rx property describes the horizontal radius of the
‘ellipse’ element and the curve radius of the ‘rect’
element.
When the computed value of ‘rx’ is auto, the used radius is equal to the absolute length used for ry, creating a circular arc.
If both ‘rx’ and ‘ry’ have a computed value of auto, the used value is 0.

Regardless of how the value is calculated, the used value of ‘rx’ for a ‘rect’ is never more than 50% of the used value of width for the same shape.

The auto behavior is new in SVG 2 for ‘ellipse’,
matching the behavior for ‘rect’ elements when rx was not specified.

The ry property describes the vertical radius of the
‘ellipse’ element and the vertical curve radius of the ‘rect’
element.
When the computed value of ‘ry’ is auto, the used radius is equal to the absolute length used for rx, creating a circular arc.
If both ‘rx’ and ‘ry’ have a computed value of auto, the used value is 0.

Regardless of how the value is calculated, the used value of ‘ry’ for a ‘rect’ is never more than 50% of the used value of height for the same shape.

The auto behavior is new in SVG 2 for ‘ellipse’,
matching the behavior for ‘rect’ elements when ry was not specified.

The y property describes the vertical coordinate of
the position of the element.

7.8. Sizing properties: the effect of the
‘width’ and ‘height’
properties

See the CSS 2.1 specification for the definitions of
width and
height.

The CSS width and height properties are used for
sizing some SVG elements. Specifically, they are used to size
‘rect’, ‘svg’, ‘image’ and
‘foreignObject’. All of these elements have ‘width’
and ‘height’ presentation attributes.
The properties are also used for laying out embedded elements from the HTML namespace.

New in SVG 2. Images embedded in SVG can now be auto-sized to the intrinsic size, or scaled to a fixed height or width according to the intrinsic aspect ratio. This matches the behavior of embedded images in HTML.

The value auto for width
and height on other elements is treated as 0.

This means that, for example, a ‘foreignObject’
object element will not shrink-wrap to its contents if
auto is used.

8.1. Introduction

All SVG content is drawn inside
SVG viewports.
Every SVG viewport defines a drawing region characterized by a size
(width, height), and an origin, measured in abstract
user units.

Note that the term SVG viewport is distinct from the
"viewport"
term used in CSS.

The initial viewport is a top-level
SVG viewport that establishes a mapping between the coordinate system used
by the containing environment (for example, CSS pixels in web browsers)
and user units. Establishing an initial viewport is described in more
detail in The initial viewport.

Each SVG viewport generates a
viewport coordinate system
and a local coordinate system, initially identical.
Providing a ‘viewBox’ on a viewport's element transforms the local coordinate system
relative to the viewport coordinate system as described in
The ‘viewBox’ attribute. Child elements of a viewport can
further modify the local coordinate system, for example by specifying
the transform property.

SVG viewports can be nested. Percentage units are resolved with reference
to the width and height of the nearest ancestral SVG viewport. Hence, nesting
SVG viewports provides an opportunity to redefine the meaning of percentage
units and provide a new reference rectangle for "fitting" a graphic relative
to a particular rectangular area.

The width, height and origin of SVG viewports is established by a negotiation
process between the SVG document fragment generating the SVG viewport, and the
parent of that fragment (whether real or implicit). See
Establishing a new SVG viewport for a
description of this negotiation process.

By default, a nested SVG viewport's viewport coordinate system is equivalent to the local
coordinate system of the parent element, translated by the origin of the SVG viewport's
element. However, a transform property on an SVG viewport's element will modify
the viewport coordinate system relative to the parent element's local coordinate system.

Abstractly, all SVG viewports are embedded in the
canvas,
a drawing region that is infinitely large in all relevant dimensions.

8.2. Computing the equivalent transform of an SVG viewport

This process converts the min-x, min-y, width and height values of a viewBox attribute,
the position and size of the element on which the viewBox attribute is defined,
and the value of the preserveAspectRatio attribute on that element into a translation and
a scale that is applied to content contained by the element.

Under these conditions, the viewport's width must be established via the
positioning properties.

Similarly, if there are
positioning properties
specified on the referencing element or on the
outermost svg element that are
sufficient to establish the height of the viewport, then these
positioning properties must establish the viewport's height;
otherwise, the initial viewport's height must be the value of the height
presentation attribute on the outermost svg element.

In the following example, an SVG graphic is embedded inline
within a parent XML document which is formatted using CSS
layout rules. Since CSS positioning properties are not provided
on the outermost svg element,
the width="100px" and
height="200px" attributes
determine the size of the initial viewport:

8.4. The initial coordinate system

For the outermost svg element, the SVG user
agent must determine an initial viewport coordinate system and an
initial local coordinate system such that the
two coordinates systems are identical. The origin of both
coordinate systems must be at the origin of the SVG viewport, and one
unit in the initial coordinate system must equal one
CSS 2.1 px
([CSS2], section 4.3.2)
in the SVG viewport.
In stand-alone SVG documents and in SVG document fragments embedded
(by reference or inline) within parent documents where the parent's
layout is determined by CSS [CSS2] or
XSL [XSL], the initial viewport
coordinate system (and therefore the initial user coordinate
system) must have its origin at the top/left of the viewport, with
the positive x-axis pointing towards the right, the positive
y-axis pointing down, and text rendered with an "upright"
orientation, which means glyphs are oriented such that Roman
characters and full-size ideographic characters for Asian
scripts have the top edge of the corresponding glyphs oriented
upwards and the right edge of the corresponding glyphs oriented
to the right.

If the SVG implementation is part of a user agent which
supports styling documents using CSS 2.1 compatible
px units, then the SVG user agent should set its
initial value for the size of a px unit in real world
units to match the value used for other styling operations;
otherwise, if the user agent can determine the size of a
px unit from its environment, it should use that
value; otherwise, it should choose an appropriate size for one
px unit. In all cases, the size of a px must
be in conformance with the rules described in CSS 2.1
([CSS2], section 4.3.2).

Example InitialCoords below
shows that the initial coordinate system has the origin at the
top/left with the x-axis pointing to the right and the y-axis
pointing down. The initial user coordinate system has one user
unit equal to the parent (implicit or explicit) user agent's
"pixel".

The ‘viewBox’ attribute, in conjunction with the
‘preserveAspectRatio’ attribute, provides the capability to
stretch an SVG viewport to fit a particular container element.

The value of the ‘viewBox’ attribute is a list of four
numbers <min-x>, <min-y>, <width> and <height>, separated by
whitespace and/or a comma, that specify a rectangle in user
space that should be mapped to the bounds of the SVG viewport
established by the given element, taking into account the
‘preserveAspectRatio’ attribute.
The presence of the ‘viewBox’ attribute results in a transformation
being applied to the viewport coordinate system as described in
Computing the equivalent transform of an SVG viewport.

A negative value for <width> or
<height> is an error and invalidates
the ‘viewBox’ attribute. A value of zero disables rendering of the
element.

Example ViewBox illustrates
the use of the ‘viewBox’ attribute
on the outermost svg element to specify that
the SVG content should stretch to fit bounds of the
SVG viewport.

The effect of the ‘viewBox’
attribute is that the user agent automatically supplies the
appropriate transformation matrix to map the specified
rectangle in local coordinate system to the bounds of a designated region
(often, the SVG viewport). To achieve the effect of the example on
the left, with SVG viewport dimensions of 300 by 200 pixels, the
user agent needs to automatically insert a transformation which
scales both X and Y by 0.2. The effect is equivalent to having
an SVG viewport of size 300px by 200px and the following
supplemental transformation in the document, as follows:

To achieve the effect of the example on the right, with
SVG viewport dimensions of 150 by 200 pixels, the user agent needs
to automatically insert a transformation which scales X by 0.1
and Y by 0.2. The effect is equivalent to having an SVG viewport of
size 150px by 200px and the following supplemental
transformation in the document, as follows:

Note that in some cases the user agent will need to supply a
translate transformation in addition to a
scale transformation. For example, on an
outermost svg element, a
translate transformation will be needed if the
‘viewBox’ attributes specifies
values other than zero for <min-x> or <min-y>.

If both transform (or ‘patternTransform’)
and ‘viewBox’ are applied to an element two new coordinate
systems are established. transform establishes the first new
coordinate system for the element. ‘viewBox’
establishes a second coordinate system for all descendants of
the element. The first coordinate system is post-multiplied by the
second coordinate system.

Unlike the
transform property,
the automatic transformation that is created
due to a ‘viewBox’ does not affect
the ‘x’, ‘y’, ‘width’ and ‘height’ attributes (or in the case of
the ‘marker’ element, the
‘markerWidth’ and ‘markerHeight’ attributes) on the
element with the ‘viewBox’
attribute. Thus, in the example above which shows an
‘svg’ element which has
width and height presentation attributes
and a ‘viewBox’ attribute,
the width and height
represent values in the coordinate system that exists before the
‘viewBox’ transformation is applied. On
the other hand, like the transform property, it does
establish a new coordinate system for all other attributes and
for descendant elements.

In some cases, typically when using the
‘viewBox’ attribute, it is desirable that the graphics stretch to
fit non-uniformly to take up the
entire SVG viewport. In other cases, it is desirable that uniform
scaling be used for the purposes of preserving the aspect ratio
of the graphics.

For ‘image’ elements,
‘preserveAspectRatio’ indicates how
referenced images should be fitted with respect to the
reference rectangle and whether the aspect ratio of the
referenced image should be preserved with respect to the
current user coordinate system.

The <align> parameter
indicates whether to force uniform scaling and, if so, the
alignment method to use in case the aspect ratio of the ‘viewBox’
doesn't match the aspect ratio of the SVG viewport. The <align> parameter must be one
of the following strings:

none - Do not force
uniform scaling. Scale the graphic content of the given
element non-uniformly if necessary such that the element's
bounding box exactly matches the SVG viewport rectangle.
(Note: if <align> is
none, then the optional <meetOrSlice> value is
ignored.)

xMinYMin - Force uniform
scaling.
Align the <min-x> of
the element's ‘viewBox’ with the smallest X
value of the SVG viewport.
Align the <min-y> of
the element's ‘viewBox’ with the smallest Y
value of the SVG viewport.

xMidYMin - Force uniform
scaling.
Align the midpoint X value of the element's
‘viewBox’ with the midpoint X value of the SVG viewport.
Align the <min-y> of
the element's ‘viewBox’ with the smallest Y
value of the SVG viewport.

xMaxYMin - Force uniform
scaling.
Align the <min-x>+<width> of the
element's ‘viewBox’ with the maximum X value
of the SVG viewport.
Align the <min-y> of
the element's ‘viewBox’ with the smallest Y
value of the SVG viewport.

xMinYMid - Force uniform
scaling.
Align the <min-x> of
the element's ‘viewBox’ with the smallest X
value of the SVG viewport.
Align the midpoint Y value of the element's ‘viewBox’
with the midpoint Y
value of the SVG viewport.

xMidYMid (the initial value) -
Force uniform scaling.
Align the midpoint X value of the element's ‘viewBox’
with the midpoint X value of the SVG viewport.
Align the midpoint Y value of the element's ‘viewBox’
with the midpoint Y value of the SVG viewport.

xMaxYMid - Force uniform
scaling.
Align the <min-x>+<width> of the
element's ‘viewBox’
with the maximum X value of the SVG viewport.
Align the midpoint Y value of the element's ‘viewBox’
with the midpoint Y
value of the SVG viewport.

xMinYMax - Force uniform
scaling.
Align the <min-x> of
the element's ‘viewBox’ with the smallest X
value of the SVG viewport.
Align the <min-y>+<height> of the
element's ‘viewBox’ with the maximum Y value
of the SVG viewport.

xMidYMax - Force uniform
scaling.
Align the midpoint X value of the element's ‘viewBox’
with the midpoint X value of the SVG viewport.
Align the <min-y>+<height> of the
element's ‘viewBox’ with the maximum Y value
of the SVG viewport.

xMaxYMax - Force uniform
scaling.
Align the <min-x>+<width> of the
element's ‘viewBox’ with the maximum X value
of the SVG viewport.
Align the <min-y>+<height> of the
element's ‘viewBox’ with the maximum Y value
of the SVG viewport.

The <meetOrSlice>
parameter is optional and, if provided, is separated from the
<align> value by one or
more spaces and then must be one of the following strings:

the ‘viewBox’ is scaled up as much
as possible, while still meeting the other criteria

In this case, if the aspect ratio of the graphic does not
match the SVG viewport, some of the SVG viewport will extend beyond
the bounds of the ‘viewBox’ (i.e., the area into
which the ‘viewBox’ will draw will be
smaller than the SVG viewport).

the ‘viewBox’ is scaled down as
much as possible, while still meeting the other
criteria

In this case, if the aspect ratio of the ‘viewBox’ does not match the
SVG viewport, some of the ‘viewBox’ will extend beyond the
bounds of the SVG viewport (i.e., the area into which the ‘viewBox’ will draw is larger
than the SVG viewport).

8.8. Establishing a new SVG viewport

Including an ‘svg’ element inside SVG content
creates a new SVG viewport into which all contained
graphics are drawn; this implicitly establishes both
a new viewport coordinate system and a new user coordinate system.
Additionally, there is a new meaning for percentage units therein,
because a new SVG viewport has been established
(see Units).

The bounds of the new SVG viewport are defined by the ‘x’, ‘y’,
‘width’ and ‘height’ attributes on the element
establishing the new SVG viewport, such as an ‘svg’ element. Both the new
viewport coordinate system and the new user coordinate system
have their origins at (‘x’, ‘y’), where ‘x’ and ‘y’
represent the value of the corresponding attributes on the
element establishing the SVG viewport. The orientation of the new
viewport coordinate system and the new user coordinate system
correspond to the orientation of the current user coordinate
system for the element establishing the SVG viewport. A single unit
in the new viewport coordinate system and the new user
coordinate system are the same size as a single unit in the
current user coordinate system for the element establishing the SVG
viewport.

For historical reasons,
the ‘pattern’ and ‘marker’ elements
do not create a new viewport,
despite accepting a ‘viewBox’ attribute.
Neither do the ‘clipPath’ or ‘mask’ elements.
Percentage lengths within the content of these elements
are not proportional to the dimensions of the graphical effect region.

The ‘foreignObject’ element establishes a new
CSS containing block
for its child content.
The same is true for a ‘video’, ‘audio’, or ‘canvas’ element
when its fallback content is being rendered.
This has some effects similar to a new viewport,
resetting the scope of layout for child content.
However, in order to render SVG elements that are descendents of ‘foreignObject’,
a new ‘svg’ element must establish an SVG document fragment and SVG viewport.

An ‘image’ or ‘iframe’ element creates a new
document viewport
for the referenced document.
If the referenced document is a SVG file, it will of course establish its own SVG viewport.

Whether a new SVG viewport also establishes a new additional
clipping path is determined by the value of the overflow property on the element
that establishes the new SVG viewport.

8.9. Units

SVG follows the description and definition of common values and
units from the CSS Values and Units Module
[css-values] for attributes,
presentation attributes and CSS properties. Each attribute and property
must specify the used component value type. Subsequent or extending
specifications published by the CSS WG or SVG WG may extend basic data
types or add new data types.

For <percentage> values that are defined to be relative
to the size of SVG viewport:

For any x-coordinate value or width value expressed as a percentage of the
SVG viewport, the value to use must be the percentage, in user
units, of the width parameter of the ‘viewBox’ applied to that viewport.
If no ‘viewBox’ is specified, then the value to use must be the percentage, in
user units, of the width of the SVG viewport.

For any y-coordinate value or height value expressed as a percentage of the
SVG viewport, the value to use must be the percentage, in user
units, of the height parameter of the ‘viewBox’ applied to that viewport.
If no ‘viewBox’ is specified, then the value to use must be the percentage, in
user units, of the height of the SVG viewport.

For any other length value expressed as a
percentage of the SVG viewport, the percentage must be calculated as a
percentage of the normalized diagonal of the ‘viewBox’ applied to that viewport.
If no ‘viewBox’ is specified, then the normalized diagonal of the SVG viewport
must be used. The normalized diagonal length must be calculated with
sqrt((width)**2 + (height)**2)/sqrt(2).

Example Units below
illustrates some of the processing rules for different types of
units.

The three rectangles on the left demonstrate the use of one
of the absolute unit identifiers, the "in" unit (inch). CSS defines 1
inch to be equal to 96 pixels. Therefore, the topmost rectangle, which is
specified in inches, is exactly the same size as the middle
rectangle, which is specified in user units such that there are
96 user units for each corresponding inch in the topmost
rectangle. The bottom rectangle of the group illustrates
what happens when values specified in inches are scaled.

The three rectangles in the middle demonstrate the use of
one of the relative unit identifiers, the "em" unit. Because
the font-size property has been set
to 150 on the outermost ‘g’ element, each "em" unit is
equal to 150 user units. The topmost rectangle, which is
specified in "em" units, is exactly the same size as the middle
rectangle, which is specified in user units such that there are
150 user units for each corresponding "em" unit in the topmost
rectangle. The bottom rectangle of the group illustrates what
happens when values specified in "em" units are scaled.

The three rectangles on the right demonstrate the use of
percentages. Note that the width and height of the SVG viewport in
the user coordinate system for the SVG viewport element (in this
case, the outermost svg element) are 4000 and
2000, respectively, because processing the ‘viewBox’ attribute results in a
transformed user coordinate system. The topmost rectangle,
which is specified in percentage units, is exactly the same
size as the middle rectangle, which is specified in equivalent
user units. In particular, note that the stroke-width property in the
middle rectangle is set to 1% of the
sqrt((actual-width)**2 +
(actual-height)**2) / sqrt(2), which in this
case is .01*sqrt(4000*4000+2000*2000)/sqrt(2), or 31.62. The
bottom rectangle of the group illustrates what happens when
values specified in percentage units are scaled.

8.10. Bounding boxes

bounding box

The bounding box (or "bbox") of an element is the tightest fitting rectangle
aligned with the axes of that element's user coordinate system that entirely
encloses it and its descendants.

Three kinds of bounding boxes can be computed for an element:

The object bounding box is the bounding box that contains only
an element's geometric shape. For basic shapes, this is the area
that is filled. Unless otherwise specified, this is what is meant by the
unqualified term "bounding box".

The stroke bounding box is the bounding box that contains
an element's geometric shape and its stroke shape.

The decorated bounding box is the bounding box that contains
an element's geometric shape, its stroke shape and its markers.

For curved shapes, the bounding box must enclose all portions of the shape
along the edge, not just end points. Note that control points for a curve which
are not defined as lying along the line of the resulting curve (e.g., the second
coordinate pair of a Cubic Bézier command) must not contribute to the dimensions
of the bounding box (though those points may fall within the area of the
bounding box, if they lie within the shape itself, or along or close to the
curve). For example, control points of a curve that are at a further distance
than the curve edge, from the non-enclosing side of the curve edge, must be
excluded from the bounding box.

The path 'M20,50 L35,100 H120 V50 Q70,10 20,50'
is shown in light blue. On the left, a correct object bounding box of the path is
shown. Note that it does not include the top-most control point of the curve, but
it does include all of the blue shape, even the parts that lie outside of the convex hull
of the control points.

Even if an element is not in the rendering tree – due to it being
'display: none', within a ‘defs’
element, not usually rendered like a ‘symbol’ element or not
currently present in the document tree – it still has a bounding box.
A call to getBBox
on the element will return the same rectangle as if the element were
rendered. However, an element that is not in the rendering tree
does not contribute to the bounding box of any ancestor element.

The following example defines a number of elements. The expected
object bounding box for each element with an ID is shown below.

For text content elements, for the purposes of the bounding box
calculation, each glyph must be treated as a separate graphics element.
The calculations must assume that all glyphs occupy the full glyph cell.
The full glyph cell must have width
equal to the horizontal advance and height equal to the EM box for horizontal
text. For vertical text that is typeset sideways, the full glyph cell must
have width equal to the EM box and height equal to the horizontal advance.
For other vertical text, the full glyph cell must have width equal to the
EM box and height equal to the vertical advance, or height equal to the height
of the EM box if no vertical advance is defined in the font.
For example, for horizontal text, the calculations must assume that each glyph
extends vertically to the full ascent and descent values for the font.

Because declarative or scripted animation can change the shape, size, and
position of an element, the bounding box is mutable. Thus, the bounding box
for an element shall reflect the current values for the element at the snapshot
in time at which the bounding box is requested, whether through a script call
or as part of a declarative or linking syntax.

An element which has zero width, zero height, or both (such as a
vertical or horizontal line, or a ‘rect’ element with a zero
width or height) still has a bounding box, with a
positive value for the positive dimension, or with '0'
for both the width and height if no positive dimension is specified. Similarly,
subpaths segments of a ‘path’ element with zero width and height must be
included in that element's geometry for the sake of the bounding box.

An element with no position specified (such as a
‘path’ element with a value of none for the d property) is positioned at the
point (0,0) for the purposes of calculating a bounding box.

Note that elements whose DOM object does not derive from SVGGraphicsElement
(such as gradient elements) do not have a bounding box, and thus have no
interface to request a bounding box.

Elements in the rendering tree which reference unresolved resources shall
still have a bounding box, defined by the position and dimensions specified in
their attributes, or by the initial value for those attributes if no
values are supplied. For example, the element <use href="#bad" x="10" y="10"/>
would have a bounding box with an x and y of 10 and a width and height of 0.

The following algorithm defines how to compute a bounding box for a given
element. The inputs to the algorithm are:

element, the element we are computing a bounding box for;

space, a coordinate space in which the bounding box will be computed;

fill, a boolean indicating whether the bounding box includes the geometry of the element and its descendants;

stroke, a boolean indicating whether the bounding box includes the stroke of the element and its descendants;

markers, a boolean indicating whether the bounding box includes the markers of the element and its descendants; and

clipped, a boolean indicating whether the bounding box is affected by any clipping paths applied to the element and its descendants.

The algorithm to compute the bounding box is as follows, depending on the type of element:

If stroke is true and the element's stroke is anything other than
none, then set box to be the union of box and the
tightest rectangle in coordinate system space that contains the stroke shape of the
element, with the assumption that the element has no dash pattern.

Otherwise, set box to be the union of box and the result of invoking the
algorithm to compute a bounding box with child as the element,
space as the target coordinate space, true for fill,
stroke and markers, and clipped for clipped.

If clipped is true and the value of clip-path on element is not
none, then set box to be the tightest rectangle
in coordinate system space that contains the intersection of box and the clipping path.

Otherwise, set box to be the union of box and the result of invoking the
algorithm to compute a bounding box with child as the element
and the same values for space, fill, stroke,
markers and clipped as the corresponding algorithm input values.

If clipped is true:

If the value of clip-path on element is not
none,
then set box to be the tightest rectangle
in coordinate system space that contains the intersection of box and the clipping path.

If the overflow property applies to the element
and does not have a value of visible,
then set box to be the tightest rectangle
in coordinate system space that contains the intersection of box and the element's overflow bounds.

If the clip property applies to the element
and does not have a value of auto,
then set box to be the tightest rectangle
in coordinate system space that contains the intersection of box and the rectangle specified by clip.

8.11. Object bounding box units

The following elements offer the option of expressing
coordinate values and lengths as fractions (and, in some cases,
percentages) of the object bounding box,
by setting a specified attribute to 'objectBoundingBox'
on the given element:

Indicates that the attributes which specify the center
(‘cx’, ‘cy’), the radius (‘r’) and focus
(‘fx’, ‘fy’) represent fractions or
percentages of the bounding box of the element to which the
gradient is applied.

Indicates that the attributes which specify the paint server
mesh starting point (‘x’, ‘y’) represent
fractions or percentages and that mesh path data represents
fractions of the bounding box of the element to which the mesh
is applied. If the mesh is rendered inside a ‘mesh’ element
the current SVG viewport is used in place of a bounding box.

When keyword objectBoundingBox is used, then the
effect is as if a supplemental transformation matrix were
inserted into the list of nested transformation matrices to
create a new user coordinate system.

First, the (minx,miny) and
(maxx,maxy) coordinates are
determined by the extends of the object bounding box of
the applicable element.

Then, coordinate (0,0) in the new user coordinate system is
mapped to the (minx,miny) corner of the tight bounding box
within the user coordinate system of the applicable element and
coordinate (1,1) in the new user coordinate system is mapped to
the (maxx,maxy) corner of the tight bounding box of the
applicable element. In most situations, the following
transformation matrix produces the correct effect:

[ (maxx-minx) 0 0 (maxy-miny) minx miny ]

When percentages are used with attributes that define the
gradient vector, the pattern tile, the filter region or the
masking region, a percentage represents the same value as the
corresponding decimal value (e.g., 50% means the same as 0.5).
If percentages are used within the content of a ‘pattern’,
‘clipPath’, ‘mask’ or ‘filter’ element, these values
are treated according to the processing rules for percentages
as defined in Units.

Any numeric value can be specified for values expressed as a
fraction or percentage of object bounding box units. In
particular, fractions less are zero or greater than one and
percentages less than 0% or greater than 100% can be
specified.

Keyword objectBoundingBox
should not be used when the geometry of the applicable element
has no width or no height, such as the case of a horizontal or
vertical line, even when the line has actual thickness when
viewed due to having a non-zero stroke width since stroke width
is ignored for bounding box calculations. When the geometry of
the applicable element has no width or height and objectBoundingBox is specified, then
the given effect (e.g., a gradient or a filter) will be
ignored.

let viewbox be the viewbox defined by the ‘viewBox’
attribute on the ‘svg’ element

return viewbox.width / viewbox.height

return null

The behaviour defined in this section is specific to CSS, but may be adapted
to other host contexts. In all host contexts, the intrinsic aspect ratio,
where available, must be respected when sizing the SVG viewport.

In this example the intrinsic aspect ratio of the outermost SVG viewport is
1:1. An aspect ratio calculation in this case allows embedding in an
object within a containing block that is only constrained in one direction.

Sometimes it is of interest to let the outline of an object keep its
original width or to let the position of an object fix no matter which
transforms are applied to it. For example, in a map with a 2px wide line
representing roads it is of interest to keep the roads 2px wide even when the
user zooms into the map, or introductory notes on the graphic chart in which
panning is possible.

To offer such effects regarding special coordinate transformations and
graphic drawings, SVG Tiny 1.2 introduced the vector-effect property.
Although SVG Tiny 1.2 introduced only non-scaling stroke behavior, this version
introduces a number of additional effects. Furthermore, since these effects
can be specified in combination, they show more various effects. And, future
versions of the SVG language will allow for more powerful vector effects
through this property.

Values of vector-effect other than
non-scaling-stroke and none
are at risk of being dropped from SVG 2 due to a lack of implementations.
Feedback from implementers is requested,
regarding the practicality of implementing them as currently specified,
during the implementation period.

Specifies that no vector effect shall be applied, i.e. the default rendering behaviour
from SVG 1.1 is used which is to first fill the geometry of a shape with a specified
paint, then stroke the outline with a specified paint.

Specifies special local coordinate system toward this element
and its descendant by constrained transformations with the following
characteristics. The scale of the local coordinate system do not
change in spite of change of CTMs from a host coordinate space.
However, it does not specify the suppression of rotation and skew. Also,
it does not specify the fixation of placement of local coordinate system.
Since non-scaling-size suppresses scaling of local coordinate system,
it also has the characteristic of non-scaling-stroke. The transformation
formula and the example behavior are indicated to the following chapter.

non-rotation

Specifies special local coordinate system toward this element
and its descendant by constrained transformations with the following
characteristics. The rotation and skew of the local coordinate system
is suppressd in spite of change of CTMs from a host coordinate space.
However, it does not specify the suppression of scaling. Also, it does not
specify the fixation of placement of local coordinate system.
The transformation formula and the example behavior are indicated to the
following chapter.

fixed-position

Specifies special local coordinate system toward this element
and its descendant by constrained transformations with the following
characteristics. The placement of local coordinate system is fixed
in spite of change of CTMs from a host coordinate space. However,
it does not specify the suppression of rotation, skew and scaling. When
the element that has fixed-position effect and also has transform
property, that property is consumed for this effect. The shift components
e and f of matrix of transform property are
used to transfer the origin of fixed local coordinate system. The
transformation formula and the example behavior are indicated to the
following chapter.

These values can be enumerated. Thereby, the effect which has these
characteristics simultaneously can be specified.

The following two values assists the above-mentioned values. They show the
host coordinate space of constrained transformations. Especially it has
effective for the element belonging to nested viewport coordinate system such
as nested contents or nested ‘svg’ elements. An initial value in case
it is not specified is viewport.

It specifies the coordinate system of content which under the immediate
control of user agent. So to speak, it is "scrren" which user agent
has. ("screen coordinate space" in SVGT1.2) Even if that element belongs to
nested viewport coordinate system, that vector effect is always effective for
change of CTM of the any hierarchy. If the SVG implementation is part
of a user agent which supports CSS compatible px units, it is a
coordinate system on CSS pixel of rootmost content. Generally, the pixel (or
dot) of a device and pixel of CSS are not always equal by influences of the
zoom function which user agent itself has, and variation of dpi. (see
resolution
[CSS Values and Units Module Level 3])
Accordingly, this value does not specify constrained transformations toward
the such a device coordinate system.

8.13.1. Computing the vector effects

This section shows the list of transformation formulas regarding
combinations of the values for clarification of the behavior of vector effects
excluding non-scaling-stroke which has clear
implications.

When the vector-effect is added to an element like the above, the
transformation formula for user coordinate to the device coordinate changes as
follows. Here, xf and yf are user
coordinate of the corresponding element and its descendant. And,
xo and yo are matrix element
e and f of the transform attribute which the
corresponding element has. In addition, |det(CTM)| is absolute value of
the determinants of CTM. When this value becomes 0 and
non-scaling-size is appointed,
vector-effect becomes invalidity namely none.

When applying seven formulas of the preceding section to nested viewport
coordinate systems, the application way of those formulas changes as follows
by whether viewport or
screen is specified as the additional value of
vector-effect.

When viewport value is specified,
user agent computes coordinates combining either of seven formulas of
the preceding chapter, and the following formulas.

An SVGTransform object can be designated as read only,
which means that attempts to modify the object will result in an exception
being thrown, as described below.

An SVGTransform object can be associated
with a particular element. The associated element is used to
determine which element's ‘transform’
presentation attribute to update if the object reflects
that attribute. Unless otherwise described, an SVGTransform object is
not associated with any element.

The numeric transform type constants defined on SVGTransform are used
to represent the type of an SVGTransform's value.
Their meanings are as follows:

Constant

Meaning

SVG_TRANSFORM_MATRIX

A matrix(…) value.

SVG_TRANSFORM_TRANSLATE

A translate(…) value.

SVG_TRANSFORM_SCALE

A scale(…) value.

SVG_TRANSFORM_ROTATE

A rotate(…) value.

SVG_TRANSFORM_SKEWX

A skewX(…) value.

SVG_TRANSFORM_SKEWY

A skewY(…) value.

SVG_TRANSFORM_UNKNOWN

Some other type of value.

The use of numeric transform type constants is an anti-pattern and
new constant values will not be introduced for any transform types supported by
SVGTransform. If other types of transforms are supported and used, the SVGTransform
uses the SVG_TRANSFORM_UNKNOWN
type. See below for details on how the other properties of an SVGTransform
operate with these types of transforms.

The type IDL attribute represents
the type of transform item that the SVGTransform's value is.
On getting type, the following steps
are run:

If the SVGTransform's value
is a
matrix(…),
translate(…),
scale(…),
rotate(…),
skewX(…) or
skewY(…) function,
then return the corresponding constant
value from the transform type table above.

The
setTranslate,
setScale,
setRotate,
setSkewX and
setSkewY methods are used
to set the SVGTransform to a new transform function
value. When one of these methods is called,
the following steps are run:

This specification imposes additional requirements on the behavior of DOMMatrix
objects beyond those described in the
the Geometry Interfaces
specification, so that they can be used to reflect presentation attributes
that take transform values.

A DOMMatrix can be designated as read only,
which means that attempts to modify the object will result in an exception
being thrown. When assigning to any of a read only DOMMatrix's
IDL attributes, or when invoking any of its mutable transform methods,
a NoModificationAllowedError exception will be thrown
instead of updating the internal value.

Note that this applies only to the read-write DOMMatrix
interface; the DOMMatrixReadOnly interface, which is not used for reflecting
transform, will already throw an exception if an attempt is made to modify it.

When assigning to any of a writable DOMMatrix's
IDL attributes, or when invoking any of its mutable transform methods,
the following steps are run after updating the internal matrix value:

The baseVal and
animVal IDL attributes
represent the value of the reflected presentation attribute.
On getting baseVal or
animVal, an
SVGTransformList object is returned that reflects the given
presentation attribute.

Similarly, the numeric meet-or-slice type constants defined on
SVGPreserveAspectRatio are used to represent the meet-or-slice
keyword values that ‘preserveAspectRatio’ can take. Their
meanings are as follows:

Constant

Meaning

SVG_MEETORSLICE_MEET

The meet keyword.

SVG_MEETORSLICE_SLICE

The slice keyword.

SVG_MEETORSLICE_UNKNOWN

Some other type of value.

The align IDL attribute
represents the alignment keyword part of the ‘preserveAspectRatio’
value. On getting, the following steps are run:

A path is described using the concept of a current point. In
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.

Paths represent the geometry of the outline of an object,
defined in terms of moveto (set a new current point),
bearing (set a new orientation), lineto
(draw a straight line), curveto (draw
a curve using a cubic Bézier), arc (elliptical
or circular arc) and closepath (close the current
shape by connecting to the last moveto) commands.
Compound paths (i.e., a path with multiple subpaths) are
possible to allow effects such as "donut holes" in objects.

9.3.1. General information about path data

A path is defined by including a ‘path’
element on which the d property specifies the
path data. The path data contains the
moveto, bearing, lineto, curveto (both cubic and
quadratic Béziers), arc and closepath
instructions.

Example triangle01
specifies a path in the shape of a triangle. (The
M indicates a moveto, the
Ls indicate linetos, and the
z indicates a closepath).

Path data can contain newline characters and thus can be
broken up into multiple lines to improve readability.
Newlines inside attributes in markup will be normalized to space
characters while parsing.

The syntax of path data is concise in order to allow for
minimal file size and efficient downloads, since many SVG files
will be dominated by their path data. Some of the ways that SVG
attempts to minimize the size of path data are as follows:

All instructions are expressed as one character (e.g., a
moveto is expressed as an M).

Superfluous white space and separators (such as commas) may
be eliminated; for instance, the following contains unnecessary
spaces: