Using RSVG with cairo: Librsvg Reference Manual

## Using RSVG with cairo Using RSVG with cairo |

## Functions

void | rsvg_handle_get_intrinsic_dimensions ()
gboolean | rsvg_handle_render_document ()
gboolean | rsvg_handle_get_geometry_for_layer ()
gboolean | rsvg_handle_render_layer ()
gboolean | rsvg_handle_get_geometry_for_element ()
gboolean | rsvg_handle_render_element ()
gboolean | rsvg_handle_render_cairo ()
gboolean | rsvg_handle_render_cairo_sub ()

## Description

## Functions

### rsvg_handle_get_intrinsic_dimensions ()

    void
    rsvg_handle_get_intrinsic_dimensions (RsvgHandle *handle,
                                          gboolean *out_has_width,
                                          RsvgLength *out_width,
                                          gboolean *out_has_height,
                                          RsvgLength *out_height,
                                          gboolean *out_has_viewbox,
                                          RsvgRectangle *out_viewbox);

Queries the `width`, `height`, and `viewBox` attributes in an SVG document.

If you are calling this function to compute a scaling factor to render the SVG, consider simply using `rsvg_handle_render_document()` instead; it will do the scaling computations automatically.

As an example, the following SVG element has a `width` of 100 pixels and a `height` of 400 pixels, but no `viewBox`:

    1
    <svg xmlns="http://www.w3.org/2000/svg" width="100" height="400">

Conversely, the following element has a `viewBox`, but no `width` or `height`:

    1
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 400">

Note that the RsvgLength return values have RsvgUnits in them; you should not assume that they are always in pixels. For example, the following SVG element will return a width value whose `units` field is RSVG_UNIT_MM.

    1
    <svg xmlns="http://www.w3.org/2000/svg" width="210mm" height="297mm">

API ordering: This function must be called on a fully-loaded `handle` . See the section API ordering for details.

Panics: this function will panic if the `handle` is not fully-loaded.

#### Parameters

handle | An RsvgHandle |
out_has_width | Will be set to TRUE if the toplevel SVG has a `width` attribute. | [out][optional]
out_width | Will be set to the value of the `width` attribute in the toplevel SVG. | [out][optional]
out_has_height | Will be set to TRUE if the toplevel SVG has a `height` attribute. | [out][optional]
out_height | Will be set to the value of the `height` attribute in the toplevel SVG. | [out][optional]
out_has_viewbox | Will be set to TRUE if the toplevel SVG has a `viewBox` attribute. | [out][optional]
out_viewbox | Will be set to the value of the `viewBox` attribute in the toplevel SVG. | [out][optional]

Since: 2.46

### rsvg_handle_render_document ()

    gboolean
    rsvg_handle_render_document (RsvgHandle *handle,
                                 cairo_t *cr,
                                 const RsvgRectangle *viewport,
                                 GError **error);

Renders the whole SVG document fitted to a viewport.

The `viewport` gives the position and size at which the whole SVG document will be rendered.

The `cr` must be in a CAIRO_STATUS_SUCCESS state, or this function will not render anything, and instead will return an error.

API ordering: This function must be called on a fully-loaded `handle` . See the section API ordering for details.

Panics: this function will panic if the `handle` is not fully-loaded.

#### Parameters

handle | An RsvgHandle |
cr | A Cairo context |
viewport | Viewport size at which the whole SVG would be fitted. |
error | a location to store a GError, or `NULL`. | [optional]

Since: 2.46

### rsvg_handle_get_geometry_for_layer ()

    gboolean
    rsvg_handle_get_geometry_for_layer (RsvgHandle *handle,
                                        const char *id,
                                        const RsvgRectangle *viewport,
                                        RsvgRectangle *out_ink_rect,
                                        RsvgRectangle *out_logical_rect,
                                        GError **error);

Computes the ink rectangle and logical rectangle of an SVG element, or the whole SVG, as if the whole SVG were rendered to a specific viewport.

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.

The "ink rectangle" is the bounding box that would be painted for fully- stroked and filled elements.

The "logical rectangle" just takes into account the unstroked paths and text outlines.

Note that these bounds are not minimum bounds; for example, clipping paths are not taken into account.

You can pass NULL for the `id` if you want to measure all the elements in the SVG, i.e. to measure everything from the root element.

This operation is not constant-time, as it involves going through all the child elements.

API ordering: This function must be called on a fully-loaded `handle` . See the section API ordering for details.

Panics: this function will panic if the `handle` is not fully-loaded.

#### Parameters

handle | An 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. Alternatively, pass `NULL` to compute the geometry for the whole SVG. | [nullable]
viewport | Viewport size at which the whole SVG would be fitted. |
out_ink_rect | Place to store the ink rectangle of the element. | [out][optional]
out_logical_rect | Place to store the logical rectangle of the element. | [out][optional]
error | a location to store a GError, or `NULL`. | [optional]

Since: 2.46

### rsvg_handle_render_layer ()

    gboolean
    rsvg_handle_render_layer (RsvgHandle *handle,
                              cairo_t *cr,
                              const char *id,
                              const RsvgRectangle *viewport,
                              GError **error);

Renders a single SVG element in the same place as for a whole SVG document.

This is equivalent to `rsvg_handle_render_document()`, but it renders only a single element and its children, as if they composed an individual layer in the SVG. The element is rendered with the same transformation matrix as it has within the whole SVG document. Applications can use this to re-render a single element and repaint it on top of a previously-rendered document, for example.

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.

You can pass NULL for the `id` if you want to render all the elements in the SVG, i.e. to render everything from the root element.

API ordering: This function must be called on a fully-loaded `handle` . See the section API ordering for details.

Panics: this function will panic if the `handle` is not fully-loaded.

#### Parameters

handle | An RsvgHandle |
cr | A Cairo context |
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 render the whole SVG document tree. | [nullable]
viewport | Viewport size at which the whole SVG would be fitted. |
error | a location to store a GError, or `NULL`. | [optional]

Since: 2.46

### rsvg_handle_get_geometry_for_element ()

    gboolean
    rsvg_handle_get_geometry_for_element (RsvgHandle *handle,
                                          const char *id,
                                          RsvgRectangle *out_ink_rect,
                                          RsvgRectangle *out_logical_rect,
                                          GError **error);

Computes the ink rectangle and logical rectangle of a single SVG element.

While `rsvg_handle_get_geometry_for_layer` computes the geometry of an SVG element subtree with its transformation matrix, this other function will compute the element's geometry as if it were being rendered under an identity transformation by itself. That is, the resulting geometry is as if the element got extracted by itself from the SVG.

This function is the counterpart to `rsvg_handle_render_element`.

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.

The "ink rectangle" is the bounding box that would be painted for fully- stroked and filled elements.

The "logical rectangle" just takes into account the unstroked paths and text outlines.

Note that these bounds are not minimum bounds; for example, clipping paths are not taken into account.

You can pass NULL for the `id` if you want to measure all the elements in the SVG, i.e. to measure everything from the root element.

This operation is not constant-time, as it involves going through all the child elements.

API ordering: This function must be called on a fully-loaded `handle` . See the section API ordering for details.

Panics: this function will panic if the `handle` is not fully-loaded.

#### Parameters

handle | An 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. Alternatively, pass `NULL` to compute the geometry for the whole SVG. | [nullable]
out_ink_rect | Place to store the ink rectangle of the element. | [out][optional]
out_logical_rect | Place to store the logical rectangle of the element. | [out][optional]
error | a location to store a GError, or `NULL`. | [optional]

Since: 2.46

### rsvg_handle_render_element ()

    gboolean
    rsvg_handle_render_element (RsvgHandle *handle,
                                cairo_t *cr,
                                const char *id,
                                const RsvgRectangle *element_viewport,
                                GError **error);

Renders a single SVG element to a given viewport

This function can be used to extract individual element subtrees and render them, scaled to a given `element_viewport` . This is useful for applications which have reusable objects in an SVG and want to render them individually; for example, an SVG full of icons that are meant to be be rendered independently of each other.

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.

You can pass NULL for the `id` if you want to render all the elements in the SVG, i.e. to render everything from the root element.

The `element_viewport` gives the position and size at which the named element will be rendered. FIXME: mention proportional scaling.

API ordering: This function must be called on a fully-loaded `handle` . See the section API ordering for details.

Panics: this function will panic if the `handle` is not fully-loaded.

#### Parameters

handle | An RsvgHandle |
cr | A Cairo context |
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 render the whole SVG document tree. | [nullable]
element_viewport | Viewport size in which to fit the element |
error | a location to store a GError, or `NULL`. | [optional]

Since: 2.46

### rsvg_handle_render_cairo ()

    gboolean
    rsvg_handle_render_cairo (RsvgHandle *handle,
                              cairo_t *cr);

Draws a loaded SVG handle to a Cairo context. Drawing will occur with respect to the `cr` 's current transformation: for example, if the `cr` has a rotated current transformation matrix, the whole SVG will be rotated in the rendered version.

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

Note that `cr` must be a Cairo context that is not in an error state, that is, `cairo_status()` must return CAIRO_STATUS_SUCCESS for it. Cairo can set a context to be in an error state in various situations, for example, if it was passed an invalid matrix or if it was created for an invalid surface.

#### Parameters

handle | A RsvgHandle |
cr | A Cairo context |

#### Returns

`TRUE` if drawing succeeded; `FALSE` otherwise.

Since: 2.14

### rsvg_handle_render_cairo_sub ()

    gboolean
    rsvg_handle_render_cairo_sub (RsvgHandle *handle,
                                  cairo_t *cr,
                                  const char *id);

Draws a subset of a loaded SVG handle to a Cairo context. Drawing will occur with respect to the `cr` 's current transformation: for example, if the `cr` has a rotated current transformation matrix, the whole SVG will be rotated in the rendered version.

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

Note that `cr` must be a Cairo context that is not in an error state, that is, `cairo_status()` must return CAIRO_STATUS_SUCCESS for it. Cairo can set a context to be in an error state in various situations, for example, if it was passed an invalid matrix or if it was created for an invalid surface.

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 |
cr | A Cairo context |
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 render the whole SVG. | [nullable]

#### Returns

`TRUE` if drawing succeeded; `FALSE` otherwise.

Since: 2.14