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:

1

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

Loading an SVG with GIO

This is the easiest and most resource-efficient way of loading SVG data into an RsvgHandle.

If you have a GFile that stands for an SVG file, you can simply call rsvg_handle_new_from_gfile_sync() to load an RsvgHandle from it.

Alternatively, if you have a GInputStream, you can use rsvg_handle_new_from_stream_sync().

Both of those methods allow specifying a GCancellable, so the loading process can be cancelled from another thread.

Loading an SVG without GIO

You can load an RsvgHandle from a simple filename or URI with rsvg_handle_new_from_file(). Note that this is a blocking operation; there is no way to cancel it if loading a remote URI takes a long time. Also, note that this method does not let you specify RsvgHandleFlags.

Otherwise, loading an SVG without GIO is not recommended, since librsvg will need to buffer your entire data internally before actually being able to parse it. The deprecated way of doing this is by creating a handle with rsvg_handle_new() or rsvg_handle_new_with_flags(), and then using rsvg_handle_write() and rsvg_handle_close() to feed the handle with SVG data. Still, please try to use the GIO stream functions instead.

Resolution of the rendered image (dots per inch, or DPI)

SVG images can contain dimensions like "5 cm" or "2 pt" that must be converted from physical units into device units. To do this, librsvg needs to know the actual dots per inch (DPI) of your target device. You can call rsvg_handle_set_dpi() or rsvg_handle_set_dpi_x_y() on an RsvgHandle to set the DPI before rendering it.

Rendering

The preferred way to render an already-loaded RsvgHandle is to use rsvg_handle_render_cairo(). Please see its documentation for details.

Alternatively, you can use rsvg_handle_get_pixbuf() to directly obtain a GdkPixbuf with the rendered image. This is simple, but it does not let you control the size at which the SVG will be rendered. It will just be rendered at the size which rsvg_handle_get_dimensions() would return, which depends on the dimensions that librsvg is able to compute from the SVG data.

API ordering

Due to the way the librsvg API evolved over time, an RsvgHandle object is available for use as soon as it is constructed. However, not all of its methods can be called at any time. For example, an RsvgHandle just constructed with rsvg_handle_new() is not loaded yet, and it does not make sense to call rsvg_handle_get_dimensions() on it just at that point.

The documentation for the available methods in RsvgHandle may mention that a particular method is only callable on a "fully loaded handle". This means either:

Before librsvg 2.46, the library did not fully verify that a handle was in a fully loaded state for the methods that require it. To preserve compatibility with old code which inadvertently called the API without checking for errors, or which called some methods outside of the expected order, librsvg will just emit a g_critical() message in those cases.

New methods introduced in librsvg 2.46 and later will check for the correct ordering, and panic if they are called out of order. This will abort the program as if it had a failed assertion.

rsvg_error_quark ()

GQuark
rsvg_error_quark (void);

The error domain for RSVG

rsvg_set_default_dpi ()

void
rsvg_set_default_dpi (double dpi);

Do not use this function. Create an RsvgHandle and call rsvg_handle_set_dpi() on it instead.

Since: 2.8

rsvg_set_default_dpi_x_y ()

void
rsvg_set_default_dpi_x_y (double dpi_x,
                          double dpi_y);

Do not use this function. Create an RsvgHandle and call rsvg_handle_set_dpi_x_y() on it instead.

Since: 2.8

rsvg_handle_set_dpi ()

void
rsvg_handle_set_dpi (RsvgHandle *handle,
                     double dpi);

Sets the DPI at which the handle will be rendered. Common values are 75, 90, and 300 DPI.

Passing a number <= 0 to dpi will reset the DPI to whatever the default value happens to be, but since rsvg_set_default_dpi() is deprecated, please do not pass values <= 0 to this function.

Since: 2.8

rsvg_handle_set_dpi_x_y ()

void
rsvg_handle_set_dpi_x_y (RsvgHandle *handle,
                         double dpi_x,
                         double dpi_y);

Sets the DPI at which the handle will be rendered. Common values are 75, 90, and 300 DPI.

Passing a number <= 0 to dpi will reset the DPI to whatever the default value happens to be, but since rsvg_set_default_dpi_x_y() is deprecated, please do not pass values <= 0 to this function.

Since: 2.8

rsvg_handle_new ()

RsvgHandle *
rsvg_handle_new (void);

Returns a new rsvg handle. Must be freed with g_object_unref . This handle can be used to load an image.

The preferred way of loading SVG data into the returned RsvgHandle is with rsvg_handle_read_stream_sync().

The deprecated way of loading SVG data is with rsvg_handle_write() and rsvg_handle_close(); note that these require buffering the entire file internally, and for this reason it is better to use the stream functions: rsvg_handle_new_from_stream_sync(), rsvg_handle_read_stream_sync(), or rsvg_handle_new_from_gfile_sync().

After loading the RsvgHandle with data, you can render it using Cairo or get a GdkPixbuf from it. When finished, free the handle with g_object_unref(). No more than one image can be loaded with one handle.

Note that this function creates an RsvgHandle with no flags set. If you require any of RsvgHandleFlags to be set, use any of rsvg_handle_new_with_flags(), rsvg_handle_new_from_stream_sync(), or rsvg_handle_new_from_gfile_sync().

rsvg_handle_new_with_flags ()

RsvgHandle *
rsvg_handle_new_with_flags (RsvgHandleFlags flags);

Creates a new RsvgHandle with flags flags . After calling this function, you can feed the resulting handle with SVG data by using rsvg_handle_read_stream_sync().

Since: 2.36

rsvg_handle_write ()

gboolean
rsvg_handle_write (RsvgHandle *handle,
                   const guchar *buf,
                   gsize count,
                   GError **error);

Loads the next count bytes of the image.

Before calling this function for the first time, you may need to call rsvg_handle_set_base_uri() or rsvg_handle_set_base_gfile() to set the "base file" for resolving references to external resources. SVG elements like <image> which reference external resources will be resolved relative to the location you specify with those functions.

rsvg_handle_close ()

gboolean
rsvg_handle_close (RsvgHandle *handle,
                   GError **error);

Closes handle , to indicate that loading the image is complete. This will return TRUE if the loader closed successfully and the SVG data was parsed correctly. Note that handle isn't freed until g_object_unref is called.

rsvg_handle_get_base_uri ()

const char *
rsvg_handle_get_base_uri (RsvgHandle *handle);

Gets the base uri for this RsvgHandle.

Since: 2.8

rsvg_handle_set_base_uri ()

void
rsvg_handle_set_base_uri (RsvgHandle *handle,
                          const char *base_uri);

Set the base URI for this SVG.

Note: This function may only be called before rsvg_handle_write() or rsvg_handle_read_stream_sync() have been called.

Since: 2.9

rsvg_handle_get_dimensions ()

void
rsvg_handle_get_dimensions (RsvgHandle *handle,
                            RsvgDimensionData *dimension_data);

Get the SVG's size. Do not call from within the size_func callback, because an infinite loop will occur.

This function depends on the RsvgHandle's DPI to compute dimensions in pixels, so you should call rsvg_handle_set_dpi() beforehand.

Since: 2.14

rsvg_handle_get_dimensions_sub ()

gboolean
rsvg_handle_get_dimensions_sub (RsvgHandle *handle,
                                RsvgDimensionData *dimension_data,
                                const char *id);

Get the size of a subelement of the SVG file. Do not call from within the size_func callback, because an infinite loop will occur.

This function depends on the RsvgHandle's DPI to compute dimensions in pixels, so you should call rsvg_handle_set_dpi() beforehand.

Element IDs should look like an URL fragment identifier; for example, pass "#foo" (hash foo) to get the geometry of the element that has an id="foo" attribute.

Since: 2.22

rsvg_handle_get_position_sub ()

gboolean
rsvg_handle_get_position_sub (RsvgHandle *handle,
                              RsvgPositionData *position_data,
                              const char *id);

Get the position of a subelement of the SVG file. Do not call from within the size_func callback, because an infinite loop will occur.

This function depends on the RsvgHandle's DPI to compute dimensions in pixels, so you should call rsvg_handle_set_dpi() beforehand.

Element IDs should look like an URL fragment identifier; for example, pass "#foo" (hash foo) to get the geometry of the element that has an id="foo" attribute.

Since: 2.22

rsvg_handle_has_sub ()

gboolean
rsvg_handle_has_sub (RsvgHandle *handle,
                     const char *id);

Checks whether the element id exists in the SVG document.

Element IDs should look like an URL fragment identifier; for example, pass "#foo" (hash foo) to get the geometry of the element that has an id="foo" attribute.

Since: 2.22

rsvg_handle_get_title ()

const char *
rsvg_handle_get_title (RsvgHandle *handle);

Since: 2.4

rsvg_handle_get_desc ()

const char *
rsvg_handle_get_desc (RsvgHandle *handle);

Since: 2.4

rsvg_handle_get_metadata ()

const char *
rsvg_handle_get_metadata (RsvgHandle *handle);

Since: 2.9

rsvg_handle_new_from_data ()

RsvgHandle *
rsvg_handle_new_from_data (const guint8 *data,
                           gsize data_len,
                           GError **error);

Loads the SVG specified by data . Note that this function creates an RsvgHandle without a base URL, and without any RsvgHandleFlags. If you need these, use rsvg_handle_new_from_stream_sync() instead by creating a GMemoryInputStream from your data.

Since: 2.14

rsvg_handle_new_from_file ()

RsvgHandle *
rsvg_handle_new_from_file (const gchar *filename,
                           GError **error);

Loads the SVG specified by file_name . Note that this function, like rsvg_handle_new(), does not specify any loading flags for the resulting handle. If you require the use of RsvgHandleFlags, use rsvg_handle_new_from_gfile_sync().

Since: 2.14

rsvg_handle_set_stylesheet ()

gboolean
rsvg_handle_set_stylesheet (RsvgHandle *handle,
                            const guint8 *css,
                            gsize css_len,
                            GError **error);

Sets a CSS stylesheet to use for an SVG document.

The css_len argument is mandatory; this function will not compute the length of the css string. This is because a provided stylesheet, which the calling program could read from a file, can have nul characters in it.

During the CSS cascade, the specified stylesheet will be used with a "User" origin.

Note that @import rules will not be resolved, except for data: URLs.

Since: 2.48

rsvg_error_get_type ()

GType
rsvg_error_get_type (void);

rsvg_init ()

void
rsvg_init (void);

This function does nothing.

Since: 2.9

rsvg_term ()

void
rsvg_term (void);

This function does nothing.

Since: 2.9

rsvg_cleanup ()

void
rsvg_cleanup (void);

Since: 2.36

rsvg_handle_free ()

void
rsvg_handle_free (RsvgHandle *handle);

Frees handle .

RsvgSizeFunc ()

void
(*RsvgSizeFunc) (gint *width,
                 gint *height,
                 gpointer user_data);

Function to let a user of the library specify the SVG's dimensions

rsvg_handle_set_size_callback ()

void
rsvg_handle_set_size_callback (RsvgHandle *handle,
                               RsvgSizeFunc size_func,
                               gpointer user_data,
                               GDestroyNotify user_data_destroy);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

void
render_scaled_proportionally (RsvgHandle *handle, cairo_t cr, int width, int height)
{
    RsvgDimensionData dimensions;
    double x_factor, y_factor;
    double scale_factor;

    rsvg_handle_get_dimensions (handle, &dimensions);

    x_factor = (double) width / dimensions.width;
    y_factor = (double) height / dimensions.height;

    scale_factor = MIN (x_factor, y_factor);

    cairo_scale (cr, scale_factor, scale_factor);

    rsvg_handle_render_cairo (handle, cr);
}

Sets the sizing function for the handle , which can be used to override the size that librsvg computes for SVG images. The size_func is called from the following functions:

Librsvg computes the size of the SVG being rendered, and passes it to the size_func , which may then modify these values to set the final size of the generated image.

enum RsvgError

An enumeration representing possible errors

RSVG_ERROR

#define RSVG_ERROR (rsvg_error_quark ())

struct RsvgHandle

struct RsvgHandle;

Lets you load SVG data and render it.

struct RsvgHandleClass

struct RsvgHandleClass {
    GObjectClass parent;
};

Class structure for RsvgHandle.

struct RsvgRectangle

struct RsvgRectangle {
    double x;
    double y;
    double width;
    double height;
};

A data structure for holding a rectangle.

Since: 2.46

RsvgLength

typedef struct {
    double   length;
    RsvgUnit unit;
} RsvgLength;

RsvgLength values are used in rsvg_handle_get_intrinsic_dimensions(), for example, to return the CSS length values of the width and height attributes of an <svg> element.

This is equivalent to CSS lengths.

It is up to the calling application to convert lengths in non-pixel units (i.e. those where the unit field is not RSVG_UNIT_PX) into something meaningful to the application. For example, if your application knows the dots-per-inch (DPI) it is using, it can convert lengths with unit in RSVG_UNIT_IN or other physical units.

enum RsvgUnit

Units for the RsvgLength struct. These have the same meaning as CSS length units.

struct RsvgDimensionData

struct RsvgDimensionData {
    int width;
    int height;
    gdouble em;
    gdouble ex;
};

Dimensions of an SVG image from rsvg_handle_get_dimensions(), or an individual element from rsvg_handle_get_dimensions_sub(). Please see the deprecation documentation for those functions.

struct RsvgPositionData

struct RsvgPositionData {
    int x;
    int y;
};

Position of an SVG fragment from rsvg_handle_get_position_sub(). Please the deprecation documentation for that function.

RSVG_TYPE_ERROR

#define RSVG_TYPE_ERROR (rsvg_error_get_type())

The “base-uri” property

  “base-uri”                 char *

Base URI for resolving relative references.

Owner: RsvgHandle

Flags: Read / Write / Construct

Default value: NULL

The “desc” property

  “desc”                     char *

SVG's description.

Owner: RsvgHandle

Flags: Read

Default value: NULL

The “dpi-x” property

  “dpi-x”                    double

Horizontal resolution in dots per inch.

Owner: RsvgHandle

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 0

The “dpi-y” property

  “dpi-y”                    double

Vertical resolution in dots per inch.

Owner: RsvgHandle

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 0

The “em” property

  “em”                       double

Exact width, in pixels, of the rendered SVG before calling the size callback as specified by rsvg_handle_set_size_callback().

Owner: RsvgHandle

Flags: Read

Allowed values: >= 0

Default value: 0

The “ex” property

  “ex”                       double

Exact height, in pixels, of the rendered SVG before calling the size callback as specified by rsvg_handle_set_size_callback().

Owner: RsvgHandle

Flags: Read

Allowed values: >= 0

Default value: 0

The “flags” property

  “flags”                    RsvgHandleFlags

Flags from RsvgHandleFlags.

Owner: RsvgHandle

Flags: Read / Write / Construct Only

Since: 2.36

The “height” property

  “height”                   int

Height, in pixels, of the rendered SVG after calling the size callback as specified by rsvg_handle_set_size_callback().

Owner: RsvgHandle

Flags: Read

Allowed values: >= 0

Default value: 0

The “metadata” property

  “metadata”                 char *

SVG's metadata

Owner: RsvgHandle

Flags: Read

Default value: NULL

The “title” property

  “title”                    char *

SVG's title.

Owner: RsvgHandle

Flags: Read

Default value: NULL

The “width” property

  “width”                    int

Width, in pixels, of the rendered SVG after calling the size callback as specified by rsvg_handle_set_size_callback().

Owner: RsvgHandle

Flags: Read

Allowed values: >= 0

Default value: 0