Crate rsvg

source ·
Expand description

Load and render SVG images into Cairo surfaces.

This crate can load SVG images and render them to Cairo surfaces, using a mixture of SVG’s static mode and secure static mode. Librsvg does not do animation nor scripting, and can load references to external data only in some situations; see below.

Librsvg supports reading SVG 1.1 data, and is gradually adding support for features in SVG 2. Librsvg also supports SVGZ files, which are just an SVG stream compressed with the GZIP algorithm.

§Basic usage

You can put the following in your Cargo.toml:

[dependencies]
librsvg = "2.59.2"
cairo-rs = "0.20"
gio = "0.20"   # only if you need streams

§Example

const WIDTH: i32 = 640;
const HEIGHT: i32 = 480;

fn main() {
    // Loading from a file

    let handle = rsvg::Loader::new().read_path("example.svg").unwrap();

    let surface = cairo::ImageSurface::create(cairo::Format::ARgb32, WIDTH, HEIGHT).unwrap();
    let cr = cairo::Context::new(&surface).expect("Failed to create a cairo context");

    let renderer = rsvg::CairoRenderer::new(&handle);
    renderer.render_document(
        &cr,
        &cairo::Rectangle::new(0.0, 0.0, f64::from(WIDTH), f64::from(HEIGHT))
    ).unwrap();

    // Loading from a static SVG asset

    let bytes = glib::Bytes::from_static(
        br#"<?xml version="1.0" encoding="UTF-8"?>
            <svg xmlns="http://www.w3.org/2000/svg" width="50" height="50">
                <rect id="foo" x="10" y="10" width="30" height="30"/>
            </svg>
        "#
    );
    let stream = gio::MemoryInputStream::from_bytes(&bytes);

    let handle = rsvg::Loader::new().read_stream(
        &stream,
        None::<&gio::File>,          // no base file as this document has no references
        None::<&gio::Cancellable>,   // no cancellable
    ).unwrap();
}

§The “base file” and resolving references to external files

When you load an SVG, librsvg needs to know the location of the “base file” for it. This is so that librsvg can determine the location of referenced entities. For example, say you have an SVG in /foo/bar/foo.svg and that it has an image element like this:

<image href="resources/foo.png" .../>

In this case, librsvg needs to know the location of the toplevel /foo/bar/foo.svg so that it can generate the appropriate reference to /foo/bar/resources/foo.png.

§Security and locations of referenced files

When processing an SVG, librsvg will only load referenced files if they are in the same directory as the base file, or in a subdirectory of it. That is, if the base file is /foo/bar/baz.svg, then librsvg will only try to load referenced files (from SVG’s <image> element, for example, or from content included through XML entities) if those files are in /foo/bar/* or in /foo/bar/*/.../*. This is so that malicious SVG documents cannot include files that are in a directory above.

The full set of rules for deciding which URLs may be loaded is as follows; they are applied in order. A referenced URL will not be loaded as soon as one of these rules fails:

  1. All data: URLs may be loaded. These are sometimes used to include raster image data, encoded as base-64, directly in an SVG file.

  2. URLs with queries (“?”) or fragment identifiers (“#”) are not allowed.

  3. All URL schemes other than data: in references require a base URL. For example, this means that if you load an SVG with Loader::read_stream without providing a base_file, then any referenced files will not be allowed (e.g. raster images to be loaded from other files will not work).

  4. If referenced URLs are absolute, rather than relative, then they must have the same scheme as the base URL. For example, if the base URL has a “file” scheme, then all URL references inside the SVG must also have the “file” scheme, or be relative references which will be resolved against the base URL.

  5. If referenced URLs have a “resource” scheme, that is, if they are included into your binary program with GLib’s resource mechanism, they are allowed to be loaded (provided that the base URL is also a “resource”, per the previous rule).

  6. Otherwise, non-file schemes are not allowed. For example, librsvg will not load http resources, to keep malicious SVG data from “phoning home”.

  7. A relative URL must resolve to the same directory as the base URL, or to one of its subdirectories. Librsvg will canonicalize filenames, by removing “..” path components and resolving symbolic links, to decide whether files meet these conditions.

Structs§

  • AcceptLanguage
    Stores a parsed version of an HTTP Accept-Language header.
  • CairoRenderer
    Can render an SvgHandle to a Cairo context.
  • IntrinsicDimensions
    Contains the computed values of the <svg> element’s width, height, and viewBox.
  • Length
    A CSS length value.
  • Loader
    Builder for loading an SvgHandle.
  • SvgHandle
    Handle used to hold SVG data in memory.
  • Viewport
    Holds the size of the current viewport in the user’s coordinate system.

Enums§