Embedded Content — SVG 2
Chapter 12: Embedded Content
12.1. Overview
Embedded content is content that imports another resource into the document, or content from another vocabulary that is inserted into the document.
This is the same definition as
HTML's
embedded content
SVG supports embedded content with the use of
image
and
foreignObject
elements.
Content embedded with
image
is compatible with
Resource Hints
for prioritizing downloading of external resources.
12.2. Placement of the embedded content
The
width
, and
height
geometry properties specify the rectangular region into which the embedded content is positioned
(the
positioning rectangle
).
The
positioning rectangle
is used as the bounding box of the element;
note, however, that graphics may overflow the positioning rectangle,
depending on the value of the
overflow
property.
When the embedded content consists of a single referenced resource
(e.g., an
image
),
the dimensions of the
positioning rectangle
in the current coordinate system after applying all transforms,
define the
specified size
for the embedded object.
concrete object size
and final position must be determined for the object using the
Default Sizing Algorithm
defined for replaced elements in CSS layout [
css-images-3
].
The
object-fit
and
object-position
affect the final
position and size of the object,
and may cause it to be extend beyond the
positioning rectangle
In that case, the
overflow
property determines whether
the rendered object should be clipped to its
positioning rectangle
When the embedded content consists of a document fragment
(e.g., a
foreignObject
),
the
positioning rectangle
defines the bounds of a
containing block
for laying out the child content using CSS.
The scale of the containing block is defined in the current coordinate system,
including all explicit and implicit (e.g.,
viewBox
) transformations.
The
foreignObject
, or other element that is positioned using SVG layout attributes,
is implicitly
absolutely-positioned
for the purposes of CSS layout.
As a result, any absolutely-positioned child elements
are positioned relative to this containing block.
Again, the
overflow
property determines
whether content that extends outside the
positioning rectangle
will be hidden.
A value of zero for either
width
or
height
disables rendering of the element and its embedded content.
The
'auto'
value for
width
or
height
is used to size the corresponding element automatically based on the
intrinsic dimensions
or
intrinsic aspect ratio
of the referenced resource.
Computation of automatically-sized values follows the
Default Sizing Algorithm
defined for replaced elements in CSS layout [
css-images-3
].
In particular, when the referenced resource does not have an intrinsic size
(such as image types with no defined dimensions),
it is assumed to have a width of 300px and a height of 150px.
CSS positioning properties (e.g.
top
and
margin
) have no effect when positioning the embedded content element in the SVG coordinate system.
They can, however, be used to position child elements of a
foreignObject
or HTML embedding element.
12.3. The
‘image’
element
image
Categories:
Graphics element
graphics referencing element
renderable element
structurally external element
Content model:
Any number of the following elements, in any order:
animation elements
animate
animateMotion
animateTransform
set
descriptive elements
desc
title
metadata
clipPath
mask
script
style
Attributes:
aria attributes
aria-activedescendant
aria-atomic
aria-autocomplete
aria-busy
aria-checked
aria-colcount
aria-colindex
aria-colspan
aria-controls
aria-current
aria-describedby
aria-details
aria-disabled
aria-dropeffect
aria-errormessage
aria-expanded
aria-flowto
aria-grabbed
aria-haspopup
aria-hidden
aria-invalid
aria-keyshortcuts
aria-label
aria-labelledby
aria-level
aria-live
aria-modal
aria-multiline
aria-multiselectable
aria-orientation
aria-owns
aria-placeholder
aria-posinset
aria-pressed
aria-readonly
aria-relevant
aria-required
aria-roledescription
aria-rowcount
aria-rowindex
aria-rowspan
aria-selected
aria-setsize
aria-sort
aria-valuemax
aria-valuemin
aria-valuenow
aria-valuetext
role
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
conditional processing attributes
requiredExtensions
systemLanguage
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
deprecated xlink attributes
xlink:href
xlink:title
presentation attributes
preserveAspectRatio
href
crossorigin
Geometry properties:
width
height
DOM Interfaces:
SVGImageElement
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. The
image
element can refer to raster
image files such as PNG or JPEG or to files with MIME type of
"image/svg+xml".
Conforming SVG
viewers
need to support at least PNG, JPEG and SVG format
files.
SVG files must be processed in
secure animated mode
if the current document supports animation,
or in
secure static mode
if the current document is static.
The result of processing an
image
is always a four-channel
RGBA result. When an
image
element references an image (such as many 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 (grayscale)
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
preserveAspectRatio
attribute
determines how the referenced image is scaled and positioned to fit
into the
concrete object size
determined from the
positioning rectangle
and the
object-fit
and
object-position
properties.
The result of applying this attribute defines an
image-rendering rectangle
used for actual image rendering.
When the referenced image is an SVG,
the
image-rendering rectangle
defines
the
SVG viewport
used for rendering that SVG.
The
preserveAspectRatio
calculations
are applied
after
determining the
concrete object size
and only have an effect if that size does not match the
intrinsic aspect ratio
of the embedded image.
If a value of
object-fit
is used that
ensures that the concrete object size matches the intrinsic aspect ratio
(i.e., any value other than the default
fill
),
then the
preserveAspectRatio
value will have no effect;
the
image-rendering rectangle
will be that determined
when scaling and positioning the object with CSS.
The
preserveAspectRatio
attribute can therefore be safely used
as a fallback for most values of
object-fit
and
object-position
it must be explicitly set to
none
to turn off aspect ratio control, regardless of
object-fit
value.
The aspect ratio to use when
evaluating the
preserveAspectRatio
attribute is
defined by the
intrinsic aspect ratio
of the referenced content.
For an SVG file, the aspect ratio is defined
in
Intrinsic sizing properties of SVG content"
For most raster content (PNG, JPEG) the pixel width and height of the image file
define an intrinsic aspect ratio.
Where the embedded image does not have an
intrinsic aspect ratio
(e.g. an SVG file with neither
viewBox
attribute nor explicit dimensions for the
outermost svg element
) the
preserveAspectRatio
attribute is
ignored;
the embedded image is drawn to fill the
positioning rectangle
defined by the geometry properties
on the
image
element.
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
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 fit such that the top/left corner of the
raster exactly aligns with coordinate (
) and the bottom/right corner of
the raster exactly aligns with coordinate (
width
height
).
For
image
elements embedding an SVG image,
the
preserveAspectRatio
attribute on the root
element in the referenced SVG image must be ignored,
and instead treated as if it had a value of
none
(see
preserveAspectRatio
for details).
This ensures that the
preserveAspectRatio
attribute on
the referencing
image
has its intended effect,
even if it is
none
When the value of the
preserveAspectRatio
attribute on the
image
is
not
none
the
image-rendering rectangle
determined
from the properties of the
image
element
will exactly match the embedded SVG's intrinsic aspect ratio.
Ignoring the
preserveAspectRatio
attribute from the embedded SVG
will therefore not usually have any effect.
The exception is if the aspect ratio of that image
is determined from absolute values for the
width
and
height
attributes
which
do not
match its
viewBox
aspect ratio.
This is an unusual situation that authors are advised to avoid, for many reasons.
The user agent stylesheet sets the value of the
overflow
property
on
image
element to
hidden
Unless over-ridden by the author, images will therefore be clipped to
the
positioning rectangle
defined by the geometry properties.
For
image
elements embedding an SVG image,
two different
overflow
values apply.
The value specified on the
image
element determines
whether the
image-rendering rectangle
is clipped to the
positioning rectangle
The value on the root element of the referenced SVG
determines whether the graphics are clipped to the
image-rendering rectangle
New in SVG 2.
Previous versions of SVG required that the
overflow
(and also
clip
property on the embedded SVG be ignored.
The new rules ensure that an overflowing
slice
layout
can be safely used without compromising the overflow control from the referenced image.
To link into particular view of an embedded SVG image,
authors can use media fragments as defined in
Linking into SVG content
To crop to a specific section of a raster image,
authors can use
Basic media fragments identifiers
Media Fragments URI 1.0 (basic)
].
Either type of fragment may affect the
intrinsic dimensions
and/or
intrinsic aspect ratio
of the image.
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.
Unlike
use
, the
image
element cannot reference
elements within an SVG file.
SVG 2 Requirement:
Support auto-sized images.
Resolution:
We will allow auto-sized images in SVG 2.
Purpose:
To allow raster images to use their own size without the need to set width and height.
Owner:
Cameron (
ACTION-3340
SVG 2 Requirement:
Support selecting part of an
image
for display.
Resolution:
We will have a method for
‘image’
to select a part of an image to display, maybe by allowing
‘viewBox’
on it.
Purpose:
To allow selection of part of an image without requiring the author to manually slice the image.
Owner:
Nobody
SVG 2 Requirement:
Support the ‘
object-fit
’ and ‘
object-position
’ properties from css-images-3.
Resolution:
SVG 2 will depend on CSS3 Image Values and CSS4 Image Values.
Purpose:
To align with the CSS way of specifying image fitting that
preserveAspectRatio
provides.
Owner:
Cameron or Erik (no action)
Attribute definitions:
Name
Value
Initial value
Animatable
crossorigin
[ anonymous | use-credentials ]?
(see HTML definition of attribute)
yes
The crossorigin attribute is a
CORS settings attribute
, and unless otherwise specified follows the same processing rules as in HTML [
HTML
].
Name
Value
Initial value
Animatable
href
URL
[URL]
(none)
yes
An
URL reference
identifying the image to render.
Refer to the common handling defined for
URL reference attributes
and
deprecated XLink attributes
The URL is processed and the resource is fetched
as described in the Linking chapter
Since image references always refer to a complete document,
a target-only URL is treated as a link to the same file,
which is rendered again as an independent embedded image.
Since the embedded image is processed in a secure mode,
its own embedded references are not processed,
preventing infinite recursion.
Example recursive-image
View this example as SVG (SVG-enabled browsers only)
12.4. The
‘foreignObject’
element
foreignObject
Categories:
Graphics element
renderable element
structurally external element
Content model:
Any elements or character data.
Attributes:
aria attributes
aria-activedescendant
aria-atomic
aria-autocomplete
aria-busy
aria-checked
aria-colcount
aria-colindex
aria-colspan
aria-controls
aria-current
aria-describedby
aria-details
aria-disabled
aria-dropeffect
aria-errormessage
aria-expanded
aria-flowto
aria-grabbed
aria-haspopup
aria-hidden
aria-invalid
aria-keyshortcuts
aria-label
aria-labelledby
aria-level
aria-live
aria-modal
aria-multiline
aria-multiselectable
aria-orientation
aria-owns
aria-placeholder
aria-posinset
aria-pressed
aria-readonly
aria-relevant
aria-required
aria-roledescription
aria-rowcount
aria-rowindex
aria-rowspan
aria-selected
aria-setsize
aria-sort
aria-valuemax
aria-valuemin
aria-valuenow
aria-valuetext
role
core attributes
id
tabindex
autofocus
lang
xml:space
class
style
conditional processing attributes
requiredExtensions
systemLanguage
global event attributes
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragexit
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
onfocus
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
presentation attributes
Geometry properties:
width
height
DOM Interfaces:
SVGForeignObjectElement
SVG is designed to be compatible with other XML languages
for describing and rendering other types of content.
The
foreignObject
element allows for inclusion of elements in a non-SVG namespace which
is rendered within a region of the SVG graphic using other user agent processes. The
included foreign graphical content is subject to SVG
transformations, filters, clipping, masking and compositing.
Examples include
inserting a
MathML
expression into
an SVG drawing [
MathML3
],
or adding a block of complex CSS-formatted HTML text or form inputs.
The HTML parser treats elements inside the
foreignObject
equivalent to elements inside an HTML document fragment.
Any
svg
or
math
element,
and their descendents,
will be parsed as being in the SVG or MathML namespace, respectively;
all other tags will be parsed as being in the HTML namespace.
SVG-namespaced elements within a
foreignObject
will not be rendered,
except in the situation where a properly defined SVG
fragment, including a root
svg
element is
defined as a descendent of the
foreignObject
foreignObject
may be used in conjunction with the
switch
element and
the
requiredExtensions
attribute to
provide proper checking for user agent support and provide an
alternate rendering in case user agent support is not
available.
This specification does not define how
requiredExtensions
values should be mapped to support for different XML languages;
a future specification may do so.
It is not required that SVG user agents support the ability
to invoke other arbitrary user agents to handle embedded
foreign object types; however, all conforming SVG user agents
would need to support the
switch
element and
must be able to render valid SVG elements when they appear as
one of the alternatives within a
switch
element.
It is expected that commercial Web browsers will
support the ability for SVG to embed
CSS-formatted HTML and also MathML content,
with the rendered content subject to transformations and compositing defined in the SVG fragment.
At this time, such a capability is not a requirement.
12.5. DOM interfaces
12.5.1. Interface SVGImageElement
An
SVGImageElement
object represents an
image
element in the DOM.
Exposed
=Window]
interface
SVGImageElement
SVGGraphicsElement
SameObject
] readonly attribute
SVGAnimatedLength
SameObject
] readonly attribute
SVGAnimatedLength
SameObject
] readonly attribute
SVGAnimatedLength
width
SameObject
] readonly attribute
SVGAnimatedLength
height
SameObject
] readonly attribute
SVGAnimatedPreserveAspectRatio
preserveAspectRatio
attribute DOMString?
crossOrigin
};
SVGImageElement
includes
SVGURIReference
The
width
and
height
IDL attributes
reflect
the computed values of the
width
and
height
properties and their corresponding
presentation attributes, respectively.
The
preserveAspectRatio
IDL attribute
reflects
the
preserveAspectRatio
content attribute.
The
crossOrigin
IDL attribute
reflects
the
crossorigin
content attribute.
12.5.2. Interface SVGForeignObjectElement
An
SVGForeignObjectElement
object represents a
foreignObject
in the DOM.
Exposed
=Window]
interface
SVGForeignObjectElement
SVGGraphicsElement
SameObject
] readonly attribute
SVGAnimatedLength
SameObject
] readonly attribute
SVGAnimatedLength
SameObject
] readonly attribute
SVGAnimatedLength
width
SameObject
] readonly attribute
SVGAnimatedLength
height
};
The
width
and
height
IDL attributes
reflect
the computed values of the
width
and
height
properties and their corresponding
presentation attributes, respectively.
US