Include an example of usage from C

Holy crap, including C code into DocBook actually works!

Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/588>

2 files changed, 121 insertions, 4 deletions

diff --git a/doc/load-and-render.c b/doc/load-and-render.c
new file mode 100644
index 00000000..cac59eee
--- /dev/null
+++ b/doc/load-and-render.c
@@ -0,0 +1,59 @@
+/* gcc -Wall -g -O2 -o load-and-render load-and-render.c `pkg-config --cflags --libs rsvg-2.0` */
+
+#include <stdlib.h>
+#include <librsvg/rsvg.h>
+
+#define WIDTH 640
+#define HEIGHT 480
+
+int
+main (void)
+{
+  /* First, load an SVG document into an RsvgHandle */
+
+  GError *error = NULL;
+  GFile *file = g_file_new_for_path ("hello.svg");
+  RsvgHandle *handle = rsvg_handle_new_from_gfile_sync (file, RSVG_HANDLE_FLAGS_NONE, NULL, &error);
+
+  if (!handle)
+    {
+      g_printerr ("could not load: %s", error->message);
+      exit (1);
+    }
+
+  /* Create a Cairo image surface and a rendering context for it */
+
+  cairo_surface_t *surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32, WIDTH, HEIGHT);
+  cairo_t *cr = cairo_create (surface);
+
+  /* Render the handle scaled proportionally into that whole surface */
+
+  RsvgRectangle viewport = {
+    .x = 0.0,
+    .y = 0.0,
+    .width = WIDTH,
+    .height = HEIGHT,
+  };
+
+  if (!rsvg_handle_render_document (handle, cr, &viewport, &error))
+    {
+      g_printerr ("could not render: %s", error->message);
+      exit (1);
+    }
+
+  /* Write a PNG file */
+
+  if (cairo_surface_write_to_png (surface, "hello.png") != CAIRO_STATUS_SUCCESS)
+    {
+      g_printerr ("could not write output file");
+      exit (1);
+    }
+
+  /* Free our memory and we are done! */
+
+  cairo_destroy (cr);
+  cairo_surface_destroy (surface);
+  g_object_unref (handle);
+  g_object_unref (file);
+  return 0;
+}
diff --git a/doc/overview.xml b/doc/overview.xml
index c930d887..d0d3eea2 100644
--- a/doc/overview.xml
+++ b/doc/overview.xml
@@ -11,7 +11,7 @@
     it to render itself to a Cairo context.
   </para>
 
-  <formalpara>
+  <section>
     <title>Loading</title>
 
     <para>
@@ -23,9 +23,19 @@
       loading completes successfully, the RsvgHandle will be ready for
       rendering.
     </para>
-  </formalpara>
 
-  <formalpara>
+    <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>
@@ -36,5 +46,53 @@
       render only that element; this is so that sub-elements can be
       extracted conveniently out of a larger SVG.
     </para>
-  </formalpara>
+
+    <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>