Using RSVG with cairo

Using RSVG with cairo

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

gboolean
rsvg_handle_get_intrinsic_size_in_pixels
                               (RsvgHandle *handle,
                                gdouble *out_width,
                                gdouble *out_height);

Converts an SVG document's intrinsic dimensions to pixels, and returns the result.

This function is able to extract the size in pixels from an SVG document if the document has both width and height attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em, ex). For physical units, the dimensions are normalized to pixels using the dots-per-inch (DPI) value set previously with rsvg_handle_set_dpi(). For font-based units, this function uses the computed value of the font-size property for the toplevel <svg> element. In those cases, this function returns TRUE.

This function is not able to extract the size in pixels directly from the intrinsic dimensions of the SVG document if the width or height are in percentage units (or if they do not exist, in which case the SVG spec mandates that they default to 100%), as these require a viewport to be resolved to a final size. In this case, the function returns FALSE.

For example, the following document fragment has intrinsic dimensions that will resolve to 20x30 pixels.

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

Similarly, if the DPI is set to 96, this document will resolve to 192x288 pixels (i.e. 96*2 x 96*3).

1
<svg xmlns="http://www.w3.org/2000/svg" width="2in" height="3in"/>

The dimensions of the following documents cannot be resolved to pixels directly, and this function would return FALSE for them:

1
2
3
4
5
6
<!-- Needs a viewport against which to compute the percentages. -->
<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%"/>

<!-- Does not have intrinsic width/height, just a 1:2 aspect ratio which
     needs to be fitted within a viewport. -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 200"/>

Parameters

handle

An RsvgHandle

 

out_width

Will be set to the computed width.

[out][optional]

out_height

Will be set to the computed height.

[out][optional]

Returns

TRUE if the dimensions could be converted directly to pixels; in this case out_width and out_height will be set accordingly. If the dimensions cannot be converted to pixels, returns FALSE and puts 0.0 in both out_width and out_height .

Since: 2.52


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 document is scaled proportionally to fit into this viewport.

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.

The viewport gives the position and size at which the whole SVG document would be rendered. The document is scaled proportionally to fit into this viewport; hence the individual layer may be smaller than this.

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

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

Please use rsvg_handle_render_document() instead; that function lets you pass a viewport and obtain a good error message.

Draws a loaded SVG handle to a Cairo context. Please try to use rsvg_handle_render_document() instead, which allows you to pick the size at which the document will be rendered.

Historically this function has picked a size by itself, based on the following rules:

  • If the SVG document has both width and height attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em, ex), the function computes the size directly based on the dots-per-inch (DPI) you have configured with rsvg_handle_set_dpi(). This is the same approach as rsvg_handle_get_intrinsic_size_in_pixels().
  • Otherwise, if there is a viewBox attribute and both width and height are set to 100% (or if they don't exist at all and thus default to 100%), the function uses the width and height of the viewBox as a pixel size. This produces a rendered document with the correct aspect ratio.
  • Otherwise, this function computes the extents of every graphical object in the SVG document to find the total extents. This is moderately expensive, but no more expensive than rendering the whole document, for example.
  • This function cannot deal with percentage-based units for width and height because there is no viewport against which they could be resolved; that is why it will compute the extents of objects in that case. This is why we recommend that you use rsvg_handle_render_document() instead, which takes in a viewport and follows the sizing policy from the web platform.

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

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

Please use rsvg_handle_render_layer() instead; that function lets you pass a viewport and obtain a good error message.

Renders a single SVG element in the same place as for a whole SVG document (a "subset" of the document). Please try to use rsvg_handle_render_layer() instead, which allows you to pick the size at which the document with the layer will be rendered.

This is equivalent to rsvg_handle_render_cairo(), but it renders only a single element and its children, as if they composed an individual layer in the SVG.

Historically this function has picked a size for the whole document by itself, based on the following rules:

  • If the SVG document has both width and height attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em, ex), the function computes the size directly based on the dots-per-inch (DPI) you have configured with rsvg_handle_set_dpi(). This is the same approach as rsvg_handle_get_intrinsic_size_in_pixels().
  • Otherwise, if there is a viewBox attribute and both width and height are set to 100% (or if they don't exist at all and thus default to 100%), the function uses the width and height of the viewBox as a pixel size. This produces a rendered document with the correct aspect ratio.
  • Otherwise, this function computes the extents of every graphical object in the SVG document to find the total extents. This is moderately expensive, but no more expensive than rendering the whole document, for example.
  • This function cannot deal with percentage-based units for width and height because there is no viewport against which they could be resolved; that is why it will compute the extents of objects in that case. This is why we recommend that you use rsvg_handle_render_layer() instead, which takes in a viewport and follows the sizing policy from the web platform.

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