Struct rsvg::CairoRenderer

source ·
pub struct CairoRenderer<'a> {
    pub(crate) handle: &'a SvgHandle,
    pub(crate) dpi: Dpi,
    user_language: UserLanguage,
    cancellable: Option<Cancellable>,
    is_testing: bool,
}
Expand description

Can render an SvgHandle to a Cairo context.

Fields§

§handle: &'a SvgHandle§dpi: Dpi§user_language: UserLanguage§cancellable: Option<Cancellable>§is_testing: bool

Implementations§

source§

impl<'a> CairoRenderer<'a>

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

fn rendering_options(&self) -> RenderingOptions

source

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.

source

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

source

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.

source

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

source

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.

Auto Trait Implementations§

§

impl<'a> !RefUnwindSafe for CairoRenderer<'a>

§

impl<'a> !Send for CairoRenderer<'a>

§

impl<'a> !Sync for CairoRenderer<'a>

§

impl<'a> Unpin for CairoRenderer<'a>

§

impl<'a> !UnwindSafe for CairoRenderer<'a>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
§

impl<SS, SP> SupersetOf<SS> for SP
where SS: SubsetOf<SP>,

§

fn to_subset(&self) -> Option<SS>

The inverse inclusion map: attempts to construct self from the equivalent element of its superset. Read more
§

fn is_in_subset(&self) -> bool

Checks if self is actually part of its subset T (and can be converted to it).
§

fn to_subset_unchecked(&self) -> SS

Use with care! Same as self.to_subset but without any property checks. Always succeeds.
§

fn from_subset(element: &SS) -> SP

The inclusion map: converts self to the equivalent element of its superset.
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.