1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
<?xml version="1.0" encoding="UTF-8" ?>
<chapter>
<title>Overview of Librsvg's API</title>
<para>
Librsvg's API is divided into two main parts: one for loading SVG
data and one for rendering it. In the <emphasis>loading
stage</emphasis>, you create an RsvgHandle object from SVG data,
which can come from a file or from a stream of bytes. In the
<emphasis>rendering stage</emphasis>, you take an RsvgHandle and ask
it to render itself to a Cairo context.
</para>
<section>
<title>Loading</title>
<para>
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 GIO stream that will provide SVG data. At this
stage you can get either I/O errors or parsing errors. If
loading completes successfully, the RsvgHandle will be ready for
rendering.
</para>
<para>
Generally you should use
<function>rsvg_handle_new_from_gfile_sync()</function> or
<function>rsvg_handle_new_from_stream_sync()</function> to load
an SVG document into an RsvgHandle. There are other convenience
functions to load an SVG document, but these two functions let
one set the "base file" and the RsvgHandleFlags in a single
call.
</para>
</section>
<section>
<title>Rendering</title>
<para>
Once you have an SVG image loaded into an RsvgHandle, you can
render it to a Cairo context any number of times, or to
different Cairo contexts, as needed. As a convenience, you can
pick a single element in the SVG by its "id" attribute and
render only that element; this is so that sub-elements can be
extracted conveniently out of a larger SVG.
</para>
<para>
Generally you should use
<function>rsvg_handle_render_document()</function> to render the
whole SVG document at any size you choose into a Cairo context.
</para>
</section>
<section>
<title>Example: simple loading and rendering</title>
<para>
The following program loads <filename>hello.svg</filename>,
renders it scaled to fit within 640x480 pixels, and writes a
<filename>hello.png</filename> file.
</para>
<para>
Note the following:
</para>
<itemizedlist>
<listitem>
<para>
<function>rsvg_handle_render_document()</function> will
scale the document proportionally to fit the viewport you
specify, and it will center the image within that viewport.
</para>
</listitem>
<listitem>
<para>
Librsvg does not paint a background color by default, so in
the following example all unfilled areas of the SVG will
appear as fully transparent. If you wish to have a specific
background, fill the viewport area yourself before rendering
the SVG.
</para>
</listitem>
</itemizedlist>
<example>
<title>Load and render an SVG document as a PNG</title>
<programlisting>
<xi:include href="load-and-render.c" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</programlisting>
</example>
</section>
</chapter>
|