Current File : //proc/self/root/kunden/kunden/usr/share/doc/liblqr-1-devel/liblqr_manual.docbook
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DOcBook XML V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd" [
    <!ENTITY lqr "Liquid Rescale">
    <!ENTITY lqrl "&lqr; library">
    <!ENTITY carv_obj "<classname>LqrCarver</classname>">
    <!ENTITY carvl_obj "<classname>LqrCarverList</classname>">
    <!ENTITY vmap_obj "<classname>LqrVMap</classname>">
    <!ENTITY vmapl_obj "<classname>LqrVMapList</classname>">
    <!ENTITY rwin_obj "<classname>LqrReadingWindow</classname>">
    <!ENTITY prog_obj "<classname>LqrProgress</classname>">
    <!ENTITY ret_true "<literal><returnvalue>TRUE</returnvalue></literal>">
    <!ENTITY ret_false "<literal><returnvalue>FALSE</returnvalue></literal>">
    <!ENTITY ret_null "<literal><returnvalue>NULL</returnvalue></literal>">
    <!ENTITY param_x "<parameter>x</parameter>">
    <!ENTITY param_y "<parameter>y</parameter>">
    <!ENTITY param_w "<parameter>width</parameter>">
    <!ENTITY param_h "<parameter>height</parameter>">
    <!ENTITY param_channels "<parameter>channels</parameter>">
    <!ENTITY param_depth "<parameter>depth</parameter>">
    <!ENTITY col_depth_8i "<literal>LQR_COLDEPTH_8I</literal>">
    <!ENTITY col_depth_16i "<literal>LQR_COLDEPTH_16I</literal>">
    <!ENTITY col_depth_32f "<literal>LQR_COLDEPTH_32F</literal>">
    <!ENTITY col_depth_64f "<literal>LQR_COLDEPTH_64F</literal>">
    <!ENTITY img_type_grey "<literal>LQR_GREY_IMAGE</literal>">
    <!ENTITY img_type_greya "<literal>LQR_GREYA_IMAGE</literal>">
    <!ENTITY img_type_rgb "<literal>LQR_RGB_IMAGE</literal>">
    <!ENTITY img_type_rgba "<literal>LQR_RGBA_IMAGE</literal>">
    <!ENTITY img_type_cmy "<literal>LQR_CMY_IMAGE</literal>">
    <!ENTITY img_type_cmyk "<literal>LQR_CMYK_IMAGE</literal>">
    <!ENTITY img_type_cmyka "<literal>LQR_CMYKA_IMAGE</literal>">
    <!ENTITY img_type_custom "<literal>LQR_CUSTOM_IMAGE</literal>">
    <!ENTITY err_ok "<literal><errorcode>LQR_OK</errorcode></literal>">
    <!ENTITY err_err "<literal><errorcode>LQR_ERROR</errorcode></literal>">
    <!ENTITY err_nomem "<literal><errorcode>LQR_NOMEM</errorcode></literal>">
    <!ENTITY err_cancel "<literal><errorcode>LQR_USRCANCEL</errorcode></literal>">
    <!ENTITY prog_init_w_mess "<computeroutput>&quot;Resizing width...&quot;</computeroutput>">
    <!ENTITY prog_init_h_mess "<computeroutput>&quot;Resizing height...&quot;</computeroutput>">
    <!ENTITY prog_end_w_mess "<computeroutput>&quot;done&quot;</computeroutput>">
    <!ENTITY prog_end_h_mess "<computeroutput>&quot;done&quot;</computeroutput>">
    ]>

<book id="liblqr-manual" lang="en">

    <bookinfo>
        <title>The &lqrl; Manual</title>
        <author>
            <firstname>Carlo</firstname>
            <surname>Baldassi</surname>
        </author>
        <productname class='copyright'>LqR library</productname>
        <productnumber>0.4.2 API (3:2:3)</productnumber>
        <copyright>
            <year>2007</year>
            <year>2008</year>
            <year>2009</year>
            <holder>Carlo Baldassi</holder>
        </copyright>
        <date>10 Maj 2009</date>
    </bookinfo>

    <chapter id="Introduction">

        <title>Introduction</title>
        <sect1 id="copyright">
            <title>Copyright</title>
            <para>
                Liquid Rescale Library Manual.
                Copyright (C) 2007-2009 Carlo Baldassi <email>carlobaldassi@gmail.com</email>
            </para>
            <para>
                This manual is released under the terms of the GNU General Public License as published by the Free
                Software Foundation; version 3 dated June, 2007.
            </para>
            <para>
                You should have received a copy of the GNU General Public License along with the library; if not, see
                <ulink url="http://www.gnu.org/licenses">http://www.gnu.org/licenses</ulink>
            </para>
        </sect1>

        <sect1 id="about-this-doc">
            <title>About this document</title>
            <para>
                This manual describes in detail the &lqrl; API, starting from a brief overview on seam carving, the
                internal image representation, a minimal list of basic methods and the full explanation of all the
                library public methods.
            </para>
            <para>
                In the `<filename>examples</filename>' directory, you will find a minimal example program, which only
                uses basic methods, and a full-featured demo program, which uses almost all of the methods described in
                this document. Both programs are fully commented, see also the <filename>README</filename> file in the
                `<filename>examples</filename>' directory.
            </para>
            <para>
                Refer to the <filename>README</filename> file for information about installing and compiling.
            </para>
            <para>
                The latest version of the &lqrl; and of this manual can be found at
                <ulink url="http://liblqr.wikidot.com">http://liblqr.wikidot.com</ulink>.
            </para>
        </sect1>

        <sect1 id="seam-carve">
            <title>Seam carving in brief</title>
            <para>
                Basically, the rescaling algorithm tries to find out which parts of the image are important, and which
                are not, based on the contrast between adjacent pixels; then, the image is resized through the
                elimination or insertion of continuous paths, called `seams'. The seams connect the top of the image
                with the bottom when rescaling horizontally, or they connect the left side with the right side when
                rescaling vertically. In the seam carving process, seams are removed in sequence, therefore shrinking
                the image by one pixel at a time. The seam insertion process mirrors the seam carving process,
                introducing interpolated seams in regions where they would have been carved.
            </para>
            <para>
                Once it has been computed, the carving information can be efficiently stored in a so called multi-sized
                image, which can be used to reproduce the carving operation on the fly at any later moment. 
            </para>
            <para>
                It often happens that the automatic feature detection fails to identify as significant some image
                regions; in these cases a preservation mask can be specified, which marks those regions. In fact, the
                feature recognition process can be manually driven quite easily to its full extent, by using custom
                masks.
            </para>
            <para>
                See also the <link linkend="references">References</link> section for more information about the
                algorithm.
            </para>

            <sect2 id="about-enlarge">
                <title>About enlarging</title>
                <para>
                    As mentioneed above, the enlargment process mirrors the carving process. More precisely, in order to
                    enlarge the image by a given amount of pixels, say N, the library first computes which would be the
                    first N seams to be removed; then, it inserts N new seams nearby those.
                </para>
                <para>
                    This means that it is clearly not possible to go beyond twice the original size in a single step. It
                    also means that doubling the image size in this way is just equivalent to standard scaling, since
                    the result is that each seam is just duplicated. For these reasons, the library rescaling engine
                    automatically divides enlarging sessions in steps, and allows to set the step size.
                </para>
                <para>
                    This same issue also affects in a tricky way the preservation of image areas when enlarging: suppose
                    your image is 1000 pixels wide, and you have protected an area which is 800 pixels wide. It is then
                    clear that you cannot shrink the image to less than 800 pixels without affecting the preserved area,
                    but the same is true when enlarging, so you should not go beyond 1200 pixels in a single step (=
                    1000 + (1000 - 800)), i.e. you should use a value lower than 1.2 for the enlargement step size.
                </para>
                <para>
                    In general, however, the optimal enlargement step size depends on the image, since large step sizes
                    have the disadvantages discussed above, while small step sizes will tend to inflate the same areas
                    of the image over and over at each step.
                </para>
            </sect2>
        </sect1>


        <sect1 id="overview">
            <title>Overview of the library</title>
            <para>
                The &lqrl; is written in C, but can be used into C++ programs without any modification. It has an
                object-oriented design, so that the terminology in this manual is borrowed from C++. The central class
                of the library is called &carv_obj;. Carver objects can generate and store multi-size images, or load
                them, and read them out at the desired size.
            </para>
            <para>
                Internally, multi-size images are stored simply as plain images with the addition of a visibility map.
                Each pixel in the image has its own visibility level. Whether to display a pixel or not simply depends
                on the comparison of each pixel's visibility with a given global visibility level. In this way, images
                of different sizes can be read out, simply by setting a global visibility level.
            </para>
            <para>
                Therefore, once the visibility map has been computed, it allows effortless, real-time scaling. However,
                visibility maps also necessarily have an orientation, either horizontal or vertical. If we want to
                resize on the other direction, the visibility map has to be computed afresh, and the previous visibility
                map becomes useless, because the two maps are not consistent one with the other.
            </para>
            <para>
                This also implies that the resizing order affects the final result: rescaling horizontally first, then
                vertically, does not yield the same result as following the reverse order. Moreover, one could choose an
                intermediate way, e.g. by rescaling by one pixel in one direction, one in the other, then iterating as
                needed to reach the final size.
            </para>
            <para>
                The default behaviour of the library is to rescale horizontally first, then vertically, but this order
                can be reversed.
            </para>
            <para>
                Visibility maps can be stored in objects of type &vmap_obj;. When an &carv_obj; object is created from
                an input image, the visibility of each pixel is uninitialised. At this point, one could either import a
                previously computed &vmap_obj;, or activate the &carv_obj; so that it creates one afresh when asked to.
            </para>
            <para>
                In either case, there's a single method to call, specifiying the new desired size; all the rest will
                automatically be computed as necessary. By default, the visibility maps are only computed up to the
                extent to which they are needed for resizing.
            </para>
        </sect1>

        <sect1 id="basic">
            <title>Basic methods</title>
            <para>
                Following is a list of the basic public methods associated with the &carv_obj; objects:
            </para>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>
                            constructors and destructor
                        </para>
                        <para>
                            <programlisting>
LqrCarver * lqr_carver_new (guchar *buffer, gint width, gint height, gint channels);
LqrCarver * lqr_carver_new_ext (void *buffer, gint width, gint height, gint channels, LqrColDepth colour_depth);
void lqr_carver_destroy (LqrCarver *carver);
                            </programlisting>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            initialization
                        </para>
                        <para>
                            <programlisting>
LqrRetVal lqr_carver_init (LqrCarver *carver, gint delta_x, gfloat rigidity);
                            </programlisting>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            image manipulations
                        </para>
                        <para>
                            <programlisting>
LqrRetVal lqr_carver_resize (LqrCarver *carver, gint new_width, gint new_width);
LqrRetVal lqr_carver_flatten (LqrCarver *carver);
                            </programlisting>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            readout
                        </para>
                        <para>
                            <programlisting>
gboolean lqr_carver_scan (LqrCarver *carver, gint *x, gint *y, guchar **rgb);
gboolean lqr_carver_scan_ext (LqrCarver *carver, gint *x, gint *y, void **rgb);
gboolean lqr_carver_scan_by_row (LqrCarver *carver);
gboolean lqr_carver_scan_line (LqrCarver *carver, gint *n, guchar **rgb);
gboolean lqr_carver_scan_line_ext (LqrCarver *carver, gint *n, void **rgb);
                            </programlisting>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            get values
                        </para>
                        <para>
                            <programlisting>
gint lqr_carver_get_width (LqrCarver *carver);
gint lqr_carver_get_height (LqrCarver *carver);
gint lqr_carver_get_channels (LqrCarver *carver);
LqrColDepth lqr_carver_get_col_depth (LqrCarver *carver);
                            </programlisting>
                        </para>
                    </listitem>

                </itemizedlist>
            </para>
            <para>
                The fastest way to see how they work is having a look at the code of
                <filename>examples/liquidrescale-basic.cpp</filename>, which is a very simple and fully commented
                demostrative program.
            </para>
            <para>
                The return value of many functions is of type <classname>LqrRetVal</classname>. This is just an enum
                type which can be used for signal handling, see the <link linkend="signals">Signal handling
                section</link>.
            </para>
            <para>
                The other classes are optional: the class &vmap_obj; is used to hold the carving information (and the
                class &vmapl_obj; is used to retrieve it from the &carv_obj; ojects); the class &prog_obj; is used to
                customize progress report from the resizing engine (by default it is turned off).
            </para>
            <para>
                A complete list of the library public methods can be found in the reference at the end of this document.
            </para>
        </sect1>
    </chapter>

    <chapter id="api-manual">

        <title>LqR library API user manual</title>

        <sect1 id="signals">
            <title>Signal handling</title>
            <para>
                Many library functions return a value of type <classname>LqrRetVal</classname>. This is an enum type
                which can hold the values:
                <variablelist>
                    <varlistentry>
                        <term>&err_ok;</term>
                        <listitem>
                            <para>
                                everyting OK
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>&err_err;</term>
                        <listitem>
                            <para>
                                generic <errortype>fatal</errortype> error
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>&err_nomem;</term>
                        <listitem>
                            <para>
                                not enough memory
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term>&err_cancel;</term>
                        <listitem>
                            <para>
                                action cancelled by the user
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </para>
            <para>
                At top level, it is important that the user handle these values explicitly, because the library
                functions don't do anything else than stopping and returning an error signal in case of errors. An easy
                way is setting up some macros and wrap each function call with those, as shown in the example files.
            </para>
            <para>
                Below top level, the library provides some convenient macros which can be used to wrap function calls,
                in order to propagate these signals:
                <variablelist>
                    <varlistentry>
                        <term><literal><function>LQR_CATCH</function> (<parameter>expr</parameter>)</literal></term>
                        <listitem>
                            <para>
                                if <parameter>expr</parameter> is equal to &err_ok; it does nothing, otherwise it
                                returns <parameter>expr</parameter> (or the result of the execution of
                                <parameter>expr</parameter> if it happens to be a function)
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><literal><function>LQR_CATCH_F</function> (<parameter>expr</parameter>)</literal></term>
                        <listitem>
                            <para>
                                returns &err_err; if <parameter>expr</parameter> is <literal>FALSE</literal>
                            </para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><literal><function>LQR_CATCH_MEM</function> (<parameter>expr</parameter>)</literal></term>
                        <listitem>
                            <para>
                                returns &err_nomem; if <parameter>expr</parameter> is <literal>NULL</literal>
                            </para>
                        </listitem>
                    </varlistentry>
                </variablelist>
                <note>
                    <para>
                        The names of these macros have changed since version <literal>0.4</literal>; the previous names
                        <function>CATCH</function>, <function>CATCH_F</function> and <function>CATCH_MEM</function> are
                        still available, but they can be disabled at configure time if they cause conflicts
                        (<command>configure --help</command> for details).
                    </para>
                </note>

            </para>
        </sect1>

        <sect1 id="generate-multi-size">
            <title>Generating the multi-size image</title>

            <sect2 id="carver-new">
                <title>Carver object creation</title>
                <para>
                    The &carv_obj; objects are initialised from a plain buffer representing an image. The default
                    constructor assumes a colour depth of 8 bits per channel:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrCarver * <function>lqr_carver_new</function></funcdef>
                            <paramdef> guchar * <parameter>buffer</parameter></paramdef>
                            <paramdef> gint <parameter>width</parameter></paramdef>
                            <paramdef> gint <parameter>height</parameter></paramdef>
                            <paramdef> gint <parameter>channels</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Here, <parameter>buffer</parameter> is the array representing an image of size
                    <parameter>width</parameter> by <parameter>height</parameter> with <parameter>channels</parameter>
                    colour channels per pixels. Thus, the overall buffer size has to be of
                    <literal><parameter>widht</parameter> * <parameter>height</parameter> *
                    <parameter>channels</parameter> </literal> unsigned characters, and ordered such that the
                    <literal><symbol>k</symbol></literal>-th colour of the pixel at row
                    <literal><symbol>y</symbol></literal> and column <literal><symbol>x</symbol></literal> is found at:
                    <programlisting>buffer[(y * width + x) * channels + k]</programlisting> (this assumes that
                    <literal><symbol>x</symbol></literal>, <literal><symbol>y</symbol></literal> and
                    <literal><symbol>k</symbol></literal> all start from <literal>0</literal> and reach the maximum
                    values <literal><symbol>widht</symbol>-1</literal>, <literal><symbol>height</symbol>-1</literal> and
                    <literal><symbol>channels</symbol>-1</literal>, respectively)
                </para>
                <para>
                    The function returns a pointer to the newly allocated &carv_obj; upon success, or
                    <literal><returnvalue>NULL</returnvalue></literal> in case of insufficient memory.
                </para>
                <para>
                    In order to create &carv_obj; objects with more than 8 bits per channel, an extended version of the
                    constructor must be used:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrCarver * <function>lqr_carver_new_ext</function></funcdef>
                            <paramdef> void * <parameter>buffer</parameter></paramdef>
                            <paramdef> gint <parameter>width</parameter></paramdef>
                            <paramdef> gint <parameter>height</parameter></paramdef>
                            <paramdef> gint <parameter>channels</parameter></paramdef>
                            <paramdef> LqrColDepth <parameter>colour_depth</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    The differnece with the default version is that the input buffer must be passed as void, and its
                    type must be specified through the additional parameter <parameter>colour_depth</parameter>, which
                    can take one of the following values:
                    <variablelist>
                        <varlistentry>
                            <term>&col_depth_8i;</term>
                            <listitem>
                                <para>
                                    8 bit unsigned integers (<type>guchar</type>)
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>&col_depth_16i;</term>
                            <listitem>
                                <para>
                                    16 bit unsigned integers (<type>guint16</type>)
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>&col_depth_32f;</term>
                            <listitem>
                                <para>
                                    32 bit floating point (<type>gfloat</type>)
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>&col_depth_64f;</term>
                            <listitem>
                                <para>
                                    64 bit floating point (<type>gdouble</type>)
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </para>
                <para>
                    Floating point type values must range between <literal>0</literal> and <literal>1</literal>.
                </para>
                <para>
                    The library has some support for different image types and color models. When a &carv_obj; object is
                    created, the image type is automatically set from the number of channels (basically, assuming that
                    the image is either grayscale or RGB with possibly an alpha channel), but it is important to set it
                    manually using the function <function>lqr_carver_set_image_type</function> if your program has to
                    deal with different color models. See the section <link linkend="image-type">Choosing the image
                    type</link> for more details.
                </para>
                <para>
                    By default, the buffer is assumed to be a copy of the original image, and therefore it is owned by
                    the &carv_obj; object and must not be accessed directly any more (and of course it must not be
                    freed, the &carv_obj; <link linkend="release">destructor</link> does it). If, instead, you want the
                    &lqrl; to keep the buffer intact, you must flag the &carv_obj; after creation (or after
                    <link linkend="carver-init">activation</link>), using this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_preserve_input_image</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    This function must be used before any other operation takes place.
                </para>
            </sect2>

            <sect2 id="carver-init">
                <title>Carver activation</title>
                <para>
                    The newly created &carv_obj; consists only of the image buffer plus an uninitialised visibility map.
                    If one had a previously computed visibility map, it could be imported into the &carv_obj; and that
                    would be enough (see the <link linkend="import-vmap">Importing a visibility map in a carver</link>
                    section).
                </para>
                <para>
                    If the visibility map has to be computed, the &carv_obj; needs to be initialised through this
                    function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_init</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef> gint <parameter>delta_x</parameter></paramdef>
                            <paramdef> gfloat <parameter>rigidity</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Here, <parameter>delta_x</parameter> is the maximum allowed transversal step of the seams (0 means
                    straight seams, the typical value is 1), while the <parameter>rigidity</parameter> parameter can be
                    used to introduce a global bias for non-straight seams (the typical value is 0; a nonzero value can
                    be modulated locally for specific areas using the functions described in section
                    <link linkend="rigmask">Adding a rigidity mask</link>).
                </para>
                <important>
                    <para>
                        It is currently an error to initalise a carver object if a visibility map has been imported
                        already.
                    </para>
                </important>
            </sect2>

            <sect2 id="image-type">
                <title>Choosing the image type</title>
                <para>
                    The library supports a small number of different image types/color models in order to correctly
                    compute quantities such as the brightness of a pixel, which are important for automatic feature
                    detection.
                </para>
                <para>
                    The image type can be set manually using the function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_image_type</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef> LqrImageType <parameter>image_type</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The type <type>LqrImageType</type> is an <literal>enum</literal> which can take these values:
                    <itemizedlist>
                        <listitem>&img_type_grey;</listitem>
                        <listitem>&img_type_greya;</listitem>
                        <listitem>&img_type_rgb;</listitem>
                        <listitem>&img_type_rgba;</listitem>
                        <listitem>&img_type_cmy;</listitem>
                        <listitem>&img_type_cmyk;</listitem>
                        <listitem>&img_type_cmyka;</listitem>
                        <listitem>&img_type_custom;</listitem>
                    </itemizedlist>
                </para>
                <para>
                    When creating a &carv_obj; object, the image type is inferred from the number of channels according
                    to this table:
                    <table id="def-image-types">
                        <title>Image types assigned by default</title>
                        <tgroup cols="2">
                            <thead>
                                <row>
                                    <entry>channels</entry>
                                    <entry>type</entry>
                                </row>
                            </thead>
                            <tbody>
                                <row>
                                    <entry>1</entry>
                                    <entry>&img_type_grey;</entry>
                                </row>
                                <row>
                                    <entry>2</entry>
                                    <entry>&img_type_greya;</entry>
                                </row>
                                <row>
                                    <entry>3</entry>
                                    <entry>&img_type_rgb;</entry>
                                </row>
                                <row>
                                    <entry>4</entry>
                                    <entry>&img_type_rgba;</entry>
                                </row>
                                <row>
                                    <entry>5</entry>
                                    <entry>&img_type_cmyka;</entry>
                                </row>
                                <row>
                                    <entry>&gt;5</entry>
                                    <entry>&img_type_custom;</entry>
                                </row>
                            </tbody>
                        </tgroup>
                    </table>
                </para>
                <para>
                    When setting a carver to &img_type_custom;, it is assumed that there are no alpha or black channels,
                    but if there are, their index can be specified with the functions:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_alpha_channel</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef> gint <parameter>channel_index</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_black_channel</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef> gint <parameter>channel_index</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    Use the value <literal>-1</literal> in the indices arguments to unset those channels. Note that
                    using &img_type_custom; in a carver normally requires special care in the choice and definitions of
                    the energy functions (see the <link linkend="energy">Automatic feature detection</link> section).
                </para>
                <note>
                    <para>
                        Setting manually the alpha or black channel with the above functions automatically sets the
                        carver image type to &img_type_custom;.
                    </para>
                </note>
                <note>
                    <para>
                        The support for CMY (and derived) color models is very naïve, since no color profiles are yet
                        managed by the library.
                    </para>
                </note>
            </sect2>
        </sect1>

        <sect1 id="lqr">
            <title>Liquid rescaling</title>

            <sect2 id="lqr-resize">
                <title>The resizing method</title>
                <para>
                    Once initialised, or if a visibility map has been loaded, the image can be resized through this
                    function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_resize</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef> gint <parameter>new_width</parameter></paramdef>
                            <paramdef> gint <parameter>new_height</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    This function decides automatically whether it can use the already computed visibility map, it has
                    to update it or waste it completely and start afresh. This last event occurs when the map was
                    computed for horizontal resizing and a vertical resize has been requested, or vice versa, and also
                    when the required enlargment is bigger than the enlargement step value (see
                    <link linkend="lqr-enl-step">Setting the enlargement step</link>). Note that only initialised
                    carvers can update or change the visibility map; if this is not the case, an error is returned.
                </para>
                <para>
                    The function also takes advantage of the fact that the enlargment process mirrors the shrink
                    process. For example, if the original size of the image is <literal>(<symbol>w0</symbol>,
                    <symbol>h0</symbol>)</literal> and <function>lqr_carver_resize</function> is invoked with
                    <literal>(<symbol>w0</symbol> - 100, <symbol>h0</symbol>)</literal> as an argument, then subsequent
                    calls to the function will allow on-the-fly resizing in the whole range from
                    <literal>(<symbol>w0</symbol> - 100, <symbol>h0</symbol>)</literal> to <literal>(<symbol>w0</symbol>
                    + 100, <symbol>h0</symbol>)</literal>. (But note that this may be overcome if
                    <literal><symbol>w0</symbol> + 100</literal> is bigger than the enlargement step.)
                </para>
            </sect2>

            <sect2 id="flatten">
                <title>Flattening</title>
                <para>
                    In order to resize in more than one step, the image can be flattened in its current state, thrugh
                    this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_flatten</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The return value is &ret_false; in case of insufficient memory, &ret_true; otherwise.
                </para>
                <para>
                    This function destroys the current visibility map and reinitialises the multi-size image from its
                    current state.
                </para>
                <note>
                    <para>
                        Every time that the image is flattened (including when changing the resize direction) the
                        original image and all information about it is lost.
                    </para>
                </note>
            </sect2>

            <sect2 id="lqr-cancel">
                <title>Cancelling an action</title>
                <para>
                    The resizing and flattening operations can be aborted using this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_cancel</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    This function can be invoked asynchronously, from a different thread with respect to the one in
                    which the resizing or flattening methods were called. If successful, this function will return
                    &err_ok;, and any ongoing resizing or flattening functions will immidiately abort and return the
                    special value &err_cancel;; however, this function will have no effect if no operation was in
                    progress when calling it.
                </para>
                <para>
                    This function can be called multiple times.
                </para>
                <important>
                    <para>
                        Whenever a function returns &err_cancel;, it means that the &carv_obj; object is in an
                        inconsistent state, and there is currently no way to recover from this situation. Therefore, any
                        further operation on it must be avoided, and it must be destroyed.
                    </para>
                </important>
                <important>
                    <para>
                        The functions <function>lqr_carver_resize</function> and <function>lqr_carver_flatten</function>
                        are not the only ones which can return &err_cancel;; instead, any function in the library whose
                        return type is <classname>LqrRetVal</classname> and which operates on &carv_obj; objects can
                        return such value: for example, any function will do so if called over a &carv_obj; object for
                        which an operation was actually cancelled (but this is not the only possibility).
                    </para>
                </important>
            </sect2>
        </sect1>

        <sect1 id="read-out">
            <title>Reading the multi-size image</title>

            <sect2 id="px-by-px">
                <title>Pixel by pixel</title>

                <para>
                    Once you have rescaled the image, you can read out the result through the functions:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_scan</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef> gint* <parameter>x</parameter></paramdef>
                            <paramdef> gint* <parameter>y</parameter></paramdef>
                            <paramdef> guchar** <parameter>rgb</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    or
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_scan_ext</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef> gint* <parameter>x</parameter></paramdef>
                            <paramdef> gint* <parameter>y</parameter></paramdef>
                            <paramdef> void** <parameter>rgb</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Here, <parameter>x</parameter> and <parameter>y</parameter> are pointers to the varaibles which will
                    hold the pixel coordinate, while <parameter>rgb</parameter> is a pointer to an array which will
                    contain the pixel colour information. If the carver was created using the standard 8-bit constructor
                    <function>lqr_carver_new</function>, the first form can be used, otherwise you must use the extended
                    form <function>lqr_carver_scan_ext</function>. In this last case, the output pointer
                    <parameter>rgb</parameter> must be passed as a pointer to <type>void*</type>, but the outcome should
                    actually be cast to a pointer to an array of the appropriate type, depending on the &carv_obj;
                    colour depth.
                </para>
                <para>
                    The return value is &ret_false; when the end of the image is reached, or the buffer has the wrong
                    number of bits, &ret_true; otherwise.
                </para>
                <para>
                    Each time these functions are invoked, they will store the coordinates and rgb information in the
                    output pointers and move to the next pixel. If they reach the end, they reset the reader and return
                    &ret_false;.
                </para>
                <para>
                    Here is a sample code usage:
                    <example id="ex-read-out">
                        <title>A simple readout example</title>
                        <programlisting>
gint x, y;
guchar *rgb;

while (lqr_carver_scan (carver, &amp;x, &amp;y, &amp;rgb) {
    my_plot (x, y, rgb[0], rgb[1], rgb[2]);
}
                        </programlisting>
                    </example>

                    In this example, it is assumed that the image has three 8-bit colour channels, and that there exist
                    some function <function>my_plot</function> which writes out the pixels somewhere.
                </para>
                <para>
                    The same readout example with different colour depth would read like this:
                    <example id="ex-read-out-ext">
                        <title>A simple readout example - extended version</title>
                        <programlisting>
gint x, y;
void *rgb;
gdouble *rgb_out;

while (lqr_carver_scan (carver, &amp;x, &amp;y, &amp;rgb) {
    rgb_out = (gdouble*) rgb;
    my_plot (x, y, rgb_out[0], rgb_out[1], rgb_out[2]);
}
                        </programlisting>
                    </example>

                    In this example it is assumed that the carver was loaded with the &col_depth_64f; as the
                    <parameter>colour_depth</parameter> argument in the constructor
                    <function>lqr_carver_new_ext</function>, and that it has <literal>3</literal> colour channels (see
                    the <link linkend="carver-new">constructor section</link> for details); therefore, the output is
                    cast to type <type>gdouble</type> before using it.
                </para>
                <important>
                    <para>
                        The <parameter>rgb</parameter> array is owned by to the carver object, so it doesn't need
                        initialization, as in the example. Indeed, it must be used for read-only purposes, and the
                        content should always be copyed after each call to a scan function.
                    </para>
                </important>
            </sect2>

            <sect2 id="line-by-line">
                <title>One line at a time</title>

                <para>
                    The image can also be read one line at a time, but it is not possible to freely decide if it is to
                    be read by row or by column. Instead, this has to be queried by calling this function: 
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_scan_by_row</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The function returns &ret_true; if the image is read by row, and &ret_false; if it is read by
                    column.
                </para>
                <para>
                    Then, the image can be read through these functions:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_scan_line</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gint* <parameter>n</parameter></paramdef>
                            <paramdef>guchar** <parameter>rgb</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    or
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_scan_line_ext</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gint* <parameter>n</parameter></paramdef>
                            <paramdef>void** <parameter>rgb</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    These functions work exactly the same way as <function>lqr_carver_scan</function> and
                    <function>lqr_carver_scan_ext</function>, but only one coordinate is stored (either the row or the
                    column number), and the <parameter>rgb</parameter> array will contain a whole line.
                </para>
                <para>
                    Here is a sample code usage for the standard 8-bit case:
                    <example id="ex-scan-line">
                        <title>Line-by-line readout example</title>
                        <programlisting>
gint n;
guchar *rgb;
gboolean by_row;

by_row = lqr_carver_scan_by_row (carver);

while (lqr_carver_scan_line (carver, &amp;n, &amp;rgb) {
    by_row ? my_plot_row (n, rgb) : my_plot_col (n, rgb);
}
                        </programlisting>
                    </example>

                    where, as before, it is assumed that the <function>my_plot_row</function> and
                    <function>my_plot_col</function> functions have been previously defined and "know what to do".
                </para>
                <para>
                    The extended version for images with more colour depth is very similar, it only requires an
                    additional cast:
                    <example id="ex-scan-line-ext">
                        <title>Line-by-line readout example - extended version</title>
                        <programlisting>
gint n;
void *rgb;
guchar *rgb_out;
gboolean by_row;

by_row = lqr_carver_scan_by_row (carver);

while (lqr_carver_scan_line_ext (carver, &amp;n, &amp;rgb) {
    rgb_out = (gboolean*) rgb;
    by_row ? my_plot_row (n, rgb_out) : my_plot_col (n, rgb_out);
}
                        </programlisting>
                    </example>
                </para>
            </sect2>

            <sect2 id="reset">
                <title>Resetting</title>

                <para>
                    Normally, it is not needed to reset the image scan. However, if the scan has been stopped at same
                    intermediate step for some reason, the following function can be used to restart from the beginning:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_scan_reset</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
            </sect2>
        </sect1>

        <sect1 id="energy">
            <title>Automatic feature detection</title>

            <sect2 id="energy-foreword">
                <title>Foreword</title>

                <para>
                    The automatic feature detection relies on the evaluation of the relevance of each pixel; this
                    quantity is called `energy': the higher the energy of a pixel, the less likely it will be that such
                    pixel will be directly involved in the rescaling. The energy function which the library uses can be
                    customised; normally, edge detector filters are the best choices for this purpose.
                </para>
                <para>
                    There is a unified framework in the &lqrl; for energy fucntions: briefly, each energy function used
                    by the library receives the current position and image size as parameters, and is provided access to
                    a square of values from the image, centered around the current position. This access is provided
                    through an object which is called a "reading window", and the image pixels are not read directly,
                    but rather they are accessed according to a "reader type", which means that the energy function can
                    get e.g. the brightness of a pixel without needing to care for the underlying image representation,
                    i.e. the image type or the colour depth.
                </para>
                <para>
                    The library provides a small set of very simple (yet normally effective) gradient-based energy
                    functions, and a customisation framework for defining more functions.
                </para>

            </sect2>
            <sect2 id="energy-builtin">
                <title>Builtin energy functions</title>

                <para>
                    The library has some builtin functions for energy evaluation; in order to set one of the builtin
                    functions in a &carv_obj; object this function is used:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_energy_function_builtin</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrEnergyFunctionBuiltinType <parameter>ef_ind</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The currently available builtin functions which can be used as <parameter>ef_ind</parameter> are:
                    <variablelist>
                        <varlistentry>
                            <term><literal>LQR_EF_GRAD_XABS</literal></term>
                            <listitem>
                                <para>
                                    absolute value of the brightness gradient in the direction
                                    of the rescaling (this is the default)
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><literal>LQR_EF_GRAD_SUMABS</literal></term>
                            <listitem>
                                <para>
                                    sum of absolute values of the brightness gradients in both directions
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><literal>LQR_EF_GRAD_NORM</literal></term>
                            <listitem>
                                <para>
                                    norm of the brightness gradient
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><literal>LQR_EF_LUMA_GRAD_XABS</literal></term>
                            <listitem>
                                <para>
                                    absolute value of the luma gradient in the direction
                                    of the rescaling
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><literal>LQR_EF_LUMA_GRAD_SUMABS</literal></term>
                            <listitem>
                                <para>
                                    sum of absolute values of the luma gradients in both directions
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><literal>LQR_EF_LUMA_GRAD_NORM</literal></term>
                            <listitem>
                                <para>
                                    norm of the luma gradient
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><literal>LQR_EF_NULL</literal></term>
                            <listitem>
                                <para>
                                    null
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </para>
                <para>
                    All of the above gradient functions have a radius of 1 pixel.
                </para>

            </sect2>

            <sect2 id="energy-custom">
                <title>Custom energy functions</title>

                <para>
                    Custom energy functions for a &carv_obj; object are set using this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_energy_function</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrEnergyFunc <parameter>ef_func</parameter></paramdef>
                            <paramdef>gint <parameter>radius</parameter></paramdef>
                            <paramdef>LqrEnergyReaderType <parameter>reader_type</parameter></paramdef>
                            <paramdef>gpointer <parameter>extra_data</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    Here, <parameter>ef_func</parameter> is the function (the prototype will be explained below),
                    <parameter>radius</parameter> is used to set the size of the square region around each pixel which
                    is used to evaluate the energy for that pixel, <parameter>reader_type</parameter> is used to set
                    which quantity is used for the energy computation (e.g. brightness, luma etc.) and
                    <parameter>extra_data</parameter> is a (void) pointer which can be used to pass additional
                    parameters to the energy function.
                </para>
                <para>
                    The <type><literal>LqrEnergyReaderType</literal></type> is an enum which can take these values (also
                    noted is the number of channels of the corresponging output):
                    <variablelist>
                        <varlistentry>
                            <term><literal>LQR_ER_BRIGHTNESS</literal></term>
                            <listitem>
                                <para>
                                    brightness (1 channel)
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><literal>LQR_ER_LUMA</literal></term>
                            <listitem>
                                <para>
                                    luma (1 channel)
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><literal>LQR_ER_RGBA</literal></term>
                            <listitem>
                                <para>
                                    RGBA (4 channels)
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><literal>LQR_ER_CUSTOM</literal></term>
                            <listitem>
                                <para>
                                    read the normalised image channels as they are (as many channels as the image has)
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                    These readouts always return values beetween <literal>0</literal> and <literal>1</literal>.
                </para>
                <note>
                    <para>
                        Note that these readouts may have special meanings depending on the image type:
                        <itemizedlist>
                            <listitem>
                                <para>
                                    for <literal>LQR_GREY_IMAGE</literal>, <literal>LQR_GREYA_IMAGE</literal> and
                                    <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_LUMA</literal>
                                    readout will yield the same result as <literal>LQR_ER_BRIGHTNESS</literal>
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    for <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_BRIGHTNESS</literal>
                                    readout will return the average pixel value (additive, i.e. if a black channel is
                                    present the channel values will be inverted and multiplied by the black channel
                                    inverse), multiplied by the alpha channel value.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    for <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_RGBA</literal>
                                    readout <emphasis>cannot be used</emphasis>: it will always return
                                    <literal>0</literal>
                                </para>
                            </listitem>
                        </itemizedlist>
                    </para>
                </note>
                <para>
                    The custom energy function must be declared like in the following sample declaration:
                    <example id="ex-custom-en-decl">
                        <title>Custom energy declaration</title>
                        <programlisting>
gfloat my_energy (gint x, gint y, gint width, gint height, LqrReadingWindow *rwindow, gpointer extra_data);
                        </programlisting>
                    </example>
                    This function should return the energy at pixel <parameter>x</parameter>, <parameter>y</parameter>,
                    based on the knowledge of the current image size (obtained from <parameter>width</parameter> and
                    <parameter>height</parameter>) and the content of the image in a square around that pixel, which is
                    passed through the <parameter>rwindow</parameter> reading window: in order to access this content,
                    this function must be used:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>gdouble <function>lqr_rwindow_read</function></funcdef>
                            <paramdef>LqrReadingWindow * <parameter>rwindow</parameter></paramdef>
                            <paramdef>gint <parameter>x</parameter></paramdef>
                            <paramdef>gint <parameter>y</parameter></paramdef>
                            <paramdef>channel <parameter>channel</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    When reading out the content from a window, the <parameter>x</parameter> and
                    <parameter>y</parameter> parameters are relative to the window centre (which instead is given by the
                    <parameter>x</parameter>, <parameter>y</parameter> parameters passed to the custom energy function),
                    and they both range between <literal><symbol>-radius</symbol></literal> and
                    <literal><symbol>radius</symbol></literal> included (<parameter>radius</parameter> being the same
                    one which is used in <function>lqr_carver_set_energy_function</function>). The parameter
                    <parameter>channel</parameter> specifies which channel to read out; depending on the
                    <parameter>read_type</parameter> passed to <function>lqr_carver_set_energy_function</function> the
                    range and meaning of this parameter will change: for the cases <literal>LQR_ER_BRIGHTNESS</literal> and
                    <literal>LQR_ER_LUMA</literal> it must be <literal>0</literal>, because the readout consists of a
                    single channel, for <literal>LQR_ER_RGBA</literal> it must be between <literal>0</literal> and
                    <literal>3</literal> (and then the readout will contain the RGBA information), while for
                    <literal>LQR_ER_CUSTOM</literal> it must be one of the original image channels.
                </para>
                <para>
                    The <parameter>rwindow</parameter> parameters can be read out from within a custom defined energy
                    function using these functions:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrEnergyReaderType <function>lqr_rwindow_get_read_t</function></funcdef>
                            <paramdef>LqrReadingWindow * <parameter>rwindow</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>gint <function>lqr_rwindow_get_radius</function></funcdef>
                            <paramdef>LqrReadingWindow * <parameter>rwindow</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>gint <function>lqr_rwindow_get_channels</function></funcdef>
                            <paramdef>LqrReadingWindow * <parameter>rwindow</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Following is an example of how a simple Sobel fliter can be defined and used within this framework:
                    <example id="ex-custom-en-def">
                        <title>Custom energy definition and setup</title>
                        <programlisting>
/* definition */

gfloat sobel(gint x, gint y, gint width, gint height, LqrReadingWindow *rw, gpointer extra_data)
{
    gint i, j;
    gdouble ex = 0;
    gdouble ey = 0;
    gdouble k[3][3] = {{0.125, 0.25, 0.125}, {0, 0, 0}, {-0.125, -0.25, -0.125}};

    for (i = -1; i &lt;=1; i++) {
        for (j = -1; j &lt;=1; j++) {
            ex += k[i + 1][j + 1] * lqr_rwindow_read(rw, i, j, 0);
            ey += k[j + 1][i + 1] * lqr_rwindow_read(rw, i, j, 0);
        }
    }
    return (gfloat) sqrt(ex * ex + ey * ey);
}

/* usage */

lqr_carver_set_energy_function (carver, sobel, 1, LQR_ER_BRIGHTNESS, NULL);
                        </programlisting>
                    </example>
                </para>
                <para>
                    In the above <function>sobel</function> function it is assumed that the radius is 1 and that the
                    readout will consist of a single channel. Furthermore, no boundary checking is performed, and
                    therefore the parameters &param_x;, &param_y;, &param_w; and &param_h; are not used. Also, no extra
                    parameters are passed to the function.
                </para>
                <note>
                    <para>
                        The function <function>lqr_rwindow_read</function> returns <literal>0</literal> when the
                        requested value is out of the image boundary or beyond the reading window radius.
                    </para>
                </note>
                <note>
                    <para>
                        The energy functions are called over the transposed image in case of vertical scaling,
                        therefore, if they are asymmetrical, the result will be different depending on the scaling
                        orientation (this is the case for example for the <literal>LQR_EF_GRAD_XABS</literal> builtin
                        function).
                    </para>
                </note>
                <note>
                    <para>
                        The energy function output should be normalised in order to be comparable with the builtin
                        functions, otherwise the scale of the bias would be different depending on the energy function
                        used. This is the reason why in the Sobel filter written above the kernel
                        <parameter>k</parameter> is scaled so that the sum of the absolute values of the matrix is equal
                        to <literal>1</literal>.
                    </para>
                </note>
                <note>
                    <para>
                        In actual code, the call to <function>lqr_carver_set_energy_function</function> should be
                        protected to test its return value.
                    </para>
                </note>
            </sect2>

            <sect2 id="energy-readout">
                <title>Reading out the energy</title>

                <para>
                    The energy can be read out with three similar functions, all of which fill a buffer provided by
                    the user, but in different ways: two of them are suitable for plotting, while the third one can be
                    used to retreive the true values of the energy, as used internally.
                </para>
                <para>
                    The first function can be used to get a buffer of normalised values, and it has a simple syntax:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_get_energy</function></funcdef>
                            <paramdef>LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef>gfloat * <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>orientation</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    This function writes the the energy values at the time of calling to the given
                    <parameter>buffer</parameter>, ordered by row and then by column. All values range between
                    <literal>0</literal> and <literal>1</literal>. The buffer must be allocated by the user before
                    calling it.
                </para>
                <para>
                    The <parameter>orientation</parameter> parameter determines which orientation will be used when
                    computing the energy: <literal>0</literal> means horizontal, <literal>1</literal> means vertical.
                </para>
                <para>
                    The <parameter>carver</parameter> need not be initialised; if a bias was added to it (see the
                    <link linkend="bias">Adding a bias</link> section), its effect is included in the output.
                </para>
                <para>
                    The above function does not return the true energy which is used internally, because that would not
                    be suitable for plotting, since the energy range is arbitrary (only the energy differences are
                    meaningful, and there is no upper nor lower bound to the values). In order to get the true energy
                    values used internally, this function must be used instead (with the same syntax):
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_get_true_energy</function></funcdef>
                            <paramdef>LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef>gfloat * <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>orientation</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The third function can be used to fill directly an image buffer:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_get_energy_image</function></funcdef>
                            <paramdef>LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef>void * <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>orientation</parameter></paramdef>
                            <paramdef>LqrColDepth <parameter>col_depth</parameter></paramdef>
                            <paramdef>LqrImageType <parameter>image_type</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    In this case, the buffer must be passed as <type>void*</type>, while the
                    <parameter>col_depth</parameter> and <parameter>image_type</parameter> are used to specify the
                    colour depth and the image type, in the same way as is done when creating an &carv_obj; object (see
                    <link linkend="carver-new">Carver objcet creation</link> and the
                    <link linkend="image-type">Choosing the image type</link> sections). The only restriction is that it
                    is not possible to ask for &img_type_custom; image types.
                </para>
                <para>
                    For any choice of the parameters, the <parameter>buffer</parameter> will hold a greyscale image,
                    ranging from black (lowest energy) to white (highest energy). The opacity (alpha) will be set to
                    <literal>1</literal>, if present. All the information will be stored in the black channel in
                    &img_type_cmyk; and &img_type_cmyka; image types.
                </para>
                <note>
                    <para>
                        Calling the function <function>lqr_carver_get_energy_image</function> with &col_depth_32f; and
                        &img_type_grey; arguments will yield the same result as calling the function
                        <function>lqr_carver_get_energy</function>, but the latter is slightly more efficient.
                    </para>
                </note>
            </sect2>
        </sect1>
        <sect1 id="bias">
            <title>Adding a bias</title>

            <sect2 id="bias-foreword">
                <title>Foreword</title>

                <para>
                    The automatic feature detection can be driven manually by adding a bias to the pixels of the image.
                </para>
                <para>
                    For example, it is possible to protect regions of the image by adding a positive bias to the
                    corresponding pixels. This will make the seams more unlikely to cross those regions, thus avoiding
                    distortion (but increasing distortion of the other regions).
                </para>
                <para>
                    It is also possible to make the seams more likely to cross some regions by adding a negative bias to
                    them. In this case, reducing the size of the image will tend to erase those regions, while
                    (possibly) keeping the rest of the image in a consistent state. 
                </para>
                <important>
                    <para>
                        The bias has to be added before the resizing takes place (but it can be added before
                        initialisation since version 0.4).
                    </para>
                </important>
                <note>
                    <para>
                        In all of the bias-related functions, the bias is added on top of the existing one, so that all
                        of the functions can be called multiple times.
                    </para>
                </note>
            </sect2>

            <sect2 id="bias-xy">
                <title>Adding a bias pixel by pixel</title>

                <para>
                    The function to use in order to add a bias to a given pixel is:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_bias_add_xy</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble <parameter>bias</parameter></paramdef>
                            <paramdef>gint <parameter>x</parameter></paramdef>
                            <paramdef>gint <parameter>y</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    Typical values for the <parameter>bias</parameter> parameter would be between <literal>100</literal>
                    and <literal>10000</literal> in module.
                </para>
            </sect2>

            <sect2 id="bias-float">
                <title>Using an array of floating-point values</title>

                <para>
                    It is possible to use a whole array of floating points at once through this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_bias_add</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>bias_factor</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Here, <parameter>buffer</parameter> is an array contining the bias values, and it is assumed to have
                    the same size as the image loaded in <parameter>carver</parameter>, while
                    <parameter>bias_factor</parameter> is an overall bias factor, which can be used to affect the global
                    bias level: if the elements of <parameter>buffer</parameter> are of order 1, a standard choice for
                    the bias_factor would be between <literal>100</literal> and <literal>10000</literal> (in module).
                </para>
                <note>
                    <para>
                        This function, and all the following, will not swallow the buffer (to the contrary of what
                        happens e.g. when creating a new &carv_obj; object and allowing the default behaviour),
                        therefore the buffer must be freed by the user afterwards.
                    </para>
                </note>
            </sect2>

            <sect2 id="bias-rgb">
                <title>Using another image</title>

                <para>
                    The bias can also be read from an 8-bit rgb buffer. This buffer has to be in the same format as the
                    one used in the 8-bit LqrCarver constructor (but may have a different number of colours per
                    channel). The function is:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_bias_add_rgb</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>guchar* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>bias_factor</parameter></paramdef>
                            <paramdef>gint <parameter>channels</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    As in the previous case, <parameter>buffer</parameter> is assumed to hold and image of the same size
                    as the one in the <parameter>carver</parameter>.
                </para>
                <para>
                    The <parameter>buffer</parameter> contents will be transformed into floating-points by averaging the
                    colour components and multiplying the result by the alpha channel (transparency) value.
                </para>
                <important>
                    <para>
                        The existence of an alpha channel is inferred from the <parameter>channels</parameter> value: if
                        this is 1 or 3, no alpha channel is assumed, if it is 2 or 4 or greater, it is assumed that the
                        last channel holds the alpha value. If this is not what you want, you should resort to one of
                        the previous methods.
                    </para>
                </important>
            </sect2>

            <sect2 id="bias-areas">
                <title>Operating on a specific area</title>

                <para>
                    The two previously described functions operate on the whole &carv_obj; image. It is also possible
                    to access specific image regions in a similar way; for the floating point case use:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_bias_add_area</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>bias_factor</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>x_off</parameter></paramdef>
                            <paramdef>gint <parameter>y_off</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    while for the rgb image case use:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_bias_add_rgb_area</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>guchar* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>bias_factor</parameter></paramdef>
                            <paramdef>gint <parameter>channels</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>x_off</parameter></paramdef>
                            <paramdef>gint <parameter>y_off</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    In both functions, &param_w; and &param_h; are used to specify the size of the area of interest,
                    while <parameter>x_off</parameter> and <parameter>y_off</parameter> specify its offset. For the
                    rest, both functions work in the same way as their global couterpart.
                </para>
                <para>
                    The provided buffers have to be of size <literal>&param_w; * &param_h;</literal> (or
                    <literal>&param_w; * &param_h; * &param_channels;</literal> for the rgb case) but the specified
                    areas need not to be strictly included inside the &carv_obj; image area: only the parts which
                    overlap with it will be used. For example, the offsets can also be negative.
                </para>
            </sect2>
        </sect1>

        <sect1 id="rigmask">
            <title>Adding a rigidity mask</title>

            <sect2 id="rigmask-foreword">
                <title>Foreword</title>

                <para>
                    The rigidity parameter which is set at carver activation time (see section
                    <link linkend="carver-init">Carver activation</link>) normally affects the whole image. It is
                    possible, however, to specify which areas of the image should be affected by using a rigidity mask.
                </para>
                <para>
                    When a rigidity mask is used, each pixel of the image acquires an individual rigidity coefficient,
                    which has to be multiplied with the overall rigidity parameter to get the actual pixel's rigidity.
                    This is useful in some situations to reduce distorsions in specific areas of the image while keeping
                    the seams optimal in other areas.
                </para>
                <para>
                    The library interface to deal with rigidity masks follows very closely the scheme for bias masks as
                    described in the <link linkend="bias">bias section</link>, the main difference being that no
                    equivalent to the bias factor has to be provided (since it is already given in the
                    <function>lqr_carver_init</function> function).
                </para>
                <important>
                    <para>
                        The rigidity mask has to be added always <emphasis>after</emphasis> the &carv_obj;
                        initialization and <emphasis>before</emphasis> resizing takes place. (Note that this is
                        different from the bias, which instead can also be added to non-initialised carver objects.)
                    </para>
                </important>
                <important>
                    <para>
                        Whenever a rigidity mask is set, all pixels for which the value is not explicitly defined will
                        have coefficient 0, i.e. the rigidity setting will will be disabled.
                    </para>
                </important>
                <note>
                    <para>
                        All of the functions can be called multiple times, but their effect is not summed up, to the
                        contrary of what happens for the bias functions; instead, new values will substitute old ones
                        when the affected regions overlap.
                    </para>
                </note>
            </sect2>

            <sect2 id="rigmask-xy">
                <title>Adding an individual rigidity coefficient to a pixel</title>

                <para>
                    The function to use in order to set the rigidity mask at a given pixel is:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_xy</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble <parameter>rigidity</parameter></paramdef>
                            <paramdef>gint <parameter>x</parameter></paramdef>
                            <paramdef>gint <parameter>y</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
            </sect2>

            <sect2 id="rigmask-float">
                <title>Using an array of floating-point values</title>

                <para>
                    It is possible to use a whole array of floating points at once through this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_rigmask_add</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Here, <parameter>buffer</parameter> is an array contining the rigidity coefficients values, and it
                    is assumed to have the same size as the image loaded in <parameter>carver</parameter>.
                </para>
                <note>
                    <para>
                        This function, and all the following, will not swallow the buffer (to the contrary of what
                        happens e.g. when creating a new &carv_obj; object and allowing the default behaviour),
                        therefore the buffer must be freed by the user afterwards.
                    </para>
                </note>
            </sect2>

            <sect2 id="rigmask-rgb">
                <title>Using another image</title>

                <para>
                    The rigidity mask can also be read from an 8-bit rgb buffer. This buffer has to be in the same
                    format as the one used in the 8-bit LqrCarver constructor (but may have a different number of
                    colours per channel). The function is:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_rgb</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>guchar* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>channels</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    As in the previous case, <parameter>buffer</parameter> is assumed to hold and image of the same size
                    as the one in the <parameter>carver</parameter>.
                </para>
                <para>
                    The <parameter>buffer</parameter> contents will be transformed into floating-points by averaging the
                    colour components and multiplying the result by the alpha channel (transparency) value.
                </para>
                <important>
                    <para>
                        The existence of an alpha channel is inferred from the <parameter>channels</parameter> value: if
                        this is 1 or 3, no alpha channel is assumed, if it is 2 or 4, it is assumed that the last
                        channel is holds the alpha value. If this is not what you want, you should resort to one of the
                        previous methods.
                    </para>
                </important>
            </sect2>

            <sect2 id="rigmask-areas">
                <title>Operating on a specific area</title>

                <para>
                    The two previously described functions operate on the whole &carv_obj; image. It is also possible
                    to access specific image regions in a similar way; for the floating point use:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_area</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>x_off</parameter></paramdef>
                            <paramdef>gint <parameter>y_off</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    while for the rgb image use:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_rgb_area</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>guchar* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>channels</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>x_off</parameter></paramdef>
                            <paramdef>gint <parameter>y_off</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    In both functions, &param_w; and &param_h; are used to specify the size of the area of interest,
                    while <parameter>x_off</parameter> and <parameter>y_off</parameter> specify its offset. For the
                    rest, both functions work in the same way as their global couterpart.
                </para>
                <para>
                    The provided buffers have to be of size <literal>&param_w; * &param_h;</literal> (or
                    <literal>&param_w; * &param_h; * &param_channels;</literal> for the rgb case) but the specified
                    areas need not to be strictly included inside the &carv_obj; image area: only the parts which
                    overlap with it will be used. For example, the offsets can also be negative.
                </para>
            </sect2>
        </sect1>

        <sect1 id="tuning">
            <title>Tuning</title>

            <para>
                The behaviour can be tuned through some additional functions.
            </para>

            <sect2 id="lqr-enl-step">
                <title>Setting the enlargement step</title>
                <para>
                    As mentioned in <link linkend="about-enlarge">About enlarging</link>, if the requested final size is
                    too big, the rescaling is automatically divided in steps.
                </para>
                <para>
                    For example, let us suppose that we have created an &carv_obj; object from a 100 by 100 pixels
                    image, and that we call <function>lqr_carver_resize</function> with 600 and 100 as width and height
                    arguments. With the default settings, the rescaling of the width will be performed in 3 steps:
                    first, from 100 to 199, then from 199 to 397, and finally from 397 to 600.
                </para>
                <para>
                    The rule here is that the maximum size which can be reached in a single step is equal to twice the
                    original size minus one, and that at each step the original size is reset to the current size
                    (through an internal call to <function>lqr_carver_flatten</function>).
                </para>
                <para>
                    In most situations, however, the steps should be smaller in order to obtain good results. This can
                    be set with this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_enl_step</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef> gfloat <parameter>enl_step</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The value of <parameter>enl_step</parameter> must be strictly grater then 1.0 and less then (or
                    equal to) 2.0. The default value is 2.0 (for back-compatibility reasons); any other value will
                    result in the function returning an error. The new maximum size for a step will then be obtained by
                    multiplying the original size by the enlargement step and subtracting 1.
                </para>
                <para>
                    The current value of the enlargement step can be retrieved with this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>gfloat <function>lqr_carver_get_enl_step</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
            </sect2>

            <sect2 id="res-order">
                <title>Choosing the resize order</title>

                <para>
                    When the function <function>lqr_carver_resize</function> is asked to resize along both directions in
                    a single step, it has to choose which direction to resize first. The resize order can be changed
                    through this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_resize_order</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrResizeOrder <parameter>resize_order</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The possible values for resize_order are:
                    <variablelist>
                        <varlistentry>
                            <term><literal>LQR_RES_ORDER_HOR</literal></term>
                            <listitem>
                                <para>
                                    resize horizonally first (this is the default) 
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term><literal>LQR_RES_ORDER_VERT</literal></term>
                            <listitem>
                                <para>
                                    resize vertically first
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </para>
            </sect2>

            <sect2 id="switch-freq">
                <title>Choosing the side switch frequency</title>

                <para>
                    When the function <function>lqr_carver_resize</function> is invoked, it chooses at each step the
                    optimal seam to carve based on the relvance value for each pixel. However, in the case two seams
                    are equivalent (which may happen when large portions of the image have the same colour, for
                    example), the algorithm always chooses the seams from one side, which might be a problem (e.g. an
                    object centered in the original image might not be centered any more in the resulting image).
                </para>
                <para>
                    In order to overcome this effect, an option is given to automatically switch the favoured side
                    during rescaling, at the cost of a slightly worse performance. The number of times such a switching
                    event occurs for each rescale operation can be set using the function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_side_switch_frequency</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>guint <parameter>switch_frequency</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The default value for newly created &carv_obj; objects is <literal>0</literal>, which is equivalent
                    to disabling this feature. Giving a value greater than the number of pixels by which to rescale
                    produces a switch for each pixel, therefore you could set <parameter>switch_freqency</parameter> to
                    a ridicolously high value in order to be sure to get this effect.
                </para>
                <para>
                    As for the final result, a very small value (e.g. <literal>1<literal> to </literal>4</literal>) will
                    normally suffice to balance the left and right side of the image (or the top and the bottom sides
                    for vertical rescalings), without noticeable computational costs. However, in order to obtain a
                    smoother behaviour for the visibiliy map, i.e. for the intermediate steps, higher values may be
                    required.
                </para>
            </sect2>

            <sect2 id="cache">
                <title>Using the cache</title>

                <para>
                    By default, the library tries to cache some quantities in order to save computational time. The
                    cache may be disabled in order to save memory instead, using this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_use_cache</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gboolean <parameter>use_cache</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    To disable the cache, set <parameter>use_cache</parameter> to <literal>FALSE</literal>. To
                    re-enable it back, set it to <literal>TRUE</literal>.
                </para>
            </sect2>

        </sect1>

        <sect1 id="vmaps">
            <title>Dealing with the visibility maps (the seams)</title>

            <sect2 id="vmap-dump">
                <title>Dumping the visibility map</title>

                <para>
                    The visibility map can be saved at any moment by calling the function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrVMap* <function>lqr_vmap_dump</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    This function will return a pointer to a newly allocated &vmap_obj; object, or &ret_null; in case of
                    failure. See also the section "<link linkend="vmaps-objs">The visibility map objects</link>".
                </para>
            </sect2>

            <sect2 id="activate-dump">
                <title>Storing the visibility maps</title>

                <para>
                    By default, the computed visibility maps are wasted. Instead of saving them individually, it is
                    possible to automatically dump them at the end of the carving process, attaching them to their
                    associated &carv_obj;. In order to activate this feature, the following function has to be called:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_dump_vmaps</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    This will have the effect of dumping the visibility map each time
                    <function>lqr_carver_resize</function> is invoked, and storing it internally. When resizing along
                    both directions, two maps will be dumped, one for each direction.
                </para>
                <para>
                    In order to revert the effect of <function>lqr_carver_set_dump_vmaps</function>, thus stopping the
                    automatic dumping, use the function
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_no_dump_vmaps</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Alternatively, the internal storage mechanism can be called over the current visibility map at any
                    given moment by calling this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_vmap_internal_dump</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The dumped maps are stored inside &vmap_obj; objects, and these are attached to their corresponing
                    &carv_obj; object through a linked list, whose type is &vmapl_obj;
                </para>
            </sect2>

            <sect2 id="access-vmap">
                <title>Accessing the internally attached visibility maps</title>

                <para>
                    To access the maps attached to a carver one has first to obtain the pointer to the list, with the
                    function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrVMapList* <function>lqr_vmap_list_start</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Then, one can iterate through the attached maps by using these two functions:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrVMap* <function>lqr_vmap_list_current</function></funcdef>
                            <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrVMapList* <function>lqr_vmap_list_next</function></funcdef>
                            <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Here is a sample code usage:
                    <example id="ex-vmaplist1">
                        <title>Accessing visibility maps #1</title>

                        <programlisting>
LqrVMap *vmap;
LqrVMapList *list;

list = lqr_vmap_list_start (carver);
while (list) {
    vmap = lqr_vmap_list_current (list);
    /* ... do something on vmap ... */
    list = lqr_vmap_list_next (list);
}
                        </programlisting>
                    </example>
                </para>
                <para>
                    The maps will always be accessed in the order in which they were dumped.
                </para>
                <para>
                    Alternatively, one can apply a function to all the elements of the list, through this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_vmap_list_foreach</function></funcdef>
                            <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
                            <paramdef>LqrVMapFunc <parameter>func</parameter></paramdef>
                            <paramdef>gpointer <parameter>data</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    To use this second method, you'll need to define a function first, as in this sample code:
                    <example id="ex-vmaplist2">
                        <title>Accessing visibility maps #2</title>
                        <programlisting>
LqrRetVal my_func (LqrVMap vmap, gpointer data)
{
    /* ... do something on vmap ... */
    return LQR_OK;
}

LqrVMapList *list;

list = lqr_vmap_list_start (carver);
lqr_vmap_list_foreach (list, my_func, NULL);
                        </programlisting>
                    </example>
                </para>
                <para>
                    In the above example, no data is actually passed on to the function.
                </para>
                <note>
                    <para>
                        In actual code the call to <function>lqr_vmap_list_foreach</function> should be protected to
                        test its return value, which is &err_ok; if all <function>my_func</function> calls have been
                        successful, or it will hold the first non-successful return value from
                        <function>my_func</function>.
                    </para>
                </note>
            </sect2>

            <sect2 id="vmaps-objs">
                <title>The visibility map objects</title>

                <para>
                    The &vmap_obj; objects contain an int buffer with the actual map data (plain array, ordered by row),
                    plus all the information needed to be able to recover it from scratch.
                </para>
                <para>
                    The information can be extracted with these functions:
                    <programlisting>
gint* <function>lqr_vmap_get_data</function> (&vmap_obj;* <parameter>vmap</parameter>);
gint <function>lqr_vmap_get_width</function> (&vmap_obj;* <parameter>vmap</parameter>);
gint <function>lqr_vmap_get_height</function> (&vmap_obj;* <parameter>vmap</parameter>);
gint <function>lqr_vmap_get_orientation</function> (&vmap_obj;* <parameter>vmap</parameter>);
gint <function>lqr_vmap_get_depth</function> (&vmap_obj;* <parameter>vmap</parameter>);
                    </programlisting>
                </para>
                <para>
                    The first one returns a pointer to the data buffer.
                </para>
                <para>
                    The orientation of the map is 0 if the map is to be used for horizontal rescaling, 1 otherwise.
                </para>
                <para>
                    The depth of the map is the maximum amount of rescaling possible with that map, either shrinking or
                    enlarging.
                </para>
                <para>
                    <example id="vmap-data">
                        <title>Reading visibility maps data</title>
                        <para>
                            If we have a &vmap_obj; pointer called <parameter>vmap</parameter>, we could access the
                            value at <literal>(<symbol>x</symbol>,<symbol>y</symbol>)</literal> by:
                        </para>
                        <programlisting>
gint *buffer;
gint width;
gint vis;

buffer = lqr_vmap_get_data (vmap);
width = lqr_vmap_get_width (vmap);
vis =  buffer[y * width + x];
                        </programlisting>
                        <para>
                            Uninitialised points will yield <literal><symbol>vis</symbol> = 0</literal>. For
			    initialised points, <literal><symbol>vis</symbol></literal> will store a positive value between
                            <literal>1</literal> (least visible points, the first to be carved away or to be duplicated)
                            and <literal>(&param_depth; + 1)</literal> (most visible points, the last to be carved away
                            or to be duplicated).
                        </para>
                        <para>
                            If the orientation is 0, the map allows resizing in the whole range form <literal>(&param_w;
                            - &param_depth;)</literal> to <literal>(&param_w; + &param_depth;)</literal>. If the
                            orientation is 1, the analogue formula holds with &param_h; in place of &param_w;.
                        </para>
                    </example>
                </para>
            </sect2>

            <sect2 id="import-vmap">
                <title>Importing a visibility map in a carver</title>

                <para>
                    Having an &vmap_obj; object, one can load it in an &carv_obj; simply by calling this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_vmap_load</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The carver must not to be initialised, neither before nor after invoking this function.
                </para>
                <note>
                    <para>
                        This implies that the map cannot be updated, and that it will only be possible to resize the
                        carver by an amount &param_depth; along the orientation given by
                        <function>lqr_vmap_orientation</function>. The enlargment step is also set to its maximum, 2.0.
                        Invoking <function>lqr_carver_resize</function> with an out-of-bounds argument results in a
                        <errortype>fatal</errortype> error (i.e. it returns &err_err;).
                    </para>
                </note>
                <note>
                    <para>
                        Do not attach other carvers after you have loaded a visibility map (see also the
                        <link linkend="attach-images">Attaching extra images</link> section).
                    </para>
                </note>
            </sect2>

            <sect2 id="save-load-vmaps">
                <title>Saving and loading visibility maps to/from files</title>

                <para>
                    The library does not include methods to load/save visibility maps to/from files. However, a way to
                    do so is shown in the demo program `<application>liquidrescale</application>' in the
                    `<filename>examples</filename>' directory.
                </para>
            </sect2>
        </sect1>

        <sect1 id="attach-images">
            <title>Attaching extra images</title>

            <sect2 id="attach-carver">
                <title>Attaching a carver</title>

                <para>
                    Given an &carv_obj; object, it is possible to attach an arbitrary number of extra carvers to it:
                    these will passively undergo the same carving process as the root carver. In order for this to be
                    possible, the carvers must be all of the same size.
                </para>
                <para>
                    The function to use is simply:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_attach</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrCarver* <parameter>aux</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    This attaches <parameter>aux</parameter> to <parameter>carver</parameter>.
                </para>
                <para>
                    It is not necessary that the parent &carv_obj; is activated. In fact, a carver can be attached to a
                    carver which is itself attached to another one.
                </para>
                <para>
                    Needless to say, no resizing operation should be done directly on an &carv_obj; once it has been
                    attached to another &carv_obj;, and neither should the cancel method be invoked directly on them.
                </para>
                <important>
                    <para>
                        The carvers always have to be attached <emphasis>before</emphasis> loading visibility maps.
                    </para>
                </important>
            </sect2>

            <sect2 id="access-attached">
                <title>Accessing attached carvers</title>

                <para>
                    Attached carvers can be read-out in the same way as their parents. There are however also methods
                    to span all them, in a way very similar to that in which internally dumped &vmap_obj;'s are
                    accessed, but &vmapl_obj; objects are substitued in this case by &carvl_obj; objects.
                </para>
                <para>
                    First, the starting point of the list has to be retreived through:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrCarverList* <function>lqr_carver_list_start</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Then, one can iterate through the attached carvers by using these two functions:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrCarver* <function>lqr_carver_list_current</function></funcdef>
                            <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrCarverList* <function>lqr_carver_list_next</function></funcdef>
                            <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    Here is a sample code usage:
                    <example id="ex-attach-list1">
                        <title>Accessing attached carvers #1</title>
                        <programlisting>
LqrCarver *aux;
LqrCarverList *list;

list = lqr_carver_list_start (carver);
while (list) {
    aux = lqr_carver_list_current (list);
    /* ... do something on aux ... */
    list = lqr_carver_list_next (list);
}
                        </programlisting>
                    </example>
                </para>
                <para>
                    The carvers will always be accessed in the order in which they were attached.
                </para>
                <para>
                    Alternatively, one can apply a function to all the elements of the list (and recursively to all the
                    elements of their attached lists, if there are any), through this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_list_foreach_recursive</function></funcdef>
                            <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
                            <paramdef>LqrCarverFunc <parameter>func</parameter></paramdef>
                            <paramdef>LqrDataTok <parameter>data</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    To use this second method, you'll need to define a function first, as in the following sample code:
                    <example id="ex-attach-list2">
                        <title>Accessing attached carvers #2</title>
                        <programlisting>
LqrRetVal my_func (LqrCarver *aux, LqrDataTok data)
{
    /* ... do something on aux ... */
    return LQR_OK;
}

LqrCarverList *list;
LqrDataTok data_tok;

list = lqr_carver_list_start (carver);
data_tok->data = NULL;
lqr_carver_list_foreach_recursive (list, my_func, data_tok);
                        </programlisting>
                    </example>
                </para>
                <para>
                    The data to be passed on to the LqrCarverFunc is of type <structname>LqrDataTok</structname>. This
                    is defined as a union, with the following fields:
                    <itemizedlist>
                        <listitem>
                            <para>&carv_obj;* <structfield>carver</structfield></para>
                        </listitem>
                        <listitem>
                            <para><type>gint</type> <structfield>integer</structfield></para>
                        </listitem>
                        <listitem>
                            <para><type>gpointer</type> <structfield>data</structfield></para> 
                        </listitem>
                    </itemizedlist>
                </para>
                <para>
                    In the above example, no data is actually passed on to the function.
                </para>
                <note>
                    <para>
                        In actual code, the call to <function>lqr_carver_list_foreach_recursive</function> should be
                        protected to test its return value, which is &err_ok; if all my_func calls have been successful
                        (or if the list is empty), or it will hold the first non-successful return value from
                        <function>my_func</function>.
                    </para>
                </note>
            </sect2>
        </sect1>

        <sect1 id="progress">
            <title>Progress indicators</title>

            <para>
                By default, the resizing is performed silently. However, it is possible to define progress report
                functions, to receive feedback while the resizing is in progress. This is done through the &prog_obj;
                objects. 
            </para>
            <sect2 id="progress-init">
                <title>Creating and attaching a progress report object</title>
                <para> 
                    A &prog_obj; object is created through the function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrProgress* <function>lqr_progress_new</function></funcdef>
                            <void></void>
                        </funcprototype>
                    </funcsynopsis>
                    and can be associated to an &carv_obj; object through this function:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_progress</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
            </sect2>

            <sect2 id="progress-set-up">
                <title>Setting up progress hooks</title>
                <para>
                    Newly created progress objects are inactive, and need to be set up.
                </para>
                <para>
                    First, hook functions have to be set, which specify the action to take as the rescaling process
                    starts, progresses, and ends, by using the functions:
                    <programlisting>
LqrRetVal <function>lqr_progress_set_init</function> (&prog_obj; * <parameter>p</parameter>, LqrProgressFuncInit <parameter>init_func</parameter>)
LqrRetVal <function>lqr_progress_set_update</function> (&prog_obj; * <parameter>p</parameter>, LqrProgressFuncUpdate <parameter>update_func</parameter>)
LqrRetVal <function>lqr_progress_set_end</function> (&prog_obj; * <parameter>p</parameter>, LqrProgressFuncEnd <parameter>end_func</parameter>)
                    </programlisting>
                    as in this sample piece of code:
                    <example id="ex-set-progress">
                        <title>Setting progress hooks</title>
                        <programlisting>
LqrProgress *p;

p = lqr_progress_new();
lqr_progress_set_init (p, my_init);
lqr_progress_set_update (p, my_update);
lqr_progress_set_end (p, my_end);
                        </programlisting>
                    </example>
                </para>
                <para>
                    The above example requires that the hook functions <function>my_init</function>,
                    <function>my_update</function> and <function>my_end</function> are defined as in the following
                    sample declarations:
                    <example id="ex-hook-decl">
                        <title>Progress hooks declaration</title>
                        <programlisting>
LqrRetVal my_init (const gchar *init_message);
LqrRetVal my_update (gdouble percentage);
LqrRetVal my_end (const gchar *end_message);
                        </programlisting>
                    </example>
                </para>
            </sect2>

            <sect2 id="progress-messages">
                <title>Initial and ending progress messages</title>
                <para>
                    The init and end hooks will be called at the beginning and at the end of each rescaling operation by
                    function <function>lqr_carver_resize</function>. The messages that will be passed to these hooks
                    will change, depending if the resizing is occurring in the horizontal or in the vertical direction.
                    The defaults for newly created &prog_obj; objects are:
                    <table id="progress-mess-def">
                        <title>Default progress messages</title>
                        <tgroup cols="3">
                            <thead>
                                <row>
                                    <entry></entry>
                                    <entry>init</entry>
                                    <entry>end</entry>
                                </row>
                            </thead>
                            <tbody>
                                <row>
                                    <entry>horizontal</entry>
                                    <entry>&prog_init_w_mess;</entry>
                                    <entry>&prog_end_w_mess;</entry>
                                </row>
                                <row>
                                    <entry>vertical</entry>
                                    <entry>&prog_init_h_mess;</entry>
                                    <entry>&prog_end_h_mess;</entry>
                                </row>
                            </tbody>
                        </tgroup>
                    </table>
                    These can be changed using these functions:
                    <programlisting>
LqrRetVal <function>lqr_progress_set_init_width_message</function> (&prog_obj; *<parameter>p</parameter>, const gchar * <parameter>message</parameter>)
LqrRetVal <function>lqr_progress_set_init_height_message</function> (&prog_obj; *<parameter>p</parameter>, const gchar * <parameter>message</parameter>)
LqrRetVal <function>lqr_progress_set_end_width_message</function> (&prog_obj; *<parameter>p</parameter>, const gchar * <parameter>message</parameter>)
LqrRetVal <function>lqr_progress_set_end_height_message</function> (&prog_obj; *<parameter>p</parameter>, const gchar * <parameter>message</parameter>)
                    </programlisting>
                </para>
            </sect2>

            <sect2 id="progress-upd-step">
                <title>Progress update step</title>
                <para>
                    The update hook will be called at regular intervals, and it will be passed the completion percentage
                    as the argument.
                </para>
                <para>
                    The update step can be specified through:
                    <funcsynopsis>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_progress_set_update_step</function></funcdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                            <paramdef>gfloat <parameter>update_step</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </para>
                <para>
                    The default step is 0.02 (i.e. 2%).
                </para>
            </sect2>
        </sect1>

        <sect1 id="release">
            <title>Releasing the memory</title>

            <para>
                &carv_obj; objects can be destroyed using this function:
                <funcsynopsis>
                    <funcprototype>
                        <funcdef>void <function>lqr_carver_destroy</function></funcdef>
                        <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                    </funcprototype>
                </funcsynopsis>
            </para>
            <para>
                This function also destroys any attached object, thus it should never be called on attached carvers.
            </para>
            <para>
                &vmap_obj; objects can be destroyed using this function:
                <funcsynopsis>
                    <funcprototype>
                        <funcdef>void <function>lqr_vmap_destroy</function></funcdef>
                        <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
                    </funcprototype>
                </funcsynopsis>
            </para>
        </sect1>
    </chapter>

    <chapter id="ref-pages">
        <title>LqR library API reference</title>

        <sect1 id="ref-const">
            <title>Types defined by the library</title>

            <refentry id="ref-lqr-ret-val">
                <refmeta>
                    <refentrytitle><type>LqrRetVal</type></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>LqrRetVal</refname>
                    <refpurpose>the return value of many &lqrl; functions</refpurpose>
                </refnamediv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The return type of many functions in the &lqrl; is <type>LqrRetVal</type>, which is an
                        <literal>enum</literal> type that can take these values:
                        <variablelist>
                            <varlistentry>
                                <term>&err_ok;</term>
                                <listitem>
                                    <para>
                                        everyting OK
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>&err_err;</term>
                                <listitem>
                                    <para>
                                        generic <errortype>fatal</errortype> error
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>&err_nomem;</term>
                                <listitem>
                                    <para>
                                        not enough memory
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>&err_cancel;</term>
                                <listitem>
                                    <para>
                                        action cancelled by the user
                                    </para>
                                </listitem>
                            </varlistentry>
                        </variablelist>
                    </para>
                    <para>
                        The user should handle the error values explicitly at each function call returning this type.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-init"></xref></member>
                            <member><xref linkend="ref-lqr-carver-cancel"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-col-depth">
                <refmeta>
                    <refentrytitle><type>LqrColDepth</type></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>LqrColDepth</refname>
                    <refpurpose>carver objects colour depth specification</refpurpose>
                </refnamediv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The default &carv_obj; object constructor <function>lqr_carver_new</function> uses a colour
                        depth of 8 bits per channel, and therefore its input must be an array of <type>unsigned
                        char</type>s. However, the &carv_obj; objects can handle images of grater colour depth, if
                        they are created with the <function>lqr_carver_new_ext</function> constructor. The possible
                        colour depths are specified through variables of type <type>LqrColDepth</type>, which is an enum
                        type; its possible values, and the type of the input buffer associated with them, are:
                        <variablelist>
                            <varlistentry>
                                <term>&col_depth_8i;</term>
                                <listitem>
                                    <para>
                                        use type <type>guchar</type> (8 bit unsigned integers) - the default
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>&col_depth_16i;</term>
                                <listitem>
                                    <para>
                                        use type <type>guint16</type> (16 bit unsigned integers)
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>&col_depth_32f;</term>
                                <listitem>
                                    <para>
                                        use type <type>gfloat</type> (32 bit floating point)
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>&col_depth_64f;</term>
                                <listitem>
                                    <para>
                                        use type <type>gdouble</type> (64 bit floating point)
                                    </para>
                                </listitem>
                            </varlistentry>
                        </variablelist>
                    </para>
                    <para>
                        These values are also relevant when reading out a &carv_obj; object with the functions
                        <function>lqr_carver_scan_ext</function> or <function>lqr_carver_scan_line_ext</function>, since
                        the readout buffer must be cast to the appropriate type to be actually read. 
                    </para>
                    <para>
                        The colour depth of an &carv_obj; object can be obtained with the function
                        <function>lqr_carver_get_col_depth</function>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-new"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan-line"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-image-type">
                <refmeta>
                    <refentrytitle><type>LqrImageType</type></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>LqrImageType</refname>
                    <refpurpose>carver objects image type (colour model) specification</refpurpose>
                </refnamediv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The &carv_obj; objects use knowledge about the image type they're working on in order to compute
                        correctly some quantities (e.g. the brightness) for the automatic feature detection. Image types
                        are set automatically by the constructors, but they can also be specified manually using
                        quantities of the type <type>LqrImageType</type>, which is an <literal>enum</literal> which can
                        take these values:
                        <itemizedlist>
                            <listitem>&img_type_grey;</listitem>
                            <listitem>&img_type_greya;</listitem>
                            <listitem>&img_type_rgb;</listitem>
                            <listitem>&img_type_rgba;</listitem>
                            <listitem>&img_type_cmy;</listitem>
                            <listitem>&img_type_cmyk;</listitem>
                            <listitem>&img_type_cmyka;</listitem>
                            <listitem>&img_type_custom;</listitem>
                        </itemizedlist>
                    </para>
                    <para>
                        Use the function <xref linkend="ref-lqr-carver-set-image-type"></xref> to set the image type of
                        a carver, and the function <xref linkend="ref-lqr-carver-get-image-type"></xref> to read it out.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-new"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-image-type"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>
        </sect1>

        <sect1 id="ref-carve">
            <title>Carver objects</title>

            <refentry id="ref-lqr-carver-new">
                <refmeta>
                    <refentrytitle><function>lqr_carver_new</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_new</refname>
                    <refname>lqr_carver_new_ext</refname>
                    <refpurpose>the &carv_obj; object constructors</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrCarver* <function>lqr_carver_new</function></funcdef>
                            <paramdef>guchar* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>channels</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>LqrCarver* <function>lqr_carver_new_ext</function></funcdef>
                            <paramdef>void* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>channels</parameter></paramdef>
                            <paramdef>LqrColDepth <parameter>colour_depth</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The functions <function>lqr_carver_new</function> and <function>lqr_carver_new_ext</function>
                        create a new &carv_obj; object from an image of size &param_w; * &param_h; with &param_channels;
                        colour channels.
                    </para>
                    <para>
                        The image must be stored in <parameter>buffer</parameter> as a plain array of unsigned chars
                        (for <function>lqr_carver_new</function>) or the appropriate type cast to void (for
                        <function>lqr_carver_new_ext</function>), ordered by row, then by column, then by colour
                        channel.
                    </para>
                    <para>
                        In the extended constructor <function>lqr_carver_new_ext</function>, the additional parameter
                        <parameter>colour_depth</parameter> is required to specify the colour depth of the buffer (see
                        <xref linkend="ref-lqr-col-depth"></xref> for more information).
                    </para>
                    <para>
                        After calling the function, the buffer will be owned by the &carv_obj; object and must not be
                        accessed any more, unless you subsequently call the <xref
                            linkend="ref-lqr-carver-set-preserve-input-image"></xref> function.
                    </para>
                    <para>
                        The image type is et automatically from the value of <parameter>channels</parameter> according
                        to this table:
                        <table id="ref-def-image-types">
                            <title>Image types assigned by default</title>
                            <tgroup cols="2">
                                <thead>
                                    <row>
                                        <entry>channels</entry>
                                        <entry>type</entry>
                                    </row>
                                </thead>
                                <tbody>
                                    <row>
                                        <entry>1</entry>
                                        <entry>&img_type_grey;</entry>
                                    </row>
                                    <row>
                                        <entry>2</entry>
                                        <entry>&img_type_greya;</entry>
                                    </row>
                                    <row>
                                        <entry>3</entry>
                                        <entry>&img_type_rgb;</entry>
                                    </row>
                                    <row>
                                        <entry>4</entry>
                                        <entry>&img_type_rgba;</entry>
                                    </row>
                                    <row>
                                        <entry>5</entry>
                                        <entry>&img_type_cmyka;</entry>
                                    </row>
                                    <row>
                                        <entry>&gt;5</entry>
                                        <entry>&img_type_custom;</entry>
                                    </row>
                                </tbody>
                            </tgroup>
                        </table>
                    </para>
                </refsect1>
                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value is the address of the newly created &carv_obj; object, or &ret_null; in case of
                        failure (insufficient memory).
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-destroy"></xref></member>
                            <member><xref linkend="ref-lqr-carver-init"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-destroy">
                <refmeta>
                    <refentrytitle><function>lqr_carver_destroy</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_destroy</refname>
                    <refpurpose>the &carv_obj; object destructor</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_destroy</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_destroy</function> destroys the &carv_obj; object pointed to
                        by <parameter>carver</parameter>, and all of its attched components (visibility maps and
                        attached carvers). It must never be invoked over a carver which is attached to another one.
                    </para>
                    <para>
                        This function will not release the memory buffer passed to
                        <xref linkend="ref-lqr-carver-new"></xref> if it was protected by calling
                        <xref linkend="ref-lqr-carver-set-preserve-input-image"></xref>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-new"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-destroy"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-init">
                <refmeta>
                    <refentrytitle><function>lqr_carver_init</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_init</refname>
                    <refpurpose>activates an &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_init</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gint <parameter>delta_x</parameter></paramdef>
                            <paramdef>gfloat <parameter>rigidity</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_init</function> initialises the &carv_obj; pointed to by
                        <parameter>carver</parameter>, so that it can compute the visibility maps as needed upon calls
                        of <function>lqr_carver_resize</function>.
                    </para>
                    <para>
                        The parameter <parameter>delta_x</parameter> controls the maximum transversal step a seam can
                        make. A value of 0 means straight seams. Normally, it is set to 1.
                    </para>
                    <para>
                        The parameter <parameter>rigidity</parameter> can be used to add a negative bias to non-straight
                        seams, and it is normally set to 0.
                    </para>
                    <para>
                        Visibility maps must not be loaded with the function <function>lqr_vmap_load</function> when
                        using this function, neither before nor after invoking it.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-carver-new"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-load"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-image-type">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_image_type</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_image_type</refname>
                    <refpurpose>sets the image type of an &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_image_type</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrImageType <parameter>image_type</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_set_image_type</function> sets the image type of the
                        &carv_obj; pointed to by <parameter>carver</parameter> to <parameter>image_type</parameter>.
                    </para>
                    <para>
                        If <parameter>image_type</parameter> is equal to &img_type_custom;, it is assumed that there are
                        no alpha or black channels. You can set those independently using
                        <xref linkend="ref-lqr-carver-set-alpha-channel"></xref> and
                        <xref linkend="ref-lqr-carver-set-black-channel"></xref>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-new"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-alpha-channel"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-black-channel"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-image-type"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-alpha-channel">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_alpha_channel</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_alpha_channel</refname>
                    <refpurpose>sets the alpha channel index in a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_alpha_channel</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef> gint <parameter>channel_index</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_set_alpha_channel</function> sets the alpha channel index of
                        the image stored in the &carv_obj; pointed to by <parameter>carver</parameter> to
                        <parameter>channel_index</parameter> (between <literal>0</literal> and <literal>channels -
                        1</literal>, where <literal>channels</literal> is the number of colour channels of the
                        <parameter>carver</parameter>).
                    </para>
                    <para>
                        Use a negative value for <parameter>cahnnel_index</parameter> to specify that no alpha channel
                        is present.
                    </para>
                    <para>
                        If the specified channel coincides with the current value of the black channel, the black
                        channel is unset.
                    </para>
                    <para>
                        Calling this function sets the image time of the <parameter>carver</parameter> to
                        &img_type_custom;.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-new"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-black-channel"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-black-channel">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_black_channel</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_black_channel</refname>
                    <refpurpose>sets the black channel index in a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_black_channel</function></funcdef>
                            <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
                            <paramdef> gint <parameter>channel_index</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_set_black_channel</function> sets the black channel index of
                        the image stored in the &carv_obj; pointed to by <parameter>carver</parameter> to
                        <parameter>channel_index</parameter> (between <literal>0</literal> and <literal>channels -
                        1</literal>, where <literal>channels</literal> is the number of colour channels of the
                        <parameter>carver</parameter>).
                    </para>
                    <para>
                        Use a negative value for <parameter>cahnnel_index</parameter> to specify that no black channel
                        is present.
                    </para>
                    <para>
                        If the specified channel coincides with the current value of the alpha channel, the alpha
                        channel is unset.
                    </para>
                    <para>
                        Calling this function sets the image time of the <parameter>carver</parameter> to
                        &img_type_custom;. Furthermore, the image color model will be assumed to be subtractive by the
                        function <xref linkend="ref-lqr-rwindow-read"></xref> when it computes the brightness or the luma.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-new"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-alpha-channel"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>



            <refentry id="ref-lqr-carver-resize">
                <refmeta>
                    <refentrytitle><function>lqr_carver_resize</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_resize</refname>
                    <refpurpose>liquid rescale a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_resize</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gint <parameter>new_width</parameter></paramdef>
                            <paramdef>gint <parameter>new_height</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_resize</function> performs the liquid rescaling over the
                        &carv_obj; object pointed to by <parameter>carver</parameter>. If a visibility map was loaded
                        through the function <function>lqr_vmap_load</function>, and the carver was not initialised, the
                        resizing operations must be limited to the direction and the sizes included in the loaded map.
                        If the carver was initialised through the function <function>lqr_carver_init</function>, there
                        are no limitations to the final size.
                    </para>
                    <para>
                        The resizing function can be called multiple times, and it will decide automatically whether the
                        computation of the visibility map is necessary or not. In case it isn't, the function returns
                        almost immediately, otherwise operations will proceed following the order given through the
                        function <function>lqr_carver_set_resize_order</function>. Currently, on-the-fly rescaling
                        without computation is only possible for a single direction at a time.
                    </para>
                    <para>
                        If the new size (in one direction or in both) is greater than or equal to the original size
                        multiplied by the enlargement step of the <parameter>carver</parameter> object (as obtained
                        through <xref linkend="ref-lqr-carver-get-enl-step"></xref>), the rescaling will be performed in
                        multiple steps. At each step, the original size stored internally is reset to the new value;
                        therefore, each step in the process can be bigger then the previous one.
                    </para>
                    <para>
                        Whenever the resizing dirction changes (this may happen in a single call of the rescaling
                        function or through multiple calls), or if performing a multiple steps enlargement as per the
                        previous paragraph, the visibility map computed during the first direction rescale is dropped to
                        make place for the one for the second (and the original size of the image is reset to the
                        current value). These visibility maps can be saved by using the
                        <function>lqr_carver_set_vmap_dump</function> function, for inspection or future use.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system. It returns an error if trying to exceed
                        the limitations of a loaded visibility map, or if passed a negative or null size.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-carver-init"></xref></member>
                            <member><xref linkend="ref-lqr-carver-flatten"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-cancel"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-load"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-flatten">
                <refmeta>
                    <refentrytitle><function>lqr_carver_flatten</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_flatten</refname>
                    <refpurpose>flatten a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_flatten</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_flatten</function> can be used to discard the visibility map
                        information and flatten the multi-size image contained in the &carv_obj; object pointed to by
                        <parameter>carver</parameter> to its current state.
                    </para>
                    <para>
                        It will also reset the internally stored original width and height, as if the image was just
                        loaded in the &carv_obj; object.
                    </para>
                    <para>
                        This function must only be invoked over initialised &carv_obj; objects.
                    </para>
                    <para>
                        This function is called internally each time the rescaling direction changes, or at each new
                        step in a multiple-step enlargement, but, when calling it manually, the discarded visibility map
                        will not be dumped automatically by it; use the functions
                        <xref linkend="ref-lqr-vmap-dump"></xref> or <xref linkend="ref-lqr-vmap-internal-dump"></xref>
                        in order to save it before invoking this function.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system. Errors can occur for non-initialised
                        &carv_obj; objects or in case of insufficient memory.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-carver-init"></xref></member>
                            <member><xref linkend="ref-lqr-carver-resize"></xref></member>
                            <member><xref linkend="ref-lqr-carver-cancel"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-cancel">
                <refmeta>
                    <refentrytitle><function>lqr_carver_cancel</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_cancel</refname>
                    <refpurpose>cancel ongoing operations on a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_cancel</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_cancel</function> can be used to cancel an ongoing operation
                        which is currently being performed on the the &carv_obj; object pointed to by
                        <parameter>carver</parameter>. It must be used asynchronouly, from within an independent thread.
                    </para>
                    <para>
                        If an operation is in fact cancelled by this function, the function which was performing the
                        operation will return the value &err_cancel;, and so will do any other operation successively
                        called on the same &carv_obj; object whose return type is <classname>LqrRetVal</classname>;
                        otherwise it will have no effect.
                    </para>
                    <para>
                        Whenever a function returns &err_cancel;, it means that the &carv_obj; object is in an
                        inconsistent state, and, since there is currently no way to recover from this situation, any
                        further operation on that object must be avoided, and it must be destroyed.
                    </para>
                    <para>
                        This function will fail if invoked over attached &carv_obj; objects.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system. However, it can be called multiple times,
                        so it will never return &err_cancel; itself.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-carver-resize"></xref></member>
                            <member><xref linkend="ref-lqr-carver-flatten"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-scan-reset">
                <refmeta>
                    <refentrytitle><function>lqr_carver_scan_reset</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_scan_reset</refname>
                    <refpurpose>reset the readout cursor of a multi-size image</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_scan_reset</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_scan_reset</function> resets the readout pointer associated
                        with the &carv_obj; object pointed to by <parameter>carver</parameter> to the start of the
                        image. (Normally, calling this function isn't needed, as the pointer is reset automatically
                        whenever an operation is performed or once a readout has completed.)
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-scan"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan-by-row"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan-line"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>

            </refentry>

            <refentry id="ref-lqr-carver-scan">
                <refmeta>
                    <refentrytitle><function>lqr_carver_scan</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_scan</refname>
                    <refname>lqr_carver_scan_ext</refname>
                    <refpurpose>read out a multi-size image one pixel at a time</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_scan</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gint* <parameter>x</parameter></paramdef>
                            <paramdef>gint* <parameter>y</parameter></paramdef>
                            <paramdef>guchar** <parameter>rgb</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_scan_ext</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gint* <parameter>x</parameter></paramdef>
                            <paramdef>gint* <parameter>y</parameter></paramdef>
                            <paramdef>void** <parameter>rgb</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The functions <function>lqr_carver_scan</function> and <function>lqr_carver_scan_ext</function>
                        are used to read out the multi-size image contained in the &carv_obj; object pointed to by
                        <parameter>carver</parameter> one pixel at a time. They store the pixel coordinates in the
                        variables pointed to by <parameter>x</parameter> and <parameter>y</parameter>, and the pixel
                        content in the array pointed to by <parameter>rgb</parameter>; then they move the readout
                        pointer to the next pixel, or they reset it if the end of the image is reached.
                    </para>
                    <para>
                        The first one must only be used on the &carv_obj; objects created with
                        <parameter>lqr_carver_new</parameter>, i.e. with 8-bit images, while the second one is general
                        (see <xref linkend="ref-lqr-col-depth"></xref>), but the <parameter>rgb</parameter> pointer must
                        be cast to the appropriate type to be used (i.e pass the address of a pointer to
                        <literal>void</literal> to the function <function>lqr_carver_scan_ext</function>, then cast it
                        to a pointer of the appropriate type and use this last one for reading the output).
                    </para>
                    <para>
                        The <parameter>rgb</parameter> variable will point to an array which is internal to the
                        &carv_obj; object, so there is no need to allocate memory for it. However, it should only be
                        accessed right after a call to the scan functions, and writing to it must be avoided.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        These functions return &ret_true; in case the readout is successful and the end of the image
                        was not reached, &ret_false; otherwise.
                        If <function>lqr_carver_scan</function> is called over a non-8-bit &carv_obj; object,
                        it will return &ret_false;.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan-reset"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan-line"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>

            </refentry>

            <refentry id="ref-lqr-carver-scan-by-row">
                <refmeta>
                    <refentrytitle><function>lqr_carver_scan_by_row</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_scan_by_row</refname>
                    <refpurpose>tells if the image in &carv_obj; will be scanned by row or by column</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_scan_by_row</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_scan_by_row</function> must be used before calling the
                        functions
                        <link linkend="ref-lqr-carver-scan-line"><function>lqr_carver_scan_line</function></link> and
                        <link linkend="ref-lqr-carver-scan-line"><function>lqr_carver_scan_line_ext</function></link>,
                        in order to ascertain if those functions will scan the multi-size image contained in the
                        &carv_obj; object pointed to by <parameter>carver</parameter> by row or by column, which depends
                        on which was last rescaling direction and cannot be controlled directly by the user.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        This function returns &ret_true; in case the image is going to be scanned by row, &ret_false; in
                        case it is going to be scanned by column;
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-scan-reset"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan-line"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-scan-line">
                <refmeta>
                    <refentrytitle><function>lqr_carver_scan_line</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_scan_line</refname>
                    <refname>lqr_carver_scan_line_ext</refname>
                    <refpurpose>read out a multi-size image one line at a time</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_scan_line</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gint* <parameter>n</parameter></paramdef>
                            <paramdef>guchar** <parameter>rgb</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>gboolean <function>lqr_carver_scan_line_ext</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gint* <parameter>n</parameter></paramdef>
                            <paramdef>void** <parameter>rgb</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The functions <function>lqr_carver_scan_line</function> and
                        <function>lqr_carver_scan_line_ext</function> are used to read out the multi-size image
                        contained in the &carv_obj; object pointed to by <parameter>carver</parameter> one line at a
                        time. They store the line number (row or column) in the variable pointed to by
                        <parameter>n</parameter> and the colour values in the array pointed to by
                        <parameter>rgb</parameter>; then they move the readout pointer to the next line, or they reset
                        it if the end of the image is reached.
                    </para>
                    <para>
                        The first one must only be used on the &carv_obj; objects created with
                        <parameter>lqr_carver_new</parameter>, i.e. with 8-bit images, while the second one is general,
                        but the <parameter>rgb</parameter> pointer must be cast to the appropriate type to be used (i.e
                        pass the address of a pointer to <literal>void</literal> to the function
                        <function>lqr_carver_scan_line_ext</function>, then cast it to a pointer of the appropriate type
                        and use this last one for reading the output).
                    </para>
                    <para>
                        Use the function <xref linkend="ref-lqr-carver-scan-by-row"></xref> before calling these to know
                        whether your image will be scanned by row or by column.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        These functions return &ret_true; in case the readout is successful and the end of the image was
                        not reached, &ret_false; otherwise. If <function>lqr_carver_scan_line</function> is called over
                        a non-8-bit &carv_obj; object, it will return &ret_false;.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan-reset"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan"></xref></member>
                            <member><xref linkend="ref-lqr-carver-scan-by-row"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-width">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_width</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_width</refname>
                    <refpurpose>get the current width of a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_carver_get_width</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_get_width</function> returns the current width of the image
                        contained in the &carv_obj; object pointed to by <parameter>carver</parameter>, in pixel units.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-height">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_height</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_height</refname>
                    <refpurpose>get the current height of a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_carver_get_height</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_get_height</function> returns the current height of the image
                        contained in the &carv_obj; object pointed to by <parameter>carver</parameter>, in pixel units.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-ref-width">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_ref_width</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_ref_width</refname>
                    <refpurpose>get the reference width of a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_carver_get_ref_width</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_get_ref_width</function> returns the internal reference width
                        of the image contained in the &carv_obj; object pointed to by <parameter>carver</parameter>, in
                        pixel units.
                    </para>
                    <para>
                        The reference width is set as the original height at carver initialization, and reset any time
                        the carver gets subsequently flattened, either explicitly through <xref
                            linkend="ref-lqr-carver-flatten"></xref> or implicitly when the rescale direction changes or
                        an enlargment beyond the maximum enlargement step is performed.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-flatten"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-ref-height">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_ref_height</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_ref_height</refname>
                    <refpurpose>get the reference height of a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_carver_get_ref_height</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_get_ref_height</function> returns the internal reference
                        height of the image contained in the &carv_obj; object pointed to by
                        <parameter>carver</parameter>, in pixel units.
                    </para>
                    <para>
                        The reference height is set as the original height at carver initialization, and reset any time
                        the carver gets subsequently flattened, either explicitly through <xref
                            linkend="ref-lqr-carver-flatten"></xref> or implicitly when the rescale direction changes or
                        an enlargment beyond the maximum enlargement step is performed.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-flatten"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-channels">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_channels</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_channels</refname>
                    <refname>lqr_carver_get_bpp</refname>
                    <refpurpose>get the number of channels in a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_carver_get_channels</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>gint <function>lqr_carver_get_bpp</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The functions <function>lqr_carver_get_channels</function> returns the number of colour channels
                        of the image contained in the &carv_obj; object pointed to by <parameter>carver</parameter>.
                    </para>
                    <para>
                        The function <function>lqr_carver_get_bpp</function> is an alias for
                        <function>lqr_carver_get_channels</function>, it is deprecated and it is maintained for backward
                        compatibility purposes only.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-col-depth">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_col_depth</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_col_depth</refname>
                    <refpurpose>get the colour depth of a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrColDepth <function>lqr_carver_get_col_depth</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_get_col_depth</function> returns the colour depth of the image
                        contained in the &carv_obj; object pointed to by <parameter>carver</parameter>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-image-type">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_image_type</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_image_type</refname>
                    <refpurpose>get the image type of a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrImageType <function>lqr_carver_get_image_type</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_get_image_type</function> returns the image type (i.e. colour
                        model) of the image contained in the &carv_obj; object pointed to by
                        <parameter>carver</parameter>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-new"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-image-type"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-enl-step">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_enl_step</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_enl_step</refname>
                    <refpurpose>get the enlargement step of a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gfloat <function>lqr_carver_get_enl_step</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_get_enl_step</function> returns the enlargement step of the
                        &carv_obj; object pointed to by <parameter>carver</parameter>, i.e. the maximum enlargement
                        allowed in a single step for that carver, expressed as the ratio with respect to its reference
                        width (for horizontal rescalings) or height (for vertical rescalings). The returned value is
                        strictly greater than 1 and less than 2.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-resize"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-orientation">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_orientation</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_orientation</refname>
                    <refpurpose>get the orientation of a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_carver_get_orientation</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_get_orientation</function> returns the current orientation of
                        the visibility map internal to the &carv_obj; object pointed to by
                        <parameter>carver</parameter>, which is <literal>0</literal> if the last rescale operation has
                        been in the horizontal direction, <literal>1</literal> if it has been in the vertical direction.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-resize"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-depth">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_depth</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_depth</refname>
                    <refpurpose>get the depth of a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_carver_get_depth</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_get_depth</function> returns the current depth of the
                        visibility map internal to the &carv_obj; object pointed to by <parameter>vmap</parameter>, i.e.
                        the maximum amount of scaling which can be performed with respect to the internal reference
                        sizes in the current orientation without updating the internal map.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-resize"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-depth"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-enl-step">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_enl_step</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_enl_step</refname>
                    <refpurpose>set the enlargement step of a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_enl_step</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gfloat <parameter>enl_step</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_set_enl_step</function> sets the enlargement step of the
                        &carv_obj; object pointed to by <parameter>carver</parameter> to the value specified in
                        <parameter>enl_step</parameter>, which must be strictly greater than 1 and less than 2.
                    </para>
                    <para>
                        The enlargement step is the maximum enlargement ratio (with respect to either the original width
                        or original height of <parameter>carver</parameter>) which the function
                        <function>lqr_carver_resize</function> applies in a single step; if that function is asked a
                        greater enlargement, it divides the process in multiple steps (and updates the original sizes
                        accordingly at each new step - these can be readout at any time with
                        <xref linkend="ref-lqr-carver-get-ref-width"></xref> and
                        <xref linkend="ref-lqr-carver-get-ref-height"></xref>).
                    </para>
                    <para>
                        The default value for new &carv_obj; objects is 2.0.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system. &err_err; is returned if the
                        <parameter>enl_step</parameter> parameter is out of bounds.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-resize"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-resize-order">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_resize_order</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_resize_order</refname>
                    <refpurpose>set &carv_obj; object resize order</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_resize_order</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrResizeOrder <parameter>resize_order</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        When the function <xref linkend="ref-lqr-carver-resize"></xref> is invoked and both the
                        horizontal and vertical sizes are different from the current ones, the rescaling occurs first in
                        one direction and then in the other.
                    </para>
                    <para>
                        The function <function>lqr_carver_set_resize_order</function> can be used to set which direction
                        to rescale first for the &carv_obj; object pointed to by <parameter>carver</parameter>. The
                        parameter <parameter>resize_order</parameter> can take either the value
                        <literal>LQR_RES_ORDER_HOR</literal> (horizontal rescale first) or
                        <literal>LQR_RES_ORDER_VERT</literal> (vertical rescale first). By default, when an &carv_obj;
                        object is created, the value is set to <literal>LQR_RES_ORDER_HOR</literal>
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-dump-vmaps">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_dump_vmaps</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_dump_vmaps</refname>
                    <refname>lqr_carver_set_no_dump_vmaps</refname>
                    <refpurpose>set the visibility maps autodump for an &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_dump_vmaps</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_no_dump_vmaps</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        Invoking function <function>lqr_carver_set_dump_vmaps</function> over the &carv_obj; object
                        pointed to by <parameter>carver</parameter> has the effect of activating the automatic dumping
                        of visibility maps at each rescale operation (which by default is turned off).
                    </para>
                    <para>
                        Rescale operations involving both directions will dump two maps.
                    </para>
                    <para>
                        The dumped maps will be attached to the &carv_obj; object and can be accessed at any later time
                        using the functions <xref linkend="ref-lqr-vmap-list-foreach"></xref> or a combination of
                        <xref linkend="ref-lqr-vmap-list-start"></xref>, <xref linkend="ref-lqr-vmap-list-current"></xref>
                        and <xref linkend="ref-lqr-vmap-list-next"></xref>.
                    </para>
                    <para>
                        Using this setting is pointless if the &carv_obj; object is not initialised.
                    </para>
                    <para>
                        The function <function>lqr_carver_set_no_dump_vmaps</function> reverts the effect of the
                        previous one (but the maps dumped so far will be kept).
                    </para>
                    <para>
                        Note that it is also possible to dump the visibility maps manually; however, using the automatic
                        dump is the only way to get intermidiate maps when the function
                        <xref linkend="ref-lqr-carver-resize"></xref> performs the rescaling in both directions, or in
                        more than one step.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-init"></xref></member>
                            <member><xref linkend="ref-lqr-carver-resize"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-resize-order"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-start"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-current"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-next"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-foreach"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-side-switch-frequency">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_side_switch_frequency</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_side_switch_frequency</refname>
                    <refpurpose>set &carv_obj; object side switch frequency</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_side_switch_frequency</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>guint <parameter>switch_frequency</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        When the function <xref linkend="ref-lqr-carver-resize"></xref> is invoked, it computes a
                        relevance value for each pixel in the image, then chooses the optimal seam to carve based on
                        such relvance values. However, in the case two seams are equivalent (which may happen when
                        large portions of the image have the same colour, for example), the algorithm always chooses the
                        seams from one side.
                    </para>
                    <para>
                        In order to overcome this effect, an option is given to automatically switch the favoured side
                        during rescaling, at the cost of a slightly worse performance.
                    </para>
                    <para>
                        The function <function>lqr_carver_set_side_switch_frequency</function> sets the side switch
                        frequency to <parameter>switch_frequency</parameter> for the &carv_obj; object pointed to by
                        <parameter>carver</parameter>. This will have the effect that, for each rescale operation, the
                        favoured side will be switched <parameter>switch_frequency</parameter> times (or as much times
                        as the number of pixels to rescale).
                    </para>
                    <para>
                        The default value for newly created &carv_obj; objects is <literal>0</literal>.
                    </para>
                    <para>
                        As for the final result, a very small value (e.g. <literal>1<literal> to </literal>4</literal>)
                        will normally suffice to balance the left and right side of the image (or the top and the boddom
                        sides for vertical rescalings), without noticeable computational costs. However, in order to
                        obtain a smoother behaviour for the visibiliy map, i.e. for the intermediate steps, higher
                        values may be required.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-resize-order"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>


            <refentry id="ref-lqr-carver-set-progress">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_progress</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_progress</refname>
                    <refpurpose>set the progress report function for an &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_progress</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_set_progress</function> associates the progress indicator
                        pointed to by <parameter>progress</parameter> to the &carv_obj; object pointed to by
                        <parameter>carver</parameter>. Progress indicators objects are created with the function
                        <xref linkend="ref-lqr-progress-new"></xref>.
                    </para>
                    <para>
                        By default, no progress indicator is used.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-progress-new"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-resize-order"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-preserve-input-image">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_preserve_input_image</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_preserve_input_image</refname>
                    <refpurpose>set a flag to preserve the buffer passed to a &carv_obj; object upon creation</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_preserve_input_image</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_set_preserve_input_image</function> flags the &carv_obj;
                        object pointed to by <parameter>carver</parameter> so that it does not alter in any way the
                        buffer which is passed to it by the constructor. It must be used before any resizing-related
                        operation takes place, either after the <parameter>carver</parameter> construction or after the
                        calls to <xref linkend="ref-lqr-carver-init"></xref> or
                        <xref linkend="ref-lqr-vmap-load"></xref>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-init"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-load"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-resize-order"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-use-cache">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_use_cache</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_use_cache</refname>
                    <refpurpose>enable/disable &carv_obj; object cache</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_use_cache</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gboolean <parameter>use_cache</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_set_use_cache</function> can be used to disable or enable the
                        cache for the &carv_obj; object pointed to by <parameter>carver</parameter>.
                    </para>
                    <para>
                        By default, the caching is on.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-resize-order"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-attach">
                <refmeta>
                    <refentrytitle><function>lqr_carver_attach</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_attach</refname>
                    <refpurpose>attach an &carv_obj; to another &carv_obj;</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_attach</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrCarver* <parameter>aux</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_attach</function> is used to attach an &carv_obj; object
                        (pointed to by <parameter>aux</parameter>) to another one (pointed to by
                        <parameter>carver</parameter>). This will have the effect that each operation performed over
                        the <parameter>carver</parameter> object will be reflected on <parameter>aux</parameter> (they
                        will share the same visibility map).
                    </para>
                    <para>
                        This function must not be used after a visibility map was loaded into the base object (the one
                        pointed to by <parameter>carver</parameter>).
                    </para>
                    <para>
                        The object pointed to by <parameter>aux</parameter> must have the same original size as the base
                        object. Note that the original size information is reset whenever a flattening operation
                        occurs, or the rescaling direction changes, so that this function should be called befor
                        rescaling occurs.
                    </para>
                    <para>
                        There is no limitation on the number of &carv_obj; objects which is possible to attach. Nesting
                        is also possible. It is irrelevant if the <parameter>aux</parameter> carver is initialised or
                        not; from the moment of attachment, it will passively undergo all transformations performed over
                        <parameter>carver</parameter>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system. &err_err; is returned if the sizes of
                        <parameter>carver</parameter> and <parameter>aux</parameter> don't match.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-start"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-current"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-next"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-foreach"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-list-start">
                <refmeta>
                    <refentrytitle><function>lqr_carver_list_start</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_list_start</refname>
                    <refpurpose>get the staritng point of the attachement list in an &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrCarverList* <function>lqr_carver_list_start</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_list_start</function> returns the stating point of the
                        &carvl_obj; object associated with the &carv_obj; object pointed to by
                        <parameter>carver</parameter>, which is used to keep track of the &carv_obj; objects attached to
                        it.  
                    </para>
                    <para>
                        The returned value is &ret_null; if there are no attached carvers.
                    </para>
                    <para>
                        Use the functions <xref linkend="ref-lqr-carver-list-current"></xref> and
                        <xref linkend="ref-lqr-carver-list-next"></xref> to access the list element individually, or the
                        function <xref linkend="ref-lqr-carver-list-foreach"></xref> to operate on whole lists.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-attach"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-current"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-next"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-foreach"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-list-current">
                <refmeta>
                    <refentrytitle><function>lqr_carver_list_current</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_list_current</refname>
                    <refpurpose>get current &carv_obj; object in a &carvl_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrCarver* <function>lqr_carver_list_current</function></funcdef>
                            <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_list_current</function> returns a pointer to the &carv_obj;
                        object corresponding to the current value of the <parameter>list</parameter> parameter, or
                        &ret_null; in case of errors.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-attach"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-start"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-next"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-foreach"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-list-next">
                <refmeta>
                    <refentrytitle><function>lqr_carver_list_next</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_list_next</refname>
                    <refpurpose>advance the &carvl_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrCarverList* <function>lqr_carver_list_next</function></funcdef>
                            <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_list_next</function> returns a pointer to the next attached
                        &carv_obj; object in <parameter>list</parameter>, or &ret_null; if the list has reached the end.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-attach"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-start"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-current"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-foreach"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-list-foreach">
                <refmeta>
                    <refentrytitle><function>lqr_carver_list_foreach</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_list_foreach</refname>
                    <refpurpose>perform operations on all &carv_obj; objects in an &carvl_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_list_foreach</function></funcdef>
                            <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
                            <paramdef>LqrCarverFunc <parameter>func</parameter></paramdef>
                            <paramdef>LqrDataTok <parameter>data</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_list_foreach_recursive</function></funcdef>
                            <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
                            <paramdef>LqrCarverFunc <parameter>func</parameter></paramdef>
                            <paramdef>LqrDataTok <parameter>data</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_list_foreach</function> can be used to apply the function
                        <parameter>func</parameter> to all the &carv_obj; objects listed in <parameter>list</parameter>.
                        The parameter <parameter>data</parameter> is used to pass arguments to the function.
                    </para>
                    <para>
                        The <parameter>list</parameter> value should be obtained through the function
                        <xref linkend="ref-lqr-carver-list-start"></xref>. The order in the list will then follow the one
                        in which carver objects were attached.
                    </para>
                    <para>
                        The function <parameter>func</parameter> is of type <classname>LqrCarverFunc</classname>, whose
                        prototype is defined by:
                        <programlisting>
typedef LqrRetVal (*LqrCarverFunc) (LqrCarver *carver, LqrDataTok data);
                        </programlisting>
                        The <parameter>data</parameter> argument is of type <structname>LqrDataTok</structname>, which
                        is defined as a union with the following fields:
                        <itemizedlist>
                            <listitem>
                                <para><type>&carv_obj;*</type> <structfield>carver</structfield></para>
                            </listitem>
                            <listitem>
                                <para><type>gint</type> <structfield>integer</structfield></para>
                            </listitem>
                            <listitem>
                                <para><type>gpointer</type> <structfield>data</structfield></para> 
                            </listitem>
                        </itemizedlist>
                    </para>
                    <para>
                        The function <function>lqr_carver_list_foreach_recursive</function> is equivelant to
                        <function>lqr_carver_list_foreach</function>, but it works recursively if the &carv_obj; objects
                        in <parameter>list</parameter> have themselves other attached &carv_obj; objects attached. In
                        this case, the function <parameter>func</parameter> will be applied to each element of the list
                        and to each element of the attached list recursively, before moving on to the next element.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-carver-attach"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-start"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-current"></xref></member>
                            <member><xref linkend="ref-lqr-carver-list-next"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>
        </sect1>


        <sect1 id="ref-vmaps">
            <title>Visibiliy maps</title>

            <refentry id="ref-lqr-vmap-new">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_new</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_new</refname>
                    <refpurpose>the &vmap_obj; object constructor</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrVMap* <function>lqr_vmap_new</function></funcdef>
                            <paramdef>gint* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>depth</parameter></paramdef>
                            <paramdef>gint <parameter>orientation</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_new</function> is the constructor for &vmap_obj; objects. It can
                        be used to convert saved data in a format which can be loaded in an &carv_obj; object.
                    </para>
                    <para>
                        The parameter <parameter>buffer</parameter> must point to an an array of
                        <literal><parameter>width</parameter> * <parameter>height</parameter></literal>
                        <type>int</type>s holding the visibility information.
                    </para>
                    <para>
                        The parameter <parameter>depth</parameter> represents the maximum possible amount of rescaling
                        with the given map.
                    </para>
                    <para>
                        The parameter <parameter>orientation</parameter> must be <literal>0</literal> if the map is to
                        be used for horizontal rescaling, <literal>1</literal> if it is to be used for vertical
                        rescaling.
                    </para>
                </refsect1>
                <refsect1>
                    <title>Visibility maps format</title>
                    <para>
                        The <parameter>buffer</parameter> must be an array of integers of size
                        <literal><parameter>width</parameter> * <parameter>height</parameter></literal>. For an
                        horizontally oriented visibility map, the format is as such: each row must contain all values
                        between 1 and <parameter>depth</parameter> (included) exactly once, with low values indicating
                        the pixels which will be operated on first during rescaling. All other pixels must be 0, which
                        means that they won't be affected by rescaling. Such a map allows for horizontal rescaling in
                        the range from <literal><parameter>width</parameter> - <parameter>depth</parameter></literal> to
                        <literal><parameter>width</parameter> + <parameter>depth</parameter></literal>. The same
                        applies to vertically oriented visibility maps, with columns in place of rows and
                        <parameter>height</parameter> in place of <parameter>width</parameter>.
                    </para>
                </refsect1>
                <refsect1>
                    <title>Return value</title>
                    <para>
                        The function returns the newly created &vmap_obj; if successful, or &ret_null; in case of
                        insufficient memory.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-destroy"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-load"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-destroy">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_destroy</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_destroy</refname>
                    <refpurpose>the &vmap_obj; object destructor</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_vmap_destroy</function></funcdef>
                            <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_destroy</function> destroys the &vmap_obj; object. It is not
                        necessary to invoke it over visibility maps which were loaded in &carv_obj; objects, as this is
                        done already by the carver object destructor.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-new"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-load"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-get-data">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_get_data</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_get_data</refname>
                    <refpurpose>get varous &vmap_obj; object quantities</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint* <function>lqr_vmap_get_data</function></funcdef>
                            <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_get_data</function> returns an array with the data stored into
                        the &vmap_obj; object pointed to by <parameter>vmap</parameter>, ordered first by row, then by
                        column.
                    </para>
                    <para>
                        Reading the data requires retrieval of the other quantities, through the functions
                        <xref linkend="ref-lqr-vmap-get-depth"></xref>,
                        <xref linkend="ref-lqr-vmap-get-width"></xref>,
                        <xref linkend="ref-lqr-vmap-get-height"></xref> and
                        <xref linkend="ref-lqr-vmap-get-orientation"></xref>.
                    </para>
                    <para>
                        See the &vmap_obj; objects format description in the page for
                        <xref linkend="ref-lqr-vmap-new"></xref>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-new"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-depth"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-get-depth">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_get_depth</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_get_depth</refname>
                    <refpurpose>get the depth of an &vmap_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_vmap_get_depth</function></funcdef>
                            <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_get_depth</function> returns the depth of the &vmap_obj; object
                        pointed to by <parameter>vmap</parameter>, i.e. the maximum scaling allowed by it.
                    </para>
                    <para>
                        See the &vmap_obj; objects format description in the page for
                        <link linkend="ref-lqr-vmap-new">&vmap_obj; constructor and destructor</link>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-new"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-data"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-get-width">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_get_width</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_get_width</refname>
                    <refpurpose>get the width of an &vmap_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_vmap_get_width</function></funcdef>
                            <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_get_width</function> returns the width of the &vmap_obj; object
                        pointed to by <parameter>vmap</parameter>.
                    </para>
                    <para>
                        See the &vmap_obj; objects format description in the page for
                        <link linkend="ref-lqr-vmap-new">&vmap_obj; constructor and destructor</link>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-new"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-data"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-depth"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-height"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-get-height">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_get_height</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_get_height</refname>
                    <refpurpose>get the height of an &vmap_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_vmap_get_height</function></funcdef>
                            <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_get_height</function> returns the height of the &vmap_obj;
                        object pointed to by <parameter>vmap</parameter>.
                    </para>
                    <para>
                        See the &vmap_obj; objects format description in the page for
                        <link linkend="ref-lqr-vmap-new">&vmap_obj; constructor and destructor</link>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-new"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-data"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-depth"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-orientation"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-get-orientation">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_get_orientation</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_get_orientation</refname>
                    <refpurpose>get the orientation of an &vmap_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_vmap_get_orientation</function></funcdef>
                            <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_get_orientation</function> returns the orientation of the
                        &vmap_obj; object pointed to by <parameter>vmap</parameter>, which is <literal>0</literal> for
                        horizontally oriented maps, <literal>1</literal> for vertically oriented ones.
                    </para>
                    <para>
                        See the &vmap_obj; objects format description in the page for
                        <link linkend="ref-lqr-vmap-new">&vmap_obj; constructor and destructor</link>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-new"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-data"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-depth"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-width"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-get-height"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-dump">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_dump</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_dump</refname>
                    <refpurpose>dump an &vmap_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrVMap* <function>lqr_vmap_dump</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_dump</function> returns the current visibility map of the
                        &carv_obj; object pointed to by <parameter>carver</parameter>, or &ret_null; in case of errors.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-load"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-internal-dump">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_internal_dump</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_internal_dump</refname>
                    <refpurpose>dump an &vmap_obj; objects into an &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_vmap_internal_dump</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_internal_dump</function> dumps the current visibility map of the
                        &carv_obj; object pointed to by <parameter>carver</parameter> internally to it, attaching it to
                        the same &vmapl_obj; object list as the one used for automatic dumping (as activated by
                        <xref linkend="ref-lqr-carver-set-dump-vmaps"></xref>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-dump"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-load"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-load">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_load</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_load</refname>
                    <refpurpose>load an &vmap_obj; object into an &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_vmap_load</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_load</function> loads the visibility map contained in the
                        &vmap_obj; object pointed to by <parameter>vmap</parameter> in the &carv_obj; object pointed to
                        by <parameter>carver</parameter>.
                    </para>
                    <para>
                        It can only be called over uninitialised carver objects, therefore care must be taken not to
                        exceed the loaded map depth when resizing (see the &vmap_obj; objects format description in the
                        page for <xref linkend="ref-lqr-vmap-new"></xref>).
                    </para>
                    <refsect1>

                    </refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-new"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-dump"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-list-start">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_list_start</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_list_start</refname>
                    <refpurpose>get the &vmapl_obj; list attached to an &carv_obj;</refpurpose>
                </refnamediv>
                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrVMapList* <function>lqr_vmap_list_start</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_list_start</function> returns the stating point of the
                        &vmapl_obj; object associated with the &carv_obj; object pointed to by
                        <parameter>carver</parameter>, which is used to keep track of the &vmap_obj; objects internally
                        dumped by it.
                    </para>
                    <para>
                        The returned value is &ret_null; if there are no dumped visibility maps.
                    </para>
                    <para>
                        The function <function>lqr_vmap_list_current</function> returns the &vmap_obj; object
                        corresponding to the current value of the <parameter>list</parameter> parameter, or &ret_null;
                        in case of errors.
                    </para>
                    <para>
                        Use the functions <xref linkend="ref-lqr-vmap-list-current"></xref> and
                        <xref linkend="ref-lqr-vmap-list-next"></xref> to access the list element individually, or the
                        function <xref linkend="ref-lqr-vmap-list-foreach"></xref> to operate on whole lists.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-list-current"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-next"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-foreach"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-list-current">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_list_current</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_list_current</refname>
                    <refpurpose>get current &vmap_obj; object in a &vmapl_obj; object</refpurpose>
                </refnamediv>
                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrVMap <function>lqr_vmap_list_current</function></funcdef>
                            <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_list_current</function> returns the &vmap_obj; object
                        corresponding to the current value of the <parameter>list</parameter> parameter, or &ret_null;
                        in case of errors.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-list-start"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-next"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-foreach"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-list-next">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_list_next</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_list_next</refname>
                    <refpurpose>advance the &vmapl_obj; object</refpurpose>
                </refnamediv>
                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrVMapList <function>lqr_vmap_list_next</function></funcdef>
                            <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_list_next</function> returns a pointer the next dumped
                        &vmap_obj; object in <parameter>list</parameter>, or &ret_null; if the list has reached the end.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-vmap-list-start"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-current"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-foreach"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-vmap-list-foreach">
                <refmeta>
                    <refentrytitle><function>lqr_vmap_list_foreach</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_vmap_list_foreach</refname>
                    <refpurpose>perform operations on all &vmap_obj; objects in an &vmapl_obj; object</refpurpose>
                </refnamediv>
                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_vmap_list_foreach</function></funcdef>
                            <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
                            <paramdef>LqrVMapFunc <parameter>func</parameter></paramdef>
                            <paramdef>gpointer <parameter>data</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_vmap_list_foreach</function> can be used to apply the function
                        <parameter>func</parameter> to all the &vmap_obj; objects listed in <parameter>list</parameter>.
                        The parameter <parameter>data</parameter> is used to pass arguments to the function.
                    </para>
                    <para>
                        The <parameter>list</parameter> value should be obtained through the function
                        <xref linkend="ref-lqr-vmap-list-start"></xref>.
                    </para>
                    <para>
                        The function <parameter>func</parameter> is of type <classname>LqrVMapFunc</classname>, whose
                        prototype is defined by:
                        <programlisting>
typedef LqrRetVal (*LqrVMapFunc) (LqrVMap *vmap, gpointer data);
                        </programlisting>
                        The <parameter>data</parameter> argument is of type <structname>gpointer</structname>, which is
                        just a pointer to <literal><type>void</type></literal>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-start"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-current"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-list-next"></xref></member>
                            <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>

            </refentry>
        </sect1>

        <sect1 id="ref-energy">
            <title>Energy</title>

            <refentry id="ref-lqr-carver-set-energy-function-builtin">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_energy_function_builtin</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_bias_set_energy_function_builtin</refname>
                    <refpurpose>set a builtin energy function for a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_energy_function_builtin</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrEnergyFuncBuiltinType <parameter>ef_ind</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>

                    <para>
                        The function <function>lqr_carver_set_energy_function_builtin</function> allows to pick a
                        builtin energy function for the &carv_obj; object pointed to by <parameter>carver</parameter>.
                    </para>
                    <para>
                        The possible values for <parameter>ef_ind</parameter> are:
                        <variablelist>
                            <varlistentry>
                                <term><literal>LQR_EF_GRAD_XABS</literal></term>
                                <listitem>
                                    <para>
                                        absolute value of the brightness gradient in the direction of the rescaling
                                        (this is the default)
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term><literal>LQR_EF_GRAD_SUMABS</literal></term>
                                <listitem>
                                    <para>
                                        sum of absolute values of the brightness gradients in both directions
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term><literal>LQR_EF_GRAD_NORM</literal></term>
                                <listitem>
                                    <para>
                                        norm of the brightness gradient
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term><literal>LQR_EF_LUMA_GRAD_XABS</literal></term>
                                <listitem>
                                    <para>
                                        absolute value of the luma gradient in the direction of the rescaling
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term><literal>LQR_EF_LUMA_GRAD_SUMABS</literal></term>
                                <listitem>
                                    <para>
                                        sum of absolute values of the luma gradients in both directions
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term><literal>LQR_EF_LUMA_GRAD_NORM</literal></term>
                                <listitem>
                                    <para>
                                        norm of the luma gradient
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term><literal>LQR_EF_NULL</literal></term>
                                <listitem>
                                    <para>
                                        null
                                    </para>
                                </listitem>
                            </varlistentry>
                        </variablelist>
                    </para>
                    <para>
                        All of the above gradient functions have a radius of 1 pixel.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-energy"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-energy-function">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_energy_function</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_bias_set_energy_function</refname>
                    <refpurpose>set a custom energy function for a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_set_energy_function</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrEnergyFunc <parameter>en_func</parameter></paramdef>
                            <paramdef>gint <parameter>radius</parameter></paramdef>
                            <paramdef>LqrEnergyReaderType <parameter>reader_type</parameter></paramdef>
                            <paramdef>gpointer <parameter>extra_data</parameter></paramdef>

                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>

                    <para>
                        The function <function>lqr_carver_set_energy_function</function> assigns the energy function
                        <parameter>en_func</parameter> to the &carv_obj; object pointed to by
                        <parameter>carver</parameter> (see below for more details on custom functions definitions).
                    </para>
                    <para>
                        The parameter <parameter>radius</parameter> determines the size of the square region which
                        affects the computation around each pixel (the side of the square will be <literal>2 *
                        <parameter>radius</parameter> + 1</literal> pixels long).
                    </para>
                    <para>
                        The parameter <parameter>reader_type</parameter> sets the reader type used when reading the
                        image, and therefore it determines what quantity will be passed on to the function
                        <parameter>en_func</parameter> (see below for more details on reader types).
                    </para>
                    <para>
                        The parameter <parameter>extra_data</parameter> is a (void) pointer which can be used to pass on
                        additional values to the function <parameter>ef_func</parameter>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Custom functions definition</title>

                    <para>
                        The function <parameter>en_func</parameter> must be of type
                        <classname>LqrEnergyFunc</classname>, whose prototype is defined by:
                        <programlisting>
typedef gfloat (*LqrEnergyFunc) (gint x, gint y, gint img_width, gint img_height, LqrReadingWindow * rwindow, gpointer extra_data);
                        </programlisting>
                        Such a function is expected to compute the energy at pixel &param_x;, &param_y; based on the
                        knowledge of the current image size (obtained from &param_w; and &param_h;) and the content of
                        the image in a square around that pixel, which is passed through the
                        <parameter>rwindow</parameter> reading window.
                    </para>
                    <para>
                        In most cases, the parameters &param_x;, &param_y;, &param_w; and &param_h; would only be used
                        to determine whether the region under consideration is at the image boundary or not.
                    </para>
                    <para>
                        The <parameter>rwindow</parameter> content must be read using the function
                        <xref linkend="ref-lqr-rwindow-read"></xref>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Reader types</title>

                    <para>
                        The <type><literal>LqrEnergyReaderType</literal></type> is an enum which can take these values
                        (also noted is the number of channels of the corresponging reading window):
                        <variablelist>
                            <varlistentry>
                                <term><literal>LQR_ER_BRIGHTNESS</literal></term>
                                <listitem>
                                    <para>
                                        brightness (1 channel)
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term><literal>LQR_ER_BRIGHTNESS</literal></term>
                                <listitem>
                                    <para>
                                        luma (1 channel)
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term><literal>LQR_ER_RGBA</literal></term>
                                <listitem>
                                    <para>
                                        RGBA (4 channels)
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term><literal>LQR_ER_CUSTOM</literal></term>
                                <listitem>
                                    <para>
                                        read the normalised image channels as they are (as many channels as the image has)
                                    </para>
                                </listitem>
                            </varlistentry>
                        </variablelist>
                        These readouts always return values beetween <literal>0</literal> and <literal>1</literal>.
                    </para>
                    <para>
                        Note that these readouts may have special meanings depending on the image type:
                        <itemizedlist>
                            <listitem>
                                <para>
                                    for <literal>LQR_GREY_IMAGE</literal>, <literal>LQR_GREYA_IMAGE</literal> and
                                    <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_LUMA</literal>
                                    readout will yield the same result as <literal>LQR_ER_BRIGHTNESS</literal>
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    for <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_BRIGHTNESS</literal>
                                    readout will return the average pixel value (additive, i.e. if a black channel is
                                    present the channel values will be inverted and multiplied by the black channel
                                    inverse), multiplied by the alpha channel value.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    for <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_RGBA</literal>
                                    readout <emphasis>cannot be used</emphasis>: it will always return
                                    <literal>0</literal>
                                </para>
                            </listitem>
                        </itemizedlist>
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-energy-function-builtin"></xref></member>
                            <member><xref linkend="ref-lqr-carver-get-energy"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-read"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-read-t"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-radius"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-channels"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-get-energy">
                <refmeta>
                    <refentrytitle><function>lqr_carver_get_energy</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_get_energy</refname>
                    <refname>lqr_carver_get_true_energy</refname>
                    <refname>lqr_carver_get_energy_image</refname>
                    <refpurpose>get the energy map for a &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_get_energy</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gfloat * <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>orientation</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_get_true_energy</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gfloat * <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>orientation</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_get_energy</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>void * <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>orientation</parameter></paramdef>
                            <paramdef>LqrColDepth <parameter>col_depth</parameter></paramdef>
                            <paramdef>LqrImageType <parameter>image_type</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>

                    <para>
                        The function <function>lqr_carver_get_energy</function> writes the energy map of the &carv_obj;
                        object pointed to by <parameter>carver</parameter> to the given <parameter>buffer</parameter>,
                        in a format suitable for plotting: all values are in the range between <literal>0</literal> and
                        <literal>1</literal>, and the true values are mapped nonlinearly and stretched on this whole
                        range, so that the differences between the middle values are enhanced with respect to very high
                        or very low values.
                    </para>
                    <para>
                        The <parameter>orientation</parameter> parameter must be either <literal>0</literal> to get the
                        energy map used for horizontal scalings, or <literal>1</literal> to get the map for vertical
                        scalings.
                    </para>
                    <para>
                        The buffer must be allocated by the user before calling this function, and its size must be at
                        least <literal>&param_w; * &param_h;</literal>, where &param_w; and &param_h; are the current
                        width and height of the <parameter>carver</parameter>. The energy values are ordered by row
                        first, then by column.
                    </para>
                    <para>
                        The outcome will include the effect of the bias added to the <parameter>carver</parameter>, if
                        any.
                    </para>
                    <para>
                        This function can be called over non-initialised &carv_obj; objects, e.g. to provide previews on
                        the effect of different energy functions, but it can also be invoked at any later time. Note,
                        however, that in this latter case the <parameter>carver</parameter> could be flattened if
                        necessary, therefore the function invocation is potentially destructive of the internal
                        visibiliy map.
                    </para>
                    <para>
                        The function <function>lqr_carvet_get_true_energy</function> is identical to the previous one,
                        but the resulting buffer will contain the true energy, not scaled nor shifted.
                    </para>
                    <para>
                        The function <function>lqr_carver_get_energy_image</function> is very similar to the function
                        <function>lqr_carveR_get_energy</function>, but it can be used to fill directly an image buffer
                        of the format specified through the additional parameters <parameter>col_depth</parameter> and
                        <parameter>image_type</parameter> (see <xref linkend="ref-lqr-col-depth"></xref> and
                        <xref linkend="ref-lqr-image-type"></xref>). The <parameter>buffer</parameter> must be passed as
                        <type>void*</type>, but it must point to a memory area with sufficient allocated space for the
                        chosen image type and colour depth. The image type cannot be &img_type_custom;.
                    </para>
                    <para>
                        For any choice of the parameters describing the image, the resulting
                        <parameter>buffer</parameter> will hold a greyscale image, ranging from black (lowest energy) to
                        white (highest energy). The opacity (alpha) will be set to <literal>1</literal>, if present. All
                        the information will be stored in the black channel in &img_type_cmyk; and &img_type_cmyka;
                        image types.
                    </para>

                </refsect1>

                <refsect1>
                    <title>Return values</title>
                    <para>
                        The return values follow the &lqrl; signalling system. The function
                        <function>lqr_carver_get_energy_image</function> will return an error if
                        <parameter>image_type</parameter> is &img_type_custom;.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-energy-function-builtin"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
                            <member><xref linkend="ref-lqr-carver-bias-add"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-rwindow-read">
                <refmeta>
                    <refentrytitle><function>lqr_rwindow_read</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_rwindow_read</refname>
                    <refpurpose>read the content of a &rwin_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gfloat <function>lqr_rwindow_read</function></funcdef>
                            <paramdef>LqrReadingWindow* <parameter>rwindow</parameter></paramdef>
                            <paramdef>gint <parameter>x</parameter></paramdef>
                            <paramdef>gint <parameter>y</parameter></paramdef>
                            <paramdef>gint <parameter>channel</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>

                    <para>
                        The function <function>lqr_rwindow_read</function> returns the content of the reading window
                        <parameter>rwindow</parameter> at point &param_x;, &param_y; and at channel
                        <parameter>channel</parameter>.
                    </para>
                    <para>
                        The coordinates &param_x; and &param_y; are relative to the <parameter>rwindow</parameter>
                        centre, and they both can range from <literal>-radius</literal> to <literal>radius</literal>
                        (extremes included), where <literal>radius</literal> can be obtained with the function
                        <xref linkend="ref-lqr-rwindow-get-radius"></xref>.
                    </para>
                    <para>
                        The function returns <literal>0</literal> when the coordinates are out of range, either because
                        they are beyond the <parameter>rwindow</parameter> radius or because they are outside the image
                        boundary.
                    </para>
                    <para>
                        The <parameter>channel</parameter> parameter specifies which channel to read out; depending on
                        the <parameter>rwindow</parameter> reader type, the range and meaning of this parameter changes:
                        for the cases <literal>LQR_ER_BRIGHTNESS</literal> and <literal>LQR_ER_LUMA</literal> it must be
                        <literal>0</literal>, because the readout consists of a single channel, for
                        <literal>LQR_ER_RGBA</literal> it must be between <literal>0</literal> and <literal>3</literal>
                        (and then the readout will contain the RGBA information), while for
                        <literal>LQR_ER_CUSTOM</literal> it must be one of the original image channels.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-read-t"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-radius"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-channels"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-rwindow-get-read-t">
                <refmeta>
                    <refentrytitle><function>lqr_rwindow_get_read_t</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_rwindow_get_read_t</refname>
                    <refpurpose>get the reader type of a &rwin_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrEnergyReaderType <function>lqr_rwindow_get_read_t</function></funcdef>
                            <paramdef>LqrReadingWindow* <parameter>rwindow</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>

                    <para>
                        The function <function>lqr_rwindow_get_read_t</function> returns the reader type associated with
                        the reading window <parameter>rwindow</parameter>.
                    </para>
                    <para>
                        The reader types are described in the page for
                        <xref linkend="ref-lqr-carver-set-energy-function"></xref>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-read"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-radius"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-channels"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-rwindow-get-radius">
                <refmeta>
                    <refentrytitle><function>lqr_rwindow_get_radius</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_rwindow_get_radius</refname>
                    <refpurpose>get the size of the region accessible from a &rwin_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_rwindow_get_radius</function></funcdef>
                            <paramdef>LqrReadingWindow* <parameter>rwindow</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>

                    <para>
                        The function <function>lqr_rwindow_get_radius</function> returns the radius of the region
                        accessible through the reading window <parameter>rwindow</parameter>.
                    </para>
                    <para>
                        The region is a square of size <literal>2 * <parameter>radius</parameter> - 1</literal> pixels.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-read"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-read-t"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-channels"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-rwindow-get-channels">
                <refmeta>
                    <refentrytitle><function>lqr_rwindow_get_channels</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_rwindow_get_channels</refname>
                    <refpurpose>get the number of channels of a &rwin_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>gint <function>lqr_rwindow_get_channels</function></funcdef>
                            <paramdef>LqrReadingWindow* <parameter>rwindow</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>

                    <para>
                        The function <function>lqr_rwindow_get_channels</function> returns the number of channels of
                        reading window <parameter>rwindow</parameter>.
                    </para>
                    <para>
                        This function is actually only necessary when the <parameter>rwindow</parameter> reader type is
                        <literal>LQR_ER_CUSTOM</literal>.
                    </para>
                    <para>
                        The reader types are described in the page for
                        <xref linkend="ref-lqr-carver-set-energy-function"></xref>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-read"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-read-t"></xref></member>
                            <member><xref linkend="ref-lqr-rwindow-get-radius"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-set-gradient-function">
                <refmeta>
                    <refentrytitle><function>lqr_carver_set_gradient_function</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_set_gradient_function</refname>
                    <refpurpose>set the gradient function for an &carv_obj; object</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_set_gradient_function</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>LqrGradFuncType <parameter>gf_ind</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_carver_set_gradient_function</function> is deprecated and should not
                        be used in newly written code. The function
                        <xref linkend="ref-lqr-carver-set-energy-function-builtin"></xref> should be used instead.
                    </para>
                    <para>
                        The function <function>lqr_carver_set_gradient_function</function> is still maintained for
                        backwards compatibility reasons; its result is equivalent to calling
                        <function>lqr_carver_set_energy_function_builtin</function>, with the following mapping between
                        the argument <parameter>gs_ind</parameter> of the former and the argument
                        <parameter>ef_ind</parameter> of the latter:
                        <informaltable id="ref-gs-ef-mapping">
                            <tgroup cols="2">
                                <thead>
                                    <row>
                                        <entry><type><literal>LqrGradFuncType</literal></type></entry>
                                        <entry><type><literal>LqrEnergyFuncBuiltinType</literal></type></entry>
                                    </row>
                                </thead>
                                <tbody>
                                    <row>
                                        <entry><literal>LQR_GF_XABS</literal></entry>
                                        <entry><literal>LQR_EF_GRAD_XABS</literal></entry>
                                    </row>
                                    <row>
                                        <entry><literal>LQR_GF_SUMABS</literal></entry>
                                        <entry><literal>LQR_EF_GRAD_SUMABS</literal></entry>
                                    </row>
                                    <row>
                                        <entry><literal>LQR_GF_NORM</literal></entry>
                                        <entry><literal>LQR_EF_GRAD_NORM</literal></entry>
                                    </row>
                                    <row>
                                        <entry><literal>LQR_GF_NULL</literal></entry>
                                        <entry><literal>LQR_EF_NULL</literal></entry>
                                    </row>
                                </tbody>
                            </tgroup>
                        </informaltable>
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-set-energy-function-builtin"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>
        </sect1>


        <sect1 id="ref-bias">
            <title>Bias</title>

            <refentry id="ref-lqr-carver-bias-add">
                <refmeta>
                    <refentrytitle><function>lqr_carver_bias_add</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_bias_add_xy</refname>
                    <refname>lqr_carver_bias_add_area</refname>
                    <refname>lqr_carver_bias_add</refname>
                    <refname>lqr_carver_bias_add_rgb_area</refname>
                    <refname>lqr_carver_bias_add_rgb</refname>
                    <refpurpose>update an &carv_obj; bias</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_bias_add_xy</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble <parameter>bias</parameter></paramdef>
                            <paramdef>gint <parameter>x</parameter></paramdef>
                            <paramdef>gint <parameter>y</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_bias_add_area</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>bias_factor</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>x_off</parameter></paramdef>
                            <paramdef>gint <parameter>y_off</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_bias_add</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>bias_factor</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_bias_add_rgb_area</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>bias_factor</parameter></paramdef>
                            <paramdef>gint <parameter>channels</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>x_off</parameter></paramdef>
                            <paramdef>gint <parameter>y_off</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_bias_add_rgb</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>bias_factor</parameter></paramdef>
                            <paramdef>gint <parameter>channels</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Foreword</title>

                    <para>
                        All the functions described in this page are used to add a bias to &carv_obj; objects. A
                        positive biased pixel will be more likely to be avoided by seams, and thus be preserved during
                        rescaling, while a negative bias has the opposite effect.
                    </para>
                    <para>
                        All of these functions must be called before <xref linkend="ref-lqr-carver-resize"></xref>. If
                        called multiple times, the biases added at each call will sum up.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Adding a bias pixel by pixel</title>

                    <para>
                        The function <function>lqr_carver_bias_add_xy</function> adds a bias to the &param_x;, &param_y;
                        pixel of the image loaded into the &carv_obj; object pointed to by <parameter>carver</parameter>
                    </para>
                    <para>
                        A typical value for <parameter>bias_factor</parameter> would be <literal>1000</literal> (in
                        absolute value).
                    </para>
                </refsect1>

                <refsect1>
                    <title>Adding a bias from a buffer</title>

                    <para>
                        The function <function>lqr_carver_bias_add_area</function> adds a bias to an area of the image
                        loaded into the &carv_obj; object pointed to by <parameter>carver</parameter>.
                    </para>
                    <para>
                        The parameter <parameter>buffer</parameter> must point to an array of <type>doubles</type> of
                        size <literal><parameter>width</parameter> * <parameter>height</parameter></literal>, ordered
                        first by rows, then by columns.
                    </para>
                    <para>
                        The offset of the area relative to the image can be specified through
                        <parameter>x_off</parameter> and <parameter>y_off</parameter>. The bias area can exceed the
                        boundary of the image, and the offsets can be negative.
                    </para>
                    <para>
                        The parameter <parameter>bias_factor</parameter> is an overall bias scale. A typical value when
                        the buffer contents are of the order of <literal>1</literal> would be <literal>1000</literal>
                        (in absolute value).
                    </para>
                    <para>
                        The function <function>lqr_carver_bias_add</function> can be used when the area to add is of the
                        same size of the image loaded in the &carv_obj; object and the offsets are <literal>0</literal>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Adding a bias from an image</title>

                    <para>
                        The functions <function>lqr_carver_bias_add_rgb_area</function> and
                        <function>lqr_carver_bias_add_rgb</function> are very similar to
                        <function>lqr_carver_bias_add_area</function> and <function>lqr_carver_bias_add</function>,
                        except that they use 8-bit multi-channel images as inputs.
                    </para>
                    <para>
                        The number of channels in the image is passed via the parameter <parameter>channels</parameter>.
                        The last channel is assumed to be the alpha (opacity) channel if <parameter>channels</parameter>
                        is equal to <literal>2</literal> or greater than <literal>3</literal> (if this is not the case,
                        use the previous functions).
                    </para>
                    <para>
                        The bias is computed from the average of the colour channels, multiplied by the value of the
                        alpha channel if present. For example, in RGBA images a white, nontransparent pixel is
                        equivalent to a value of <literal>1.0</literal> when using a buffer in
                        <function>lqr_carver_bias_add_area</function>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return values</title>
                    <para>
                        The return values follow the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-carver-init"></xref></member>
                            <member><xref linkend="ref-lqr-carver-rigmask-add"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-bias-clear">
                <refmeta>
                    <refentrytitle><function>lqr_carver_bias_clear</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_bias_clear</refname>
                    <refpurpose>clear an &carv_obj; bias</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_bias_clear</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>

                    <para>
                        The function <function>lqr_carver_bias_clear</function> clears the bias from the &carv_obj;
                        object pointed to by <parameter>carver</parameter>
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-bias-add"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>
        </sect1>

        <sect1 id="ref-rigmask">
            <title>Rigidity masks</title>

            <refentry id="ref-lqr-carver-rigmask-add">
                <refmeta>
                    <refentrytitle><function>lqr_carver_rigmask_add</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_rigmask_add_xy</refname>
                    <refname>lqr_carver_rigmask_add_area</refname>
                    <refname>lqr_carver_rigmask_add</refname>
                    <refname>lqr_carver_rigmask_add_rgb_area</refname>
                    <refname>lqr_carver_rigmask_add_rgb</refname>
                    <refpurpose>update an &carv_obj; rigidity mask</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_xy</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble <parameter>rigidity</parameter></paramdef>
                            <paramdef>gint <parameter>x</parameter></paramdef>
                            <paramdef>gint <parameter>y</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_area</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>x_off</parameter></paramdef>
                            <paramdef>gint <parameter>y_off</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_rigmask_add</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_area</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>channels</parameter></paramdef>
                            <paramdef>gint <parameter>width</parameter></paramdef>
                            <paramdef>gint <parameter>height</parameter></paramdef>
                            <paramdef>gint <parameter>x_off</parameter></paramdef>
                            <paramdef>gint <parameter>y_off</parameter></paramdef>
                        </funcprototype>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_rgb</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                            <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
                            <paramdef>gint <parameter>channels</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Foreword</title>

                    <para>
                        All the functions described in this page are used to add a rigidity mask to &carv_obj; objects.
                        Whenever one of these functions is called, a rigidity mask is activated for the whole image; the
                        mask contains coefficients which modulate the value of the rigidity (which is set with
                        <xref linkend="ref-lqr-carver-init"></xref>) in different areas of the image.
                    </para>
                    <para>
                        It is very important to note that using no rigidity masks at all is equivalent to use a rigidity
                        mask over the whole image with all the values set to <literal>1.0</literal>, but, when first
                        adding a rigidity mask to a &carv_obj; object, all the pixels outside the affected area will
                        have their rigidity set to zero; therefore, the functions
                        <function>lqr_carver_rigmask_add_xy</function>, <function>lqr_carver_rigmask_add_area</function>
                        and <function>lqr_carver_rigmask_add_rgb_area</function> actually affect the whole image,
                        despite their name.
                    </para>
                    <para>
                        All the functions must be called after <function>lqr_carver_init</function> and before
                        <function>lqr_carver_resize</function>. If called multiple times over the same area, new values
                        will replace the old ones.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Setting the rigidity mask pixel by pixel</title>

                    <para>
                        The function <function>lqr_carver_rigmask_add_xy</function> sets the rigidity mask value of the
                        &param_x;, &param_y; pixel of the image loaded into the &carv_obj; object pointed to by
                        <parameter>carver</parameter>
                    </para>
                </refsect1>

                <refsect1>
                    <title>Setting the rigidity mask from a buffer</title>

                    <para>
                        The function <function>lqr_carver_rigmask_add_area</function> adds a rigidity mask to an area of
                        the image loaded in the &carv_obj; object pointed to by <parameter>carver</parameter>.
                    </para>
                    <para>
                        The parameter <parameter>buffer</parameter> must point to an array of <type>doubles</type> of
                        size <literal><parameter>width</parameter> * <parameter>height</parameter></literal>, ordered
                        first by rows, then by columns.
                    </para>
                    <para>
                        The offset of the area relative to the image are specified through <parameter>x_off</parameter>
                        and <parameter>y_off</parameter>. The rigidity mask area can exceed the boundary of the image,
                        and the offsets can be negative.
                    </para>
                    <para>
                        The values in the given <parameter>buffer</parameter> are scaled by the overall
                        <parameter>rigidity</parameter> value set when calling the function
                        <function>lqr_carver_init</function>.
                    </para>
                    <para>
                        The function <function>lqr_carver_rigmask_add</function> can be used when the area to add is of
                        the same size of the image loaded in the &carv_obj; object and the offsets are
                        <literal>0</literal>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Setting the rigidity mask from an image</title>

                    <para>
                        The functions <function>lqr_carver_rigmask_add_rgb_area</function> and
                        <function>lqr_carver_rigmask_add_rgb</function> are very similar to
                        <function>lqr_carver_rigmask_add_area</function> and
                        <function>lqr_carver_rigmask_add</function>, but use 8-bit multi-channel images as inputs.
                    </para>
                    <para>
                        The number of channels in the image is passed via the parameter <parameter>channels</parameter>.
                        The last channel is assumed to be the alpha (opacity) channel if <parameter>channels</parameter>
                        is equal to <literal>2</literal> or greater than <literal>3</literal> (if this is not the case,
                        use the previous functions).
                    </para>
                    <para>
                        The rigidity value is computed from the average of the colour channels, multiplied by the value
                        of the alpha channel if present. For example, in RGBA images a white, nontransparent pixel is
                        equivalent to a value of <literal>1.0</literal> when using a buffer in
                        <function>lqr_carver_rigmask_add_area</function>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return values follow the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-carver-init"></xref></member>
                            <member><xref linkend="ref-lqr-carver-bias-add"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-carver-rigmask-clear">
                <refmeta>
                    <refentrytitle><function>lqr_carver_rigmask_clear</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_carver_rigmask_clear</refname>
                    <refpurpose>clear an &carv_obj; rigidity mask</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>void <function>lqr_carver_rigmask_clear</function></funcdef>
                            <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>

                    <para>
                        The function <function>lqr_carver_rigmask_clear</function> clears the rigidity mask from the
                        &carv_obj; object pointed to by <parameter>carver</parameter>
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-carver-rigmask-add"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>
        </sect1>

        <sect1 id="ref-progress">
            <title>Progress reports</title>

            <refentry id="ref-lqr-progress-new">
                <refmeta>
                    <refentrytitle><function>lqr_progress_new</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_progress_new</refname>
                    <refpurpose>the &prog_obj; object constructor</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrProgress* <function>lqr_progress_new</function></funcdef>
                            <void></void>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_progress_new</function> is the constructor for &prog_obj; objects. It
                        can be used to setup a progress report indicator for rescale operations performed through
                        <xref linkend="ref-lqr-carver-resize"></xref>.
                    </para>
                    <para>
                        Newly created &prog_obj; objects are inactive, and need to be set up using the functions
                        <xref linkend="ref-lqr-progress-set-init"></xref>,
                        <xref linkend="ref-lqr-progress-set-update"></xref> and
                        <xref linkend="ref-lqr-progress-set-end"></xref>.
                    </para>
                    <para>
                        &prog_obj; objects are associated to &carv_obj; objects using the function
                        <xref linkend="ref-lqr-carver-set-progress"></xref>
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The function returns the newly created &prog_obj; if successful, or &ret_null; in case of
                        insufficient memory.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-progress-set-init">
                <refmeta>
                    <refentrytitle><function>lqr_progress_set_init</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_progress_set_init</refname>
                    <refpurpose>execude custom code before each rescaling operation</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_progress_set_init</function></funcdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                            <paramdef>LqrProgressFuncInit <parameter>init_func</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_progress_set_init</function> sets the hook
                        <parameter>init_func</parameter> to the &prog_obj; object pointed to by
                        <parameter>p</parameter>.
                    </para>
                    <para>
                        The function <parameter>init_func</parameter> is of type
                        <classname>LqrProgressFuncInit</classname>, whose prototype is defined by:
                        <programlisting>
typedef LqrRetVal (*LqrProgressFuncInit) (const gchar* init_message);
                        </programlisting>
                        Each time that the function <xref linkend="ref-lqr-carver-resize"></xref> performs a rescale
                        operation (recall that it can perform more than one rescale operation at each call) this
                        function will be called first, with a string argument passed through the parameter
                        <parameter>init_message</parameter>, which is different for horizontal and vertical rescalings.
                    </para>
                    <para>
                        The message arguments can be set with the functions
                        <xref linkend="ref-lqr-progress-set-init-width-message"></xref> and
                        <xref linkend="ref-lqr-progress-set-init-height-message"></xref>.
                    </para>
                    <para>
                        The default values for newly created &prog_obj; objects are:
                        <variablelist>
                            <varlistentry>
                                <term>Horizontal:</term>
                                <listitem>
                                    <para>
                                        &prog_init_w_mess;
                                    </para>
                                </listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>Vertical:</term>
                                <listitem>
                                    <para>
                                        &prog_init_h_mess;
                                    </para>
                                </listitem>
                            </varlistentry>
                        </variablelist>
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-progress-new"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-progress-set-update">
                <refmeta>
                    <refentrytitle><function>lqr_progress_set_update</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_progress_set_update</refname>
                    <refpurpose>execude custom code at regular steps during each rescaling operation</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_progress_set_update</function></funcdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                            <paramdef>LqrProgressFuncUpdate <parameter>update_func</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_progress_set_update</function> sets the hook
                        <parameter>update_func</parameter> to the &prog_obj; object pointed to by
                        <parameter>p</parameter>.
                    </para>
                    <para>
                        The function <parameter>update_func</parameter> is of type
                        <classname>LqrProgressFuncUpdate</classname>, whose prototype is defined by:
                        <programlisting>
typedef LqrRetVal (*LqrProgressFuncUpdate) (gdouble completion_percentage);
                        </programlisting>
                        Each time that the function <xref linkend="ref-lqr-carver-resize"></xref> performs a rescale
                        operation (recall that it can perform more than one rescale operation at each call) this
                        function will be called at regular intervale, with the current completion percentage
                        <parameter>completion_percentage</parameter> as an argument.
                    </para>
                    <para>
                        The update step can be set with the function
                        <xref linkend="ref-lqr-progress-set-update-step"></xref>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-progress-new"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-progress-set-end">
                <refmeta>
                    <refentrytitle><function>lqr_progress_set_end</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_progress_set_end</refname>
                    <refpurpose>execude custom code after each rescaling operation</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_progress_set_end</function></funcdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                            <paramdef>LqrProgressFuncEnd <parameter>end_func</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_progress_set_end</function> sets the hook
                        <parameter>end_func</parameter> to the &prog_obj; object pointed to by <parameter>p</parameter>.
                    </para>
                    <para>
                        The function <parameter>end_func</parameter> is of type
                        <classname>LqrProgressFuncEnd</classname>, whose prototype is defined by:
                        <programlisting>
typedef LqrRetVal (*LqrProgressFuncEnd) (const gchar* end_message);
                        </programlisting>
                        Each time that the function <xref linkend="ref-lqr-carver-resize"></xref> performs a rescale
                        operation (recall that it can perform more than one rescale operation at each call) this
                        function will be called at the end, with a string argument passed through the parameter
                        <parameter>end_message</parameter>, which is different for horizontal and vertical rescalings.
                    </para>
                    <para>
                        The message arguments can be set with the functions
                        <xref linkend="ref-lqr-progress-set-end-width-message"></xref> and
                        <xref linkend="ref-lqr-progress-set-end-height-message"></xref>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-progress-new"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-progress-set-update-step">
                <refmeta>
                    <refentrytitle><function>lqr_progress_set_update_step</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_progress_set_update_step</refname>
                    <refpurpose>setup update step for &prog_obj; objects</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_progress_set_update_step</function></funcdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                            <paramdef>gfloat <parameter>update_step</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_progress_set_update_step</function> sets the update step of the
                        &prog_obj; pointed to by <parameter>p</parameter> to the value
                        <parameter>update_step</parameter>.
                    </para>
                    <para>
                        The update step must be between <literal>0</literal> and <literal>1</literal>.
                    </para>
                    <para>
                        The default value is <literal>0.02</literal> (i.e. <literal>2%</literal>).
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-progress-new"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-progress-set-init-width-message">
                <refmeta>
                    <refentrytitle><function>lqr_progress_set_init_width_message</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_progress_set_init_width_message</refname>
                    <refpurpose>setup width message for init hooks in &prog_obj; objects</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_progress_set_init_width_message</function></funcdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                            <paramdef>const guchar* <parameter>message</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_progress_set_init_width_message</function> sets the string
                        <parameter>message</parameter> in the &prog_obj; object pointed to by <parameter>p</parameter>
                        as the argument when rescaling the width for init hooks set with
                        <xref linkend="ref-lqr-progress-set-init"></xref>
                    </para>
                    <para>
                        The default value for newly created &prog_obj; objects is: &prog_init_w_mess;
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-progress-new"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-progress-set-init-height-message">
                <refmeta>
                    <refentrytitle><function>lqr_progress_set_init_height_message</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_progress_set_init_height_message</refname>
                    <refpurpose>setup height message for init hooks in &prog_obj; objects</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_progress_set_init_height_message</function></funcdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                            <paramdef>const guchar* <parameter>message</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_progress_set_init_height_message</function> sets the string
                        <parameter>message</parameter> in the &prog_obj; object pointed to by <parameter>p</parameter>
                        as the argument when rescaling the height for init hooks set with
                        <xref linkend="ref-lqr-progress-set-init"></xref>
                    </para>
                    <para>
                        The default value for newly created &prog_obj; objects is: &prog_init_h_mess;
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-progress-new"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-progress-set-end-width-message">
                <refmeta>
                    <refentrytitle><function>lqr_progress_set_end_width_message</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_progress_set_end_width_message</refname>
                    <refpurpose>setup width message for end hooks in &prog_obj; objects</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_progress_set_end_width_message</function></funcdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                            <paramdef>const guchar* <parameter>message</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_progress_set_end_width_message</function> sets the string
                        <parameter>message</parameter> in the &prog_obj; object pointed to by <parameter>p</parameter>
                        as the argument when rescaling the width for end hooks set with
                        <xref linkend="ref-lqr-progress-set-end"></xref>
                    </para>
                    <para>
                        The default value for newly created &prog_obj; objects is:
                        <computeroutput>"done"</computeroutput>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-progress-new"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>

            <refentry id="ref-lqr-progress-set-end-height-message">
                <refmeta>
                    <refentrytitle><function>lqr_progress_set_end_height_message</function></refentrytitle>
                    <manvolnum>3</manvolnum>
                </refmeta>

                <refnamediv>
                    <refname>lqr_progress_set_end_height_message</refname>
                    <refpurpose>setup height message for end hooks in &prog_obj; objects</refpurpose>
                </refnamediv>

                <refsynopsisdiv>
                    <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
                        <funcprototype>
                            <funcdef>LqrRetVal <function>lqr_progress_set_end_height_message</function></funcdef>
                            <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
                            <paramdef>const guchar* <parameter>message</parameter></paramdef>
                        </funcprototype>
                    </funcsynopsis>
                </refsynopsisdiv>

                <refsect1>
                    <title>Description</title>
                    <para>
                        The function <function>lqr_progress_set_end_height_message</function> sets the string
                        <parameter>message</parameter> in the &prog_obj; object pointed to by <parameter>p</parameter>
                        as the argument when rescaling the height for end hooks set with
                        <xref linkend="ref-lqr-progress-set-end"></xref>
                    </para>
                    <para>
                        The default value for newly created &prog_obj; objects is:
                        <computeroutput>"done"</computeroutput>.
                    </para>
                </refsect1>

                <refsect1>
                    <title>Return value</title>
                    <para>
                        The return value follows the &lqrl; signalling system.
                    </para>
                </refsect1>

                <refsect1>
                    <title>See also</title>
                    <para>
                        <simplelist type="inline">
                            <member><xref linkend="ref-lqr-ret-val"></xref></member>
                            <member><xref linkend="ref-lqr-progress-new"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
                            <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
                            <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
                        </simplelist>
                    </para>
                </refsect1>
            </refentry>
        </sect1>
    </chapter>


    <chapter id="references">
        <title>References</title>

        <para>
            The library implements the algorithm described in the paper "Seam Carving for Content-Aware Image Resizing"
            by Shai Avidan and Ariel Shamir, which can be found at
            <ulink url="http://www.faculty.idc.ac.il/arik/imret.pdf">http://www.faculty.idc.ac.il/arik/imret.pdf</ulink>
        </para>
    </chapter>

    <appendix id="app-new">
        <title>API changes in new versions of the library</title>

        <sect1 id="app-new-0-4">
            <title>New symbols in version 0.4</title>
            <para>
                <simplelist>
                    <member><link linkend="ref-lqr-image-type"><type>LqrImageType</type></link></member>
                    <member><link linkend="ref-lqr-carver-set-image-type"><function>lqr_carver_set_image_type</function></link></member>
                    <member><link linkend="ref-lqr-carver-get-image-type"><function>lqr_carver_get_image_type</function></link></member>
                    <member><link linkend="ref-lqr-carver-set-alpha-channel"><function>lqr_carver_set_alpha_channel</function></link></member>
                    <member><link linkend="ref-lqr-carver-set-black-channel"><function>lqr_carver_set_black_channel</function></link></member>
                    <member><link linkend="ref-lqr-carver-set-preserve-input-image"><function>lqr_carver_set_preserve_input_image</function></link></member>
                    <member><link linkend="ref-lqr-carver-set-use-cache"><function>lqr_carver_set_use_cache</function></link></member>
                    <member><link linkend="ref-lqr-carver-list-foreach"><function>lqr_carver_list_foreach_recursive</function></link></member>
                    <member><link linkend="ref-lqr-carver-set-energy-function-builtin"><function>lqr_carver_set_energy_function_builtin</function></link></member>
                    <member><link linkend="ref-lqr-carver-set-energy-function"><function>lqr_carver_set_energy_function</function></link></member>
                    <member><link linkend="ref-lqr-carver-get-energy"><function>lqr_carver_get_energy</function></link></member>
                    <member><link linkend="ref-lqr-carver-get-energy"><function>lqr_carver_get_true_energy</function></link></member>
                    <member><link linkend="ref-lqr-carver-get-energy"><function>lqr_carver_get_energy_image</function></link></member>
                    <member><link linkend="ref-lqr-rwindow-read"><function>lqr_rwindow_read</function></link></member>
                    <member><link linkend="ref-lqr-rwindow-get-read-t"><function>lqr_rwindow_get_read_t</function></link></member>
                    <member><link linkend="ref-lqr-rwindow-get-radius"><function>lqr_rwindow_get_radius</function></link></member>
                    <member><link linkend="ref-lqr-rwindow-get-channels"><function>lqr_rwindow_get_channels</function></link></member>
                    <member><link linkend="ref-lqr-carver-bias-add"><function>lqr_carver_bias_add_xy</function></link></member>
                    <member><link linkend="ref-lqr-carver-bias-clear"><function>lqr_carver_bias_clear</function></link></member>
                    <member><link linkend="ref-lqr-carver-rigmask-add"><function>lqr_carver_rigmask_add_xy</function></link></member>
                    <member><link linkend="ref-lqr-carver-rigmask-clear"><function>lqr_carver_rigmask_clear</function></link></member>
                    <member><link linkend="ref-lqr-carver-cancel"><function>lqr_carver_cancel</function></link></member>
                </simplelist>
            </para>
        </sect1>

        <sect1 id="app-new-0-3">
            <title>New symbols in version 0.3</title>
            <para>
                <simplelist>
                    <member><link linkend="ref-lqr-carver-get-enl-step"><function>lqr_carver_get_enl_step</function></link></member>
                    <member><link linkend="ref-lqr-carver-set-enl-step"><function>lqr_carver_set_enl_step</function></link></member>
                    <member><link linkend="ref-lqr-carver-get-ref-width"><function>lqr_carver_get_ref_width</function></link></member>
                    <member><link linkend="ref-lqr-carver-get-ref-height"><function>lqr_carver_get_ref_height</function></link></member>
                    <member><link linkend="ref-lqr-carver-get-orientation"><function>lqr_carver_get_orientation</function></link></member>
                    <member><link linkend="ref-lqr-carver-get-depth"><function>lqr_carver_get_depth</function></link></member>
                </simplelist>
            </para>
        </sect1>

        <sect1 id="app-new-0-2">
            <title>New symbols in version 0.2</title>
            <para>
                <simplelist>
                    <member><link linkend="ref-lqr-col-depth"><type>LqrColDepth</type></link></member>
                    <member><link linkend="ref-lqr-carver-new"><function>lqr_carver_new_ext</function></link></member>
                    <member><link linkend="ref-lqr-carver-scan"><function>lqr_carver_scan_ext</function></link></member>
                    <member><link linkend="ref-lqr-carver-scan-line"><function>lqr_carver_scan_line_ext</function></link></member>
                    <member><link linkend="ref-lqr-carver-get-channels"><function>lqr_carver_get_channels</function></link></member>
                    <member><link linkend="ref-lqr-carver-get-col-depth"><function>lqr_carver_get_col_depth</function></link></member>
                    <member><link linkend="ref-lqr-carver-set-side-switch-frequency"><function>lqr_carver_set_side_switch_frequency</function></link></member>
                    <member><link linkend="ref-lqr-carver-rigmask-add"><function>lqr_carver_rigmask_add</function></link></member>
                    <member><link linkend="ref-lqr-carver-rigmask-add"><function>lqr_carver_rigmask_add_area</function></link></member>
                    <member><link linkend="ref-lqr-carver-rigmask-add"><function>lqr_carver_rigmask_add_rgb</function></link></member>
                    <member><link linkend="ref-lqr-carver-rigmask-add"><function>lqr_carver_rigmask_add_rgb_area</function></link></member>
                </simplelist>
            </para>
        </sect1>

        <sect1 id="app-deprecated">
            <title>Deprecated symbols</title>
            <para>
                <simplelist>
                    <member><link linkend="ref-lqr-carver-get-channels"><function>lqr_carver_get_bpp</function></link></member>
                    <member><link linkend="ref-lqr-carver-set-gradient-function"><function>lqr_carver_set_gradient_function</function></link></member>
                </simplelist>
            </para>
        </sect1>
    </appendix>
</book>