Struct rsvg::CairoRenderer

pub struct CairoRenderer<'a> { /* private fields */ }

Can render an SvgHandle to a Cairo context.

Implementations

impl<'a> CairoRenderer<'a>

pub fn new(handle: &'a SvgHandle) -> Self

Creates a CairoRenderer for the specified SvgHandle.

The default dots-per-inch (DPI) value is set to 96; you can change it with the with_dpi method.

pub fn with_dpi(self, dpi_x: f64, dpi_y: f64) -> Self

Configures the dots-per-inch for resolving physical lengths.

If an SVG document has physical units like 5cm, they must be resolved to pixel-based values. The default pixel density is 96 DPI in both dimensions.

pub fn with_language(self, language: &Language) -> Self

Configures the set of languages used for rendering.

SVG documents can use the <switch> element, whose children have a systemLanguage attribute; only the first child which has a systemLanguage that matches the preferred languages will be rendered.

This function sets the preferred languages. The default is Language::FromEnvironment, which means that the set of preferred languages will be obtained from the program’s environment. To set an explicit list of languages, you can use Language::AcceptLanguage instead.

pub fn with_cancellable<C: IsA<Cancellable>>(self, cancellable: &C) -> Self

Sets a cancellable to be able to interrupt rendering.

The rendering functions like render_document will normally render the whole SVG document tree. However, they can be interrupted if you set a cancellable object with this method. To interrupt rendering, you can call [gio::CancellableExt::cancel()] from a different thread than where the rendering is happening.

Since rendering happens as a side-effect on the Cairo context (cr) that is passed to the rendering functions, it may be that the cr’s target surface is in an undefined state if the rendering is cancelled. The surface may have not yet been painted on, or it may contain a partially-rendered document. For this reason, if your application does not want to leave the target surface in an inconsistent state, you may prefer to use a temporary surface for rendering, which can be discarded if your code cancels the rendering.

pub fn intrinsic_dimensions(&self) -> IntrinsicDimensions

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 render_document instead; it will do the scaling computations automatically.

See also intrinsic_size_in_pixels, which does the conversion to pixels if possible.

pub fn intrinsic_size_in_pixels(&self) -> Option<(f64, f64)>

Converts the SVG document’s intrinsic dimensions to pixels, if possible.

Returns Some(width, height) in pixel units if the SVG document has width and height attributes with physical dimensions (CSS pixels, cm, in, etc.) or font-based dimensions (em, ex).

Note that the dimensions are floating-point numbers, so your application can know the exact size of an SVG document. To get integer dimensions, you should use f64::ceil() to round up to the nearest integer (just using f64::round(), may may chop off pixels with fractional coverage).

If the SVG document has percentage-based width and height attributes, or if either of those attributes are not present, returns None. Dimensions of that kind require more information to be resolved to pixels; for example, the calling application can use a viewport size to scale percentage-based dimensions.

pub fn render_document( &self, cr: &Context, viewport: &Rectangle, ) -> Result<(), RenderingError>

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 RenderingError::Cairo with the cr’s current error state.

pub fn geometry_for_layer( &self, id: Option<&str>, viewport: &Rectangle, ) -> Result<(Rectangle, Rectangle), RenderingError>

Computes the (ink_rect, logical_rect) of an SVG element, as if the SVG were rendered to a specific viewport.

Element IDs should look like an URL fragment identifier; for example, pass Some("#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 None 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.

FIXME: example

pub fn render_layer( &self, cr: &Context, id: Option<&str>, viewport: &Rectangle, ) -> Result<(), RenderingError>

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

This is equivalent to render_document, but 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.

Note that the id must be a plain fragment identifier like #foo, with a leading # character.

The viewport gives the position and size at which the whole SVG document would be rendered. This function will effectively place the whole SVG within that viewport, but only render the element given by id.

The cr must be in a cairo::Status::Success state, or this function will not render anything, and instead will return RenderingError::Cairo with the cr’s current error state.

pub fn geometry_for_element( &self, id: Option<&str>, ) -> Result<(Rectangle, Rectangle), RenderingError>

Computes the (ink_rect, logical_rect) of a single SVG element

While 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 render_element.

Element IDs should look like an URL fragment identifier; for example, pass Some("#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 None 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.

FIXME: example

pub fn render_element( &self, cr: &Context, id: Option<&str>, element_viewport: &Rectangle, ) -> Result<(), RenderingError>

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.

Note that the id must be a plain fragment identifier like #foo, with a leading # character.

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

The cr must be in a cairo::Status::Success state, or this function will not render anything, and instead will return RenderingError::Cairo with the cr’s current error state.