Chapter 12: Embedded Content

SVG 2 Requirement: - Allow HTML5 elements in SVG: audio, canvas, iframe and video.
Resolution: - Allow audio, canvas, iframe and video elements from HTML5, don't introduce almost the same but slightly different SVG NS elements.
Purpose: To allow various HTML embedded content elements to be used directly in SVG and support dynamic loading of content.
Owner: Nobody

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.

Additionally SVG allows embedded content using HTML 'video', 'audio', 'iframe' and 'canvas' elements.

Except canvas and foreignObject, embedded content is compatible with Resource Hints for prioritizing downloading of external resources.

12.2. Placement of the embedded content

The x, y, 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.

The elements in the HTML namespace do not have SVG presentation attributes for the geometry properties. Most of these elements, however, accept the HTML width and height dimensional attributes, which are used as presentational hints to set default values for the corresponding sizing properties.

The HTML dimensional attributes must be parsed and interpretted as defined in the HTML specification [HTML]. Specifically, they only accept integer values, not CSS lengths with units. On a canvas element, the attributes are slightly different: they affect the rendered bitmap, not only its layout.

The x and y geometry properties can only be set on HTML-namespaced elements via CSS.

When the embedded content consists of a single referenced resource (e.g., an image, video, or canvas), the dimensions of the positioning rectangle, in the current coordinate system after applying all transforms, define the specified size for the embedded object. A 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, an audio or video with user-agent generated controls, or a video, audio, or canvas displaying HTML fallback content), 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 an iframe or an 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:clipPath, mask, script, style
Attributes:
Geometry properties:
DOM Interfaces:

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 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 fit 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).

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.

<?xml version="1.0" standalone="no"?>
<svg width="4in" height="3in"
     xmlns="http://www.w3.org/2000/svg">
  <desc>This graphic links to an external image
  </desc>
  <image x="200" y="200" width="100px" height="100px"
         href="myimage.png">
    <title>My image</title>
  </image>
</svg>

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.

<?xml version="1.0" standalone="no"?>
<svg width="5cm" height="3cm" viewBox="0 0 50 30"
     xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Recursive SVG</title>
  <desc>An SVG with two recursive image reference to itself.
    One reference uses the file name as a relative URL,
    the other uses a target fragment only.
    When viewed in a processing mode that supports external file references,
    the embedded images should be rendered;
    however, the embedded image must be processed in secure mode,
    so the recursion only happens once.
    The appearance should be three nested red circles in a bulls-eye pattern;
    the innermost circle has solid fill because of target styles.
  </desc>
  <style type="text/css">
    #target:target {
      fill: red;
    }
  </style>
  <circle id="target"
          stroke="red" stroke-width="5" fill="none"
          cx="50%" cy="50%" r="12" />
  <image xlink:href="recursive-image.svg"
         x="25%" y="25%" width="50%" height="50%" />
  <image xlink:href="#target"
         x="45%" y="45%" width="10%" height="10%" />
</svg>
Example recursive-image — an SVG that embeds itself, creating a bulls-eye pattern

Example recursive-image

View this example as SVG (SVG-enabled browsers only)

12.4. HTML elements in SVG subtrees

The following HTML elements render when included in an SVG subtree as a child of a container element and when using the HTML namespace:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:html="http://www.w3.org/1999/xhtml">
  <html:video src="file.mp4" controls="controls">
  </html:video>
</svg>

HTML elements, in the HTML namespace, used as children of 'video', 'audio', 'iframe' and 'canvas' elements within an SVG document fragment behave as specified in HTML. This applies in particular to fallback content; if fallback content is rendered, the embedded element behaves like an SVG foreignObject element to contain the HTML content. This would occur, for example, for a video element if the user agent does not support the specified video formats, or for a canvas element if scripting is disabled.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:html="http://www.w3.org/1999/xhtml">
  <html:video src="http://example.org/dummyvideo" controls="controls">
    <html:p>The video format is not supported by this browser.</html:p>
  </html:video>
</svg>

The HTML specification is applicable also for the 'track' and 'source' elements.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:html="http://www.w3.org/1999/xhtml">
  <html:video src="file.mp4" controls="controls">
    <html:source src="file.webm" type='video/webm;codecs="vp8, vorbis"'/>
    <html:source src="file.mp4" type='video/mp4;codecs="avc1.42E01E, mp4a.40.2"'/>
  </html:video>
</svg>

Currently, within an SVG subtree, these tagnames are not recognized by the HTML parser to be HTML-namespaced elements, although this may change in the future. Therefore, in order to include these elements within SVG, one of the following must be used:

Other HTML elements in an SVG subtree, other than those inside a foreignObject element, must be treated as unknown elements for rendering purposes.

Many HTML elements will be treated as a parse error by the HTML parser, causing the SVG fragment to terminate.

12.5. The ‘foreignObject’ element

foreignObject
Categories:
Graphics element, renderable element, structurally external element
Content model:
Any elements or character data.
Attributes:
Geometry properties:
DOM Interfaces:

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.

A 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 agent 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.

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in"
 xmlns = 'http://www.w3.org/2000/svg'>
  <desc>This example uses the 'switch' element to provide a
        fallback graphical representation of an paragraph, if
        XMHTML is not supported.</desc>
  <!-- The 'switch' element will process the first child element
       whose testing attributes evaluate to true.-->
  <switch>
    <!-- Process the embedded XHTML if the requiredExtensions attribute
         evaluates to true (i.e., the user agent supports XHTML
         embedded within SVG). -->
    <foreignObject width="100" height="50"
                   requiredExtensions="http://example.com/SVGExtensions/EmbeddedXHTML">
      <!-- XHTML content goes here -->
      <body xmlns="http://www.w3.org/1999/xhtml">
        <p>Here is a paragraph that requires word wrap</p>
      </body>
    </foreignObject>
    <!-- Else, process the following alternate SVG.
         Note that there are no testing attributes on the 'text' element.
         If no testing attributes are provided, it is as if there
         were testing attributes and they evaluated to true.-->
    <text font-size="10" font-family="Verdana">
      <tspan x="10" y="10">Here is a paragraph that</tspan>
      <tspan x="10" y="20">requires word wrap.</tspan>
    </text>
  </switch>
</svg>

12.6. DOM interfaces

12.6.1. Interface SVGImageElement

An SVGImageElement object represents an image element in the DOM.

[Exposed=Window]
interface SVGImageElement : SVGGraphicsElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
  [SameObject] readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio;
  attribute DOMString? crossOrigin;
};

SVGImageElement includes SVGURIReference;

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 preserveAspectRatio IDL attribute reflects the preserveAspectRatio content attribute.

The crossOrigin IDL attribute reflects the crossorigin content attribute.

12.6.2. Interface SVGForeignObjectElement

An SVGForeignObjectElement object represents a foreignObject in the DOM.

[Exposed=Window]
interface SVGForeignObjectElement : SVGGraphicsElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
};

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.