Current File : //kunden/kunden/proc/self/root/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>"Resizing width..."</computeroutput>">
<!ENTITY prog_init_h_mess "<computeroutput>"Resizing height..."</computeroutput>">
<!ENTITY prog_end_w_mess "<computeroutput>"done"</computeroutput>">
<!ENTITY prog_end_h_mess "<computeroutput>"done"</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>>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, &x, &y, &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, &x, &y, &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, &n, &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, &n, &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 <=1; i++) {
for (j = -1; j <=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 ¶m_x;, ¶m_y;, ¶m_w; and ¶m_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, ¶m_w; and ¶m_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>¶m_w; * ¶m_h;</literal> (or
<literal>¶m_w; * ¶m_h; * ¶m_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, ¶m_w; and ¶m_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>¶m_w; * ¶m_h;</literal> (or
<literal>¶m_w; * ¶m_h; * ¶m_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>(¶m_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>(¶m_w;
- ¶m_depth;)</literal> to <literal>(¶m_w; + ¶m_depth;)</literal>. If the
orientation is 1, the analogue formula holds with ¶m_h; in place of ¶m_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 ¶m_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 <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 ¶m_w; * ¶m_h; with ¶m_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>>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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 ¶m_x;, ¶m_y; based on the
knowledge of the current image size (obtained from ¶m_w; and ¶m_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 ¶m_x;, ¶m_y;, ¶m_w; and ¶m_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 <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 <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 <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>¶m_w; * ¶m_h;</literal>, where ¶m_w; and ¶m_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 <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 ¶m_x;, ¶m_y; and at channel
<parameter>channel</parameter>.
</para>
<para>
The coordinates ¶m_x; and ¶m_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 <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 <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 <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 <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 <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 ¶m_x;, ¶m_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 <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 <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
¶m_x;, ¶m_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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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>