RsvgHandle

RsvgHandle — Loads SVG data into memory.

Types and Values

Description

This is the main entry point into the librsvg library. An RsvgHandle is an object that represents SVG data in memory. Your program creates an RsvgHandle from an SVG file, or from a memory buffer that contains SVG data, or in the most general form, from a GInputStream that will provide SVG data.

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

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 files 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. All other URL schemes in references require a base URL. For example, this means that if you load an SVG with rsvg_handle_new_from_data() without calling rsvg_handle_set_base_uri(), then any referenced files will not be allowed (e.g. raster images to be loaded from other files will not work).
  3. If referenced URLs are absolute, rathen 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.
  4. 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).
  5. Otherwise, non-file schemes are not allowed. For example, librsvg will not load http resources, to keep malicious SVG data from "phoning home".
  6. 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.

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 from memory

If you already have SVG data in a byte buffer in memory, you can create a memory input stream with g_memory_input_stream_new_from_data() and feed that to rsvg_handle_new_from_stream_sync().

Note that in this case, it is important that you specify the base_file for the in-memory SVG data. Librsvg uses the base_file to resolve links to external content, like raster images.


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.

Functions

rsvg_error_quark ()

GQuark
rsvg_error_quark (void);

The error domain for RSVG

Returns

The error domain


rsvg_cleanup ()

void
rsvg_cleanup (void);

rsvg_cleanup has been deprecated since version 2.46 and should not be used in newly-written code.

No-op. This function should not be called from normal programs.

Since: 2.36


rsvg_set_default_dpi ()

void
rsvg_set_default_dpi (double dpi);

rsvg_set_default_dpi has been deprecated since version 2.42.3 and should not be used in newly-written code.

This function used to set a global default DPI. However, it only worked if it was called before any RsvgHandle objects had been created; it would not work after that. To avoid global mutable state, please use rsvg_handle_set_dpi() instead.

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

Parameters

dpi

Dots Per Inch (aka Pixels Per Inch)

 

Since: 2.8


rsvg_set_default_dpi_x_y ()

void
rsvg_set_default_dpi_x_y (double dpi_x,
                          double dpi_y);

rsvg_set_default_dpi_x_y has been deprecated since version 2.42.3 and should not be used in newly-written code.

This function used to set a global default DPI. However, it only worked if it was called before any RsvgHandle objects had been created; it would not work after that. To avoid global mutable state, please use rsvg_handle_set_dpi() instead.

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

Parameters

dpi_x

Dots Per Inch (aka Pixels Per Inch)

 

dpi_y

Dots Per Inch (aka Pixels Per Inch)

 

Since: 2.8


rsvg_handle_set_dpi ()

void
rsvg_handle_set_dpi (RsvgHandle *handle,
                     double dpi);

Sets the DPI for the outgoing pixbuf. 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.

Parameters

handle

An RsvgHandle

 

dpi

Dots Per Inch (aka Pixels Per Inch)

 

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 for the outgoing pixbuf. Common values are 75, 90, and 300 DPI. Passing a number <= 0 to dpi_x or dpi_y will reset the DPI to whatever the default value happens to be.

Parameters

handle

An RsvgHandle

 

dpi_x

Dots Per Inch (aka Pixels Per Inch)

 

dpi_y

Dots Per Inch (aka Pixels Per Inch)

 

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 rsvg_handle_new_with_flags() or the stream functions listed above.

Returns

A new RsvgHandle with no flags set.


rsvg_handle_new_with_flags ()

RsvgHandle *
rsvg_handle_new_with_flags (RsvgHandleFlags flags);

Creates a new RsvgHandle with flags flags .

Parameters

flags

flags from RsvgHandleFlags

 

Returns

a new RsvgHandle.

[transfer full]

Since: 2.36


rsvg_handle_write ()

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

rsvg_handle_write has been deprecated since version 2.46. and should not be used in newly-written code.

Use rsvg_handle_read_stream_sync() or the constructor functions rsvg_handle_new_from_gfile_sync() or rsvg_handle_new_from_stream_sync().

Notes: This function will accumlate data from the buf in memory until rsvg_handle_close() gets called. To avoid a big temporary buffer, use the funtions listed before, which take a GFile or a GInputStream.

Loads the next count bytes of the image.

Parameters

handle

an RsvgHandle

 

buf

pointer to svg data.

[array length=count][element-type guchar]

count

length of the buf buffer in bytes

 

error

a location to store a GError, or NULL.

[allow-none]

Returns

This function always returns TRUE, and does not set the error .


rsvg_handle_close ()

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

rsvg_handle_close has been deprecated since version 2.46. and should not be used in newly-written code.

Use rsvg_handle_read_stream_sync() or the constructor functions rsvg_handle_new_from_gfile_sync() or rsvg_handle_new_from_stream_sync().

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.

Parameters

handle

a RsvgHandle

 

error

a location to store a GError, or NULL.

[allow-none]

Returns

TRUE on success, or FALSE on error.


rsvg_handle_get_base_uri ()

const char *
rsvg_handle_get_base_uri (RsvgHandle *handle);

Gets the base uri for this RsvgHandle.

Parameters

handle

A RsvgHandle

 

Returns

the base uri, possibly null

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. This can only be called before rsvg_handle_write() has been called.

Parameters

handle

A RsvgHandle

 

base_uri

The base uri

 

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.

Parameters

handle

A RsvgHandle

 

dimension_data

A place to store the SVG's size.

[out]

Since: 2.14


rsvg_handle_get_dimensions_sub ()

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

rsvg_handle_get_dimensions_sub has been deprecated since version 2.46. and should not be used in newly-written code.

Use rsvg_handle_get_geometry_sub() instead.

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.

Parameters

handle

A RsvgHandle

 

dimension_data

A place to store the SVG's size.

[out]

id

An element's id within the SVG, starting with "##", for example, "#layer1"; or NULL to use the whole SVG.

[nullable]

Since: 2.22


rsvg_handle_get_position_sub ()

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

rsvg_handle_get_position_sub has been deprecated since version 2.46. and should not be used in newly-written code.

Use rsvg_handle_get_geometry_sub() instead.

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.

Parameters

handle

A RsvgHandle

 

position_data

A place to store the SVG fragment's position.

[out]

id

An element's id within the SVG, starting with "##", for example, "#layer1"; or NULL to use the whole SVG.

[nullable]

Since: 2.22


rsvg_handle_get_geometry_sub ()

gboolean
rsvg_handle_get_geometry_sub (RsvgHandle *handle,
                              RsvgRectangle *ink_rect,
                              RsvgRectangle *logical_rect,
                              const char *id);

Get the geometry of a subelement of the SVG file.

Note that unlike rsvg_handle_get_position_sub() and rsvg_handle_get_dimensions_sub(), this function does not call the size_func.

Parameters

handle

A RsvgHandle

 

ink_rect

A place to store the SVG fragment's geometry.

[out][allow-none]

logical_rect

A place to store the SVG fragment's logical geometry.

[out][allow-none]

id

An element's id within the SVG, starting with "##", for example, "#layer1"; or NULL to use the whole SVG.

[nullable]

Since: 2.46


rsvg_handle_has_sub ()

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

Checks whether the element id exists in the SVG document.

Parameters

handle

a RsvgHandle

 

id

an element's id within the SVG, starting with "##", for example, "#layer1".

 

Returns

TRUE if id exists in the SVG document

Since: 2.22


rsvg_handle_get_title ()

const char *
rsvg_handle_get_title (RsvgHandle *handle);

rsvg_handle_get_title has been deprecated since version 2.36. and should not be used in newly-written code.

Librsvg does not read the metadata/desc/title elements; this function always returns NULL.

Parameters

handle

An RsvgHandle

 

Returns

This function always returns NULL.

[nullable]

Since: 2.4


rsvg_handle_get_desc ()

const char *
rsvg_handle_get_desc (RsvgHandle *handle);

rsvg_handle_get_desc has been deprecated since version 2.36. and should not be used in newly-written code.

Librsvg does not read the metadata/desc/title elements; this function always returns NULL.

Parameters

handle

An RsvgHandle

 

Returns

This function always returns NULL.

[nullable]

Since: 2.4


rsvg_handle_get_metadata ()

const char *
rsvg_handle_get_metadata (RsvgHandle *handle);

rsvg_handle_get_metadata has been deprecated since version 2.36. and should not be used in newly-written code.

Librsvg does not read the metadata/desc/title elements; this function always returns NULL.

Parameters

handle

An RsvgHandle

 

Returns

This function always returns NULL.

[nullable]

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.

Parameters

data

The SVG data.

[array length=data_len]

data_len

The length of data , in bytes

 

error

return location for errors

 

Returns

A RsvgHandle or NULL if an error occurs.

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 .

Parameters

filename

The file name to load, or a URI.

 

error

return location for errors

 

Returns

A RsvgHandle or NULL if an error occurs.

Since: 2.14


rsvg_error_get_type ()

GType
rsvg_error_get_type (void);

rsvg_init ()

void
rsvg_init (void);

rsvg_init has been deprecated since version 2.36 and should not be used in newly-written code.

There is no need to initialize librsvg.

This function does nothing.

Since: 2.9


rsvg_term ()

void
rsvg_term (void);

rsvg_term has been deprecated since version 2.36 and should not be used in newly-written code.

There is no need to de-initialize librsvg.

This function does nothing.

Since: 2.9


rsvg_handle_free ()

void
rsvg_handle_free (RsvgHandle *handle);

rsvg_handle_free is deprecated and should not be used in newly-written code.

Use g_object_unref() instead.

Frees handle .

Parameters

handle

An RsvgHandle

 

RsvgSizeFunc ()

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

RsvgSizeFunc has been deprecated since version 2.14. and should not be used in newly-written code.

Set up a cairo matrix and use rsvg_handle_render_cairo() instead. See the documentation for rsvg_handle_set_size_callback() for an example, and for the reasons for deprecation.

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

Parameters

width

the width of the SVG.

[out]

height

the height of the SVG.

[out]

user_data

user data

 

rsvg_handle_set_size_callback ()

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

rsvg_handle_set_size_callback has been deprecated since version 2.14. and should not be used in newly-written code.

Set up a cairo matrix and use rsvg_handle_render_cairo() instead. You can call rsvg_handle_get_dimensions() to figure out the size of your SVG, and then scale it to the desired size via Cairo. For example, the following code renders an SVG at a specified size, scaled proportionally from whatever original size it may have had:

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);
}

This function was deprecated because when the size_func is used, it makes it unclear when the librsvg functions which call the size_func will use the size computed originally, or the callback-specified size, or whether it refers to the whole SVG or to just a sub-element of it. It is easier, and unambiguous, to use code similar to the example above.

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.

Parameters

handle

An RsvgHandle

 

size_func

A sizing function, or NULL.

[nullable]

user_data

User data to pass to size_func , or NULL

 

user_data_destroy

Function to be called to destroy the data passed in user_data , or NULL.

 

Types and Values

enum RsvgError

An enumeration representing possible errors

Members

RSVG_ERROR_FAILED

the request failed

 

RSVG_ERROR

#define RSVG_ERROR (rsvg_error_quark ())

struct RsvgHandle

struct RsvgHandle {
    GObject parent;
};

Lets you load SVG data and render it.

Members

GObject parent;

parent instance

 

struct RsvgHandleClass

struct RsvgHandleClass {
    GObjectClass parent;
};

Class structure for RsvgHandle.

Members

GObjectClass parent;

parent class

 

struct RsvgRectangle

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

A data structure for holding a rectangle.

Members

double x;

X coordinate of the left side of the rectangle

 

double y;

Y coordinate of the the top side of the rectangle

 

double width;

width of the rectangle

 

double height;

height of the rectangle

 

Since: 2.46


struct RsvgDimensionData

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

RsvgDimensionData has been deprecated since version 2.46. and should not be used in newly-written code.

Please use rsvg_handle_get_geometry_sub().

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.

Members

int width;

SVG's width, in pixels

 

int height;

SVG's height, in pixels

 

gdouble em;

SVG's original width, unmodified by RsvgSizeFunc

 

gdouble ex;

SVG's original height, unmodified by RsvgSizeFunc

 

struct RsvgPositionData

struct RsvgPositionData {
    int x;
    int y;
};

RsvgPositionData has been deprecated since version 2.46. and should not be used in newly-written code.

Please use rsvg_handle_get_geometry_sub().

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

Members

int x;

position on the x axis

 

int y;

position on the y axis

 

RSVG_TYPE_ERROR

#define RSVG_TYPE_ERROR (rsvg_error_get_type())