Top | ![]() |
![]() |
![]() |
![]() |
GQuark | rsvg_error_quark () |
void | rsvg_cleanup () |
void | rsvg_set_default_dpi () |
void | rsvg_set_default_dpi_x_y () |
void | rsvg_handle_set_dpi () |
void | rsvg_handle_set_dpi_x_y () |
RsvgHandle * | rsvg_handle_new () |
RsvgHandle * | rsvg_handle_new_with_flags () |
gboolean | rsvg_handle_write () |
gboolean | rsvg_handle_close () |
const char * | rsvg_handle_get_base_uri () |
void | rsvg_handle_set_base_uri () |
void | rsvg_handle_get_dimensions () |
gboolean | rsvg_handle_get_dimensions_sub () |
gboolean | rsvg_handle_get_position_sub () |
void | rsvg_handle_get_intrinsic_dimensions () |
gboolean | rsvg_handle_get_geometry_for_element () |
gboolean | rsvg_handle_has_sub () |
const char * | rsvg_handle_get_title () |
const char * | rsvg_handle_get_desc () |
const char * | rsvg_handle_get_metadata () |
RsvgHandle * | rsvg_handle_new_from_data () |
RsvgHandle * | rsvg_handle_new_from_file () |
GType | rsvg_error_get_type () |
void | rsvg_init () |
void | rsvg_term () |
void | rsvg_handle_free () |
void | (*RsvgSizeFunc) () |
void | rsvg_handle_set_size_callback () |
enum | RsvgError |
#define | RSVG_ERROR |
struct | RsvgHandle |
struct | RsvgHandleClass |
struct | RsvgRectangle |
RsvgLength | |
enum | RsvgUnit |
struct | RsvgDimensionData |
struct | RsvgPositionData |
#define | RSVG_TYPE_ERROR |
This is the main entry point into the librsvg library. An RsvgHandle is an object that represents SVG data in memory. Your program creates an RsvgHandle from an SVG file, or from a memory buffer that contains SVG data, or in the most general form, from a GInputStream that will provide SVG data.
Librsvg can load SVG images and render them to Cairo surfaces, using a mixture of SVG's [static mode] and [secure static mode]. Librsvg does not do animation nor scripting, and can load references to external data only in some situations; see below.
Librsvg supports reading SVG 1.1 data, and is gradually adding support for features in SVG 2. Librsvg also supports SVGZ files, which are just an SVG stream compressed with the GZIP algorithm.
When you load an SVG, librsvg needs to know the location of the "base file"
for it. This is so that librsvg can determine the location of referenced
entities. For example, say you have an SVG in /foo/bar/foo.svg
and that it has an image element like this:
<image href="resources/foo.png" .../>
In this case, librsvg needs to know the location of the toplevel
/foo/bar/foo.svg
so that it can generate the appropriate
reference to /foo/bar/resources/foo.png
.
When processing an SVG, librsvg will only load referenced files if they are
in the same directory as the base file, or in a subdirectory of it. That is,
if the base file is /foo/bar/baz.svg
, then librsvg will
only try to load referenced files (from SVG's
<image>
element, for example, or from content
included through XML entities) if those files are in /foo/bar/*
or in /foo/bar/*/.../*
. This is so that malicious SVG files cannot include files
that are in a directory above.
The full set of rules for deciding which URLs may be loaded is as follows; they are applied in order. A referenced URL will not be loaded as soon as one of these rules fails:
data:
URLs may be loaded. These are sometimes used
to include raster image data, encoded as base-64, directly in an SVG file.
rsvg_handle_new_from_data()
without calling rsvg_handle_set_base_uri()
,
then any referenced files will not be allowed (e.g. raster images to be
loaded from other files will not work).
file
" scheme, then all URL references inside the SVG must
also have the "file
" scheme, or be relative references which
will be resolved against the base URL.
resource
" scheme, that is,
if they are included into your binary program with GLib's resource
mechanism, they are allowed to be loaded (provided that the base URL is
also a "resource
", per the previous rule).
file
schemes are not allowed. For
example, librsvg will not load http
resources, to keep
malicious SVG data from "phoning home".
This is the easiest and most resource-efficient way of loading SVG data into an RsvgHandle.
If you have a GFile that stands for an SVG file, you can simply call
rsvg_handle_new_from_gfile_sync()
to load an RsvgHandle from it.
Alternatively, if you have a GInputStream, you can use
rsvg_handle_new_from_stream_sync()
.
Both of those methods allow specifying a GCancellable, so the loading process can be cancelled from another thread.
If you already have SVG data in a byte buffer in memory, you can create a
memory input stream with g_memory_input_stream_new_from_data()
and feed that
to rsvg_handle_new_from_stream_sync()
.
Note that in this case, it is important that you specify the base_file for the in-memory SVG data. Librsvg uses the base_file to resolve links to external content, like raster images.
You can load an RsvgHandle from a simple filename or URI with
rsvg_handle_new_from_file()
. Note that this is a blocking operation; there
is no way to cancel it if loading a remote URI takes a long time. Also, note that
this method does not let you specify RsvgHandleFlags.
Otherwise, loading an SVG without GIO is not recommended, since librsvg will
need to buffer your entire data internally before actually being able to
parse it. The deprecated way of doing this is by creating a handle with
rsvg_handle_new()
or rsvg_handle_new_with_flags()
, and then using
rsvg_handle_write()
and rsvg_handle_close()
to feed the handle with SVG data.
Still, please try to use the GIO stream functions instead.
SVG images can contain dimensions like "5 cm
" or
"2 pt
" that must be converted from physical units into
device units. To do this, librsvg needs to know the actual dots per inch
(DPI) of your target device. You can call rsvg_handle_set_dpi()
or
rsvg_handle_set_dpi_x_y()
on an RsvgHandle to set the DPI before rendering
it.
The preferred way to render an already-loaded RsvgHandle is to use
rsvg_handle_render_cairo()
. Please see its documentation for details.
Alternatively, you can use rsvg_handle_get_pixbuf()
to directly obtain a
GdkPixbuf with the rendered image. This is simple, but it does not let you
control the size at which the SVG will be rendered. It will just be rendered
at the size which rsvg_handle_get_dimensions()
would return, which depends on
the dimensions that librsvg is able to compute from the SVG data.
void
rsvg_cleanup (void
);
rsvg_cleanup
has been deprecated since version 2.46 and should not be used in newly-written code.
No-op. This function should not be called from normal programs.
Since: 2.36
void
rsvg_set_default_dpi (double dpi
);
rsvg_set_default_dpi
has been deprecated since version 2.42.3 and should not be used in newly-written code.
This function used to set a global default DPI. However,
it only worked if it was called before any RsvgHandle objects had been
created; it would not work after that. To avoid global mutable state, please
use rsvg_handle_set_dpi()
instead.
Do not use this function. Create an RsvgHandle and call
rsvg_handle_set_dpi()
on it instead.
Since: 2.8
void rsvg_set_default_dpi_x_y (double dpi_x
,double dpi_y
);
rsvg_set_default_dpi_x_y
has been deprecated since version 2.42.3 and should not be used in newly-written code.
This function used to set a global default DPI. However,
it only worked if it was called before any RsvgHandle objects had been
created; it would not work after that. To avoid global mutable state, please
use rsvg_handle_set_dpi()
instead.
Do not use this function. Create an RsvgHandle and call
rsvg_handle_set_dpi_x_y()
on it instead.
Since: 2.8
void rsvg_handle_set_dpi (RsvgHandle *handle
,double dpi
);
Sets the DPI for the outgoing pixbuf. Common values are
75, 90, and 300 DPI. Passing a number <= 0 to dpi
will
reset the DPI to whatever the default value happens to be.
Since: 2.8
void rsvg_handle_set_dpi_x_y (RsvgHandle *handle
,double dpi_x
,double dpi_y
);
Sets the DPI for the outgoing pixbuf. Common values are
75, 90, and 300 DPI. Passing a number <= 0 to dpi_x or dpi_y
will
reset the DPI to whatever the default value happens to be.
handle |
An RsvgHandle |
|
dpi_x |
Dots Per Inch (aka Pixels Per Inch) |
|
dpi_y |
Dots Per Inch (aka Pixels Per Inch) |
Since: 2.8
RsvgHandle *
rsvg_handle_new (void
);
Returns a new rsvg handle. Must be freed with g_object_unref
. This
handle can be used to load an image.
The preferred way of loading SVG data into the returned RsvgHandle is with
rsvg_handle_read_stream_sync()
.
The deprecated way of loading SVG data is with rsvg_handle_write()
and
rsvg_handle_close()
; note that these require buffering the entire file
internally, and for this reason it is better to use the stream functions:
rsvg_handle_new_from_stream_sync()
, rsvg_handle_read_stream_sync()
, or
rsvg_handle_new_from_gfile_sync()
.
After loading the RsvgHandle with data, you can render it using Cairo or get
a GdkPixbuf from it. When finished, free the handle with g_object_unref()
. No
more than one image can be loaded with one handle.
Note that this function creates an RsvgHandle with no flags set. If you require
any of RsvgHandleFlags to be set, use rsvg_handle_new_with_flags()
or the stream
functions listed above.
RsvgHandle *
rsvg_handle_new_with_flags (RsvgHandleFlags flags
);
Creates a new RsvgHandle with flags flags
.
Since: 2.36
gboolean rsvg_handle_write (RsvgHandle *handle
,const guchar *buf
,gsize count
,GError **error
);
rsvg_handle_write
has been deprecated since version 2.46. and should not be used in newly-written code.
Use rsvg_handle_read_stream_sync()
or the constructor
functions rsvg_handle_new_from_gfile_sync()
or rsvg_handle_new_from_stream_sync()
.
Notes: This function will accumlate data from the buf
in memory until
rsvg_handle_close()
gets called. To avoid a big temporary buffer, use the
funtions listed before, which take a GFile or a GInputStream.
Loads the next count
bytes of the image.
handle |
an RsvgHandle |
|
buf |
pointer to svg data. |
[array length=count][element-type guchar] |
count |
length of the |
|
error |
[allow-none] |
gboolean rsvg_handle_close (RsvgHandle *handle
,GError **error
);
rsvg_handle_close
has been deprecated since version 2.46. and should not be used in newly-written code.
Use rsvg_handle_read_stream_sync()
or the constructor
functions rsvg_handle_new_from_gfile_sync()
or rsvg_handle_new_from_stream_sync()
.
Closes handle
, to indicate that loading the image is complete. This will
return TRUE
if the loader closed successfully and the SVG data was parsed
correctly. Note that handle
isn't freed until g_object_unref
is called.
const char *
rsvg_handle_get_base_uri (RsvgHandle *handle
);
Gets the base uri for this RsvgHandle.
Since: 2.8
void rsvg_handle_set_base_uri (RsvgHandle *handle
,const char *base_uri
);
Set the base URI for this SVG. This can only be called before rsvg_handle_write()
has been called.
Since: 2.9
void rsvg_handle_get_dimensions (RsvgHandle *handle
,RsvgDimensionData *dimension_data
);
Get the SVG's size. Do not call from within the size_func callback, because an infinite loop will occur.
Since: 2.14
gboolean rsvg_handle_get_dimensions_sub (RsvgHandle *handle
,RsvgDimensionData *dimension_data
,const char *id
);
rsvg_handle_get_dimensions_sub
has been deprecated since version 2.46. and should not be used in newly-written code.
Use rsvg_handle_get_geometry_for_element()
instead.
Get the size of a subelement of the SVG file. Do not call from within the size_func callback, because an infinite loop will occur.
handle |
||
dimension_data |
A place to store the SVG's size. |
[out] |
id |
An element's id within the SVG, starting with "##", for
example, "#layer1"; or |
[nullable] |
Since: 2.22
gboolean rsvg_handle_get_position_sub (RsvgHandle *handle
,RsvgPositionData *position_data
,const char *id
);
rsvg_handle_get_position_sub
has been deprecated since version 2.46. and should not be used in newly-written code.
Use rsvg_handle_get_geometry_for_element()
instead.
Get the position of a subelement of the SVG file. Do not call from within the size_func callback, because an infinite loop will occur.
handle |
||
position_data |
A place to store the SVG fragment's position. |
[out] |
id |
An element's id within the SVG, starting with "##", for
example, "#layer1"; or |
[nullable] |
Since: 2.22
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_to_viewport()
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
:
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="400">
Conversely, the following element has a viewBox
, but no width
or height
:
<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.
<svg xmlns="http://www.w3.org/2000/svg" width="210mm" height="297mm">
handle |
An RsvgHandle |
|
out_has_width |
Will be set to TRUE if the toplevel SVG has a |
[out][optional] |
out_width |
Will be set to the value of the |
[out][optional] |
out_has_height |
Will be set to TRUE if the toplevel SVG has a |
[out][optional] |
out_height |
Will be set to the value of the |
[out][optional] |
out_has_viewbox |
Will be set to TRUE if the toplevel SVG has a |
[out][optional] |
out_viewbox |
Will be set to the value of the |
[out][optional] |
Since: 2.46
gboolean rsvg_handle_get_geometry_for_element (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" 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.
handle |
An RsvgHandle |
|
id |
An element's id within the SVG, or |
[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 |
[allow-none] |
Since: 2.46
gboolean rsvg_handle_has_sub (RsvgHandle *handle
,const char *id
);
Checks whether the element id
exists in the SVG document.
Since: 2.22
const char *
rsvg_handle_get_title (RsvgHandle *handle
);
rsvg_handle_get_title
has been deprecated since version 2.36. and should not be used in newly-written code.
Librsvg does not read the metadata/desc/title elements; this function always returns NULL.
Since: 2.4
const char *
rsvg_handle_get_desc (RsvgHandle *handle
);
rsvg_handle_get_desc
has been deprecated since version 2.36. and should not be used in newly-written code.
Librsvg does not read the metadata/desc/title elements; this function always returns NULL.
Since: 2.4
const char *
rsvg_handle_get_metadata (RsvgHandle *handle
);
rsvg_handle_get_metadata
has been deprecated since version 2.36. and should not be used in newly-written code.
Librsvg does not read the metadata/desc/title elements; this function always returns NULL.
Since: 2.9
RsvgHandle * rsvg_handle_new_from_data (const guint8 *data
,gsize data_len
,GError **error
);
Loads the SVG specified by data
. Note that this function creates an
RsvgHandle without a base URL, and without any RsvgHandleFlags. If you
need these, use rsvg_handle_new_from_stream_sync()
instead by creating
a GMemoryInputStream from your data.
data |
The SVG data. |
[array length=data_len] |
data_len |
The length of |
|
error |
return location for errors |
Since: 2.14
RsvgHandle * rsvg_handle_new_from_file (const gchar *filename
,GError **error
);
Loads the SVG specified by file_name
.
Since: 2.14
void
rsvg_init (void
);
rsvg_init
has been deprecated since version 2.36 and should not be used in newly-written code.
There is no need to initialize librsvg.
This function does nothing.
Since: 2.9
void
rsvg_term (void
);
rsvg_term
has been deprecated since version 2.36 and should not be used in newly-written code.
There is no need to de-initialize librsvg.
This function does nothing.
Since: 2.9
void
rsvg_handle_free (RsvgHandle *handle
);
rsvg_handle_free
is deprecated and should not be used in newly-written code.
Use g_object_unref()
instead.
Frees handle
.
void (*RsvgSizeFunc) (gint *width
,gint *height
,gpointer user_data
);
RsvgSizeFunc
has been deprecated since version 2.14. and should not be used in newly-written code.
Set up a cairo matrix and use rsvg_handle_render_cairo()
instead.
See the documentation for rsvg_handle_set_size_callback()
for an example, and
for the reasons for deprecation.
Function to let a user of the library specify the SVG's dimensions
void rsvg_handle_set_size_callback (RsvgHandle *handle
,RsvgSizeFunc size_func
,gpointer user_data
,GDestroyNotify user_data_destroy
);
rsvg_handle_set_size_callback
has been deprecated since version 2.14. and should not be used in newly-written code.
Set up a cairo matrix and use rsvg_handle_render_cairo()
instead.
You can call rsvg_handle_get_dimensions()
to figure out the size of your SVG,
and then scale it to the desired size via Cairo. For example, the following
code renders an SVG at a specified size, scaled proportionally from whatever
original size it may have had:
void render_scaled_proportionally (RsvgHandle *handle, cairo_t cr, int width, int height) { RsvgDimensionData dimensions; double x_factor, y_factor; double scale_factor; rsvg_handle_get_dimensions (handle, &dimensions); x_factor = (double) width / dimensions.width; y_factor = (double) height / dimensions.height; scale_factor = MIN (x_factor, y_factor); cairo_scale (cr, scale_factor, scale_factor); rsvg_handle_render_cairo (handle, cr); }
This function was deprecated because when the size_func
is used, it makes it
unclear when the librsvg functions which call the size_func
will use the
size computed originally, or the callback-specified size, or whether it
refers to the whole SVG or to just a sub-element of it. It is easier, and
unambiguous, to use code similar to the example above.
Sets the sizing function for the handle
, which can be used to override the
size that librsvg computes for SVG images. The size_func
is called from the
following functions:
Librsvg computes the size of the SVG being rendered, and passes it to the
size_func
, which may then modify these values to set the final size of the
generated image.
handle |
An RsvgHandle |
|
size_func |
A sizing function, or |
[nullable] |
user_data |
User data to pass to |
|
user_data_destroy |
Function to be called to destroy the data passed in |
struct RsvgHandleClass { GObjectClass parent; };
Class structure for RsvgHandle.
struct RsvgRectangle { double x; double y; double width; double height; };
A data structure for holding a rectangle.
Since: 2.46
typedef struct { double length; RsvgUnit unit; } RsvgLength;
RsvgLength values are used in rsvg_handle_get_intrinsic_dimensions()
, for
example, to return the CSS length values of the width
and
height
attributes of an <svg>
element.
This is equivalent to CSS lengths.
It is up to the calling application to convert lengths in non-pixel units
(i.e. those where the unit
field is not RSVG_UNIT_PX) into something
meaningful to the application. For example, if your application knows the
dots-per-inch (DPI) it is using, it can convert lengths with unit
in
RSVG_UNIT_IN or other physical units.
Units for the RsvgLength struct. These have the same meaning as
struct RsvgDimensionData { int width; int height; gdouble em; gdouble ex; };
RsvgDimensionData
has been deprecated since version 2.46. and should not be used in newly-written code.
FIXME: point to deprecation documentation.
Dimensions of an SVG image from rsvg_handle_get_dimensions()
, or an
individual element from rsvg_handle_get_dimensions_sub()
. Please see
the deprecation documentation for those functions.
SVG's width, in pixels |
||
SVG's height, in pixels |
||
gdouble |
SVG's original width, unmodified by RsvgSizeFunc |
|
gdouble |
SVG's original height, unmodified by RsvgSizeFunc |
struct RsvgPositionData { int x; int y; };
RsvgPositionData
has been deprecated since version 2.46. and should not be used in newly-written code.
FIXME: point to deprecation documentation.
Position of an SVG fragment from rsvg_handle_get_position_sub()
. Please
the deprecation documentation for that function.