RsvgHandle: Librsvg Reference Manual

## RsvgHandle RsvgHandle — Loads SVG data into memory. |

## Functions

GQuark | rsvg_error_quark ()
void | rsvg_set_default_dpi ()
void | rsvg_set_default_dpi_x_y ()
void | rsvg_handle_set_dpi ()
void | rsvg_handle_set_dpi_x_y ()
RsvgHandle * | rsvg_handle_new ()
RsvgHandle * | rsvg_handle_new_with_flags ()
gboolean | rsvg_handle_write ()
gboolean | rsvg_handle_close ()
const char * | rsvg_handle_get_base_uri ()
void | rsvg_handle_set_base_uri ()
void | rsvg_handle_get_dimensions ()
gboolean | rsvg_handle_get_dimensions_sub ()
gboolean | rsvg_handle_get_position_sub ()
gboolean | rsvg_handle_has_sub ()
const char * | rsvg_handle_get_title ()
const char * | rsvg_handle_get_desc ()
const char * | rsvg_handle_get_metadata ()
RsvgHandle * | rsvg_handle_new_from_data ()
RsvgHandle * | rsvg_handle_new_from_file ()
gboolean | rsvg_handle_set_stylesheet ()
GType | rsvg_error_get_type ()
void | rsvg_init ()
void | rsvg_term ()
void | rsvg_cleanup ()
void | rsvg_handle_free ()
void | (*RsvgSizeFunc) ()
void | rsvg_handle_set_size_callback ()

## Properties

gchar * | base-uri | Read / Write / Construct
gchar * | desc | Read
gdouble | dpi-x | Read / Write / Construct
gdouble | dpi-y | Read / Write / Construct
gdouble | em | Read
gdouble | ex | Read
RsvgHandleFlags | flags | Read / Write / Construct Only
gint | height | Read
gchar * | metadata | Read
gchar * | title | Read
gint | width | Read

## Types and Values

enum | RsvgError
#define | RSVG_ERROR
struct | RsvgHandle
struct | RsvgHandleClass
struct | RsvgRectangle
| RsvgLength
enum | RsvgUnit
struct | RsvgDimensionData
struct | RsvgPositionData
#define | RSVG_TYPE_ERROR

## Object Hierarchy

        GObject
        ╰── RsvgHandle

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

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

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

### 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:

- The handle was loaded with `rsvg_handle_write()` and `rsvg_handle_close()`, and those functions returned no errors.
- The handle was loaded with `rsvg_handle_read_stream_sync()` and that function returned no errors.

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.

## Functions

### rsvg_error_quark ()

    GQuark
    rsvg_error_quark (void);

The error domain for RSVG

#### Returns

The error domain

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

#### Parameters

handle | An RsvgHandle |
dpi | Dots Per Inch (i.e. as 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 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.

#### Parameters

handle | An RsvgHandle |
dpi_x | Dots Per Inch (i.e. Pixels Per Inch) |
dpi_y | Dots Per Inch (i.e. 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 any of `rsvg_handle_new_with_flags()`, `rsvg_handle_new_from_stream_sync()`, or `rsvg_handle_new_from_gfile_sync()`.

#### 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` . After calling this function, you can feed the resulting handle with SVG data by using `rsvg_handle_read_stream_sync()`.

#### 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()`. This function is deprecated because it will accumulate data from the `buf` in memory until `rsvg_handle_close()` gets called. To avoid a big temporary buffer, use the suggested functions, which take a GFile or a GInputStream and do not require a temporary buffer.

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.

#### 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`. | [optional]

#### Returns

`TRUE` on success, or `FALSE` on 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()`. See the deprecation notes for `rsvg_handle_write()` for more information.

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`. | [optional]

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

Note: This function may only be called before `rsvg_handle_write()` or `rsvg_handle_read_stream_sync()` have 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.

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

#### 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_for_layer()` 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.

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.

#### 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 "##" (a single hash character), for example, "#layer1". This notation corresponds to a URL's fragment ID. Alternatively, pass `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_for_layer()` 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.

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.

#### 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 "##" (a single hash character), for example, "#layer1". This notation corresponds to a URL's fragment ID. Alternatively, pass `NULL` to use the whole SVG. | [nullable]

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.

#### Parameters

handle | a RsvgHandle |
id | An element's id within the SVG, starting with "##" (a single hash character), for example, "#layer1". This notation corresponds to a URL's fragment ID. |

#### Returns

`TRUE` if `id` exists in the SVG document, `FALSE` otherwise.

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. | [optional]

#### 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` . 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()`.

#### Parameters

filename | The file name to load, or a URI. |
error | return location for errors. | [optional]

#### Returns

A RsvgHandle or `NULL` if an error occurs.

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.

#### Parameters

handle | A RsvgHandle. |
css | String with CSS data; must be valid UTF-8. | [array length=css_len]
css_len | Length of the `css` data in bytes. |
error | return location for errors. | [optional]

Since: 2.48

### 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_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_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:

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

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:

- `rsvg_handle_get_dimensions()`
- `rsvg_handle_get_dimensions_sub()`
- `rsvg_handle_get_position_sub()`
- `rsvg_handle_render_cairo()`
- `rsvg_handle_render_cairo_sub()`

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;

Lets you load SVG data and render it.

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

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

#### Members

double `length`; | numeric part of the length |
RsvgUnit `unit`; | unit part of the length |

### enum RsvgUnit

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

#### Members

RSVG_UNIT_PERCENT | percentage values; where `1.0` means 100%. |
RSVG_UNIT_PX | pixels |
RSVG_UNIT_EM | em, or the current font size |
RSVG_UNIT_EX | x-height of the current font |
RSVG_UNIT_IN | inches |
RSVG_UNIT_CM | centimeters |
RSVG_UNIT_MM | millimeters |
RSVG_UNIT_PT | points, or 1/72 inch |
RSVG_UNIT_PC | picas, or 1/6 inch (12 points) |

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

FIXME: point to deprecation documentation.

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.

FIXME: point to deprecation documentation.

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())

## Property Details

### The `“base-uri”` property

      “base-uri”                 gchar *

Base URI for resolving relative references.

Owner: RsvgHandle

Flags: Read / Write / Construct

Default value: NULL

### The `“desc”` property

      “desc”                     gchar *

SVG's description.

`RsvgHandle:desc` has been deprecated since version 2.36. and should not be used in newly-written code.

Reading this property always returns NULL.

Owner: RsvgHandle

Flags: Read

Default value: NULL

### The `“dpi-x”` property

      “dpi-x”                    gdouble

Horizontal resolution in dots per inch.

Owner: RsvgHandle

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 0

### The `“dpi-y”` property

      “dpi-y”                    gdouble

Vertical resolution in dots per inch.

Owner: RsvgHandle

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 0

### The `“em”` property

      “em”                       gdouble

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

`RsvgHandle:em` has been deprecated since version 2.46. and should not be used in newly-written code.

Reading each of the size properties causes the size of the SVG to be recomputed, so reading both the `em` and `ex` properties will cause two such computations. Please use `rsvg_handle_get_intrinsic_dimensions()` instead.

Owner: RsvgHandle

Flags: Read

Allowed values: >= 0

Default value: 0

### The `“ex”` property

      “ex”                       gdouble

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

`RsvgHandle:ex` has been deprecated since version 2.46. and should not be used in newly-written code.

Reading each of the size properties causes the size of the SVG to be recomputed, so reading both the `em` and `ex` properties will cause two such computations. Please use `rsvg_handle_get_intrinsic_dimensions()` instead.

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”                   gint

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

`RsvgHandle:height` has been deprecated since version 2.46. and should not be used in newly-written code.

For historical reasons, this property is of integer type, which cannot give the exact size of SVG images that are not pixel-aligned. Moreover, reading each of the size properties causes the size of the SVG to be recomputed, so reading both the `width` and `height` properties will cause two such computations. Please use `rsvg_handle_get_intrinsic_dimensions()` instead.

Owner: RsvgHandle

Flags: Read

Allowed values: >= 0

Default value: 0

### The `“metadata”` property

      “metadata”                 gchar *

SVG's metadata

`RsvgHandle:metadata` has been deprecated since version 2.36. and should not be used in newly-written code.

Reading this property always returns NULL.

Owner: RsvgHandle

Flags: Read

Default value: NULL

### The `“title”` property

      “title”                    gchar *

SVG's title.

`RsvgHandle:title` has been deprecated since version 2.36. and should not be used in newly-written code.

Reading this property always returns NULL.

Owner: RsvgHandle

Flags: Read

Default value: NULL

### The `“width”` property

      “width”                    gint

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

`RsvgHandle:width` has been deprecated since version 2.46. and should not be used in newly-written code.

For historical reasons, this property is of integer type, which cannot give the exact size of SVG images that are not pixel-aligned. Moreover, reading each of the size properties causes the size of the SVG to be recomputed, so reading both the `width` and `height` properties will cause two such computations. Please use `rsvg_handle_get_intrinsic_dimensions()` instead.

Owner: RsvgHandle

Flags: Read

Allowed values: >= 0

Default value: 0