<?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>
