Rsvg.Handle.render_cairo_sub

### Method

# Rsvg Handlerender_cairo_sub

deprecated: 2.52. since: 2.14

#### Declaration [src]

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

#### Description [src]

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.

Available since: 2.14

Deprecated since: 2.52.

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

#### Parameters

`cr`

  Type: `cairo_t`

  A Cairo context.

  The data is owned by the caller of the method.

`id`

  Type: `const char*`

  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.

  The argument can be `NULL`.
  The data is owned by the caller of the method.
  The value is a NUL terminated UTF-8 string.

#### Return value

Type: `gboolean`

`TRUE` if drawing succeeded; `FALSE` otherwise. This function will emit a `g_warning()` if a rendering error occurs.