Deprecated functions to render with Cairo: Librsvg Reference Manual

Deprecated functions to render with Cairo

Functions

gboolean	rsvg_handle_render_cairo ()
gboolean	rsvg_handle_render_cairo_sub ()

Description

Functions

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.