An SVG document fragment consists of any number of SVG elements contained within an 'svg' element.
An SVG document fragment can range from an empty fragment (i.e., no content inside of the 'svg' element), to a very simple SVG document fragment containing a single SVG graphics element such as a 'rect', to a complex, deeply nested collection of container elements and graphics elements.
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 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:
<?xml version="1.0" standalone="yes"?> <parent xmlns="http://example.org" xmlns:svg="http://www.w3.org/2000/svg"> <!-- parent contents here --> <svg:svg width="4cm" height="8cm" version="1.2" baseProfile="tiny" viewBox="0 0 100 100"> <svg:title>An ellipse</svg:title> <svg:ellipse cx="50" cy="50" rx="40" ry="20" /> </svg:svg> <!-- ... --> </parent>
This example shows a slightly more complex (i.e., it contains multiple rectangles) stand-alone, self-contained SVG document:
<?xml version="1.0" standalone="no"?> <svg width="5cm" height="4cm" xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" viewBox="0 0 100 100"> <desc>Four separate rectangles </desc> <rect x="20" y="20" width="20" height="20"/> <rect x="50" y="20" width="30" height="15"/> <rect x="20" y="50" width="20" height="20"/> <rect x="50" y="50" width="20" height="40"/> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="98" height="98" fill="none" stroke="blue" stroke-width="2" /> </svg>
An SVG document fragment can only contain one single 'svg' element, this means that 'svg' elements cannot appear in the middle of SVG content.
In all cases, for compliance with the "Namespaces in XML 1.1" Recommendation [XML-NS], an SVG namespace declaration must be in scope on the 'svg' element, so that all SVG elements are identified as belonging to the SVG namespace.
For example, 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:
<svg xmlns="http://www.w3.org/2000/svg"...> <rect .../> </svg>
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:
<svg:svg xmlns:svg="http://www.w3.org/2000/svg"...> <svg:rect .../> </svg:svg>
Namespace declarations can also be specified on ancestor elements (illustrated in the above example). For more information, refer to the "Namespaces in XML" Recommendation [XML-NS].
<define name='svg'> <element name='svg'> <ref name='svg.AT'/> <zeroOrMore><ref name='svg.G.group'/></zeroOrMore> </element> </define> <define name='svg.AT' combine='interleave'> <ref name='svg.Properties.attr'/> <ref name='svg.External.attr'/> <ref name='svg.Focus.attr'/> <ref name='svg.AnimateSync.attr'/> <ref name='svg.Core.attr'/> <ref name='svg.WH.attr'/> <ref name='svg.PAR.attr'/> <optional> <attribute name='viewBox' svg:animatable='true' svg:inheritable='false'> <ref name='ViewBoxSpec.datatype'/> </attribute> </optional> <optional> <attribute name='zoomAndPan' a:defaultValue='magnify' svg:animatable='false' svg:inheritable='false'> <choice> <value>disable</value> <value>magnify</value> </choice> </attribute> </optional> <optional> <attribute name='version' a:defaultValue='1.1' svg:animatable='false' svg:inheritable='false'> <choice> <value type='string'>1.0</value> <value type='string'>1.1</value> <value type='string'>1.2</value> </choice> </attribute> </optional> <optional> <attribute name='baseProfile' a:defaultValue='none' svg:animatable='false' svg:inheritable='false'> <ref name='Text.datatype'/> </attribute> </optional> <optional> <attribute name='contentScriptType' a:defaultValue='text/ecmascript' svg:animatable='false' svg:inheritable='false'> <ref name='ContentType.datatype'/> </attribute> </optional> <optional> <attribute name='snapshotTime' svg:animatable='false' svg:inheritable='false'><text/></attribute> </optional> <optional> <attribute name='timelineBegin' a:defaultValue='onLoad' svg:animatable='false' svg:inheritable='false'> <choice> <value type='string'>onLoad</value> <value type='string'>onStart</value> </choice> </attribute> </optional> <optional> <attribute name='playbackOrder' a:defaultValue='all' svg:animatable='false' svg:inheritable='false'> <choice> <value type='string'>all</value> <value type='string'>forwardOnly</value> </choice> </attribute> </optional> </define>
Attribute definitions:
An SVG document should include a viewBox attribute on the 'svg' element of the referenced document. This describes the region of world coordinate space used by the graphic. This attribute thus provides a convenient way to design SVG documents to scale-to-fit into an arbitrary viewport.
The first example below has a fixed width and height in pixels. Content like this is often produced by illustration programs originally targetted at print. The second example is scalable, and has a viewBox rather than a width and height.
<?xml version="1.0" standalone="no"?> <svg width="300px" height="600px" xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny"> <desc>...</desc> </svg>
<?xml version="1.0" standalone="no"?> <svg width="100%" height="100%" xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" viewBox="0 0 300 600"> <desc>...</desc> </svg>
Below is an example of snapshotTime. A User Agent is displaying a number of SVG files in a directory by rendering a thumbnail image. It uses the snapshotTime as the time to render when generating the image, thus giving a more representative static view of the animation. The appearance of the thumbnail for a User Agent that honors the snapshotTime and for a User Agent that does not is shown below the example (UA with snapshot support at the left, without snapshot support at the right).
<svg version="1.2" snapShotTime="3" baseProfile="tiny" xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 400 300"> <title>Snapshot time example</title> <desc>This example shows the use of snapshot time on an animation of color </desc> <rect x="60" y="85" width="256" height="65" fill="none" stroke="rgb(60,126,220)" stroke-width="4"/> <text x="65" y="140" fill="rgb(60,126,220)" font-size="60">Hello SVG <animateColor attributeName="fill" begin="0" dur="3" from="white" to="rgb(60,126,220)"/> </text> </svg>
The 'g' element is a container element for grouping together related graphics elements.
Grouping constructs, when used in conjunction with the 'desc' and 'title' elements, provide information about document structure and semantics. Documents that are rich in structure may be rendered graphically, as speech, or as braille, and thus promote accessibility.
A group of elements, as well as individual objects, can be given a name using the id attribute. Named groups are needed for several purposes such as animation and re-usable objects.
An example:
<?xml version="1.0" standalone="no"?> <svg width="5cm" height="5cm" xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" viewBox="0 0 5 5"> <desc>Two groups, each of two rectangles </desc> <g id="group1" fill="red" > <desc>First group of two red rectangles</desc> <rect x="1" y="1" width="1" height="1" /> <rect x="3" y="1" width="1" height="1" /> </g> <g id="group2" fill="blue" > <desc>Second group of two blue rectangles</desc> <rect x="1" y="3" width="1" height="1" /> <rect x="3" y="3" width="1" height="1" /> </g> <!-- Show outline of canvas using 'rect' element --> <rect x=".01" y=".01" width="4.98" height="4.98" fill="none" stroke="blue" stroke-width=".02" /> </svg>
A 'g' element can contain other 'g' elements nested within it, to an arbitrary depth. Thus, the following is possible:
<?xml version="1.0" standalone="no"?> <svg width="5cm" height="5cm" xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny"> <desc>Groups can nest </desc> <g> <g> <g> </g> </g> </g> </svg>
Any element that is not contained within a 'g' is treated (at least conceptually) as if it were in its own group.
<define name='g'> <element name='g'> <ref name='g.AT'/> <zeroOrMore><ref name='svg.G.group'/></zeroOrMore> </element> </define> <define name='g.AT' combine='interleave'> <ref name='svg.Properties.attr'/> <ref name='svg.Core.attr'/> <ref name='svg.External.attr'/> <ref name='svg.Conditional.attr'/> <ref name='svg.Focus.attr'/> <ref name='svg.Transform.attr'/> </define>
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; they are prevented from becoming part of the rendering tree just as if the 'defs' element were a 'g' element and the 'display' property were set to none. Note, however, that the descendants of a 'defs' are always present in the source tree and can be referenced by other elements. The actual value of the 'display' property on the 'defs' element or any of its descendants does not change the rendering of these elements or prevent these elements from being referenced.
<define name='defs'> <element name='defs'> <ref name='defs.AT'/> <zeroOrMore><ref name='svg.G.group'/></zeroOrMore> </element> </define> <define name='defs.AT' combine='interleave'> <ref name='svg.Properties.attr'/> <ref name='svg.Core.attr'/> <ref name='svg.Conditional.attr'/> <ref name='svg.Transform.attr'/> </define>
To provide some SVG user agents with an opportunity to implement efficient implementations in streaming environments, creators of SVG content are encouraged to place all elements which are targets of local IRI references within a 'defs' element which is a direct child of one of the ancestors of the referencing element. For example:
<?xml version="1.0" standalone="no"?> <svg width="100%" height="100%" xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" viewBox="0 0 8 3"> <desc>Local URI references within ancestor's 'defs' element.</desc> <defs> <linearGradient id="Gradient01"> <stop offset="20%" stop-color="#39F" /> <stop offset="90%" stop-color="#F3F" /> </linearGradient> </defs> <rect x="1" y="1" width="6" height="1" fill="url(#Gradient01)" /> <!-- Show outline of canvas using 'rect' element --> <rect x=".01" y=".01" width="7.98" height="2.98" fill="none" stroke="blue" stroke-width=".02" /> </svg>
In the document above, the linear gradient is defined within a 'defs' element which is the direct child of the 'svg' element, which in turn is an ancestor of the 'rect' element which references the linear gradient. Thus, the above document conforms to the guideline.
The 'discard' element allows authors to specify the time at which particular elements may be discarded, therefore reducing the resources required by an SVG UA. This is particularly useful for the SVG viewers to handle long-running documents. This element will not be processed by static SVG viewers.
The 'discard' element can appear in the DOM tree in the same place as the 'animate' element.
<define name='discard'> <element name='discard'> <ref name='discard.AT'/> <ref name='discard.CM'/> </element> </define> <define name='discard.AT' combine='interleave'> <ref name='svg.Core.attr'/> <ref name='svg.XLinkRequired.attr'/> <ref name='svg.AnimateBegin.attr'/> </define> <define name='discard.CM'> <zeroOrMore> <ref name='svg.Desc.group'/> <ref name='svg.Handler.group'/> </zeroOrMore> </define>
Attribute definitions:
xlink:href
= "
<iri>"begin
= "
offset-value | syncbase-value | event-value | accessKey-value"removeChild
was called
on the parent of the target element.If the target element does not exist when the 'discard' element gets active, then the 'discard' element is ignored. An element gets discarded either when it is the target of a 'discard' element and the value of the 'begin' attribute of this latter is reached or when one of its ancestors is discarded. The 'discard' element itself can be discarded. It is discarded at the earliest: soon after its target element has been discarded or because it is the target of an other 'discard' element.
When the 'discard' element is used, the end user may see unexpected results when seeking backward because the seek will not re-insert the discarded elements. So, authors are encouraged to set the 'playbackOrder' attribute to true when using the 'discard' element.
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" width="352" height="240" sequentialContent="true"> <ellipse cx="98.5" cy="17.5" rx="20.5" ry="17.5" fill="blue" stroke="black" transform="translate(9 252) translate(3 -296)"> <animateTransform attributeName="transform" begin="0s" dur="2s" fill="remove" calcMode="linear" type="translate" additive="sum" from="0 0" to="-18 305"/> <discard begin="2s"/> </ellipse> <rect x="182" y="-39" width="39" height="30" transform="translate(30 301)" fill="red" stroke="black"> <animateTransform attributeName="transform" begin="1s" dur="2s" fill="remove" calcMode="linear" type="translate" additive="sum" from="0 0" to="-26 -304"/> <discard begin="3s"/> </rect> <polygon points="-66,83.5814 -43,123.419 -89,123.419" fill="green" stroke="black" transform="matrix(1 0 0 1.1798 0 -18.6096)"> <animateTransform attributeName="transform" begin="2s" dur="2s" fill="remove" calcMode="linear" type="translate" additive="sum" from="0 0" to="460 63.5699"/> <discard begin="4s"/> </polygon> </svg>
Each container element or graphics element in an SVG drawing can supply a 'desc' and/or a 'title' description string where the description is text-only. When the current SVG document fragment is rendered as SVG on visual media, 'desc' and 'title' elements are not rendered as part of the graphics. User agents may, however, for example, display the 'title' element as a tooltip, as the pointing device moves over particular elements. Alternate presentations are possible, both visual and aural, which display the 'desc' and 'title' elements but do not display 'path' elements or other graphics elements. For deep hierarchies, and for following 'use' element references, it is sometimes desirable to allow the user to control how deep they drill down into descriptive text.
<define name='desc'> <element name='desc'> <ref name='DTM.AT'/> <ref name='DTM.CM'/> </element> </define> <define name='DTM.AT' combine='interleave'> <ref name='svg.Core.attr'/> </define> <define name='DTM.CM'> <text/> </define>
<define name='desc'> <element name='desc'> <ref name='DTM.AT'/> <ref name='DTM.CM'/> </element> </define>
The following is an example. In typical operation, the SVG user agent would not render the 'desc' and 'title' elements but would render the remaining contents of the 'g' element.
<?xml version="1.0" standalone="no"?> <svg width="100%" height="100%" xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny"> <g> <title> Company sales by region </title> <desc> This is a bar chart which shows company sales by region. </desc> <!-- Bar chart defined as vector data --> </g> </svg>
Description and title elements can contain marked-up text from other namespaces. Here is an example:
<?xml version="1.0" standalone="yes"?> <svg width="100%" height="100%" xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny"> <desc xmlns:mydoc="http://example.org/mydoc"> <mydoc:title>This is an example SVG file</mydoc:title> <mydoc:para>The global description uses markup from the <mydoc:emph>mydoc</mydoc:emph> namespace.</mydoc:para> </desc> <g> <!-- the picture goes here --> </g> </svg>
Authors should always provide a 'title' child element to the 'svg' element within a stand-alone SVG document. The 'title' child element to an 'svg' element serves the purposes of identifying the content of the given SVG document fragment. Since users often consult documents out of context, authors should provide context-rich titles. Thus, instead of a title such as "Introduction", which doesnt 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 'svg' element available to users. The mechanism for doing so depends on the user agent (e.g., as a caption, spoken).
It is strongly recommended that at most one 'desc' and at most one 'title' element appear as a child of any particular element, and that these elements appear before any other child elements (except possibly 'metadata' elements) or character data content. If user agents need to choose among multiple 'desc' or 'title' elements for processing (e.g., to decide which string to use for a tooltip), the user agent shall choose the first one.
Any 'g' or graphics element is potentially a template object that can be re-used (i.e. "instanced") in the SVG document via a 'use' element. The 'use' element references another element and indicates that the graphical contents of that element is included/drawn at that given point in the document.
Unlike 'animation', the 'use' element cannot reference entire files.
Besides what is described about the 'use' element in this section important restrictions for 'use' can be found in the Reference Section.
The 'use' element has optional attributes x and y which are used to place the graphical contents of the referenced element into the current coordinate system.
The effect of a 'use' element is as if the contents of the referenced element were deeply cloned into a separate non-exposed DOM tree which had the 'use' element as its parent and all of the 'use' element's ancestors as its higher-level ancestors. Because the cloned DOM tree is non-exposed, the SVG Document Object Model (DOM) only contains the 'use' element and its attributes. The SVG DOM does not show the referenced element's contents as children of 'use' element.
Property inheritance works as if the referenced element had been textually included as a deeply cloned child of the 'use' element. The referenced element inherits properties from the 'use' element and the 'use' element's ancestors. An instance of a referenced element does not inherit properties from the referenced element's original parents.
If event attributes are assigned to referenced elements, then the actual target for the event will be the SVGElementInstance object within the "instance tree" corresponding to the given referenced element.
The event handling for the non-exposed tree works as if the referenced element had been textually included as a deeply cloned child of the 'use' element, except that events are dispatched to the SVGElementInstance objects. The event's target and currentTarget attributes are set to the SVGElementInstance that corresponds to the target and current target elements in the referenced subtree. An event propagates through the exposed and non-exposed portions of the tree in the same manner as it would in the regular document tree: first going to the target of the event, then bubbling back through non-exposed tree to the use element and then back through regular tree to the root element in the bubbling phase.
An element and all its corresponding SVGElementInstance objects share an event listener list. The currentTarget attribute of the event can be used to determine through which object an event listener was invoked.
The behavior of the 'visibility' property conforms to this model of property inheritance. Thus, specifying visibility='hidden' on a 'use' element does not guarantee that the referenced content will not be rendered. If the 'use' element specifies visibility='hidden' and the element it references specifies visibility='hidden' or visibility='inherit', then that one element will be hidden. However, if the referenced element instead specifies visibility='visible', then that element will be visible even if the 'use' element specifies visibility='hidden'.
Animations on a referenced element will cause the instances to also be animated.
As listed in the Reference Section the 'use' element is not allowed to reference an 'svg' element
A 'use' element has the same visual effect as if the 'use' element were replaced by the following generated content:
Example Use01 below has a simple 'use' on a 'rect'.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.2" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" baseProfile="tiny"> <desc>Example Use01 - Simple case of 'use' on a 'rect'</desc> <defs> <rect id="MyRect" width="60" height="10"/> </defs> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <use x="20" y="10" xlink:href="#MyRect" /> </svg>
The visual effect would be equivalent to the following document:
<?xml version="1.0" standalone="no"?> <svg width="100%" height="100%" viewBox="0 0 100 30" version="1.2" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" baseProfile="tiny"> <desc>Example Use01-GeneratedContent - Simple case of 'use' on a 'rect'</desc> <!-- 'defs' section left out --> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <!-- Start of generated content. Replaces 'use' --> <g transform="translate(20,10)"> <rect width="60" height="10"/> </g> <!-- End of generated content --> </svg>
Example Use03 illustrates what happens when a 'use' has a transform attribute.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.2" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" baseProfile="tiny"> <desc>Example Use03 - 'use' with a 'transform' attribute</desc> <defs> <rect id="MyRect" x="0" y="0" width="60" height="10"/> </defs> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <use xlink:href="#MyRect" transform="translate(20,2.5) rotate(10)" /> </svg>
The visual effect would be equivalent to the following document:
<?xml version="1.0" standalone="no"?> <?xml version="1.0" standalone="no"?> <svg width="100%" height="100%" viewBox="0 0 100 30" version="1.2" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" baseProfile="tiny"> <desc>Example Use03-GeneratedContent - 'use' with a 'transform' attribute</desc> <!-- 'defs' section left out --> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <!-- Start of generated content. Replaces 'use' --> <g transform="translate(20,2.5) rotate(10)"> <rect x="0" y="0" width="60" height="10"/> </g> <!-- End of generated content --> </svg>
When a 'use' references another element which is another 'use' or whose content contains a 'use' element, then the deep 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 error, as described in the References section.
<define name='use'> <element name='use'> <ref name='use.AT'/> <ref name='use.CM'/> </element> </define> <define name='use.AT' combine='interleave'> <ref name='svg.Properties.attr'/> <ref name='svg.Core.attr'/> <ref name='svg.Conditional.attr'/> <ref name='svg.Transform.attr'/> <ref name='svg.XLinkEmbed.attr'/> <ref name='svg.Focus.attr'/> <ref name='svg.External.attr'/> <ref name='svg.XY.attr'/> <ref name='svg.Overflow.attr'/> </define> <define name='use.CM'> <zeroOrMore> <choice> <ref name='svg.Desc.group'/> <ref name='svg.Animate.group'/> <ref name='svg.Handler.group'/> </choice> </zeroOrMore> </define>
Attribute definitions:
The 'image' element indicates that the contents of a complete file are to be rendered into a given rectangle within the current user coordinate system. In SVG Tiny 1.2, the 'image' must reference content that is a raster image format, such as PNG and JPG. SVG Tiny 1.2 does not allow SVG images to be referenced by the 'image' element; Instead, authors should use the 'animation' element. Conforming SVG viewers need to support at least PNG and JPEG format files.
The result of processing an 'image' is always a four-channel RGBA result. When an 'image' element references a raster image file such as PNG or JPEG files which only has three channels (RGB), then the effect is as if the object were converted into a 4-channel RGBA image with the alpha channel uniformly set to 1. For a single-channel raster image, the effect is as if the object were converted into a 4-channel RGBA image, where the single channel from the referenced object is used to compute the three color channels and the alpha channel is uniformly set to 1.
The 'image' element supports the 'opacity' property for controlling the image opacity.
An 'image' element establishes a new viewport for the referenced file as described in Establishing a new viewport. The bounds for the new viewport are defined by attributes x, y, width and height. The placement and scaling of the referenced image are controlled by the preserveAspectRatio attribute on the 'image' element.
The value of the 'viewBox' attribute to use when evaluating the preserveAspectRatio attribute is defined by the referenced content. For content that clearly identifies a viewBox that value should be used. For most raster content (PNG, JPEG) the bounds of the image should be used (i.e. the 'image' element has an implicit 'viewBox' of "0 0 raster-image-width raster-image-height"). Where no value is readily available the preserveAspectRatio attribute is ignored, and only the translate due to the 'x' & 'y' attributes of the viewport is used to display the content.
For example, if the image element referenced a PNG or JPEG
and preserveAspectRatio="xMinYMin
meet", then the aspect ratio of the raster would be
preserved (which means that the scale factor from image's
coordinates to current user space coordinates would be the same
for both X and Y), the raster would be sized as large as
possible while ensuring that the entire raster fits within the
viewport, and the top/left of the raster would be aligned with
the top/left of the viewport as defined by the attributes 'x', 'y', 'width' and 'height' on the 'image' element. If the value
of preserveAspectRatio was 'none'
then aspect ratio of the image would not be preserved. The
image would be fitted such that the top/left corner of the
raster exactly aligns with coordinate (x, y) and the bottom/right corner of
the raster exactly aligns with coordinate (x+width,y+height).
The resource referenced by the 'image' element represents a separate document which generates its own parse tree and document object model (if the resource is XML). Thus, there is no inheritance of properties into the image.
The SVG specification does not specify when an image that is not being displayed should be loaded. A user agent is not required to load image data for an image that is not displayed (e.g. is is outside the initial document viewport). However, it should be noted that this may cause a delay when an image becomes visible for the first time. In the case where an author wants to suggest that the user agent load image data before it is displayed, they should use the 'prefetch' element.
<define name='image'> <element name='image'> <ref name='image.AT'/> <ref name='image.CM'/> </element> </define> <define name='image.AT' combine='interleave'> <ref name='svg.Core.attr'/> <ref name='svg.XLinkEmbed.attr'/> <ref name='svg.Conditional.attr'/> <ref name='svg.External.attr'/> <ref name='svg.Focus.attr'/> <ref name='svg.Transform.attr'/> <ref name='svg.Opacity.attr'/> <ref name='svg.XYWH.attr'/> <ref name='svg.PAR.attr'/> <ref name='svg.ContentType.attr'/> </define> <define name='image.CM'> <zeroOrMore> <choice> <ref name='svg.Desc.group'/> <ref name='svg.Animate.group'/> <ref name='svg.Handler.group'/> <ref name='svg.Discard.group'/> </choice> </zeroOrMore> </define>
Attribute definitions:
An example:
<?xml version="1.0" standalone="no"?> <svg width="100%" height="100%" version="1.2" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" baseProfile="tiny"> <desc>This graphic links to an external image </desc> <image x="200" y="200" width="100px" height="100px" xlink:href="myimage.png"> <title>My image</title> </image> </svg>
SVG contains a 'switch' element along with attributes requiredFeatures, requiredExtensions, systemLanguage, requiredFormats and requiredFonts to provide an ability to specify alternate viewing depending on the capabilities of a given user agent or the user's language.
<define name='svg.Conditional.attr' combine='interleave'> <optional> <attribute name='requiredFeatures' svg:animatable='false' svg:inheritable='false'> <ref name='FeatureList.datatype'/> </attribute> </optional> <optional> <attribute name='requiredExtensions' svg:animatable='false' svg:inheritable='false'> <ref name='ExtensionList.datatype'/> </attribute> </optional> <optional> <attribute name='requiredFormats' svg:animatable='false' svg:inheritable='false'> <ref name='FormatList.datatype'/> </attribute> </optional> <optional> <attribute name='requiredFonts' svg:animatable='false' svg:inheritable='false'> <ref name='FontList.datatype'/> </attribute> </optional> <optional> <attribute name='systemLanguage' svg:animatable='false' svg:inheritable='false'> <ref name='LanguageCodes.datatype'/> </attribute> </optional> </define>
Attributes requiredFeatures, requiredExtensions, systemLanguage, requiredFormats and requiredFonts act as tests and return either true or false results. 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.
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').
In consequence:
The 'switch' element evaluates the requiredFeatures, requiredExtensions, systemLanguage, requiredFormats and requiredFonts 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.
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.
<element name='switch'> <ref name='switch.AT'/> <!-- the content model for switch is defined as part of the element that can contain it --> </element> <define name='switch.AT' combine='interleave'> <ref name='svg.Core.attr'/> <ref name='svg.Conditional.attr'/> <ref name='svg.Properties.attr'/> <ref name='svg.External.attr'/> <ref name='svg.Transform.attr'/> </define>
For more information and an example, see Embedding foreign object types.
Definition of requiredFeatures:
If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute requiredFeatures, the attribute returns "false".
requiredFeatures is often used in conjunction with the 'switch' element. If the requiredFeatures is used in other situations, then it represents a simple switch on the given element whether to render the element or not.
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 a IRI reference.
Definition of requiredExtensions:
If a given IRI reference contains white space within itself, that white space must be escaped.
If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute requiredExtensions, the attribute returns "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 IRI 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.
The attribute value is a comma-separated list of language names as defined in [RFC3066].
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.
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.
For the systemLanguage attribute: Animatable: no.
If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute systemLanguage, the attribute returns "false".
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.
Many resources, especially media such as audio and video, have a wide range of formats. As it is often not possible to require support for a particular format, due to legal or platform restrictions, it is often necessary to provide alternatives so that user agents can choose the format they support.
The requiredFormats attribute is a generic conditional processing attribute that can be used to enable or disable particular branches in the SVG document. It defines a list of resource formats. Each format is defined by the format definition with the syntax varied according to the specific type of resource. The User Agent must support all of the resource types for the attribute to evaluate to true.
Definition of requiredFormats:
Each format definition is separated by whitespace. A format definition can be a MIME-type beginning "image/", "video/" or "audio/", or must use one of the following formats:
For a list of MIME types for audio/video codecs, see the IANA registry and RFC2361.
Given that several important file formats are still not registered or not specific enough, the following format definitions are also understood:
The following requiredFormats must always evaluate to true in compliant SVG viewers:
If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute requiredFormats, the attribute returns "false". Format definitions that are not understood by the user agent return "false".
requiredFormats is often used in conjunction with the 'switch' element. If the requiredFormats is used in other situations, then it represents a simple switch on the given element whether to render the element or not.
If the author wishes to have complete control over the appearance and location of text in the document then they must ensure that the correct font is used when rendering the text. This can be achieved by using SVG Fonts and embedding the font in the document. However, this is not practical in all cases, especially when the number of glyphs used is very large or if the licensing of the font forbids such embedding.
Definition of requiredFonts:
If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute requiredFonts, the attribute returns "false".
requiredFonts is often used in conjunction with the 'switch' element. If the requiredFonts is used in other situations, then it represents a simple switch on the given element whether to render the element or not.
Documents often reference and use the contents of other files (and other Web resources) as part of their rendering. In some cases, authors want to specify that particular resources are required for a document to be considered correct.
Attribute externalResourcesRequired is available on all container elements and to all elements which potentially can reference external resources. It specifies whether referenced resources that are not part of the current document are required for proper rendering of the given container element or graphics element.
Attribute definition:
Attribute externalResourcesRequired is not inheritable (from a sense of attribute value inheritance), but if set on a container element, its value will apply to all elements within the container.
Because setting externalResourcesRequired="true" on a container element can have the effect of disabling progressive display of the contents of that container, tools that generate SVG content are cautioned against using simply setting externalResourcesRequired="true" on the 'svg' element on a universal basis. Instead, it is better to specify externalResourcesRequired="true" on those particular graphics elements or container elements which specifically need the availability of external resources in order to render properly.
For externalResourcesRequired: Animatable: no.
When progressively downloading a document, a user agent conceptually builds a tree of nodes in various states. The possible states for these nodes are unresolved, resolved and error. This description of progressive rendering uses SAX events. However, user implementations are not required to implement SAX, any implementation producing the same result would be compliant.
The two SAX events referred to in the following prose are the startElement and endElement events. The startElement event is generally considered to be triggered when the Start-Tag or an Empty-Element Tag is read. The endElement event occurs either immediately preceding the statElement event in the case of an Empty-Element Tag or when the End-Tag is read.
When loading a document following the startElement event on a node, that node becomes part of the document tree in the unresolved state. If the node's dependencies are successfully resolved, then the node enters the resolved state or if the node's dependencies are found to be in error, then the node enters the error state.
Node dependencies include both children content (like the child elements on a g) and resources (e.g. images referenced by an image) referenced from that node or from its children. Children become resolved when the endElement event occurs on an element. Resources become resolved (or found in error) by a user agent specific mechanism.
A user agent implementing progressive rendering must render the current document tree with the following rules:
Fonts are an exception to the above rules: startElement and endElement events on font element children ( font-face, hkern, missing-glyph, glyph ) do not cause an update of the document rendering. However, the endElement event on the font element does cause a document rendering as for other node types.
Example
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2" baseProfile="tiny" id="svg-root" width="100%" height="100%" viewBox="0 0 480 360"> <desc>externalResourcesRequired example.</desc> <g externalResourcesRequired="true"> <rect id="rect_1" .... /> ... <rect id="rect_1000" ..../> <image xlink:href="myImage.png" externalResourcesRequired="true" ... /> <rect id="rect_1001" ..../> </g> </svg>
In this example, the g element rendering will start when the g closing tag has been parsed and processed and when all the resources needed by its children have been resolved. This means that the group's rendering will start when the group has been fully parsed and myImage.png has been successfully retrieved.
Forward reference of use element
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2" baseProfile="tiny" id="svg-root" width="100%" height="100%" viewBox="0 0 480 360"> <desc>Forward reference of use element</desc> <use xlink:href="#myRect" x="200" fill="green"/> <circle cx="450" cy="50" r="50" fill="yellow" /> <g fill="red"> <rect id="myRect" width="100" height="100" /> </g> </svg>
In this example, the various renderings will be (the rendering state follows the semi-colon):
Forward reference on use with externalResourcesRequired="true"
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2" baseProfile="tiny" id="svg-root" width="100%" height="100%" viewBox="0 0 480 360"> <desc>Forward reference on use with eRR=true</desc> <use xlink:href="#myGroup" x="200" fill="green" externalResourcesRequired="true"/> <circle cx="450" cy="50" r="50" fill="yellow" /> <g fill="red"> <g id="myGroup"> <rect id="myRect" width="100" height="100" /> <use xlink:href="#myRect" x="50" fill="purple"/> </g> </g> </svg>
Forward reference with use to an element under a container with externalResourcesRequired="true"
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2" baseProfile="tiny" id="svg-root" width="100%" height="100%" viewBox="0 0 480 360"> <desc>Forward Reference to a use under a container with eRR=true</desc> <use xlink:href="#myRect" x="200" fill="green"/> <circle cx="250" cy="50" r="50" fill="pink" /> <g fill="red" externalResourcesRequired="true"> <circle cx="450" cy="50" r="50" fill="yellow" /> <rect id="myRect" width="100" height="100" /> </g> </svg>
Font Resolution Example
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2" baseProfile="tiny" id="svg-root" width="100%" height="100%" viewBox="0 0 480 360"> <desc>Font Resolution Example</desc> <text x="240" y="230" text-anchor="middle" font-size="120" font-family="fontC, fontB, fontA">A</text> <defs> <font id="fontA" horiz-adv-x="224" > <font-face font-family="fontA" units-per-em="1000" panose-1="0 0 0 0 0 0 0 0 0 0" ascent="917" descent="-250" alphabetic="0" /> <missing-glyph horiz-adv-x="800" d="..." /> <glyph unicode="A" glyph-name="A" ... /> </font> <font id="fontB" horiz-adv-x="224"> <font-face font-family="fontB" units-per-em="1000" panose-1="0 0 0 0 0 0 0 0 0 0" ascent="917" descent="-250" alphabetic="0" /> <missing-glyph ... /> <glyph unicode="A" glyph-name="B" ... /> </font> <font id="fontC" horiz-adv-x="224" > <font-face font-family="fontC" units-per-em="1000" panose-1="0 0 0 0 0 0 0 0 0 0" ascent="917" descent="-250" alphabetic="0" /> <missing-glyph ... /> <glyph unicode="A" glyph-name="C" ... /> </font> </defs> </svg>
Progressive rendering:
In SVG 1.1 it is not clear when an user agent should begin downloading references media, particularly when the media is not used in the initial document state (e.g. it is offscreen or hidden). SVG 1.2 does not require user agents to download referenced media that is not visual at the time the document is loaded. This means there may be a pause to download the file the first time a piece of media is displayed. More advanced user agents may wish to predict that particular media streams will be needed and therefore download them in anticipation.
SVG 1.2 also adds functionality (adapted from Section 4.4 of SMIL 2.0 - The PrefetchControl Module) to allow content developers to suggest fetching content from the server before it is needed to improve the rendering performance of the document.
The prefetch element will give a suggestion or hint to a user agent that media will be used in the future and the author would like part or all of it fetched ahead of time to make the document playback smoother. User-agents can ignore prefetch elements, though doing so may cause an interruption in the document playback when the resource is needed. It gives authoring tools and authors the ability to schedule retrieval of resources when they think that there is available bandwidth or time to do it.
When instead of referring to external media, prefetch refers to the same document it occurs in, then it can only reference a top level 'g' element. To enable smooth playback during progressive downloading in this scenario, it is recommended that each adjacent top level 'g' element contain adjacent chronological scenes in the animation. In this case the prefetch element must appear in a defs block before all defined 'g' elements in the document. In such cases, 'prefetch' is used to tell the user agent how much it needs to buffer in order to be able to play content back in a smooth and predictable manner.
None of the attributes on the prefetch element are animatable or inherited.
<define name='prefetch'> <element name='prefetch'> <ref name='prefetch.AT'/> <ref name='prefetch.CM'/> </element> </define> <define name='prefetch.AT' combine='interleave'> <ref name='svg.Core.attr'/> <ref name='svg.XLinkRequired.attr'/> <optional> <attribute name='mediaSize' svg:animatable='false' svg:inheritable='false'> <ref name='NumberOrPercentage.datatype'/> </attribute> </optional> <optional> <attribute name='mediaTime' svg:animatable='false' svg:inheritable='false'><text/></attribute> </optional> <optional> <attribute name='mediaCharacterEncoding' svg:animatable='false' svg:inheritable='false'><text/></attribute> </optional> <optional> <attribute name='mediaContentEncodings' svg:animatable='false' svg:inheritable='false'><text/></attribute> </optional> <optional> <attribute name='bandwidth' svg:animatable='false' svg:inheritable='false'> <ref name='NumberOrPercentage.datatype'/> </attribute> </optional> </define> <define name='prefetch.CM'> <zeroOrMore> <ref name='svg.Desc.group'/> </zeroOrMore> </define>
Attribute definitions:
When prefetch refers to external media, if both mediaSize and mediaTime are specified, then mediaSize is used and mediaTime is ignored.
When prefetch refers to a resource in the same document (e.g. a 'g' element), both the mediaSize and mediaTime attributes can be used together by a more advanced user agent to determine how much it needs to buffer in order to be able to play content back in a smooth manner.
Below is an example of the prefetch element when it refers to external media:
<svg width="400" height="300" version="1.2" xmlns="http://www.w3.org/2000/svg" baseProfile="tiny" xmlns:xlink="http://www.w3.org/1999/xlink"> <desc> Prefetch the large images before starting the animation if possible. </desc> <defs> <prefetch id="pf1" xlink:href="http://www.example.com/images/huge1.png"/> <prefetch id="pf2" xlink:href="http://www.example.com/images/huge2.png"/> <prefetch id="pf3" xlink:href="http://www.example.com/images/huge3.png"/> </defs> <image x="0" y="0" width="400" height="300" xlink:href="http://www.example.com/images/huge1.png" display="none"> <set attributeName="display" to="inline" begin="10s"/> <animate attributeName="xlink:href" values=" http://www.example.com/images/huge1.png; http://www.example.com/images/huge2.png; http://www.example.com/images/huge3.png" begin="15s" dur="30s"/> </image> </svg>
Below is an example of the prefetch element when it refers to a resource (e.g. a 'g' element in the same document):
<?xml version="1.0" encoding="utf-8"?> <svg width="400" height="300" version="1.2" xmlns="http://www.w3.org/2000/svg" baseProfile="tiny" xmlns:xlink="http://www.w3.org/1999/xlink" timelineBegin="onStart" playbackOrder="forwardOnly"> <desc> Example of using SVGT 1.2 features for smooth playback during progressive downloading. </desc> <defs> <prefetch id="pf1" xlink:href="#scene1" mediaCharacterEncoding="UTF-16" mediaTime="5s" mediaSize="48" mediaEncodings="UTF-8"/> <prefetch id="pf2" xlink:href="#scene2" mediaCharacterEncoding="UTF-16" mediaTime="10s" mediaSize="1234" mediaEncodings="UTF-8"/> <prefetch id="pf3" xlink:href="#scene3" mediaCharacterEncoding="UTF-16" mediaTime="5s" mediaSize="62" mediaEncodings="UTF-8"/> </defs> <g id="scene1"> <discard at="6s"/> <!-- graphics for scene 1 go here --> </g> <g id="scene2"> <discard at="16s"/> <!-- graphics for scene 2 go here --> </g> <g id="scene3"> <discard at="21s"/> <!-- graphics for scene 3 go here --> </g> </svg>
The class, id, xml:id and xml:base attributes are available on all SVG elements:
Attribute definitions:
Elements that might contain character data content have attributes xml:lang and xml:space:
<attribute name='xml:space' svg:animatable='false' svg:inheritable='false'> <choice> <value>default</value> <value>preserve</value> </choice> </attribute> <attribute name='xml:lang' svg:animatable='false' svg:inheritable='false'> <choice> <ref name='LanguageCode.datatype'/> <empty/> </choice> </attribute>
Attribute definitions:
The Core Attribute Module contains the following attributes:
The Structure Module contains the following elements:
The Conditional Processing Module contains the following element:
The Conditional Processing Attribute Module contains the following attributes:
The Image Module contains the following element:
The Prefetch Module contains the following element:
The ExternalResourcesRequired Attribute Module contains the following attributes: