Debian Codegraph @

docs/liblqr_manual.docbook

raw
1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DOcBook XML V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd" [
3 <!ENTITY lqr "Liquid Rescale">
4 <!ENTITY lqrl "&lqr; library">
5 <!ENTITY carv_obj "<classname>LqrCarver</classname>">
6 <!ENTITY carvl_obj "<classname>LqrCarverList</classname>">
7 <!ENTITY vmap_obj "<classname>LqrVMap</classname>">
8 <!ENTITY vmapl_obj "<classname>LqrVMapList</classname>">
9 <!ENTITY rwin_obj "<classname>LqrReadingWindow</classname>">
10 <!ENTITY prog_obj "<classname>LqrProgress</classname>">
11 <!ENTITY ret_true "<literal><returnvalue>TRUE</returnvalue></literal>">
12 <!ENTITY ret_false "<literal><returnvalue>FALSE</returnvalue></literal>">
13 <!ENTITY ret_null "<literal><returnvalue>NULL</returnvalue></literal>">
14 <!ENTITY param_x "<parameter>x</parameter>">
15 <!ENTITY param_y "<parameter>y</parameter>">
16 <!ENTITY param_w "<parameter>width</parameter>">
17 <!ENTITY param_h "<parameter>height</parameter>">
18 <!ENTITY param_channels "<parameter>channels</parameter>">
19 <!ENTITY param_depth "<parameter>depth</parameter>">
20 <!ENTITY col_depth_8i "<literal>LQR_COLDEPTH_8I</literal>">
21 <!ENTITY col_depth_16i "<literal>LQR_COLDEPTH_16I</literal>">
22 <!ENTITY col_depth_32f "<literal>LQR_COLDEPTH_32F</literal>">
23 <!ENTITY col_depth_64f "<literal>LQR_COLDEPTH_64F</literal>">
24 <!ENTITY img_type_grey "<literal>LQR_GREY_IMAGE</literal>">
25 <!ENTITY img_type_greya "<literal>LQR_GREYA_IMAGE</literal>">
26 <!ENTITY img_type_rgb "<literal>LQR_RGB_IMAGE</literal>">
27 <!ENTITY img_type_rgba "<literal>LQR_RGBA_IMAGE</literal>">
28 <!ENTITY img_type_cmy "<literal>LQR_CMY_IMAGE</literal>">
29 <!ENTITY img_type_cmyk "<literal>LQR_CMYK_IMAGE</literal>">
30 <!ENTITY img_type_cmyka "<literal>LQR_CMYKA_IMAGE</literal>">
31 <!ENTITY img_type_custom "<literal>LQR_CUSTOM_IMAGE</literal>">
32 <!ENTITY err_ok "<literal><errorcode>LQR_OK</errorcode></literal>">
33 <!ENTITY err_err "<literal><errorcode>LQR_ERROR</errorcode></literal>">
34 <!ENTITY err_nomem "<literal><errorcode>LQR_NOMEM</errorcode></literal>">
35 <!ENTITY err_cancel "<literal><errorcode>LQR_USRCANCEL</errorcode></literal>">
36 <!ENTITY prog_init_w_mess "<computeroutput>&quot;Resizing width...&quot;</computeroutput>">
37 <!ENTITY prog_init_h_mess "<computeroutput>&quot;Resizing height...&quot;</computeroutput>">
38 <!ENTITY prog_end_w_mess "<computeroutput>&quot;done&quot;</computeroutput>">
39 <!ENTITY prog_end_h_mess "<computeroutput>&quot;done&quot;</computeroutput>">
40 ]>
41
42 <book id="liblqr-manual" lang="en">
43
44 <bookinfo>
45 <title>The &lqrl; Manual</title>
46 <author>
47 <firstname>Carlo</firstname>
48 <surname>Baldassi</surname>
49 </author>
50 <productname class='copyright'>LqR library</productname>
51 <productnumber>0.4.2 API (3:2:3)</productnumber>
52 <copyright>
53 <year>2007</year>
54 <year>2008</year>
55 <year>2009</year>
56 <holder>Carlo Baldassi</holder>
57 </copyright>
58 <date>10 Maj 2009</date>
59 </bookinfo>
60
61 <chapter id="Introduction">
62
63 <title>Introduction</title>
64 <sect1 id="copyright">
65 <title>Copyright</title>
66 <para>
67 Liquid Rescale Library Manual.
68 Copyright (C) 2007-2009 Carlo Baldassi <email>[email protected]</email>
69 </para>
70 <para>
71 This manual is released under the terms of the GNU General Public License as published by the Free
72 Software Foundation; version 3 dated June, 2007.
73 </para>
74 <para>
75 You should have received a copy of the GNU General Public License along with the library; if not, see
76 <ulink url="http://www.gnu.org/licenses">http://www.gnu.org/licenses</ulink>
77 </para>
78 </sect1>
79
80 <sect1 id="about-this-doc">
81 <title>About this document</title>
82 <para>
83 This manual describes in detail the &lqrl; API, starting from a brief overview on seam carving, the
84 internal image representation, a minimal list of basic methods and the full explanation of all the
85 library public methods.
86 </para>
87 <para>
88 In the `<filename>examples</filename>' directory, you will find a minimal example program, which only
89 uses basic methods, and a full-featured demo program, which uses almost all of the methods described in
90 this document. Both programs are fully commented, see also the <filename>README</filename> file in the
91 `<filename>examples</filename>' directory.
92 </para>
93 <para>
94 Refer to the <filename>README</filename> file for information about installing and compiling.
95 </para>
96 <para>
97 The latest version of the &lqrl; and of this manual can be found at
98 <ulink url="http://liblqr.wikidot.com">http://liblqr.wikidot.com</ulink>.
99 </para>
100 </sect1>
101
102 <sect1 id="seam-carve">
103 <title>Seam carving in brief</title>
104 <para>
105 Basically, the rescaling algorithm tries to find out which parts of the image are important, and which
106 are not, based on the contrast between adjacent pixels; then, the image is resized through the
107 elimination or insertion of continuous paths, called `seams'. The seams connect the top of the image
108 with the bottom when rescaling horizontally, or they connect the left side with the right side when
109 rescaling vertically. In the seam carving process, seams are removed in sequence, therefore shrinking
110 the image by one pixel at a time. The seam insertion process mirrors the seam carving process,
111 introducing interpolated seams in regions where they would have been carved.
112 </para>
113 <para>
114 Once it has been computed, the carving information can be efficiently stored in a so called multi-sized
115 image, which can be used to reproduce the carving operation on the fly at any later moment.
116 </para>
117 <para>
118 It often happens that the automatic feature detection fails to identify as significant some image
119 regions; in these cases a preservation mask can be specified, which marks those regions. In fact, the
120 feature recognition process can be manually driven quite easily to its full extent, by using custom
121 masks.
122 </para>
123 <para>
124 See also the <link linkend="references">References</link> section for more information about the
125 algorithm.
126 </para>
127
128 <sect2 id="about-enlarge">
129 <title>About enlarging</title>
130 <para>
131 As mentioneed above, the enlargment process mirrors the carving process. More precisely, in order to
132 enlarge the image by a given amount of pixels, say N, the library first computes which would be the
133 first N seams to be removed; then, it inserts N new seams nearby those.
134 </para>
135 <para>
136 This means that it is clearly not possible to go beyond twice the original size in a single step. It
137 also means that doubling the image size in this way is just equivalent to standard scaling, since
138 the result is that each seam is just duplicated. For these reasons, the library rescaling engine
139 automatically divides enlarging sessions in steps, and allows to set the step size.
140 </para>
141 <para>
142 This same issue also affects in a tricky way the preservation of image areas when enlarging: suppose
143 your image is 1000 pixels wide, and you have protected an area which is 800 pixels wide. It is then
144 clear that you cannot shrink the image to less than 800 pixels without affecting the preserved area,
145 but the same is true when enlarging, so you should not go beyond 1200 pixels in a single step (=
146 1000 + (1000 - 800)), i.e. you should use a value lower than 1.2 for the enlargement step size.
147 </para>
148 <para>
149 In general, however, the optimal enlargement step size depends on the image, since large step sizes
150 have the disadvantages discussed above, while small step sizes will tend to inflate the same areas
151 of the image over and over at each step.
152 </para>
153 </sect2>
154 </sect1>
155
156
157 <sect1 id="overview">
158 <title>Overview of the library</title>
159 <para>
160 The &lqrl; is written in C, but can be used into C++ programs without any modification. It has an
161 object-oriented design, so that the terminology in this manual is borrowed from C++. The central class
162 of the library is called &carv_obj;. Carver objects can generate and store multi-size images, or load
163 them, and read them out at the desired size.
164 </para>
165 <para>
166 Internally, multi-size images are stored simply as plain images with the addition of a visibility map.
167 Each pixel in the image has its own visibility level. Whether to display a pixel or not simply depends
168 on the comparison of each pixel's visibility with a given global visibility level. In this way, images
169 of different sizes can be read out, simply by setting a global visibility level.
170 </para>
171 <para>
172 Therefore, once the visibility map has been computed, it allows effortless, real-time scaling. However,
173 visibility maps also necessarily have an orientation, either horizontal or vertical. If we want to
174 resize on the other direction, the visibility map has to be computed afresh, and the previous visibility
175 map becomes useless, because the two maps are not consistent one with the other.
176 </para>
177 <para>
178 This also implies that the resizing order affects the final result: rescaling horizontally first, then
179 vertically, does not yield the same result as following the reverse order. Moreover, one could choose an
180 intermediate way, e.g. by rescaling by one pixel in one direction, one in the other, then iterating as
181 needed to reach the final size.
182 </para>
183 <para>
184 The default behaviour of the library is to rescale horizontally first, then vertically, but this order
185 can be reversed.
186 </para>
187 <para>
188 Visibility maps can be stored in objects of type &vmap_obj;. When an &carv_obj; object is created from
189 an input image, the visibility of each pixel is uninitialised. At this point, one could either import a
190 previously computed &vmap_obj;, or activate the &carv_obj; so that it creates one afresh when asked to.
191 </para>
192 <para>
193 In either case, there's a single method to call, specifiying the new desired size; all the rest will
194 automatically be computed as necessary. By default, the visibility maps are only computed up to the
195 extent to which they are needed for resizing.
196 </para>
197 </sect1>
198
199 <sect1 id="basic">
200 <title>Basic methods</title>
201 <para>
202 Following is a list of the basic public methods associated with the &carv_obj; objects:
203 </para>
204 <para>
205 <itemizedlist>
206 <listitem>
207 <para>
208 constructors and destructor
209 </para>
210 <para>
211 <programlisting>
212 LqrCarver * lqr_carver_new (guchar *buffer, gint width, gint height, gint channels);
213 LqrCarver * lqr_carver_new_ext (void *buffer, gint width, gint height, gint channels, LqrColDepth colour_depth);
214 void lqr_carver_destroy (LqrCarver *carver);
215 </programlisting>
216 </para>
217 </listitem>
218 <listitem>
219 <para>
220 initialization
221 </para>
222 <para>
223 <programlisting>
224 LqrRetVal lqr_carver_init (LqrCarver *carver, gint delta_x, gfloat rigidity);
225 </programlisting>
226 </para>
227 </listitem>
228 <listitem>
229 <para>
230 image manipulations
231 </para>
232 <para>
233 <programlisting>
234 LqrRetVal lqr_carver_resize (LqrCarver *carver, gint new_width, gint new_width);
235 LqrRetVal lqr_carver_flatten (LqrCarver *carver);
236 </programlisting>
237 </para>
238 </listitem>
239 <listitem>
240 <para>
241 readout
242 </para>
243 <para>
244 <programlisting>
245 gboolean lqr_carver_scan (LqrCarver *carver, gint *x, gint *y, guchar **rgb);
246 gboolean lqr_carver_scan_ext (LqrCarver *carver, gint *x, gint *y, void **rgb);
247 gboolean lqr_carver_scan_by_row (LqrCarver *carver);
248 gboolean lqr_carver_scan_line (LqrCarver *carver, gint *n, guchar **rgb);
249 gboolean lqr_carver_scan_line_ext (LqrCarver *carver, gint *n, void **rgb);
250 </programlisting>
251 </para>
252 </listitem>
253 <listitem>
254 <para>
255 get values
256 </para>
257 <para>
258 <programlisting>
259 gint lqr_carver_get_width (LqrCarver *carver);
260 gint lqr_carver_get_height (LqrCarver *carver);
261 gint lqr_carver_get_channels (LqrCarver *carver);
262 LqrColDepth lqr_carver_get_col_depth (LqrCarver *carver);
263 </programlisting>
264 </para>
265 </listitem>
266
267 </itemizedlist>
268 </para>
269 <para>
270 The fastest way to see how they work is having a look at the code of
271 <filename>examples/liquidrescale-basic.cpp</filename>, which is a very simple and fully commented
272 demostrative program.
273 </para>
274 <para>
275 The return value of many functions is of type <classname>LqrRetVal</classname>. This is just an enum
276 type which can be used for signal handling, see the <link linkend="signals">Signal handling
277 section</link>.
278 </para>
279 <para>
280 The other classes are optional: the class &vmap_obj; is used to hold the carving information (and the
281 class &vmapl_obj; is used to retrieve it from the &carv_obj; ojects); the class &prog_obj; is used to
282 customize progress report from the resizing engine (by default it is turned off).
283 </para>
284 <para>
285 A complete list of the library public methods can be found in the reference at the end of this document.
286 </para>
287 </sect1>
288 </chapter>
289
290 <chapter id="api-manual">
291
292 <title>LqR library API user manual</title>
293
294 <sect1 id="signals">
295 <title>Signal handling</title>
296 <para>
297 Many library functions return a value of type <classname>LqrRetVal</classname>. This is an enum type
298 which can hold the values:
299 <variablelist>
300 <varlistentry>
301 <term>&err_ok;</term>
302 <listitem>
303 <para>
304 everyting OK
305 </para>
306 </listitem>
307 </varlistentry>
308 <varlistentry>
309 <term>&err_err;</term>
310 <listitem>
311 <para>
312 generic <errortype>fatal</errortype> error
313 </para>
314 </listitem>
315 </varlistentry>
316 <varlistentry>
317 <term>&err_nomem;</term>
318 <listitem>
319 <para>
320 not enough memory
321 </para>
322 </listitem>
323 </varlistentry>
324 <varlistentry>
325 <term>&err_cancel;</term>
326 <listitem>
327 <para>
328 action cancelled by the user
329 </para>
330 </listitem>
331 </varlistentry>
332 </variablelist>
333 </para>
334 <para>
335 At top level, it is important that the user handle these values explicitly, because the library
336 functions don't do anything else than stopping and returning an error signal in case of errors. An easy
337 way is setting up some macros and wrap each function call with those, as shown in the example files.
338 </para>
339 <para>
340 Below top level, the library provides some convenient macros which can be used to wrap function calls,
341 in order to propagate these signals:
342 <variablelist>
343 <varlistentry>
344 <term><literal><function>LQR_CATCH</function> (<parameter>expr</parameter>)</literal></term>
345 <listitem>
346 <para>
347 if <parameter>expr</parameter> is equal to &err_ok; it does nothing, otherwise it
348 returns <parameter>expr</parameter> (or the result of the execution of
349 <parameter>expr</parameter> if it happens to be a function)
350 </para>
351 </listitem>
352 </varlistentry>
353 <varlistentry>
354 <term><literal><function>LQR_CATCH_F</function> (<parameter>expr</parameter>)</literal></term>
355 <listitem>
356 <para>
357 returns &err_err; if <parameter>expr</parameter> is <literal>FALSE</literal>
358 </para>
359 </listitem>
360 </varlistentry>
361 <varlistentry>
362 <term><literal><function>LQR_CATCH_MEM</function> (<parameter>expr</parameter>)</literal></term>
363 <listitem>
364 <para>
365 returns &err_nomem; if <parameter>expr</parameter> is <literal>NULL</literal>
366 </para>
367 </listitem>
368 </varlistentry>
369 </variablelist>
370 <note>
371 <para>
372 The names of these macros have changed since version <literal>0.4</literal>; the previous names
373 <function>CATCH</function>, <function>CATCH_F</function> and <function>CATCH_MEM</function> are
374 still available, but they can be disabled at configure time if they cause conflicts
375 (<command>configure --help</command> for details).
376 </para>
377 </note>
378
379 </para>
380 </sect1>
381
382 <sect1 id="generate-multi-size">
383 <title>Generating the multi-size image</title>
384
385 <sect2 id="carver-new">
386 <title>Carver object creation</title>
387 <para>
388 The &carv_obj; objects are initialised from a plain buffer representing an image. The default
389 constructor assumes a colour depth of 8 bits per channel:
390 <funcsynopsis>
391 <funcprototype>
392 <funcdef>LqrCarver * <function>lqr_carver_new</function></funcdef>
393 <paramdef> guchar * <parameter>buffer</parameter></paramdef>
394 <paramdef> gint <parameter>width</parameter></paramdef>
395 <paramdef> gint <parameter>height</parameter></paramdef>
396 <paramdef> gint <parameter>channels</parameter></paramdef>
397 </funcprototype>
398 </funcsynopsis>
399 </para>
400 <para>
401 Here, <parameter>buffer</parameter> is the array representing an image of size
402 <parameter>width</parameter> by <parameter>height</parameter> with <parameter>channels</parameter>
403 colour channels per pixels. Thus, the overall buffer size has to be of
404 <literal><parameter>widht</parameter> * <parameter>height</parameter> *
405 <parameter>channels</parameter> </literal> unsigned characters, and ordered such that the
406 <literal><symbol>k</symbol></literal>-th colour of the pixel at row
407 <literal><symbol>y</symbol></literal> and column <literal><symbol>x</symbol></literal> is found at:
408 <programlisting>buffer[(y * width + x) * channels + k]</programlisting> (this assumes that
409 <literal><symbol>x</symbol></literal>, <literal><symbol>y</symbol></literal> and
410 <literal><symbol>k</symbol></literal> all start from <literal>0</literal> and reach the maximum
411 values <literal><symbol>widht</symbol>-1</literal>, <literal><symbol>height</symbol>-1</literal> and
412 <literal><symbol>channels</symbol>-1</literal>, respectively)
413 </para>
414 <para>
415 The function returns a pointer to the newly allocated &carv_obj; upon success, or
416 <literal><returnvalue>NULL</returnvalue></literal> in case of insufficient memory.
417 </para>
418 <para>
419 In order to create &carv_obj; objects with more than 8 bits per channel, an extended version of the
420 constructor must be used:
421 <funcsynopsis>
422 <funcprototype>
423 <funcdef>LqrCarver * <function>lqr_carver_new_ext</function></funcdef>
424 <paramdef> void * <parameter>buffer</parameter></paramdef>
425 <paramdef> gint <parameter>width</parameter></paramdef>
426 <paramdef> gint <parameter>height</parameter></paramdef>
427 <paramdef> gint <parameter>channels</parameter></paramdef>
428 <paramdef> LqrColDepth <parameter>colour_depth</parameter></paramdef>
429 </funcprototype>
430 </funcsynopsis>
431 The differnece with the default version is that the input buffer must be passed as void, and its
432 type must be specified through the additional parameter <parameter>colour_depth</parameter>, which
433 can take one of the following values:
434 <variablelist>
435 <varlistentry>
436 <term>&col_depth_8i;</term>
437 <listitem>
438 <para>
439 8 bit unsigned integers (<type>guchar</type>)
440 </para>
441 </listitem>
442 </varlistentry>
443 <varlistentry>
444 <term>&col_depth_16i;</term>
445 <listitem>
446 <para>
447 16 bit unsigned integers (<type>guint16</type>)
448 </para>
449 </listitem>
450 </varlistentry>
451 <varlistentry>
452 <term>&col_depth_32f;</term>
453 <listitem>
454 <para>
455 32 bit floating point (<type>gfloat</type>)
456 </para>
457 </listitem>
458 </varlistentry>
459 <varlistentry>
460 <term>&col_depth_64f;</term>
461 <listitem>
462 <para>
463 64 bit floating point (<type>gdouble</type>)
464 </para>
465 </listitem>
466 </varlistentry>
467 </variablelist>
468 </para>
469 <para>
470 Floating point type values must range between <literal>0</literal> and <literal>1</literal>.
471 </para>
472 <para>
473 The library has some support for different image types and color models. When a &carv_obj; object is
474 created, the image type is automatically set from the number of channels (basically, assuming that
475 the image is either grayscale or RGB with possibly an alpha channel), but it is important to set it
476 manually using the function <function>lqr_carver_set_image_type</function> if your program has to
477 deal with different color models. See the section <link linkend="image-type">Choosing the image
478 type</link> for more details.
479 </para>
480 <para>
481 By default, the buffer is assumed to be a copy of the original image, and therefore it is owned by
482 the &carv_obj; object and must not be accessed directly any more (and of course it must not be
483 freed, the &carv_obj; <link linkend="release">destructor</link> does it). If, instead, you want the
484 &lqrl; to keep the buffer intact, you must flag the &carv_obj; after creation (or after
485 <link linkend="carver-init">activation</link>), using this function:
486 <funcsynopsis>
487 <funcprototype>
488 <funcdef>void <function>lqr_carver_set_preserve_input_image</function></funcdef>
489 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
490 </funcprototype>
491 </funcsynopsis>
492 This function must be used before any other operation takes place.
493 </para>
494 </sect2>
495
496 <sect2 id="carver-init">
497 <title>Carver activation</title>
498 <para>
499 The newly created &carv_obj; consists only of the image buffer plus an uninitialised visibility map.
500 If one had a previously computed visibility map, it could be imported into the &carv_obj; and that
501 would be enough (see the <link linkend="import-vmap">Importing a visibility map in a carver</link>
502 section).
503 </para>
504 <para>
505 If the visibility map has to be computed, the &carv_obj; needs to be initialised through this
506 function:
507 <funcsynopsis>
508 <funcprototype>
509 <funcdef>LqrRetVal <function>lqr_carver_init</function></funcdef>
510 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
511 <paramdef> gint <parameter>delta_x</parameter></paramdef>
512 <paramdef> gfloat <parameter>rigidity</parameter></paramdef>
513 </funcprototype>
514 </funcsynopsis>
515 </para>
516 <para>
517 Here, <parameter>delta_x</parameter> is the maximum allowed transversal step of the seams (0 means
518 straight seams, the typical value is 1), while the <parameter>rigidity</parameter> parameter can be
519 used to introduce a global bias for non-straight seams (the typical value is 0; a nonzero value can
520 be modulated locally for specific areas using the functions described in section
521 <link linkend="rigmask">Adding a rigidity mask</link>).
522 </para>
523 <important>
524 <para>
525 It is currently an error to initalise a carver object if a visibility map has been imported
526 already.
527 </para>
528 </important>
529 </sect2>
530
531 <sect2 id="image-type">
532 <title>Choosing the image type</title>
533 <para>
534 The library supports a small number of different image types/color models in order to correctly
535 compute quantities such as the brightness of a pixel, which are important for automatic feature
536 detection.
537 </para>
538 <para>
539 The image type can be set manually using the function:
540 <funcsynopsis>
541 <funcprototype>
542 <funcdef>LqrRetVal <function>lqr_carver_set_image_type</function></funcdef>
543 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
544 <paramdef> LqrImageType <parameter>image_type</parameter></paramdef>
545 </funcprototype>
546 </funcsynopsis>
547 </para>
548 <para>
549 The type <type>LqrImageType</type> is an <literal>enum</literal> which can take these values:
550 <itemizedlist>
551 <listitem>&img_type_grey;</listitem>
552 <listitem>&img_type_greya;</listitem>
553 <listitem>&img_type_rgb;</listitem>
554 <listitem>&img_type_rgba;</listitem>
555 <listitem>&img_type_cmy;</listitem>
556 <listitem>&img_type_cmyk;</listitem>
557 <listitem>&img_type_cmyka;</listitem>
558 <listitem>&img_type_custom;</listitem>
559 </itemizedlist>
560 </para>
561 <para>
562 When creating a &carv_obj; object, the image type is inferred from the number of channels according
563 to this table:
564 <table id="def-image-types">
565 <title>Image types assigned by default</title>
566 <tgroup cols="2">
567 <thead>
568 <row>
569 <entry>channels</entry>
570 <entry>type</entry>
571 </row>
572 </thead>
573 <tbody>
574 <row>
575 <entry>1</entry>
576 <entry>&img_type_grey;</entry>
577 </row>
578 <row>
579 <entry>2</entry>
580 <entry>&img_type_greya;</entry>
581 </row>
582 <row>
583 <entry>3</entry>
584 <entry>&img_type_rgb;</entry>
585 </row>
586 <row>
587 <entry>4</entry>
588 <entry>&img_type_rgba;</entry>
589 </row>
590 <row>
591 <entry>5</entry>
592 <entry>&img_type_cmyka;</entry>
593 </row>
594 <row>
595 <entry>&gt;5</entry>
596 <entry>&img_type_custom;</entry>
597 </row>
598 </tbody>
599 </tgroup>
600 </table>
601 </para>
602 <para>
603 When setting a carver to &img_type_custom;, it is assumed that there are no alpha or black channels,
604 but if there are, their index can be specified with the functions:
605 <funcsynopsis>
606 <funcprototype>
607 <funcdef>LqrRetVal <function>lqr_carver_set_alpha_channel</function></funcdef>
608 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
609 <paramdef> gint <parameter>channel_index</parameter></paramdef>
610 </funcprototype>
611 </funcsynopsis>
612 <funcsynopsis>
613 <funcprototype>
614 <funcdef>LqrRetVal <function>lqr_carver_set_black_channel</function></funcdef>
615 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
616 <paramdef> gint <parameter>channel_index</parameter></paramdef>
617 </funcprototype>
618 </funcsynopsis>
619 Use the value <literal>-1</literal> in the indices arguments to unset those channels. Note that
620 using &img_type_custom; in a carver normally requires special care in the choice and definitions of
621 the energy functions (see the <link linkend="energy">Automatic feature detection</link> section).
622 </para>
623 <note>
624 <para>
625 Setting manually the alpha or black channel with the above functions automatically sets the
626 carver image type to &img_type_custom;.
627 </para>
628 </note>
629 <note>
630 <para>
631 The support for CMY (and derived) color models is very naïve, since no color profiles are yet
632 managed by the library.
633 </para>
634 </note>
635 </sect2>
636 </sect1>
637
638 <sect1 id="lqr">
639 <title>Liquid rescaling</title>
640
641 <sect2 id="lqr-resize">
642 <title>The resizing method</title>
643 <para>
644 Once initialised, or if a visibility map has been loaded, the image can be resized through this
645 function:
646 <funcsynopsis>
647 <funcprototype>
648 <funcdef>LqrRetVal <function>lqr_carver_resize</function></funcdef>
649 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
650 <paramdef> gint <parameter>new_width</parameter></paramdef>
651 <paramdef> gint <parameter>new_height</parameter></paramdef>
652 </funcprototype>
653 </funcsynopsis>
654 </para>
655 <para>
656 This function decides automatically whether it can use the already computed visibility map, it has
657 to update it or waste it completely and start afresh. This last event occurs when the map was
658 computed for horizontal resizing and a vertical resize has been requested, or vice versa, and also
659 when the required enlargment is bigger than the enlargement step value (see
660 <link linkend="lqr-enl-step">Setting the enlargement step</link>). Note that only initialised
661 carvers can update or change the visibility map; if this is not the case, an error is returned.
662 </para>
663 <para>
664 The function also takes advantage of the fact that the enlargment process mirrors the shrink
665 process. For example, if the original size of the image is <literal>(<symbol>w0</symbol>,
666 <symbol>h0</symbol>)</literal> and <function>lqr_carver_resize</function> is invoked with
667 <literal>(<symbol>w0</symbol> - 100, <symbol>h0</symbol>)</literal> as an argument, then subsequent
668 calls to the function will allow on-the-fly resizing in the whole range from
669 <literal>(<symbol>w0</symbol> - 100, <symbol>h0</symbol>)</literal> to <literal>(<symbol>w0</symbol>
670 + 100, <symbol>h0</symbol>)</literal>. (But note that this may be overcome if
671 <literal><symbol>w0</symbol> + 100</literal> is bigger than the enlargement step.)
672 </para>
673 </sect2>
674
675 <sect2 id="flatten">
676 <title>Flattening</title>
677 <para>
678 In order to resize in more than one step, the image can be flattened in its current state, thrugh
679 this function:
680 <funcsynopsis>
681 <funcprototype>
682 <funcdef>gboolean <function>lqr_carver_flatten</function></funcdef>
683 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
684 </funcprototype>
685 </funcsynopsis>
686 </para>
687 <para>
688 The return value is &ret_false; in case of insufficient memory, &ret_true; otherwise.
689 </para>
690 <para>
691 This function destroys the current visibility map and reinitialises the multi-size image from its
692 current state.
693 </para>
694 <note>
695 <para>
696 Every time that the image is flattened (including when changing the resize direction) the
697 original image and all information about it is lost.
698 </para>
699 </note>
700 </sect2>
701
702 <sect2 id="lqr-cancel">
703 <title>Cancelling an action</title>
704 <para>
705 The resizing and flattening operations can be aborted using this function:
706 <funcsynopsis>
707 <funcprototype>
708 <funcdef>LqrRetVal <function>lqr_carver_cancel</function></funcdef>
709 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
710 </funcprototype>
711 </funcsynopsis>
712 </para>
713 <para>
714 This function can be invoked asynchronously, from a different thread with respect to the one in
715 which the resizing or flattening methods were called. If successful, this function will return
716 &err_ok;, and any ongoing resizing or flattening functions will immidiately abort and return the
717 special value &err_cancel;; however, this function will have no effect if no operation was in
718 progress when calling it.
719 </para>
720 <para>
721 This function can be called multiple times.
722 </para>
723 <important>
724 <para>
725 Whenever a function returns &err_cancel;, it means that the &carv_obj; object is in an
726 inconsistent state, and there is currently no way to recover from this situation. Therefore, any
727 further operation on it must be avoided, and it must be destroyed.
728 </para>
729 </important>
730 <important>
731 <para>
732 The functions <function>lqr_carver_resize</function> and <function>lqr_carver_flatten</function>
733 are not the only ones which can return &err_cancel;; instead, any function in the library whose
734 return type is <classname>LqrRetVal</classname> and which operates on &carv_obj; objects can
735 return such value: for example, any function will do so if called over a &carv_obj; object for
736 which an operation was actually cancelled (but this is not the only possibility).
737 </para>
738 </important>
739 </sect2>
740 </sect1>
741
742 <sect1 id="read-out">
743 <title>Reading the multi-size image</title>
744
745 <sect2 id="px-by-px">
746 <title>Pixel by pixel</title>
747
748 <para>
749 Once you have rescaled the image, you can read out the result through the functions:
750 <funcsynopsis>
751 <funcprototype>
752 <funcdef>gboolean <function>lqr_carver_scan</function></funcdef>
753 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
754 <paramdef> gint* <parameter>x</parameter></paramdef>
755 <paramdef> gint* <parameter>y</parameter></paramdef>
756 <paramdef> guchar** <parameter>rgb</parameter></paramdef>
757 </funcprototype>
758 </funcsynopsis>
759 or
760 <funcsynopsis>
761 <funcprototype>
762 <funcdef>gboolean <function>lqr_carver_scan_ext</function></funcdef>
763 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
764 <paramdef> gint* <parameter>x</parameter></paramdef>
765 <paramdef> gint* <parameter>y</parameter></paramdef>
766 <paramdef> void** <parameter>rgb</parameter></paramdef>
767 </funcprototype>
768 </funcsynopsis>
769 </para>
770 <para>
771 Here, <parameter>x</parameter> and <parameter>y</parameter> are pointers to the varaibles which will
772 hold the pixel coordinate, while <parameter>rgb</parameter> is a pointer to an array which will
773 contain the pixel colour information. If the carver was created using the standard 8-bit constructor
774 <function>lqr_carver_new</function>, the first form can be used, otherwise you must use the extended
775 form <function>lqr_carver_scan_ext</function>. In this last case, the output pointer
776 <parameter>rgb</parameter> must be passed as a pointer to <type>void*</type>, but the outcome should
777 actually be cast to a pointer to an array of the appropriate type, depending on the &carv_obj;
778 colour depth.
779 </para>
780 <para>
781 The return value is &ret_false; when the end of the image is reached, or the buffer has the wrong
782 number of bits, &ret_true; otherwise.
783 </para>
784 <para>
785 Each time these functions are invoked, they will store the coordinates and rgb information in the
786 output pointers and move to the next pixel. If they reach the end, they reset the reader and return
787 &ret_false;.
788 </para>
789 <para>
790 Here is a sample code usage:
791 <example id="ex-read-out">
792 <title>A simple readout example</title>
793 <programlisting>
794 gint x, y;
795 guchar *rgb;
796
797 while (lqr_carver_scan (carver, &amp;x, &amp;y, &amp;rgb) {
798 my_plot (x, y, rgb[0], rgb[1], rgb[2]);
799 }
800 </programlisting>
801 </example>
802
803 In this example, it is assumed that the image has three 8-bit colour channels, and that there exist
804 some function <function>my_plot</function> which writes out the pixels somewhere.
805 </para>
806 <para>
807 The same readout example with different colour depth would read like this:
808 <example id="ex-read-out-ext">
809 <title>A simple readout example - extended version</title>
810 <programlisting>
811 gint x, y;
812 void *rgb;
813 gdouble *rgb_out;
814
815 while (lqr_carver_scan (carver, &amp;x, &amp;y, &amp;rgb) {
816 rgb_out = (gdouble*) rgb;
817 my_plot (x, y, rgb_out[0], rgb_out[1], rgb_out[2]);
818 }
819 </programlisting>
820 </example>
821
822 In this example it is assumed that the carver was loaded with the &col_depth_64f; as the
823 <parameter>colour_depth</parameter> argument in the constructor
824 <function>lqr_carver_new_ext</function>, and that it has <literal>3</literal> colour channels (see
825 the <link linkend="carver-new">constructor section</link> for details); therefore, the output is
826 cast to type <type>gdouble</type> before using it.
827 </para>
828 <important>
829 <para>
830 The <parameter>rgb</parameter> array is owned by to the carver object, so it doesn't need
831 initialization, as in the example. Indeed, it must be used for read-only purposes, and the
832 content should always be copyed after each call to a scan function.
833 </para>
834 </important>
835 </sect2>
836
837 <sect2 id="line-by-line">
838 <title>One line at a time</title>
839
840 <para>
841 The image can also be read one line at a time, but it is not possible to freely decide if it is to
842 be read by row or by column. Instead, this has to be queried by calling this function:
843 <funcsynopsis>
844 <funcprototype>
845 <funcdef>gboolean <function>lqr_carver_scan_by_row</function></funcdef>
846 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
847 </funcprototype>
848 </funcsynopsis>
849 </para>
850 <para>
851 The function returns &ret_true; if the image is read by row, and &ret_false; if it is read by
852 column.
853 </para>
854 <para>
855 Then, the image can be read through these functions:
856 <funcsynopsis>
857 <funcprototype>
858 <funcdef>gboolean <function>lqr_carver_scan_line</function></funcdef>
859 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
860 <paramdef>gint* <parameter>n</parameter></paramdef>
861 <paramdef>guchar** <parameter>rgb</parameter></paramdef>
862 </funcprototype>
863 </funcsynopsis>
864 or
865 <funcsynopsis>
866 <funcprototype>
867 <funcdef>gboolean <function>lqr_carver_scan_line_ext</function></funcdef>
868 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
869 <paramdef>gint* <parameter>n</parameter></paramdef>
870 <paramdef>void** <parameter>rgb</parameter></paramdef>
871 </funcprototype>
872 </funcsynopsis>
873 </para>
874 <para>
875 These functions work exactly the same way as <function>lqr_carver_scan</function> and
876 <function>lqr_carver_scan_ext</function>, but only one coordinate is stored (either the row or the
877 column number), and the <parameter>rgb</parameter> array will contain a whole line.
878 </para>
879 <para>
880 Here is a sample code usage for the standard 8-bit case:
881 <example id="ex-scan-line">
882 <title>Line-by-line readout example</title>
883 <programlisting>
884 gint n;
885 guchar *rgb;
886 gboolean by_row;
887
888 by_row = lqr_carver_scan_by_row (carver);
889
890 while (lqr_carver_scan_line (carver, &amp;n, &amp;rgb) {
891 by_row ? my_plot_row (n, rgb) : my_plot_col (n, rgb);
892 }
893 </programlisting>
894 </example>
895
896 where, as before, it is assumed that the <function>my_plot_row</function> and
897 <function>my_plot_col</function> functions have been previously defined and "know what to do".
898 </para>
899 <para>
900 The extended version for images with more colour depth is very similar, it only requires an
901 additional cast:
902 <example id="ex-scan-line-ext">
903 <title>Line-by-line readout example - extended version</title>
904 <programlisting>
905 gint n;
906 void *rgb;
907 guchar *rgb_out;
908 gboolean by_row;
909
910 by_row = lqr_carver_scan_by_row (carver);
911
912 while (lqr_carver_scan_line_ext (carver, &amp;n, &amp;rgb) {
913 rgb_out = (gboolean*) rgb;
914 by_row ? my_plot_row (n, rgb_out) : my_plot_col (n, rgb_out);
915 }
916 </programlisting>
917 </example>
918 </para>
919 </sect2>
920
921 <sect2 id="reset">
922 <title>Resetting</title>
923
924 <para>
925 Normally, it is not needed to reset the image scan. However, if the scan has been stopped at same
926 intermediate step for some reason, the following function can be used to restart from the beginning:
927 <funcsynopsis>
928 <funcprototype>
929 <funcdef>void <function>lqr_carver_scan_reset</function></funcdef>
930 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
931 </funcprototype>
932 </funcsynopsis>
933 </para>
934 </sect2>
935 </sect1>
936
937 <sect1 id="energy">
938 <title>Automatic feature detection</title>
939
940 <sect2 id="energy-foreword">
941 <title>Foreword</title>
942
943 <para>
944 The automatic feature detection relies on the evaluation of the relevance of each pixel; this
945 quantity is called `energy': the higher the energy of a pixel, the less likely it will be that such
946 pixel will be directly involved in the rescaling. The energy function which the library uses can be
947 customised; normally, edge detector filters are the best choices for this purpose.
948 </para>
949 <para>
950 There is a unified framework in the &lqrl; for energy fucntions: briefly, each energy function used
951 by the library receives the current position and image size as parameters, and is provided access to
952 a square of values from the image, centered around the current position. This access is provided
953 through an object which is called a "reading window", and the image pixels are not read directly,
954 but rather they are accessed according to a "reader type", which means that the energy function can
955 get e.g. the brightness of a pixel without needing to care for the underlying image representation,
956 i.e. the image type or the colour depth.
957 </para>
958 <para>
959 The library provides a small set of very simple (yet normally effective) gradient-based energy
960 functions, and a customisation framework for defining more functions.
961 </para>
962
963 </sect2>
964 <sect2 id="energy-builtin">
965 <title>Builtin energy functions</title>
966
967 <para>
968 The library has some builtin functions for energy evaluation; in order to set one of the builtin
969 functions in a &carv_obj; object this function is used:
970 <funcsynopsis>
971 <funcprototype>
972 <funcdef>LqrRetVal <function>lqr_carver_set_energy_function_builtin</function></funcdef>
973 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
974 <paramdef>LqrEnergyFunctionBuiltinType <parameter>ef_ind</parameter></paramdef>
975 </funcprototype>
976 </funcsynopsis>
977 </para>
978 <para>
979 The currently available builtin functions which can be used as <parameter>ef_ind</parameter> are:
980 <variablelist>
981 <varlistentry>
982 <term><literal>LQR_EF_GRAD_XABS</literal></term>
983 <listitem>
984 <para>
985 absolute value of the brightness gradient in the direction
986 of the rescaling (this is the default)
987 </para>
988 </listitem>
989 </varlistentry>
990 <varlistentry>
991 <term><literal>LQR_EF_GRAD_SUMABS</literal></term>
992 <listitem>
993 <para>
994 sum of absolute values of the brightness gradients in both directions
995 </para>
996 </listitem>
997 </varlistentry>
998 <varlistentry>
999 <term><literal>LQR_EF_GRAD_NORM</literal></term>
1000 <listitem>
1001 <para>
1002 norm of the brightness gradient
1003 </para>
1004 </listitem>
1005 </varlistentry>
1006 <varlistentry>
1007 <term><literal>LQR_EF_LUMA_GRAD_XABS</literal></term>
1008 <listitem>
1009 <para>
1010 absolute value of the luma gradient in the direction
1011 of the rescaling
1012 </para>
1013 </listitem>
1014 </varlistentry>
1015 <varlistentry>
1016 <term><literal>LQR_EF_LUMA_GRAD_SUMABS</literal></term>
1017 <listitem>
1018 <para>
1019 sum of absolute values of the luma gradients in both directions
1020 </para>
1021 </listitem>
1022 </varlistentry>
1023 <varlistentry>
1024 <term><literal>LQR_EF_LUMA_GRAD_NORM</literal></term>
1025 <listitem>
1026 <para>
1027 norm of the luma gradient
1028 </para>
1029 </listitem>
1030 </varlistentry>
1031 <varlistentry>
1032 <term><literal>LQR_EF_NULL</literal></term>
1033 <listitem>
1034 <para>
1035 null
1036 </para>
1037 </listitem>
1038 </varlistentry>
1039 </variablelist>
1040 </para>
1041 <para>
1042 All of the above gradient functions have a radius of 1 pixel.
1043 </para>
1044
1045 </sect2>
1046
1047 <sect2 id="energy-custom">
1048 <title>Custom energy functions</title>
1049
1050 <para>
1051 Custom energy functions for a &carv_obj; object are set using this function:
1052 <funcsynopsis>
1053 <funcprototype>
1054 <funcdef>LqrRetVal <function>lqr_carver_set_energy_function</function></funcdef>
1055 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1056 <paramdef>LqrEnergyFunc <parameter>ef_func</parameter></paramdef>
1057 <paramdef>gint <parameter>radius</parameter></paramdef>
1058 <paramdef>LqrEnergyReaderType <parameter>reader_type</parameter></paramdef>
1059 <paramdef>gpointer <parameter>extra_data</parameter></paramdef>
1060 </funcprototype>
1061 </funcsynopsis>
1062 Here, <parameter>ef_func</parameter> is the function (the prototype will be explained below),
1063 <parameter>radius</parameter> is used to set the size of the square region around each pixel which
1064 is used to evaluate the energy for that pixel, <parameter>reader_type</parameter> is used to set
1065 which quantity is used for the energy computation (e.g. brightness, luma etc.) and
1066 <parameter>extra_data</parameter> is a (void) pointer which can be used to pass additional
1067 parameters to the energy function.
1068 </para>
1069 <para>
1070 The <type><literal>LqrEnergyReaderType</literal></type> is an enum which can take these values (also
1071 noted is the number of channels of the corresponging output):
1072 <variablelist>
1073 <varlistentry>
1074 <term><literal>LQR_ER_BRIGHTNESS</literal></term>
1075 <listitem>
1076 <para>
1077 brightness (1 channel)
1078 </para>
1079 </listitem>
1080 </varlistentry>
1081 <varlistentry>
1082 <term><literal>LQR_ER_LUMA</literal></term>
1083 <listitem>
1084 <para>
1085 luma (1 channel)
1086 </para>
1087 </listitem>
1088 </varlistentry>
1089 <varlistentry>
1090 <term><literal>LQR_ER_RGBA</literal></term>
1091 <listitem>
1092 <para>
1093 RGBA (4 channels)
1094 </para>
1095 </listitem>
1096 </varlistentry>
1097 <varlistentry>
1098 <term><literal>LQR_ER_CUSTOM</literal></term>
1099 <listitem>
1100 <para>
1101 read the normalised image channels as they are (as many channels as the image has)
1102 </para>
1103 </listitem>
1104 </varlistentry>
1105 </variablelist>
1106 These readouts always return values beetween <literal>0</literal> and <literal>1</literal>.
1107 </para>
1108 <note>
1109 <para>
1110 Note that these readouts may have special meanings depending on the image type:
1111 <itemizedlist>
1112 <listitem>
1113 <para>
1114 for <literal>LQR_GREY_IMAGE</literal>, <literal>LQR_GREYA_IMAGE</literal> and
1115 <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_LUMA</literal>
1116 readout will yield the same result as <literal>LQR_ER_BRIGHTNESS</literal>
1117 </para>
1118 </listitem>
1119 <listitem>
1120 <para>
1121 for <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_BRIGHTNESS</literal>
1122 readout will return the average pixel value (additive, i.e. if a black channel is
1123 present the channel values will be inverted and multiplied by the black channel
1124 inverse), multiplied by the alpha channel value.
1125 </para>
1126 </listitem>
1127 <listitem>
1128 <para>
1129 for <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_RGBA</literal>
1130 readout <emphasis>cannot be used</emphasis>: it will always return
1131 <literal>0</literal>
1132 </para>
1133 </listitem>
1134 </itemizedlist>
1135 </para>
1136 </note>
1137 <para>
1138 The custom energy function must be declared like in the following sample declaration:
1139 <example id="ex-custom-en-decl">
1140 <title>Custom energy declaration</title>
1141 <programlisting>
1142 gfloat my_energy (gint x, gint y, gint width, gint height, LqrReadingWindow *rwindow, gpointer extra_data);
1143 </programlisting>
1144 </example>
1145 This function should return the energy at pixel <parameter>x</parameter>, <parameter>y</parameter>,
1146 based on the knowledge of the current image size (obtained from <parameter>width</parameter> and
1147 <parameter>height</parameter>) and the content of the image in a square around that pixel, which is
1148 passed through the <parameter>rwindow</parameter> reading window: in order to access this content,
1149 this function must be used:
1150 <funcsynopsis>
1151 <funcprototype>
1152 <funcdef>gdouble <function>lqr_rwindow_read</function></funcdef>
1153 <paramdef>LqrReadingWindow * <parameter>rwindow</parameter></paramdef>
1154 <paramdef>gint <parameter>x</parameter></paramdef>
1155 <paramdef>gint <parameter>y</parameter></paramdef>
1156 <paramdef>channel <parameter>channel</parameter></paramdef>
1157 </funcprototype>
1158 </funcsynopsis>
1159 When reading out the content from a window, the <parameter>x</parameter> and
1160 <parameter>y</parameter> parameters are relative to the window centre (which instead is given by the
1161 <parameter>x</parameter>, <parameter>y</parameter> parameters passed to the custom energy function),
1162 and they both range between <literal><symbol>-radius</symbol></literal> and
1163 <literal><symbol>radius</symbol></literal> included (<parameter>radius</parameter> being the same
1164 one which is used in <function>lqr_carver_set_energy_function</function>). The parameter
1165 <parameter>channel</parameter> specifies which channel to read out; depending on the
1166 <parameter>read_type</parameter> passed to <function>lqr_carver_set_energy_function</function> the
1167 range and meaning of this parameter will change: for the cases <literal>LQR_ER_BRIGHTNESS</literal> and
1168 <literal>LQR_ER_LUMA</literal> it must be <literal>0</literal>, because the readout consists of a
1169 single channel, for <literal>LQR_ER_RGBA</literal> it must be between <literal>0</literal> and
1170 <literal>3</literal> (and then the readout will contain the RGBA information), while for
1171 <literal>LQR_ER_CUSTOM</literal> it must be one of the original image channels.
1172 </para>
1173 <para>
1174 The <parameter>rwindow</parameter> parameters can be read out from within a custom defined energy
1175 function using these functions:
1176 <funcsynopsis>
1177 <funcprototype>
1178 <funcdef>LqrEnergyReaderType <function>lqr_rwindow_get_read_t</function></funcdef>
1179 <paramdef>LqrReadingWindow * <parameter>rwindow</parameter></paramdef>
1180 </funcprototype>
1181 <funcprototype>
1182 <funcdef>gint <function>lqr_rwindow_get_radius</function></funcdef>
1183 <paramdef>LqrReadingWindow * <parameter>rwindow</parameter></paramdef>
1184 </funcprototype>
1185 <funcprototype>
1186 <funcdef>gint <function>lqr_rwindow_get_channels</function></funcdef>
1187 <paramdef>LqrReadingWindow * <parameter>rwindow</parameter></paramdef>
1188 </funcprototype>
1189 </funcsynopsis>
1190 </para>
1191 <para>
1192 Following is an example of how a simple Sobel fliter can be defined and used within this framework:
1193 <example id="ex-custom-en-def">
1194 <title>Custom energy definition and setup</title>
1195 <programlisting>
1196 /* definition */
1197
1198 gfloat sobel(gint x, gint y, gint width, gint height, LqrReadingWindow *rw, gpointer extra_data)
1199 {
1200 gint i, j;
1201 gdouble ex = 0;
1202 gdouble ey = 0;
1203 gdouble k[3][3] = {{0.125, 0.25, 0.125}, {0, 0, 0}, {-0.125, -0.25, -0.125}};
1204
1205 for (i = -1; i &lt;=1; i++) {
1206 for (j = -1; j &lt;=1; j++) {
1207 ex += k[i + 1][j + 1] * lqr_rwindow_read(rw, i, j, 0);
1208 ey += k[j + 1][i + 1] * lqr_rwindow_read(rw, i, j, 0);
1209 }
1210 }
1211 return (gfloat) sqrt(ex * ex + ey * ey);
1212 }
1213
1214 /* usage */
1215
1216 lqr_carver_set_energy_function (carver, sobel, 1, LQR_ER_BRIGHTNESS, NULL);
1217 </programlisting>
1218 </example>
1219 </para>
1220 <para>
1221 In the above <function>sobel</function> function it is assumed that the radius is 1 and that the
1222 readout will consist of a single channel. Furthermore, no boundary checking is performed, and
1223 therefore the parameters &param_x;, &param_y;, &param_w; and &param_h; are not used. Also, no extra
1224 parameters are passed to the function.
1225 </para>
1226 <note>
1227 <para>
1228 The function <function>lqr_rwindow_read</function> returns <literal>0</literal> when the
1229 requested value is out of the image boundary or beyond the reading window radius.
1230 </para>
1231 </note>
1232 <note>
1233 <para>
1234 The energy functions are called over the transposed image in case of vertical scaling,
1235 therefore, if they are asymmetrical, the result will be different depending on the scaling
1236 orientation (this is the case for example for the <literal>LQR_EF_GRAD_XABS</literal> builtin
1237 function).
1238 </para>
1239 </note>
1240 <note>
1241 <para>
1242 The energy function output should be normalised in order to be comparable with the builtin
1243 functions, otherwise the scale of the bias would be different depending on the energy function
1244 used. This is the reason why in the Sobel filter written above the kernel
1245 <parameter>k</parameter> is scaled so that the sum of the absolute values of the matrix is equal
1246 to <literal>1</literal>.
1247 </para>
1248 </note>
1249 <note>
1250 <para>
1251 In actual code, the call to <function>lqr_carver_set_energy_function</function> should be
1252 protected to test its return value.
1253 </para>
1254 </note>
1255 </sect2>
1256
1257 <sect2 id="energy-readout">
1258 <title>Reading out the energy</title>
1259
1260 <para>
1261 The energy can be read out with three similar functions, all of which fill a buffer provided by
1262 the user, but in different ways: two of them are suitable for plotting, while the third one can be
1263 used to retreive the true values of the energy, as used internally.
1264 </para>
1265 <para>
1266 The first function can be used to get a buffer of normalised values, and it has a simple syntax:
1267 <funcsynopsis>
1268 <funcprototype>
1269 <funcdef>LqrRetVal <function>lqr_carver_get_energy</function></funcdef>
1270 <paramdef>LqrCarver * <parameter>carver</parameter></paramdef>
1271 <paramdef>gfloat * <parameter>buffer</parameter></paramdef>
1272 <paramdef>gint <parameter>orientation</parameter></paramdef>
1273 </funcprototype>
1274 </funcsynopsis>
1275 This function writes the the energy values at the time of calling to the given
1276 <parameter>buffer</parameter>, ordered by row and then by column. All values range between
1277 <literal>0</literal> and <literal>1</literal>. The buffer must be allocated by the user before
1278 calling it.
1279 </para>
1280 <para>
1281 The <parameter>orientation</parameter> parameter determines which orientation will be used when
1282 computing the energy: <literal>0</literal> means horizontal, <literal>1</literal> means vertical.
1283 </para>
1284 <para>
1285 The <parameter>carver</parameter> need not be initialised; if a bias was added to it (see the
1286 <link linkend="bias">Adding a bias</link> section), its effect is included in the output.
1287 </para>
1288 <para>
1289 The above function does not return the true energy which is used internally, because that would not
1290 be suitable for plotting, since the energy range is arbitrary (only the energy differences are
1291 meaningful, and there is no upper nor lower bound to the values). In order to get the true energy
1292 values used internally, this function must be used instead (with the same syntax):
1293 <funcsynopsis>
1294 <funcprototype>
1295 <funcdef>LqrRetVal <function>lqr_carver_get_true_energy</function></funcdef>
1296 <paramdef>LqrCarver * <parameter>carver</parameter></paramdef>
1297 <paramdef>gfloat * <parameter>buffer</parameter></paramdef>
1298 <paramdef>gint <parameter>orientation</parameter></paramdef>
1299 </funcprototype>
1300 </funcsynopsis>
1301 </para>
1302 <para>
1303 The third function can be used to fill directly an image buffer:
1304 <funcsynopsis>
1305 <funcprototype>
1306 <funcdef>LqrRetVal <function>lqr_carver_get_energy_image</function></funcdef>
1307 <paramdef>LqrCarver * <parameter>carver</parameter></paramdef>
1308 <paramdef>void * <parameter>buffer</parameter></paramdef>
1309 <paramdef>gint <parameter>orientation</parameter></paramdef>
1310 <paramdef>LqrColDepth <parameter>col_depth</parameter></paramdef>
1311 <paramdef>LqrImageType <parameter>image_type</parameter></paramdef>
1312 </funcprototype>
1313 </funcsynopsis>
1314 In this case, the buffer must be passed as <type>void*</type>, while the
1315 <parameter>col_depth</parameter> and <parameter>image_type</parameter> are used to specify the
1316 colour depth and the image type, in the same way as is done when creating an &carv_obj; object (see
1317 <link linkend="carver-new">Carver objcet creation</link> and the
1318 <link linkend="image-type">Choosing the image type</link> sections). The only restriction is that it
1319 is not possible to ask for &img_type_custom; image types.
1320 </para>
1321 <para>
1322 For any choice of the parameters, the <parameter>buffer</parameter> will hold a greyscale image,
1323 ranging from black (lowest energy) to white (highest energy). The opacity (alpha) will be set to
1324 <literal>1</literal>, if present. All the information will be stored in the black channel in
1325 &img_type_cmyk; and &img_type_cmyka; image types.
1326 </para>
1327 <note>
1328 <para>
1329 Calling the function <function>lqr_carver_get_energy_image</function> with &col_depth_32f; and
1330 &img_type_grey; arguments will yield the same result as calling the function
1331 <function>lqr_carver_get_energy</function>, but the latter is slightly more efficient.
1332 </para>
1333 </note>
1334 </sect2>
1335 </sect1>
1336 <sect1 id="bias">
1337 <title>Adding a bias</title>
1338
1339 <sect2 id="bias-foreword">
1340 <title>Foreword</title>
1341
1342 <para>
1343 The automatic feature detection can be driven manually by adding a bias to the pixels of the image.
1344 </para>
1345 <para>
1346 For example, it is possible to protect regions of the image by adding a positive bias to the
1347 corresponding pixels. This will make the seams more unlikely to cross those regions, thus avoiding
1348 distortion (but increasing distortion of the other regions).
1349 </para>
1350 <para>
1351 It is also possible to make the seams more likely to cross some regions by adding a negative bias to
1352 them. In this case, reducing the size of the image will tend to erase those regions, while
1353 (possibly) keeping the rest of the image in a consistent state.
1354 </para>
1355 <important>
1356 <para>
1357 The bias has to be added before the resizing takes place (but it can be added before
1358 initialisation since version 0.4).
1359 </para>
1360 </important>
1361 <note>
1362 <para>
1363 In all of the bias-related functions, the bias is added on top of the existing one, so that all
1364 of the functions can be called multiple times.
1365 </para>
1366 </note>
1367 </sect2>
1368
1369 <sect2 id="bias-xy">
1370 <title>Adding a bias pixel by pixel</title>
1371
1372 <para>
1373 The function to use in order to add a bias to a given pixel is:
1374 <funcsynopsis>
1375 <funcprototype>
1376 <funcdef>LqrRetVal <function>lqr_carver_bias_add_xy</function></funcdef>
1377 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1378 <paramdef>gdouble <parameter>bias</parameter></paramdef>
1379 <paramdef>gint <parameter>x</parameter></paramdef>
1380 <paramdef>gint <parameter>y</parameter></paramdef>
1381 </funcprototype>
1382 </funcsynopsis>
1383 Typical values for the <parameter>bias</parameter> parameter would be between <literal>100</literal>
1384 and <literal>10000</literal> in module.
1385 </para>
1386 </sect2>
1387
1388 <sect2 id="bias-float">
1389 <title>Using an array of floating-point values</title>
1390
1391 <para>
1392 It is possible to use a whole array of floating points at once through this function:
1393 <funcsynopsis>
1394 <funcprototype>
1395 <funcdef>LqrRetVal <function>lqr_carver_bias_add</function></funcdef>
1396 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1397 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
1398 <paramdef>gint <parameter>bias_factor</parameter></paramdef>
1399 </funcprototype>
1400 </funcsynopsis>
1401 </para>
1402 <para>
1403 Here, <parameter>buffer</parameter> is an array contining the bias values, and it is assumed to have
1404 the same size as the image loaded in <parameter>carver</parameter>, while
1405 <parameter>bias_factor</parameter> is an overall bias factor, which can be used to affect the global
1406 bias level: if the elements of <parameter>buffer</parameter> are of order 1, a standard choice for
1407 the bias_factor would be between <literal>100</literal> and <literal>10000</literal> (in module).
1408 </para>
1409 <note>
1410 <para>
1411 This function, and all the following, will not swallow the buffer (to the contrary of what
1412 happens e.g. when creating a new &carv_obj; object and allowing the default behaviour),
1413 therefore the buffer must be freed by the user afterwards.
1414 </para>
1415 </note>
1416 </sect2>
1417
1418 <sect2 id="bias-rgb">
1419 <title>Using another image</title>
1420
1421 <para>
1422 The bias can also be read from an 8-bit rgb buffer. This buffer has to be in the same format as the
1423 one used in the 8-bit LqrCarver constructor (but may have a different number of colours per
1424 channel). The function is:
1425 <funcsynopsis>
1426 <funcprototype>
1427 <funcdef>LqrRetVal <function>lqr_carver_bias_add_rgb</function></funcdef>
1428 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1429 <paramdef>guchar* <parameter>buffer</parameter></paramdef>
1430 <paramdef>gint <parameter>bias_factor</parameter></paramdef>
1431 <paramdef>gint <parameter>channels</parameter></paramdef>
1432 </funcprototype>
1433 </funcsynopsis>
1434 </para>
1435 <para>
1436 As in the previous case, <parameter>buffer</parameter> is assumed to hold and image of the same size
1437 as the one in the <parameter>carver</parameter>.
1438 </para>
1439 <para>
1440 The <parameter>buffer</parameter> contents will be transformed into floating-points by averaging the
1441 colour components and multiplying the result by the alpha channel (transparency) value.
1442 </para>
1443 <important>
1444 <para>
1445 The existence of an alpha channel is inferred from the <parameter>channels</parameter> value: if
1446 this is 1 or 3, no alpha channel is assumed, if it is 2 or 4 or greater, it is assumed that the
1447 last channel holds the alpha value. If this is not what you want, you should resort to one of
1448 the previous methods.
1449 </para>
1450 </important>
1451 </sect2>
1452
1453 <sect2 id="bias-areas">
1454 <title>Operating on a specific area</title>
1455
1456 <para>
1457 The two previously described functions operate on the whole &carv_obj; image. It is also possible
1458 to access specific image regions in a similar way; for the floating point case use:
1459 <funcsynopsis>
1460 <funcprototype>
1461 <funcdef>LqrRetVal <function>lqr_carver_bias_add_area</function></funcdef>
1462 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1463 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
1464 <paramdef>gint <parameter>bias_factor</parameter></paramdef>
1465 <paramdef>gint <parameter>width</parameter></paramdef>
1466 <paramdef>gint <parameter>height</parameter></paramdef>
1467 <paramdef>gint <parameter>x_off</parameter></paramdef>
1468 <paramdef>gint <parameter>y_off</parameter></paramdef>
1469 </funcprototype>
1470 </funcsynopsis>
1471 while for the rgb image case use:
1472 <funcsynopsis>
1473 <funcprototype>
1474 <funcdef>LqrRetVal <function>lqr_carver_bias_add_rgb_area</function></funcdef>
1475 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1476 <paramdef>guchar* <parameter>buffer</parameter></paramdef>
1477 <paramdef>gint <parameter>bias_factor</parameter></paramdef>
1478 <paramdef>gint <parameter>channels</parameter></paramdef>
1479 <paramdef>gint <parameter>width</parameter></paramdef>
1480 <paramdef>gint <parameter>height</parameter></paramdef>
1481 <paramdef>gint <parameter>x_off</parameter></paramdef>
1482 <paramdef>gint <parameter>y_off</parameter></paramdef>
1483 </funcprototype>
1484 </funcsynopsis>
1485 </para>
1486 <para>
1487 In both functions, &param_w; and &param_h; are used to specify the size of the area of interest,
1488 while <parameter>x_off</parameter> and <parameter>y_off</parameter> specify its offset. For the
1489 rest, both functions work in the same way as their global couterpart.
1490 </para>
1491 <para>
1492 The provided buffers have to be of size <literal>&param_w; * &param_h;</literal> (or
1493 <literal>&param_w; * &param_h; * &param_channels;</literal> for the rgb case) but the specified
1494 areas need not to be strictly included inside the &carv_obj; image area: only the parts which
1495 overlap with it will be used. For example, the offsets can also be negative.
1496 </para>
1497 </sect2>
1498 </sect1>
1499
1500 <sect1 id="rigmask">
1501 <title>Adding a rigidity mask</title>
1502
1503 <sect2 id="rigmask-foreword">
1504 <title>Foreword</title>
1505
1506 <para>
1507 The rigidity parameter which is set at carver activation time (see section
1508 <link linkend="carver-init">Carver activation</link>) normally affects the whole image. It is
1509 possible, however, to specify which areas of the image should be affected by using a rigidity mask.
1510 </para>
1511 <para>
1512 When a rigidity mask is used, each pixel of the image acquires an individual rigidity coefficient,
1513 which has to be multiplied with the overall rigidity parameter to get the actual pixel's rigidity.
1514 This is useful in some situations to reduce distorsions in specific areas of the image while keeping
1515 the seams optimal in other areas.
1516 </para>
1517 <para>
1518 The library interface to deal with rigidity masks follows very closely the scheme for bias masks as
1519 described in the <link linkend="bias">bias section</link>, the main difference being that no
1520 equivalent to the bias factor has to be provided (since it is already given in the
1521 <function>lqr_carver_init</function> function).
1522 </para>
1523 <important>
1524 <para>
1525 The rigidity mask has to be added always <emphasis>after</emphasis> the &carv_obj;
1526 initialization and <emphasis>before</emphasis> resizing takes place. (Note that this is
1527 different from the bias, which instead can also be added to non-initialised carver objects.)
1528 </para>
1529 </important>
1530 <important>
1531 <para>
1532 Whenever a rigidity mask is set, all pixels for which the value is not explicitly defined will
1533 have coefficient 0, i.e. the rigidity setting will will be disabled.
1534 </para>
1535 </important>
1536 <note>
1537 <para>
1538 All of the functions can be called multiple times, but their effect is not summed up, to the
1539 contrary of what happens for the bias functions; instead, new values will substitute old ones
1540 when the affected regions overlap.
1541 </para>
1542 </note>
1543 </sect2>
1544
1545 <sect2 id="rigmask-xy">
1546 <title>Adding an individual rigidity coefficient to a pixel</title>
1547
1548 <para>
1549 The function to use in order to set the rigidity mask at a given pixel is:
1550 <funcsynopsis>
1551 <funcprototype>
1552 <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_xy</function></funcdef>
1553 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1554 <paramdef>gdouble <parameter>rigidity</parameter></paramdef>
1555 <paramdef>gint <parameter>x</parameter></paramdef>
1556 <paramdef>gint <parameter>y</parameter></paramdef>
1557 </funcprototype>
1558 </funcsynopsis>
1559 </para>
1560 </sect2>
1561
1562 <sect2 id="rigmask-float">
1563 <title>Using an array of floating-point values</title>
1564
1565 <para>
1566 It is possible to use a whole array of floating points at once through this function:
1567 <funcsynopsis>
1568 <funcprototype>
1569 <funcdef>LqrRetVal <function>lqr_carver_rigmask_add</function></funcdef>
1570 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1571 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
1572 </funcprototype>
1573 </funcsynopsis>
1574 </para>
1575 <para>
1576 Here, <parameter>buffer</parameter> is an array contining the rigidity coefficients values, and it
1577 is assumed to have the same size as the image loaded in <parameter>carver</parameter>.
1578 </para>
1579 <note>
1580 <para>
1581 This function, and all the following, will not swallow the buffer (to the contrary of what
1582 happens e.g. when creating a new &carv_obj; object and allowing the default behaviour),
1583 therefore the buffer must be freed by the user afterwards.
1584 </para>
1585 </note>
1586 </sect2>
1587
1588 <sect2 id="rigmask-rgb">
1589 <title>Using another image</title>
1590
1591 <para>
1592 The rigidity mask can also be read from an 8-bit rgb buffer. This buffer has to be in the same
1593 format as the one used in the 8-bit LqrCarver constructor (but may have a different number of
1594 colours per channel). The function is:
1595 <funcsynopsis>
1596 <funcprototype>
1597 <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_rgb</function></funcdef>
1598 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1599 <paramdef>guchar* <parameter>buffer</parameter></paramdef>
1600 <paramdef>gint <parameter>channels</parameter></paramdef>
1601 </funcprototype>
1602 </funcsynopsis>
1603 </para>
1604 <para>
1605 As in the previous case, <parameter>buffer</parameter> is assumed to hold and image of the same size
1606 as the one in the <parameter>carver</parameter>.
1607 </para>
1608 <para>
1609 The <parameter>buffer</parameter> contents will be transformed into floating-points by averaging the
1610 colour components and multiplying the result by the alpha channel (transparency) value.
1611 </para>
1612 <important>
1613 <para>
1614 The existence of an alpha channel is inferred from the <parameter>channels</parameter> value: if
1615 this is 1 or 3, no alpha channel is assumed, if it is 2 or 4, it is assumed that the last
1616 channel is holds the alpha value. If this is not what you want, you should resort to one of the
1617 previous methods.
1618 </para>
1619 </important>
1620 </sect2>
1621
1622 <sect2 id="rigmask-areas">
1623 <title>Operating on a specific area</title>
1624
1625 <para>
1626 The two previously described functions operate on the whole &carv_obj; image. It is also possible
1627 to access specific image regions in a similar way; for the floating point use:
1628 <funcsynopsis>
1629 <funcprototype>
1630 <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_area</function></funcdef>
1631 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1632 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
1633 <paramdef>gint <parameter>width</parameter></paramdef>
1634 <paramdef>gint <parameter>height</parameter></paramdef>
1635 <paramdef>gint <parameter>x_off</parameter></paramdef>
1636 <paramdef>gint <parameter>y_off</parameter></paramdef>
1637 </funcprototype>
1638 </funcsynopsis>
1639 while for the rgb image use:
1640 <funcsynopsis>
1641 <funcprototype>
1642 <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_rgb_area</function></funcdef>
1643 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1644 <paramdef>guchar* <parameter>buffer</parameter></paramdef>
1645 <paramdef>gint <parameter>channels</parameter></paramdef>
1646 <paramdef>gint <parameter>width</parameter></paramdef>
1647 <paramdef>gint <parameter>height</parameter></paramdef>
1648 <paramdef>gint <parameter>x_off</parameter></paramdef>
1649 <paramdef>gint <parameter>y_off</parameter></paramdef>
1650 </funcprototype>
1651 </funcsynopsis>
1652 </para>
1653 <para>
1654 In both functions, &param_w; and &param_h; are used to specify the size of the area of interest,
1655 while <parameter>x_off</parameter> and <parameter>y_off</parameter> specify its offset. For the
1656 rest, both functions work in the same way as their global couterpart.
1657 </para>
1658 <para>
1659 The provided buffers have to be of size <literal>&param_w; * &param_h;</literal> (or
1660 <literal>&param_w; * &param_h; * &param_channels;</literal> for the rgb case) but the specified
1661 areas need not to be strictly included inside the &carv_obj; image area: only the parts which
1662 overlap with it will be used. For example, the offsets can also be negative.
1663 </para>
1664 </sect2>
1665 </sect1>
1666
1667 <sect1 id="tuning">
1668 <title>Tuning</title>
1669
1670 <para>
1671 The behaviour can be tuned through some additional functions.
1672 </para>
1673
1674 <sect2 id="lqr-enl-step">
1675 <title>Setting the enlargement step</title>
1676 <para>
1677 As mentioned in <link linkend="about-enlarge">About enlarging</link>, if the requested final size is
1678 too big, the rescaling is automatically divided in steps.
1679 </para>
1680 <para>
1681 For example, let us suppose that we have created an &carv_obj; object from a 100 by 100 pixels
1682 image, and that we call <function>lqr_carver_resize</function> with 600 and 100 as width and height
1683 arguments. With the default settings, the rescaling of the width will be performed in 3 steps:
1684 first, from 100 to 199, then from 199 to 397, and finally from 397 to 600.
1685 </para>
1686 <para>
1687 The rule here is that the maximum size which can be reached in a single step is equal to twice the
1688 original size minus one, and that at each step the original size is reset to the current size
1689 (through an internal call to <function>lqr_carver_flatten</function>).
1690 </para>
1691 <para>
1692 In most situations, however, the steps should be smaller in order to obtain good results. This can
1693 be set with this function:
1694 <funcsynopsis>
1695 <funcprototype>
1696 <funcdef>LqrRetVal <function>lqr_carver_set_enl_step</function></funcdef>
1697 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
1698 <paramdef> gfloat <parameter>enl_step</parameter></paramdef>
1699 </funcprototype>
1700 </funcsynopsis>
1701 </para>
1702 <para>
1703 The value of <parameter>enl_step</parameter> must be strictly grater then 1.0 and less then (or
1704 equal to) 2.0. The default value is 2.0 (for back-compatibility reasons); any other value will
1705 result in the function returning an error. The new maximum size for a step will then be obtained by
1706 multiplying the original size by the enlargement step and subtracting 1.
1707 </para>
1708 <para>
1709 The current value of the enlargement step can be retrieved with this function:
1710 <funcsynopsis>
1711 <funcprototype>
1712 <funcdef>gfloat <function>lqr_carver_get_enl_step</function></funcdef>
1713 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
1714 </funcprototype>
1715 </funcsynopsis>
1716 </para>
1717 </sect2>
1718
1719 <sect2 id="res-order">
1720 <title>Choosing the resize order</title>
1721
1722 <para>
1723 When the function <function>lqr_carver_resize</function> is asked to resize along both directions in
1724 a single step, it has to choose which direction to resize first. The resize order can be changed
1725 through this function:
1726 <funcsynopsis>
1727 <funcprototype>
1728 <funcdef>void <function>lqr_carver_set_resize_order</function></funcdef>
1729 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1730 <paramdef>LqrResizeOrder <parameter>resize_order</parameter></paramdef>
1731 </funcprototype>
1732 </funcsynopsis>
1733 </para>
1734 <para>
1735 The possible values for resize_order are:
1736 <variablelist>
1737 <varlistentry>
1738 <term><literal>LQR_RES_ORDER_HOR</literal></term>
1739 <listitem>
1740 <para>
1741 resize horizonally first (this is the default)
1742 </para>
1743 </listitem>
1744 </varlistentry>
1745 <varlistentry>
1746 <term><literal>LQR_RES_ORDER_VERT</literal></term>
1747 <listitem>
1748 <para>
1749 resize vertically first
1750 </para>
1751 </listitem>
1752 </varlistentry>
1753 </variablelist>
1754 </para>
1755 </sect2>
1756
1757 <sect2 id="switch-freq">
1758 <title>Choosing the side switch frequency</title>
1759
1760 <para>
1761 When the function <function>lqr_carver_resize</function> is invoked, it chooses at each step the
1762 optimal seam to carve based on the relvance value for each pixel. However, in the case two seams
1763 are equivalent (which may happen when large portions of the image have the same colour, for
1764 example), the algorithm always chooses the seams from one side, which might be a problem (e.g. an
1765 object centered in the original image might not be centered any more in the resulting image).
1766 </para>
1767 <para>
1768 In order to overcome this effect, an option is given to automatically switch the favoured side
1769 during rescaling, at the cost of a slightly worse performance. The number of times such a switching
1770 event occurs for each rescale operation can be set using the function:
1771 <funcsynopsis>
1772 <funcprototype>
1773 <funcdef>void <function>lqr_carver_set_side_switch_frequency</function></funcdef>
1774 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1775 <paramdef>guint <parameter>switch_frequency</parameter></paramdef>
1776 </funcprototype>
1777 </funcsynopsis>
1778 </para>
1779 <para>
1780 The default value for newly created &carv_obj; objects is <literal>0</literal>, which is equivalent
1781 to disabling this feature. Giving a value greater than the number of pixels by which to rescale
1782 produces a switch for each pixel, therefore you could set <parameter>switch_freqency</parameter> to
1783 a ridicolously high value in order to be sure to get this effect.
1784 </para>
1785 <para>
1786 As for the final result, a very small value (e.g. <literal>1<literal> to </literal>4</literal>) will
1787 normally suffice to balance the left and right side of the image (or the top and the bottom sides
1788 for vertical rescalings), without noticeable computational costs. However, in order to obtain a
1789 smoother behaviour for the visibiliy map, i.e. for the intermediate steps, higher values may be
1790 required.
1791 </para>
1792 </sect2>
1793
1794 <sect2 id="cache">
1795 <title>Using the cache</title>
1796
1797 <para>
1798 By default, the library tries to cache some quantities in order to save computational time. The
1799 cache may be disabled in order to save memory instead, using this function:
1800 <funcsynopsis>
1801 <funcprototype>
1802 <funcdef>void <function>lqr_carver_set_use_cache</function></funcdef>
1803 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1804 <paramdef>gboolean <parameter>use_cache</parameter></paramdef>
1805 </funcprototype>
1806 </funcsynopsis>
1807 </para>
1808 <para>
1809 To disable the cache, set <parameter>use_cache</parameter> to <literal>FALSE</literal>. To
1810 re-enable it back, set it to <literal>TRUE</literal>.
1811 </para>
1812 </sect2>
1813
1814 </sect1>
1815
1816 <sect1 id="vmaps">
1817 <title>Dealing with the visibility maps (the seams)</title>
1818
1819 <sect2 id="vmap-dump">
1820 <title>Dumping the visibility map</title>
1821
1822 <para>
1823 The visibility map can be saved at any moment by calling the function:
1824 <funcsynopsis>
1825 <funcprototype>
1826 <funcdef>LqrVMap* <function>lqr_vmap_dump</function></funcdef>
1827 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1828 </funcprototype>
1829 </funcsynopsis>
1830 </para>
1831 <para>
1832 This function will return a pointer to a newly allocated &vmap_obj; object, or &ret_null; in case of
1833 failure. See also the section "<link linkend="vmaps-objs">The visibility map objects</link>".
1834 </para>
1835 </sect2>
1836
1837 <sect2 id="activate-dump">
1838 <title>Storing the visibility maps</title>
1839
1840 <para>
1841 By default, the computed visibility maps are wasted. Instead of saving them individually, it is
1842 possible to automatically dump them at the end of the carving process, attaching them to their
1843 associated &carv_obj;. In order to activate this feature, the following function has to be called:
1844 <funcsynopsis>
1845 <funcprototype>
1846 <funcdef>void <function>lqr_carver_set_dump_vmaps</function></funcdef>
1847 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1848 </funcprototype>
1849 </funcsynopsis>
1850 </para>
1851 <para>
1852 This will have the effect of dumping the visibility map each time
1853 <function>lqr_carver_resize</function> is invoked, and storing it internally. When resizing along
1854 both directions, two maps will be dumped, one for each direction.
1855 </para>
1856 <para>
1857 In order to revert the effect of <function>lqr_carver_set_dump_vmaps</function>, thus stopping the
1858 automatic dumping, use the function
1859 <funcsynopsis>
1860 <funcprototype>
1861 <funcdef>void <function>lqr_carver_set_no_dump_vmaps</function></funcdef>
1862 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1863 </funcprototype>
1864 </funcsynopsis>
1865 </para>
1866 <para>
1867 Alternatively, the internal storage mechanism can be called over the current visibility map at any
1868 given moment by calling this function:
1869 <funcsynopsis>
1870 <funcprototype>
1871 <funcdef>LqrRetVal <function>lqr_vmap_internal_dump</function></funcdef>
1872 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1873 </funcprototype>
1874 </funcsynopsis>
1875 </para>
1876 <para>
1877 The dumped maps are stored inside &vmap_obj; objects, and these are attached to their corresponing
1878 &carv_obj; object through a linked list, whose type is &vmapl_obj;
1879 </para>
1880 </sect2>
1881
1882 <sect2 id="access-vmap">
1883 <title>Accessing the internally attached visibility maps</title>
1884
1885 <para>
1886 To access the maps attached to a carver one has first to obtain the pointer to the list, with the
1887 function:
1888 <funcsynopsis>
1889 <funcprototype>
1890 <funcdef>LqrVMapList* <function>lqr_vmap_list_start</function></funcdef>
1891 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
1892 </funcprototype>
1893 </funcsynopsis>
1894 </para>
1895 <para>
1896 Then, one can iterate through the attached maps by using these two functions:
1897 <funcsynopsis>
1898 <funcprototype>
1899 <funcdef>LqrVMap* <function>lqr_vmap_list_current</function></funcdef>
1900 <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
1901 </funcprototype>
1902 </funcsynopsis>
1903 <funcsynopsis>
1904 <funcprototype>
1905 <funcdef>LqrVMapList* <function>lqr_vmap_list_next</function></funcdef>
1906 <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
1907 </funcprototype>
1908 </funcsynopsis>
1909 </para>
1910 <para>
1911 Here is a sample code usage:
1912 <example id="ex-vmaplist1">
1913 <title>Accessing visibility maps #1</title>
1914
1915 <programlisting>
1916 LqrVMap *vmap;
1917 LqrVMapList *list;
1918
1919 list = lqr_vmap_list_start (carver);
1920 while (list) {
1921 vmap = lqr_vmap_list_current (list);
1922 /* ... do something on vmap ... */
1923 list = lqr_vmap_list_next (list);
1924 }
1925 </programlisting>
1926 </example>
1927 </para>
1928 <para>
1929 The maps will always be accessed in the order in which they were dumped.
1930 </para>
1931 <para>
1932 Alternatively, one can apply a function to all the elements of the list, through this function:
1933 <funcsynopsis>
1934 <funcprototype>
1935 <funcdef>LqrRetVal <function>lqr_vmap_list_foreach</function></funcdef>
1936 <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
1937 <paramdef>LqrVMapFunc <parameter>func</parameter></paramdef>
1938 <paramdef>gpointer <parameter>data</parameter></paramdef>
1939 </funcprototype>
1940 </funcsynopsis>
1941 </para>
1942 <para>
1943 To use this second method, you'll need to define a function first, as in this sample code:
1944 <example id="ex-vmaplist2">
1945 <title>Accessing visibility maps #2</title>
1946 <programlisting>
1947 LqrRetVal my_func (LqrVMap vmap, gpointer data)
1948 {
1949 /* ... do something on vmap ... */
1950 return LQR_OK;
1951 }
1952
1953 LqrVMapList *list;
1954
1955 list = lqr_vmap_list_start (carver);
1956 lqr_vmap_list_foreach (list, my_func, NULL);
1957 </programlisting>
1958 </example>
1959 </para>
1960 <para>
1961 In the above example, no data is actually passed on to the function.
1962 </para>
1963 <note>
1964 <para>
1965 In actual code the call to <function>lqr_vmap_list_foreach</function> should be protected to
1966 test its return value, which is &err_ok; if all <function>my_func</function> calls have been
1967 successful, or it will hold the first non-successful return value from
1968 <function>my_func</function>.
1969 </para>
1970 </note>
1971 </sect2>
1972
1973 <sect2 id="vmaps-objs">
1974 <title>The visibility map objects</title>
1975
1976 <para>
1977 The &vmap_obj; objects contain an int buffer with the actual map data (plain array, ordered by row),
1978 plus all the information needed to be able to recover it from scratch.
1979 </para>
1980 <para>
1981 The information can be extracted with these functions:
1982 <programlisting>
1983 gint* <function>lqr_vmap_get_data</function> (&vmap_obj;* <parameter>vmap</parameter>);
1984 gint <function>lqr_vmap_get_width</function> (&vmap_obj;* <parameter>vmap</parameter>);
1985 gint <function>lqr_vmap_get_height</function> (&vmap_obj;* <parameter>vmap</parameter>);
1986 gint <function>lqr_vmap_get_orientation</function> (&vmap_obj;* <parameter>vmap</parameter>);
1987 gint <function>lqr_vmap_get_depth</function> (&vmap_obj;* <parameter>vmap</parameter>);
1988 </programlisting>
1989 </para>
1990 <para>
1991 The first one returns a pointer to the data buffer.
1992 </para>
1993 <para>
1994 The orientation of the map is 0 if the map is to be used for horizontal rescaling, 1 otherwise.
1995 </para>
1996 <para>
1997 The depth of the map is the maximum amount of rescaling possible with that map, either shrinking or
1998 enlarging.
1999 </para>
2000 <para>
2001 <example id="vmap-data">
2002 <title>Reading visibility maps data</title>
2003 <para>
2004 If we have a &vmap_obj; pointer called <parameter>vmap</parameter>, we could access the
2005 value at <literal>(<symbol>x</symbol>,<symbol>y</symbol>)</literal> by:
2006 </para>
2007 <programlisting>
2008 gint *buffer;
2009 gint width;
2010 gint vis;
2011
2012 buffer = lqr_vmap_get_data (vmap);
2013 width = lqr_vmap_get_width (vmap);
2014 vis = buffer[y * width + x];
2015 </programlisting>
2016 <para>
2017 Uninitialised points will yield <literal><symbol>vis</symbol> = 0</literal>. For
2018 initialised points, <literal><symbol>vis</symbol></literal> will store a positive value between
2019 <literal>1</literal> (least visible points, the first to be carved away or to be duplicated)
2020 and <literal>(&param_depth; + 1)</literal> (most visible points, the last to be carved away
2021 or to be duplicated).
2022 </para>
2023 <para>
2024 If the orientation is 0, the map allows resizing in the whole range form <literal>(&param_w;
2025 - &param_depth;)</literal> to <literal>(&param_w; + &param_depth;)</literal>. If the
2026 orientation is 1, the analogue formula holds with &param_h; in place of &param_w;.
2027 </para>
2028 </example>
2029 </para>
2030 </sect2>
2031
2032 <sect2 id="import-vmap">
2033 <title>Importing a visibility map in a carver</title>
2034
2035 <para>
2036 Having an &vmap_obj; object, one can load it in an &carv_obj; simply by calling this function:
2037 <funcsynopsis>
2038 <funcprototype>
2039 <funcdef>LqrRetVal <function>lqr_vmap_load</function></funcdef>
2040 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
2041 <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
2042 </funcprototype>
2043 </funcsynopsis>
2044 </para>
2045 <para>
2046 The carver must not to be initialised, neither before nor after invoking this function.
2047 </para>
2048 <note>
2049 <para>
2050 This implies that the map cannot be updated, and that it will only be possible to resize the
2051 carver by an amount &param_depth; along the orientation given by
2052 <function>lqr_vmap_orientation</function>. The enlargment step is also set to its maximum, 2.0.
2053 Invoking <function>lqr_carver_resize</function> with an out-of-bounds argument results in a
2054 <errortype>fatal</errortype> error (i.e. it returns &err_err;).
2055 </para>
2056 </note>
2057 <note>
2058 <para>
2059 Do not attach other carvers after you have loaded a visibility map (see also the
2060 <link linkend="attach-images">Attaching extra images</link> section).
2061 </para>
2062 </note>
2063 </sect2>
2064
2065 <sect2 id="save-load-vmaps">
2066 <title>Saving and loading visibility maps to/from files</title>
2067
2068 <para>
2069 The library does not include methods to load/save visibility maps to/from files. However, a way to
2070 do so is shown in the demo program `<application>liquidrescale</application>' in the
2071 `<filename>examples</filename>' directory.
2072 </para>
2073 </sect2>
2074 </sect1>
2075
2076 <sect1 id="attach-images">
2077 <title>Attaching extra images</title>
2078
2079 <sect2 id="attach-carver">
2080 <title>Attaching a carver</title>
2081
2082 <para>
2083 Given an &carv_obj; object, it is possible to attach an arbitrary number of extra carvers to it:
2084 these will passively undergo the same carving process as the root carver. In order for this to be
2085 possible, the carvers must be all of the same size.
2086 </para>
2087 <para>
2088 The function to use is simply:
2089 <funcsynopsis>
2090 <funcprototype>
2091 <funcdef>LqrRetVal <function>lqr_carver_attach</function></funcdef>
2092 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
2093 <paramdef>LqrCarver* <parameter>aux</parameter></paramdef>
2094 </funcprototype>
2095 </funcsynopsis>
2096 </para>
2097 <para>
2098 This attaches <parameter>aux</parameter> to <parameter>carver</parameter>.
2099 </para>
2100 <para>
2101 It is not necessary that the parent &carv_obj; is activated. In fact, a carver can be attached to a
2102 carver which is itself attached to another one.
2103 </para>
2104 <para>
2105 Needless to say, no resizing operation should be done directly on an &carv_obj; once it has been
2106 attached to another &carv_obj;, and neither should the cancel method be invoked directly on them.
2107 </para>
2108 <important>
2109 <para>
2110 The carvers always have to be attached <emphasis>before</emphasis> loading visibility maps.
2111 </para>
2112 </important>
2113 </sect2>
2114
2115 <sect2 id="access-attached">
2116 <title>Accessing attached carvers</title>
2117
2118 <para>
2119 Attached carvers can be read-out in the same way as their parents. There are however also methods
2120 to span all them, in a way very similar to that in which internally dumped &vmap_obj;'s are
2121 accessed, but &vmapl_obj; objects are substitued in this case by &carvl_obj; objects.
2122 </para>
2123 <para>
2124 First, the starting point of the list has to be retreived through:
2125 <funcsynopsis>
2126 <funcprototype>
2127 <funcdef>LqrCarverList* <function>lqr_carver_list_start</function></funcdef>
2128 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
2129 </funcprototype>
2130 </funcsynopsis>
2131 </para>
2132 <para>
2133 Then, one can iterate through the attached carvers by using these two functions:
2134 <funcsynopsis>
2135 <funcprototype>
2136 <funcdef>LqrCarver* <function>lqr_carver_list_current</function></funcdef>
2137 <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
2138 </funcprototype>
2139 </funcsynopsis>
2140 <funcsynopsis>
2141 <funcprototype>
2142 <funcdef>LqrCarverList* <function>lqr_carver_list_next</function></funcdef>
2143 <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
2144 </funcprototype>
2145 </funcsynopsis>
2146 </para>
2147 <para>
2148 Here is a sample code usage:
2149 <example id="ex-attach-list1">
2150 <title>Accessing attached carvers #1</title>
2151 <programlisting>
2152 LqrCarver *aux;
2153 LqrCarverList *list;
2154
2155 list = lqr_carver_list_start (carver);
2156 while (list) {
2157 aux = lqr_carver_list_current (list);
2158 /* ... do something on aux ... */
2159 list = lqr_carver_list_next (list);
2160 }
2161 </programlisting>
2162 </example>
2163 </para>
2164 <para>
2165 The carvers will always be accessed in the order in which they were attached.
2166 </para>
2167 <para>
2168 Alternatively, one can apply a function to all the elements of the list (and recursively to all the
2169 elements of their attached lists, if there are any), through this function:
2170 <funcsynopsis>
2171 <funcprototype>
2172 <funcdef>LqrRetVal <function>lqr_carver_list_foreach_recursive</function></funcdef>
2173 <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
2174 <paramdef>LqrCarverFunc <parameter>func</parameter></paramdef>
2175 <paramdef>LqrDataTok <parameter>data</parameter></paramdef>
2176 </funcprototype>
2177 </funcsynopsis>
2178 </para>
2179 <para>
2180 To use this second method, you'll need to define a function first, as in the following sample code:
2181 <example id="ex-attach-list2">
2182 <title>Accessing attached carvers #2</title>
2183 <programlisting>
2184 LqrRetVal my_func (LqrCarver *aux, LqrDataTok data)
2185 {
2186 /* ... do something on aux ... */
2187 return LQR_OK;
2188 }
2189
2190 LqrCarverList *list;
2191 LqrDataTok data_tok;
2192
2193 list = lqr_carver_list_start (carver);
2194 data_tok->data = NULL;
2195 lqr_carver_list_foreach_recursive (list, my_func, data_tok);
2196 </programlisting>
2197 </example>
2198 </para>
2199 <para>
2200 The data to be passed on to the LqrCarverFunc is of type <structname>LqrDataTok</structname>. This
2201 is defined as a union, with the following fields:
2202 <itemizedlist>
2203 <listitem>
2204 <para>&carv_obj;* <structfield>carver</structfield></para>
2205 </listitem>
2206 <listitem>
2207 <para><type>gint</type> <structfield>integer</structfield></para>
2208 </listitem>
2209 <listitem>
2210 <para><type>gpointer</type> <structfield>data</structfield></para>
2211 </listitem>
2212 </itemizedlist>
2213 </para>
2214 <para>
2215 In the above example, no data is actually passed on to the function.
2216 </para>
2217 <note>
2218 <para>
2219 In actual code, the call to <function>lqr_carver_list_foreach_recursive</function> should be
2220 protected to test its return value, which is &err_ok; if all my_func calls have been successful
2221 (or if the list is empty), or it will hold the first non-successful return value from
2222 <function>my_func</function>.
2223 </para>
2224 </note>
2225 </sect2>
2226 </sect1>
2227
2228 <sect1 id="progress">
2229 <title>Progress indicators</title>
2230
2231 <para>
2232 By default, the resizing is performed silently. However, it is possible to define progress report
2233 functions, to receive feedback while the resizing is in progress. This is done through the &prog_obj;
2234 objects.
2235 </para>
2236 <sect2 id="progress-init">
2237 <title>Creating and attaching a progress report object</title>
2238 <para>
2239 A &prog_obj; object is created through the function:
2240 <funcsynopsis>
2241 <funcprototype>
2242 <funcdef>LqrProgress* <function>lqr_progress_new</function></funcdef>
2243 <void></void>
2244 </funcprototype>
2245 </funcsynopsis>
2246 and can be associated to an &carv_obj; object through this function:
2247 <funcsynopsis>
2248 <funcprototype>
2249 <funcdef>void <function>lqr_carver_set_progress</function></funcdef>
2250 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
2251 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
2252 </funcprototype>
2253 </funcsynopsis>
2254 </para>
2255 </sect2>
2256
2257 <sect2 id="progress-set-up">
2258 <title>Setting up progress hooks</title>
2259 <para>
2260 Newly created progress objects are inactive, and need to be set up.
2261 </para>
2262 <para>
2263 First, hook functions have to be set, which specify the action to take as the rescaling process
2264 starts, progresses, and ends, by using the functions:
2265 <programlisting>
2266 LqrRetVal <function>lqr_progress_set_init</function> (&prog_obj; * <parameter>p</parameter>, LqrProgressFuncInit <parameter>init_func</parameter>)
2267 LqrRetVal <function>lqr_progress_set_update</function> (&prog_obj; * <parameter>p</parameter>, LqrProgressFuncUpdate <parameter>update_func</parameter>)
2268 LqrRetVal <function>lqr_progress_set_end</function> (&prog_obj; * <parameter>p</parameter>, LqrProgressFuncEnd <parameter>end_func</parameter>)
2269 </programlisting>
2270 as in this sample piece of code:
2271 <example id="ex-set-progress">
2272 <title>Setting progress hooks</title>
2273 <programlisting>
2274 LqrProgress *p;
2275
2276 p = lqr_progress_new();
2277 lqr_progress_set_init (p, my_init);
2278 lqr_progress_set_update (p, my_update);
2279 lqr_progress_set_end (p, my_end);
2280 </programlisting>
2281 </example>
2282 </para>
2283 <para>
2284 The above example requires that the hook functions <function>my_init</function>,
2285 <function>my_update</function> and <function>my_end</function> are defined as in the following
2286 sample declarations:
2287 <example id="ex-hook-decl">
2288 <title>Progress hooks declaration</title>
2289 <programlisting>
2290 LqrRetVal my_init (const gchar *init_message);
2291 LqrRetVal my_update (gdouble percentage);
2292 LqrRetVal my_end (const gchar *end_message);
2293 </programlisting>
2294 </example>
2295 </para>
2296 </sect2>
2297
2298 <sect2 id="progress-messages">
2299 <title>Initial and ending progress messages</title>
2300 <para>
2301 The init and end hooks will be called at the beginning and at the end of each rescaling operation by
2302 function <function>lqr_carver_resize</function>. The messages that will be passed to these hooks
2303 will change, depending if the resizing is occurring in the horizontal or in the vertical direction.
2304 The defaults for newly created &prog_obj; objects are:
2305 <table id="progress-mess-def">
2306 <title>Default progress messages</title>
2307 <tgroup cols="3">
2308 <thead>
2309 <row>
2310 <entry></entry>
2311 <entry>init</entry>
2312 <entry>end</entry>
2313 </row>
2314 </thead>
2315 <tbody>
2316 <row>
2317 <entry>horizontal</entry>
2318 <entry>&prog_init_w_mess;</entry>
2319 <entry>&prog_end_w_mess;</entry>
2320 </row>
2321 <row>
2322 <entry>vertical</entry>
2323 <entry>&prog_init_h_mess;</entry>
2324 <entry>&prog_end_h_mess;</entry>
2325 </row>
2326 </tbody>
2327 </tgroup>
2328 </table>
2329 These can be changed using these functions:
2330 <programlisting>
2331 LqrRetVal <function>lqr_progress_set_init_width_message</function> (&prog_obj; *<parameter>p</parameter>, const gchar * <parameter>message</parameter>)
2332 LqrRetVal <function>lqr_progress_set_init_height_message</function> (&prog_obj; *<parameter>p</parameter>, const gchar * <parameter>message</parameter>)
2333 LqrRetVal <function>lqr_progress_set_end_width_message</function> (&prog_obj; *<parameter>p</parameter>, const gchar * <parameter>message</parameter>)
2334 LqrRetVal <function>lqr_progress_set_end_height_message</function> (&prog_obj; *<parameter>p</parameter>, const gchar * <parameter>message</parameter>)
2335 </programlisting>
2336 </para>
2337 </sect2>
2338
2339 <sect2 id="progress-upd-step">
2340 <title>Progress update step</title>
2341 <para>
2342 The update hook will be called at regular intervals, and it will be passed the completion percentage
2343 as the argument.
2344 </para>
2345 <para>
2346 The update step can be specified through:
2347 <funcsynopsis>
2348 <funcprototype>
2349 <funcdef>LqrRetVal <function>lqr_progress_set_update_step</function></funcdef>
2350 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
2351 <paramdef>gfloat <parameter>update_step</parameter></paramdef>
2352 </funcprototype>
2353 </funcsynopsis>
2354 </para>
2355 <para>
2356 The default step is 0.02 (i.e. 2%).
2357 </para>
2358 </sect2>
2359 </sect1>
2360
2361 <sect1 id="release">
2362 <title>Releasing the memory</title>
2363
2364 <para>
2365 &carv_obj; objects can be destroyed using this function:
2366 <funcsynopsis>
2367 <funcprototype>
2368 <funcdef>void <function>lqr_carver_destroy</function></funcdef>
2369 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
2370 </funcprototype>
2371 </funcsynopsis>
2372 </para>
2373 <para>
2374 This function also destroys any attached object, thus it should never be called on attached carvers.
2375 </para>
2376 <para>
2377 &vmap_obj; objects can be destroyed using this function:
2378 <funcsynopsis>
2379 <funcprototype>
2380 <funcdef>void <function>lqr_vmap_destroy</function></funcdef>
2381 <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
2382 </funcprototype>
2383 </funcsynopsis>
2384 </para>
2385 </sect1>
2386 </chapter>
2387
2388 <chapter id="ref-pages">
2389 <title>LqR library API reference</title>
2390
2391 <sect1 id="ref-const">
2392 <title>Types defined by the library</title>
2393
2394 <refentry id="ref-lqr-ret-val">
2395 <refmeta>
2396 <refentrytitle><type>LqrRetVal</type></refentrytitle>
2397 <manvolnum>3</manvolnum>
2398 </refmeta>
2399
2400 <refnamediv>
2401 <refname>LqrRetVal</refname>
2402 <refpurpose>the return value of many &lqrl; functions</refpurpose>
2403 </refnamediv>
2404
2405 <refsect1>
2406 <title>Description</title>
2407 <para>
2408 The return type of many functions in the &lqrl; is <type>LqrRetVal</type>, which is an
2409 <literal>enum</literal> type that can take these values:
2410 <variablelist>
2411 <varlistentry>
2412 <term>&err_ok;</term>
2413 <listitem>
2414 <para>
2415 everyting OK
2416 </para>
2417 </listitem>
2418 </varlistentry>
2419 <varlistentry>
2420 <term>&err_err;</term>
2421 <listitem>
2422 <para>
2423 generic <errortype>fatal</errortype> error
2424 </para>
2425 </listitem>
2426 </varlistentry>
2427 <varlistentry>
2428 <term>&err_nomem;</term>
2429 <listitem>
2430 <para>
2431 not enough memory
2432 </para>
2433 </listitem>
2434 </varlistentry>
2435 <varlistentry>
2436 <term>&err_cancel;</term>
2437 <listitem>
2438 <para>
2439 action cancelled by the user
2440 </para>
2441 </listitem>
2442 </varlistentry>
2443 </variablelist>
2444 </para>
2445 <para>
2446 The user should handle the error values explicitly at each function call returning this type.
2447 </para>
2448 </refsect1>
2449
2450 <refsect1>
2451 <title>See also</title>
2452 <para>
2453 <simplelist type="inline">
2454 <member><xref linkend="ref-lqr-carver-init"></xref></member>
2455 <member><xref linkend="ref-lqr-carver-cancel"></xref></member>
2456 </simplelist>
2457 </para>
2458 </refsect1>
2459 </refentry>
2460
2461 <refentry id="ref-lqr-col-depth">
2462 <refmeta>
2463 <refentrytitle><type>LqrColDepth</type></refentrytitle>
2464 <manvolnum>3</manvolnum>
2465 </refmeta>
2466
2467 <refnamediv>
2468 <refname>LqrColDepth</refname>
2469 <refpurpose>carver objects colour depth specification</refpurpose>
2470 </refnamediv>
2471
2472 <refsect1>
2473 <title>Description</title>
2474 <para>
2475 The default &carv_obj; object constructor <function>lqr_carver_new</function> uses a colour
2476 depth of 8 bits per channel, and therefore its input must be an array of <type>unsigned
2477 char</type>s. However, the &carv_obj; objects can handle images of grater colour depth, if
2478 they are created with the <function>lqr_carver_new_ext</function> constructor. The possible
2479 colour depths are specified through variables of type <type>LqrColDepth</type>, which is an enum
2480 type; its possible values, and the type of the input buffer associated with them, are:
2481 <variablelist>
2482 <varlistentry>
2483 <term>&col_depth_8i;</term>
2484 <listitem>
2485 <para>
2486 use type <type>guchar</type> (8 bit unsigned integers) - the default
2487 </para>
2488 </listitem>
2489 </varlistentry>
2490 <varlistentry>
2491 <term>&col_depth_16i;</term>
2492 <listitem>
2493 <para>
2494 use type <type>guint16</type> (16 bit unsigned integers)
2495 </para>
2496 </listitem>
2497 </varlistentry>
2498 <varlistentry>
2499 <term>&col_depth_32f;</term>
2500 <listitem>
2501 <para>
2502 use type <type>gfloat</type> (32 bit floating point)
2503 </para>
2504 </listitem>
2505 </varlistentry>
2506 <varlistentry>
2507 <term>&col_depth_64f;</term>
2508 <listitem>
2509 <para>
2510 use type <type>gdouble</type> (64 bit floating point)
2511 </para>
2512 </listitem>
2513 </varlistentry>
2514 </variablelist>
2515 </para>
2516 <para>
2517 These values are also relevant when reading out a &carv_obj; object with the functions
2518 <function>lqr_carver_scan_ext</function> or <function>lqr_carver_scan_line_ext</function>, since
2519 the readout buffer must be cast to the appropriate type to be actually read.
2520 </para>
2521 <para>
2522 The colour depth of an &carv_obj; object can be obtained with the function
2523 <function>lqr_carver_get_col_depth</function>.
2524 </para>
2525 </refsect1>
2526
2527 <refsect1>
2528 <title>See also</title>
2529 <para>
2530 <simplelist type="inline">
2531 <member><xref linkend="ref-lqr-carver-new"></xref></member>
2532 <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
2533 <member><xref linkend="ref-lqr-carver-scan"></xref></member>
2534 <member><xref linkend="ref-lqr-carver-scan-line"></xref></member>
2535 </simplelist>
2536 </para>
2537 </refsect1>
2538 </refentry>
2539
2540 <refentry id="ref-lqr-image-type">
2541 <refmeta>
2542 <refentrytitle><type>LqrImageType</type></refentrytitle>
2543 <manvolnum>3</manvolnum>
2544 </refmeta>
2545
2546 <refnamediv>
2547 <refname>LqrImageType</refname>
2548 <refpurpose>carver objects image type (colour model) specification</refpurpose>
2549 </refnamediv>
2550
2551 <refsect1>
2552 <title>Description</title>
2553 <para>
2554 The &carv_obj; objects use knowledge about the image type they're working on in order to compute
2555 correctly some quantities (e.g. the brightness) for the automatic feature detection. Image types
2556 are set automatically by the constructors, but they can also be specified manually using
2557 quantities of the type <type>LqrImageType</type>, which is an <literal>enum</literal> which can
2558 take these values:
2559 <itemizedlist>
2560 <listitem>&img_type_grey;</listitem>
2561 <listitem>&img_type_greya;</listitem>
2562 <listitem>&img_type_rgb;</listitem>
2563 <listitem>&img_type_rgba;</listitem>
2564 <listitem>&img_type_cmy;</listitem>
2565 <listitem>&img_type_cmyk;</listitem>
2566 <listitem>&img_type_cmyka;</listitem>
2567 <listitem>&img_type_custom;</listitem>
2568 </itemizedlist>
2569 </para>
2570 <para>
2571 Use the function <xref linkend="ref-lqr-carver-set-image-type"></xref> to set the image type of
2572 a carver, and the function <xref linkend="ref-lqr-carver-get-image-type"></xref> to read it out.
2573 </para>
2574 </refsect1>
2575
2576 <refsect1>
2577 <title>See also</title>
2578 <para>
2579 <simplelist type="inline">
2580 <member><xref linkend="ref-lqr-carver-new"></xref></member>
2581 <member><xref linkend="ref-lqr-carver-set-image-type"></xref></member>
2582 <member><xref linkend="ref-lqr-carver-get-image-type"></xref></member>
2583 </simplelist>
2584 </para>
2585 </refsect1>
2586 </refentry>
2587 </sect1>
2588
2589 <sect1 id="ref-carve">
2590 <title>Carver objects</title>
2591
2592 <refentry id="ref-lqr-carver-new">
2593 <refmeta>
2594 <refentrytitle><function>lqr_carver_new</function></refentrytitle>
2595 <manvolnum>3</manvolnum>
2596 </refmeta>
2597
2598 <refnamediv>
2599 <refname>lqr_carver_new</refname>
2600 <refname>lqr_carver_new_ext</refname>
2601 <refpurpose>the &carv_obj; object constructors</refpurpose>
2602 </refnamediv>
2603
2604 <refsynopsisdiv>
2605 <funcsynopsis>
2606 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
2607 <funcprototype>
2608 <funcdef>LqrCarver* <function>lqr_carver_new</function></funcdef>
2609 <paramdef>guchar* <parameter>buffer</parameter></paramdef>
2610 <paramdef>gint <parameter>width</parameter></paramdef>
2611 <paramdef>gint <parameter>height</parameter></paramdef>
2612 <paramdef>gint <parameter>channels</parameter></paramdef>
2613 </funcprototype>
2614 <funcprototype>
2615 <funcdef>LqrCarver* <function>lqr_carver_new_ext</function></funcdef>
2616 <paramdef>void* <parameter>buffer</parameter></paramdef>
2617 <paramdef>gint <parameter>width</parameter></paramdef>
2618 <paramdef>gint <parameter>height</parameter></paramdef>
2619 <paramdef>gint <parameter>channels</parameter></paramdef>
2620 <paramdef>LqrColDepth <parameter>colour_depth</parameter></paramdef>
2621 </funcprototype>
2622 </funcsynopsis>
2623 </refsynopsisdiv>
2624
2625 <refsect1>
2626 <title>Description</title>
2627 <para>
2628 The functions <function>lqr_carver_new</function> and <function>lqr_carver_new_ext</function>
2629 create a new &carv_obj; object from an image of size &param_w; * &param_h; with &param_channels;
2630 colour channels.
2631 </para>
2632 <para>
2633 The image must be stored in <parameter>buffer</parameter> as a plain array of unsigned chars
2634 (for <function>lqr_carver_new</function>) or the appropriate type cast to void (for
2635 <function>lqr_carver_new_ext</function>), ordered by row, then by column, then by colour
2636 channel.
2637 </para>
2638 <para>
2639 In the extended constructor <function>lqr_carver_new_ext</function>, the additional parameter
2640 <parameter>colour_depth</parameter> is required to specify the colour depth of the buffer (see
2641 <xref linkend="ref-lqr-col-depth"></xref> for more information).
2642 </para>
2643 <para>
2644 After calling the function, the buffer will be owned by the &carv_obj; object and must not be
2645 accessed any more, unless you subsequently call the <xref
2646 linkend="ref-lqr-carver-set-preserve-input-image"></xref> function.
2647 </para>
2648 <para>
2649 The image type is et automatically from the value of <parameter>channels</parameter> according
2650 to this table:
2651 <table id="ref-def-image-types">
2652 <title>Image types assigned by default</title>
2653 <tgroup cols="2">
2654 <thead>
2655 <row>
2656 <entry>channels</entry>
2657 <entry>type</entry>
2658 </row>
2659 </thead>
2660 <tbody>
2661 <row>
2662 <entry>1</entry>
2663 <entry>&img_type_grey;</entry>
2664 </row>
2665 <row>
2666 <entry>2</entry>
2667 <entry>&img_type_greya;</entry>
2668 </row>
2669 <row>
2670 <entry>3</entry>
2671 <entry>&img_type_rgb;</entry>
2672 </row>
2673 <row>
2674 <entry>4</entry>
2675 <entry>&img_type_rgba;</entry>
2676 </row>
2677 <row>
2678 <entry>5</entry>
2679 <entry>&img_type_cmyka;</entry>
2680 </row>
2681 <row>
2682 <entry>&gt;5</entry>
2683 <entry>&img_type_custom;</entry>
2684 </row>
2685 </tbody>
2686 </tgroup>
2687 </table>
2688 </para>
2689 </refsect1>
2690 <refsect1>
2691 <title>Return value</title>
2692 <para>
2693 The return value is the address of the newly created &carv_obj; object, or &ret_null; in case of
2694 failure (insufficient memory).
2695 </para>
2696 </refsect1>
2697
2698 <refsect1>
2699 <title>See also</title>
2700 <para>
2701 <simplelist type="inline">
2702 <member><xref linkend="ref-lqr-col-depth"></xref></member>
2703 <member><xref linkend="ref-lqr-image-type"></xref></member>
2704 <member><xref linkend="ref-lqr-carver-destroy"></xref></member>
2705 <member><xref linkend="ref-lqr-carver-init"></xref></member>
2706 <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
2707 </simplelist>
2708 </para>
2709 </refsect1>
2710 </refentry>
2711
2712 <refentry id="ref-lqr-carver-destroy">
2713 <refmeta>
2714 <refentrytitle><function>lqr_carver_destroy</function></refentrytitle>
2715 <manvolnum>3</manvolnum>
2716 </refmeta>
2717
2718 <refnamediv>
2719 <refname>lqr_carver_destroy</refname>
2720 <refpurpose>the &carv_obj; object destructor</refpurpose>
2721 </refnamediv>
2722
2723 <refsynopsisdiv>
2724 <funcsynopsis>
2725 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
2726 <funcprototype>
2727 <funcdef>void <function>lqr_carver_destroy</function></funcdef>
2728 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
2729 </funcprototype>
2730 </funcsynopsis>
2731 </refsynopsisdiv>
2732
2733 <refsect1>
2734 <title>Description</title>
2735 <para>
2736 The function <function>lqr_carver_destroy</function> destroys the &carv_obj; object pointed to
2737 by <parameter>carver</parameter>, and all of its attched components (visibility maps and
2738 attached carvers). It must never be invoked over a carver which is attached to another one.
2739 </para>
2740 <para>
2741 This function will not release the memory buffer passed to
2742 <xref linkend="ref-lqr-carver-new"></xref> if it was protected by calling
2743 <xref linkend="ref-lqr-carver-set-preserve-input-image"></xref>.
2744 </para>
2745 </refsect1>
2746
2747 <refsect1>
2748 <title>See also</title>
2749 <para>
2750 <simplelist type="inline">
2751 <member><xref linkend="ref-lqr-carver-new"></xref></member>
2752 <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
2753 <member><xref linkend="ref-lqr-vmap-destroy"></xref></member>
2754 </simplelist>
2755 </para>
2756 </refsect1>
2757 </refentry>
2758
2759 <refentry id="ref-lqr-carver-init">
2760 <refmeta>
2761 <refentrytitle><function>lqr_carver_init</function></refentrytitle>
2762 <manvolnum>3</manvolnum>
2763 </refmeta>
2764
2765 <refnamediv>
2766 <refname>lqr_carver_init</refname>
2767 <refpurpose>activates an &carv_obj; object</refpurpose>
2768 </refnamediv>
2769
2770 <refsynopsisdiv>
2771 <funcsynopsis>
2772 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
2773 <funcprototype>
2774 <funcdef>LqrRetVal <function>lqr_carver_init</function></funcdef>
2775 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
2776 <paramdef>gint <parameter>delta_x</parameter></paramdef>
2777 <paramdef>gfloat <parameter>rigidity</parameter></paramdef>
2778 </funcprototype>
2779 </funcsynopsis>
2780 </refsynopsisdiv>
2781
2782 <refsect1>
2783 <title>Description</title>
2784 <para>
2785 The function <function>lqr_carver_init</function> initialises the &carv_obj; pointed to by
2786 <parameter>carver</parameter>, so that it can compute the visibility maps as needed upon calls
2787 of <function>lqr_carver_resize</function>.
2788 </para>
2789 <para>
2790 The parameter <parameter>delta_x</parameter> controls the maximum transversal step a seam can
2791 make. A value of 0 means straight seams. Normally, it is set to 1.
2792 </para>
2793 <para>
2794 The parameter <parameter>rigidity</parameter> can be used to add a negative bias to non-straight
2795 seams, and it is normally set to 0.
2796 </para>
2797 <para>
2798 Visibility maps must not be loaded with the function <function>lqr_vmap_load</function> when
2799 using this function, neither before nor after invoking it.
2800 </para>
2801 </refsect1>
2802
2803 <refsect1>
2804 <title>Return value</title>
2805 <para>
2806 The return value follows the &lqrl; signalling system.
2807 </para>
2808 </refsect1>
2809
2810 <refsect1>
2811 <title>See also</title>
2812 <para>
2813 <simplelist type="inline">
2814 <member><xref linkend="ref-lqr-ret-val"></xref></member>
2815 <member><xref linkend="ref-lqr-carver-new"></xref></member>
2816 <member><xref linkend="ref-lqr-vmap-load"></xref></member>
2817 <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
2818 </simplelist>
2819 </para>
2820 </refsect1>
2821 </refentry>
2822
2823 <refentry id="ref-lqr-carver-set-image-type">
2824 <refmeta>
2825 <refentrytitle><function>lqr_carver_set_image_type</function></refentrytitle>
2826 <manvolnum>3</manvolnum>
2827 </refmeta>
2828
2829 <refnamediv>
2830 <refname>lqr_carver_set_image_type</refname>
2831 <refpurpose>sets the image type of an &carv_obj; object</refpurpose>
2832 </refnamediv>
2833
2834 <refsynopsisdiv>
2835 <funcsynopsis>
2836 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
2837 <funcprototype>
2838 <funcdef>LqrRetVal <function>lqr_carver_set_image_type</function></funcdef>
2839 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
2840 <paramdef>LqrImageType <parameter>image_type</parameter></paramdef>
2841 </funcprototype>
2842 </funcsynopsis>
2843 </refsynopsisdiv>
2844
2845 <refsect1>
2846 <title>Description</title>
2847 <para>
2848 The function <function>lqr_carver_set_image_type</function> sets the image type of the
2849 &carv_obj; pointed to by <parameter>carver</parameter> to <parameter>image_type</parameter>.
2850 </para>
2851 <para>
2852 If <parameter>image_type</parameter> is equal to &img_type_custom;, it is assumed that there are
2853 no alpha or black channels. You can set those independently using
2854 <xref linkend="ref-lqr-carver-set-alpha-channel"></xref> and
2855 <xref linkend="ref-lqr-carver-set-black-channel"></xref>.
2856 </para>
2857 </refsect1>
2858
2859 <refsect1>
2860 <title>Return value</title>
2861 <para>
2862 The return value follows the &lqrl; signalling system.
2863 </para>
2864 </refsect1>
2865
2866 <refsect1>
2867 <title>See also</title>
2868 <para>
2869 <simplelist type="inline">
2870 <member><xref linkend="ref-lqr-image-type"></xref></member>
2871 <member><xref linkend="ref-lqr-carver-new"></xref></member>
2872 <member><xref linkend="ref-lqr-carver-set-alpha-channel"></xref></member>
2873 <member><xref linkend="ref-lqr-carver-set-black-channel"></xref></member>
2874 <member><xref linkend="ref-lqr-carver-get-image-type"></xref></member>
2875 </simplelist>
2876 </para>
2877 </refsect1>
2878 </refentry>
2879
2880 <refentry id="ref-lqr-carver-set-alpha-channel">
2881 <refmeta>
2882 <refentrytitle><function>lqr_carver_set_alpha_channel</function></refentrytitle>
2883 <manvolnum>3</manvolnum>
2884 </refmeta>
2885
2886 <refnamediv>
2887 <refname>lqr_carver_set_alpha_channel</refname>
2888 <refpurpose>sets the alpha channel index in a &carv_obj; object</refpurpose>
2889 </refnamediv>
2890
2891 <refsynopsisdiv>
2892 <funcsynopsis>
2893 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
2894 <funcprototype>
2895 <funcdef>LqrRetVal <function>lqr_carver_set_alpha_channel</function></funcdef>
2896 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
2897 <paramdef> gint <parameter>channel_index</parameter></paramdef>
2898 </funcprototype>
2899 </funcsynopsis>
2900 </refsynopsisdiv>
2901
2902 <refsect1>
2903 <title>Description</title>
2904 <para>
2905 The function <function>lqr_carver_set_alpha_channel</function> sets the alpha channel index of
2906 the image stored in the &carv_obj; pointed to by <parameter>carver</parameter> to
2907 <parameter>channel_index</parameter> (between <literal>0</literal> and <literal>channels -
2908 1</literal>, where <literal>channels</literal> is the number of colour channels of the
2909 <parameter>carver</parameter>).
2910 </para>
2911 <para>
2912 Use a negative value for <parameter>cahnnel_index</parameter> to specify that no alpha channel
2913 is present.
2914 </para>
2915 <para>
2916 If the specified channel coincides with the current value of the black channel, the black
2917 channel is unset.
2918 </para>
2919 <para>
2920 Calling this function sets the image time of the <parameter>carver</parameter> to
2921 &img_type_custom;.
2922 </para>
2923 </refsect1>
2924
2925 <refsect1>
2926 <title>Return value</title>
2927 <para>
2928 The return value follows the &lqrl; signalling system.
2929 </para>
2930 </refsect1>
2931
2932 <refsect1>
2933 <title>See also</title>
2934 <para>
2935 <simplelist type="inline">
2936 <member><xref linkend="ref-lqr-image-type"></xref></member>
2937 <member><xref linkend="ref-lqr-carver-new"></xref></member>
2938 <member><xref linkend="ref-lqr-carver-set-image-type"></xref></member>
2939 <member><xref linkend="ref-lqr-carver-set-black-channel"></xref></member>
2940 <member><xref linkend="ref-lqr-carver-get-image-type"></xref></member>
2941 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
2942 </simplelist>
2943 </para>
2944 </refsect1>
2945 </refentry>
2946
2947 <refentry id="ref-lqr-carver-set-black-channel">
2948 <refmeta>
2949 <refentrytitle><function>lqr_carver_set_black_channel</function></refentrytitle>
2950 <manvolnum>3</manvolnum>
2951 </refmeta>
2952
2953 <refnamediv>
2954 <refname>lqr_carver_set_black_channel</refname>
2955 <refpurpose>sets the black channel index in a &carv_obj; object</refpurpose>
2956 </refnamediv>
2957
2958 <refsynopsisdiv>
2959 <funcsynopsis>
2960 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
2961 <funcprototype>
2962 <funcdef>LqrRetVal <function>lqr_carver_set_black_channel</function></funcdef>
2963 <paramdef> LqrCarver * <parameter>carver</parameter></paramdef>
2964 <paramdef> gint <parameter>channel_index</parameter></paramdef>
2965 </funcprototype>
2966 </funcsynopsis>
2967 </refsynopsisdiv>
2968
2969 <refsect1>
2970 <title>Description</title>
2971 <para>
2972 The function <function>lqr_carver_set_black_channel</function> sets the black channel index of
2973 the image stored in the &carv_obj; pointed to by <parameter>carver</parameter> to
2974 <parameter>channel_index</parameter> (between <literal>0</literal> and <literal>channels -
2975 1</literal>, where <literal>channels</literal> is the number of colour channels of the
2976 <parameter>carver</parameter>).
2977 </para>
2978 <para>
2979 Use a negative value for <parameter>cahnnel_index</parameter> to specify that no black channel
2980 is present.
2981 </para>
2982 <para>
2983 If the specified channel coincides with the current value of the alpha channel, the alpha
2984 channel is unset.
2985 </para>
2986 <para>
2987 Calling this function sets the image time of the <parameter>carver</parameter> to
2988 &img_type_custom;. Furthermore, the image color model will be assumed to be subtractive by the
2989 function <xref linkend="ref-lqr-rwindow-read"></xref> when it computes the brightness or the luma.
2990 </para>
2991 </refsect1>
2992
2993 <refsect1>
2994 <title>Return value</title>
2995 <para>
2996 The return value follows the &lqrl; signalling system.
2997 </para>
2998 </refsect1>
2999
3000 <refsect1>
3001 <title>See also</title>
3002 <para>
3003 <simplelist type="inline">
3004 <member><xref linkend="ref-lqr-image-type"></xref></member>
3005 <member><xref linkend="ref-lqr-carver-new"></xref></member>
3006 <member><xref linkend="ref-lqr-carver-set-image-type"></xref></member>
3007 <member><xref linkend="ref-lqr-carver-set-alpha-channel"></xref></member>
3008 <member><xref linkend="ref-lqr-carver-get-image-type"></xref></member>
3009 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
3010 </simplelist>
3011 </para>
3012 </refsect1>
3013 </refentry>
3014
3015
3016
3017 <refentry id="ref-lqr-carver-resize">
3018 <refmeta>
3019 <refentrytitle><function>lqr_carver_resize</function></refentrytitle>
3020 <manvolnum>3</manvolnum>
3021 </refmeta>
3022
3023 <refnamediv>
3024 <refname>lqr_carver_resize</refname>
3025 <refpurpose>liquid rescale a &carv_obj; object</refpurpose>
3026 </refnamediv>
3027
3028 <refsynopsisdiv>
3029 <funcsynopsis>
3030 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3031 <funcprototype>
3032 <funcdef>LqrRetVal <function>lqr_carver_resize</function></funcdef>
3033 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3034 <paramdef>gint <parameter>new_width</parameter></paramdef>
3035 <paramdef>gint <parameter>new_height</parameter></paramdef>
3036 </funcprototype>
3037 </funcsynopsis>
3038 </refsynopsisdiv>
3039
3040 <refsect1>
3041 <title>Description</title>
3042 <para>
3043 The function <function>lqr_carver_resize</function> performs the liquid rescaling over the
3044 &carv_obj; object pointed to by <parameter>carver</parameter>. If a visibility map was loaded
3045 through the function <function>lqr_vmap_load</function>, and the carver was not initialised, the
3046 resizing operations must be limited to the direction and the sizes included in the loaded map.
3047 If the carver was initialised through the function <function>lqr_carver_init</function>, there
3048 are no limitations to the final size.
3049 </para>
3050 <para>
3051 The resizing function can be called multiple times, and it will decide automatically whether the
3052 computation of the visibility map is necessary or not. In case it isn't, the function returns
3053 almost immediately, otherwise operations will proceed following the order given through the
3054 function <function>lqr_carver_set_resize_order</function>. Currently, on-the-fly rescaling
3055 without computation is only possible for a single direction at a time.
3056 </para>
3057 <para>
3058 If the new size (in one direction or in both) is greater than or equal to the original size
3059 multiplied by the enlargement step of the <parameter>carver</parameter> object (as obtained
3060 through <xref linkend="ref-lqr-carver-get-enl-step"></xref>), the rescaling will be performed in
3061 multiple steps. At each step, the original size stored internally is reset to the new value;
3062 therefore, each step in the process can be bigger then the previous one.
3063 </para>
3064 <para>
3065 Whenever the resizing dirction changes (this may happen in a single call of the rescaling
3066 function or through multiple calls), or if performing a multiple steps enlargement as per the
3067 previous paragraph, the visibility map computed during the first direction rescale is dropped to
3068 make place for the one for the second (and the original size of the image is reset to the
3069 current value). These visibility maps can be saved by using the
3070 <function>lqr_carver_set_vmap_dump</function> function, for inspection or future use.
3071 </para>
3072 </refsect1>
3073
3074 <refsect1>
3075 <title>Return value</title>
3076 <para>
3077 The return value follows the &lqrl; signalling system. It returns an error if trying to exceed
3078 the limitations of a loaded visibility map, or if passed a negative or null size.
3079 </para>
3080 </refsect1>
3081
3082 <refsect1>
3083 <title>See also</title>
3084 <para>
3085 <simplelist type="inline">
3086 <member><xref linkend="ref-lqr-ret-val"></xref></member>
3087 <member><xref linkend="ref-lqr-carver-init"></xref></member>
3088 <member><xref linkend="ref-lqr-carver-flatten"></xref></member>
3089 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
3090 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
3091 <member><xref linkend="ref-lqr-carver-cancel"></xref></member>
3092 <member><xref linkend="ref-lqr-vmap-load"></xref></member>
3093 </simplelist>
3094 </para>
3095 </refsect1>
3096 </refentry>
3097
3098 <refentry id="ref-lqr-carver-flatten">
3099 <refmeta>
3100 <refentrytitle><function>lqr_carver_flatten</function></refentrytitle>
3101 <manvolnum>3</manvolnum>
3102 </refmeta>
3103
3104 <refnamediv>
3105 <refname>lqr_carver_flatten</refname>
3106 <refpurpose>flatten a &carv_obj; object</refpurpose>
3107 </refnamediv>
3108
3109 <refsynopsisdiv>
3110 <funcsynopsis>
3111 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3112 <funcprototype>
3113 <funcdef>LqrRetVal <function>lqr_carver_flatten</function></funcdef>
3114 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3115 </funcprototype>
3116 </funcsynopsis>
3117 </refsynopsisdiv>
3118
3119 <refsect1>
3120 <title>Description</title>
3121 <para>
3122 The function <function>lqr_carver_flatten</function> can be used to discard the visibility map
3123 information and flatten the multi-size image contained in the &carv_obj; object pointed to by
3124 <parameter>carver</parameter> to its current state.
3125 </para>
3126 <para>
3127 It will also reset the internally stored original width and height, as if the image was just
3128 loaded in the &carv_obj; object.
3129 </para>
3130 <para>
3131 This function must only be invoked over initialised &carv_obj; objects.
3132 </para>
3133 <para>
3134 This function is called internally each time the rescaling direction changes, or at each new
3135 step in a multiple-step enlargement, but, when calling it manually, the discarded visibility map
3136 will not be dumped automatically by it; use the functions
3137 <xref linkend="ref-lqr-vmap-dump"></xref> or <xref linkend="ref-lqr-vmap-internal-dump"></xref>
3138 in order to save it before invoking this function.
3139 </para>
3140 </refsect1>
3141
3142 <refsect1>
3143 <title>Return value</title>
3144 <para>
3145 The return value follows the &lqrl; signalling system. Errors can occur for non-initialised
3146 &carv_obj; objects or in case of insufficient memory.
3147 </para>
3148 </refsect1>
3149
3150 <refsect1>
3151 <title>See also</title>
3152 <para>
3153 <simplelist type="inline">
3154 <member><xref linkend="ref-lqr-ret-val"></xref></member>
3155 <member><xref linkend="ref-lqr-carver-init"></xref></member>
3156 <member><xref linkend="ref-lqr-carver-resize"></xref></member>
3157 <member><xref linkend="ref-lqr-carver-cancel"></xref></member>
3158 </simplelist>
3159 </para>
3160 </refsect1>
3161 </refentry>
3162
3163 <refentry id="ref-lqr-carver-cancel">
3164 <refmeta>
3165 <refentrytitle><function>lqr_carver_cancel</function></refentrytitle>
3166 <manvolnum>3</manvolnum>
3167 </refmeta>
3168
3169 <refnamediv>
3170 <refname>lqr_carver_cancel</refname>
3171 <refpurpose>cancel ongoing operations on a &carv_obj; object</refpurpose>
3172 </refnamediv>
3173
3174 <refsynopsisdiv>
3175 <funcsynopsis>
3176 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3177 <funcprototype>
3178 <funcdef>LqrRetVal <function>lqr_carver_cancel</function></funcdef>
3179 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3180 </funcprototype>
3181 </funcsynopsis>
3182 </refsynopsisdiv>
3183
3184 <refsect1>
3185 <title>Description</title>
3186 <para>
3187 The function <function>lqr_carver_cancel</function> can be used to cancel an ongoing operation
3188 which is currently being performed on the the &carv_obj; object pointed to by
3189 <parameter>carver</parameter>. It must be used asynchronouly, from within an independent thread.
3190 </para>
3191 <para>
3192 If an operation is in fact cancelled by this function, the function which was performing the
3193 operation will return the value &err_cancel;, and so will do any other operation successively
3194 called on the same &carv_obj; object whose return type is <classname>LqrRetVal</classname>;
3195 otherwise it will have no effect.
3196 </para>
3197 <para>
3198 Whenever a function returns &err_cancel;, it means that the &carv_obj; object is in an
3199 inconsistent state, and, since there is currently no way to recover from this situation, any
3200 further operation on that object must be avoided, and it must be destroyed.
3201 </para>
3202 <para>
3203 This function will fail if invoked over attached &carv_obj; objects.
3204 </para>
3205 </refsect1>
3206
3207 <refsect1>
3208 <title>Return value</title>
3209 <para>
3210 The return value follows the &lqrl; signalling system. However, it can be called multiple times,
3211 so it will never return &err_cancel; itself.
3212 </para>
3213 </refsect1>
3214
3215 <refsect1>
3216 <title>See also</title>
3217 <para>
3218 <simplelist type="inline">
3219 <member><xref linkend="ref-lqr-ret-val"></xref></member>
3220 <member><xref linkend="ref-lqr-carver-resize"></xref></member>
3221 <member><xref linkend="ref-lqr-carver-flatten"></xref></member>
3222 </simplelist>
3223 </para>
3224 </refsect1>
3225 </refentry>
3226
3227 <refentry id="ref-lqr-carver-scan-reset">
3228 <refmeta>
3229 <refentrytitle><function>lqr_carver_scan_reset</function></refentrytitle>
3230 <manvolnum>3</manvolnum>
3231 </refmeta>
3232
3233 <refnamediv>
3234 <refname>lqr_carver_scan_reset</refname>
3235 <refpurpose>reset the readout cursor of a multi-size image</refpurpose>
3236 </refnamediv>
3237
3238 <refsynopsisdiv>
3239 <funcsynopsis>
3240 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3241 <funcprototype>
3242 <funcdef>void <function>lqr_carver_scan_reset</function></funcdef>
3243 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3244 </funcprototype>
3245 </funcsynopsis>
3246 </refsynopsisdiv>
3247
3248 <refsect1>
3249 <title>Description</title>
3250 <para>
3251 The function <function>lqr_carver_scan_reset</function> resets the readout pointer associated
3252 with the &carv_obj; object pointed to by <parameter>carver</parameter> to the start of the
3253 image. (Normally, calling this function isn't needed, as the pointer is reset automatically
3254 whenever an operation is performed or once a readout has completed.)
3255 </para>
3256 </refsect1>
3257
3258 <refsect1>
3259 <title>See also</title>
3260 <para>
3261 <simplelist type="inline">
3262 <member><xref linkend="ref-lqr-carver-scan"></xref></member>
3263 <member><xref linkend="ref-lqr-carver-scan-by-row"></xref></member>
3264 <member><xref linkend="ref-lqr-carver-scan-line"></xref></member>
3265 </simplelist>
3266 </para>
3267 </refsect1>
3268
3269 </refentry>
3270
3271 <refentry id="ref-lqr-carver-scan">
3272 <refmeta>
3273 <refentrytitle><function>lqr_carver_scan</function></refentrytitle>
3274 <manvolnum>3</manvolnum>
3275 </refmeta>
3276
3277 <refnamediv>
3278 <refname>lqr_carver_scan</refname>
3279 <refname>lqr_carver_scan_ext</refname>
3280 <refpurpose>read out a multi-size image one pixel at a time</refpurpose>
3281 </refnamediv>
3282
3283 <refsynopsisdiv>
3284 <funcsynopsis>
3285 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3286 <funcprototype>
3287 <funcdef>gboolean <function>lqr_carver_scan</function></funcdef>
3288 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3289 <paramdef>gint* <parameter>x</parameter></paramdef>
3290 <paramdef>gint* <parameter>y</parameter></paramdef>
3291 <paramdef>guchar** <parameter>rgb</parameter></paramdef>
3292 </funcprototype>
3293 <funcprototype>
3294 <funcdef>gboolean <function>lqr_carver_scan_ext</function></funcdef>
3295 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3296 <paramdef>gint* <parameter>x</parameter></paramdef>
3297 <paramdef>gint* <parameter>y</parameter></paramdef>
3298 <paramdef>void** <parameter>rgb</parameter></paramdef>
3299 </funcprototype>
3300 </funcsynopsis>
3301 </refsynopsisdiv>
3302
3303 <refsect1>
3304 <title>Description</title>
3305 <para>
3306 The functions <function>lqr_carver_scan</function> and <function>lqr_carver_scan_ext</function>
3307 are used to read out the multi-size image contained in the &carv_obj; object pointed to by
3308 <parameter>carver</parameter> one pixel at a time. They store the pixel coordinates in the
3309 variables pointed to by <parameter>x</parameter> and <parameter>y</parameter>, and the pixel
3310 content in the array pointed to by <parameter>rgb</parameter>; then they move the readout
3311 pointer to the next pixel, or they reset it if the end of the image is reached.
3312 </para>
3313 <para>
3314 The first one must only be used on the &carv_obj; objects created with
3315 <parameter>lqr_carver_new</parameter>, i.e. with 8-bit images, while the second one is general
3316 (see <xref linkend="ref-lqr-col-depth"></xref>), but the <parameter>rgb</parameter> pointer must
3317 be cast to the appropriate type to be used (i.e pass the address of a pointer to
3318 <literal>void</literal> to the function <function>lqr_carver_scan_ext</function>, then cast it
3319 to a pointer of the appropriate type and use this last one for reading the output).
3320 </para>
3321 <para>
3322 The <parameter>rgb</parameter> variable will point to an array which is internal to the
3323 &carv_obj; object, so there is no need to allocate memory for it. However, it should only be
3324 accessed right after a call to the scan functions, and writing to it must be avoided.
3325 </para>
3326 </refsect1>
3327
3328 <refsect1>
3329 <title>Return value</title>
3330 <para>
3331 These functions return &ret_true; in case the readout is successful and the end of the image
3332 was not reached, &ret_false; otherwise.
3333 If <function>lqr_carver_scan</function> is called over a non-8-bit &carv_obj; object,
3334 it will return &ret_false;.
3335 </para>
3336 </refsect1>
3337
3338 <refsect1>
3339 <title>See also</title>
3340 <para>
3341 <simplelist type="inline">
3342 <member><xref linkend="ref-lqr-col-depth"></xref></member>
3343 <member><xref linkend="ref-lqr-carver-scan-reset"></xref></member>
3344 <member><xref linkend="ref-lqr-carver-scan-line"></xref></member>
3345 </simplelist>
3346 </para>
3347 </refsect1>
3348
3349 </refentry>
3350
3351 <refentry id="ref-lqr-carver-scan-by-row">
3352 <refmeta>
3353 <refentrytitle><function>lqr_carver_scan_by_row</function></refentrytitle>
3354 <manvolnum>3</manvolnum>
3355 </refmeta>
3356
3357 <refnamediv>
3358 <refname>lqr_carver_scan_by_row</refname>
3359 <refpurpose>tells if the image in &carv_obj; will be scanned by row or by column</refpurpose>
3360 </refnamediv>
3361
3362 <refsynopsisdiv>
3363 <funcsynopsis>
3364 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3365 <funcprototype>
3366 <funcdef>gboolean <function>lqr_carver_scan_by_row</function></funcdef>
3367 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3368 </funcprototype>
3369 </funcsynopsis>
3370 </refsynopsisdiv>
3371
3372 <refsect1>
3373 <title>Description</title>
3374 <para>
3375 The function <function>lqr_carver_scan_by_row</function> must be used before calling the
3376 functions
3377 <link linkend="ref-lqr-carver-scan-line"><function>lqr_carver_scan_line</function></link> and
3378 <link linkend="ref-lqr-carver-scan-line"><function>lqr_carver_scan_line_ext</function></link>,
3379 in order to ascertain if those functions will scan the multi-size image contained in the
3380 &carv_obj; object pointed to by <parameter>carver</parameter> by row or by column, which depends
3381 on which was last rescaling direction and cannot be controlled directly by the user.
3382 </para>
3383 </refsect1>
3384
3385 <refsect1>
3386 <title>Return value</title>
3387 <para>
3388 This function returns &ret_true; in case the image is going to be scanned by row, &ret_false; in
3389 case it is going to be scanned by column;
3390 </para>
3391 </refsect1>
3392
3393 <refsect1>
3394 <title>See also</title>
3395 <para>
3396 <simplelist type="inline">
3397 <member><xref linkend="ref-lqr-carver-scan-reset"></xref></member>
3398 <member><xref linkend="ref-lqr-carver-scan"></xref></member>
3399 <member><xref linkend="ref-lqr-carver-scan-line"></xref></member>
3400 </simplelist>
3401 </para>
3402 </refsect1>
3403 </refentry>
3404
3405 <refentry id="ref-lqr-carver-scan-line">
3406 <refmeta>
3407 <refentrytitle><function>lqr_carver_scan_line</function></refentrytitle>
3408 <manvolnum>3</manvolnum>
3409 </refmeta>
3410
3411 <refnamediv>
3412 <refname>lqr_carver_scan_line</refname>
3413 <refname>lqr_carver_scan_line_ext</refname>
3414 <refpurpose>read out a multi-size image one line at a time</refpurpose>
3415 </refnamediv>
3416
3417 <refsynopsisdiv>
3418 <funcsynopsis>
3419 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3420 <funcprototype>
3421 <funcdef>gboolean <function>lqr_carver_scan_line</function></funcdef>
3422 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3423 <paramdef>gint* <parameter>n</parameter></paramdef>
3424 <paramdef>guchar** <parameter>rgb</parameter></paramdef>
3425 </funcprototype>
3426 <funcprototype>
3427 <funcdef>gboolean <function>lqr_carver_scan_line_ext</function></funcdef>
3428 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3429 <paramdef>gint* <parameter>n</parameter></paramdef>
3430 <paramdef>void** <parameter>rgb</parameter></paramdef>
3431 </funcprototype>
3432 </funcsynopsis>
3433 </refsynopsisdiv>
3434
3435 <refsect1>
3436 <title>Description</title>
3437 <para>
3438 The functions <function>lqr_carver_scan_line</function> and
3439 <function>lqr_carver_scan_line_ext</function> are used to read out the multi-size image
3440 contained in the &carv_obj; object pointed to by <parameter>carver</parameter> one line at a
3441 time. They store the line number (row or column) in the variable pointed to by
3442 <parameter>n</parameter> and the colour values in the array pointed to by
3443 <parameter>rgb</parameter>; then they move the readout pointer to the next line, or they reset
3444 it if the end of the image is reached.
3445 </para>
3446 <para>
3447 The first one must only be used on the &carv_obj; objects created with
3448 <parameter>lqr_carver_new</parameter>, i.e. with 8-bit images, while the second one is general,
3449 but the <parameter>rgb</parameter> pointer must be cast to the appropriate type to be used (i.e
3450 pass the address of a pointer to <literal>void</literal> to the function
3451 <function>lqr_carver_scan_line_ext</function>, then cast it to a pointer of the appropriate type
3452 and use this last one for reading the output).
3453 </para>
3454 <para>
3455 Use the function <xref linkend="ref-lqr-carver-scan-by-row"></xref> before calling these to know
3456 whether your image will be scanned by row or by column.
3457 </para>
3458 </refsect1>
3459
3460 <refsect1>
3461 <title>Return value</title>
3462 <para>
3463 These functions return &ret_true; in case the readout is successful and the end of the image was
3464 not reached, &ret_false; otherwise. If <function>lqr_carver_scan_line</function> is called over
3465 a non-8-bit &carv_obj; object, it will return &ret_false;.
3466 </para>
3467 </refsect1>
3468
3469 <refsect1>
3470 <title>See also</title>
3471 <para>
3472 <simplelist type="inline">
3473 <member><xref linkend="ref-lqr-col-depth"></xref></member>
3474 <member><xref linkend="ref-lqr-carver-scan-reset"></xref></member>
3475 <member><xref linkend="ref-lqr-carver-scan"></xref></member>
3476 <member><xref linkend="ref-lqr-carver-scan-by-row"></xref></member>
3477 </simplelist>
3478 </para>
3479 </refsect1>
3480 </refentry>
3481
3482 <refentry id="ref-lqr-carver-get-width">
3483 <refmeta>
3484 <refentrytitle><function>lqr_carver_get_width</function></refentrytitle>
3485 <manvolnum>3</manvolnum>
3486 </refmeta>
3487
3488 <refnamediv>
3489 <refname>lqr_carver_get_width</refname>
3490 <refpurpose>get the current width of a &carv_obj; object</refpurpose>
3491 </refnamediv>
3492
3493 <refsynopsisdiv>
3494 <funcsynopsis>
3495 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3496 <funcprototype>
3497 <funcdef>gint <function>lqr_carver_get_width</function></funcdef>
3498 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3499 </funcprototype>
3500 </funcsynopsis>
3501 </refsynopsisdiv>
3502
3503 <refsect1>
3504 <title>Description</title>
3505 <para>
3506 The function <function>lqr_carver_get_width</function> returns the current width of the image
3507 contained in the &carv_obj; object pointed to by <parameter>carver</parameter>, in pixel units.
3508 </para>
3509 </refsect1>
3510
3511 <refsect1>
3512 <title>See also</title>
3513 <para>
3514 <simplelist type="inline">
3515 <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
3516 <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
3517 <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
3518 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
3519 <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
3520 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
3521 <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
3522 </simplelist>
3523 </para>
3524 </refsect1>
3525 </refentry>
3526
3527 <refentry id="ref-lqr-carver-get-height">
3528 <refmeta>
3529 <refentrytitle><function>lqr_carver_get_height</function></refentrytitle>
3530 <manvolnum>3</manvolnum>
3531 </refmeta>
3532
3533 <refnamediv>
3534 <refname>lqr_carver_get_height</refname>
3535 <refpurpose>get the current height of a &carv_obj; object</refpurpose>
3536 </refnamediv>
3537
3538 <refsynopsisdiv>
3539 <funcsynopsis>
3540 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3541 <funcprototype>
3542 <funcdef>gint <function>lqr_carver_get_height</function></funcdef>
3543 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3544 </funcprototype>
3545 </funcsynopsis>
3546 </refsynopsisdiv>
3547
3548 <refsect1>
3549 <title>Description</title>
3550 <para>
3551 The function <function>lqr_carver_get_height</function> returns the current height of the image
3552 contained in the &carv_obj; object pointed to by <parameter>carver</parameter>, in pixel units.
3553 </para>
3554 </refsect1>
3555
3556 <refsect1>
3557 <title>See also</title>
3558 <para>
3559 <simplelist type="inline">
3560 <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
3561 <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
3562 <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
3563 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
3564 <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
3565 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
3566 <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
3567 </simplelist>
3568 </para>
3569 </refsect1>
3570 </refentry>
3571
3572 <refentry id="ref-lqr-carver-get-ref-width">
3573 <refmeta>
3574 <refentrytitle><function>lqr_carver_get_ref_width</function></refentrytitle>
3575 <manvolnum>3</manvolnum>
3576 </refmeta>
3577
3578 <refnamediv>
3579 <refname>lqr_carver_get_ref_width</refname>
3580 <refpurpose>get the reference width of a &carv_obj; object</refpurpose>
3581 </refnamediv>
3582
3583 <refsynopsisdiv>
3584 <funcsynopsis>
3585 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3586 <funcprototype>
3587 <funcdef>gint <function>lqr_carver_get_ref_width</function></funcdef>
3588 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3589 </funcprototype>
3590 </funcsynopsis>
3591 </refsynopsisdiv>
3592
3593 <refsect1>
3594 <title>Description</title>
3595 <para>
3596 The function <function>lqr_carver_get_ref_width</function> returns the internal reference width
3597 of the image contained in the &carv_obj; object pointed to by <parameter>carver</parameter>, in
3598 pixel units.
3599 </para>
3600 <para>
3601 The reference width is set as the original height at carver initialization, and reset any time
3602 the carver gets subsequently flattened, either explicitly through <xref
3603 linkend="ref-lqr-carver-flatten"></xref> or implicitly when the rescale direction changes or
3604 an enlargment beyond the maximum enlargement step is performed.
3605 </para>
3606 </refsect1>
3607
3608 <refsect1>
3609 <title>See also</title>
3610 <para>
3611 <simplelist type="inline">
3612 <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
3613 <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
3614 <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
3615 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
3616 <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
3617 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
3618 <member><xref linkend="ref-lqr-carver-flatten"></xref></member>
3619 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
3620 <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
3621 </simplelist>
3622 </para>
3623 </refsect1>
3624 </refentry>
3625
3626 <refentry id="ref-lqr-carver-get-ref-height">
3627 <refmeta>
3628 <refentrytitle><function>lqr_carver_get_ref_height</function></refentrytitle>
3629 <manvolnum>3</manvolnum>
3630 </refmeta>
3631
3632 <refnamediv>
3633 <refname>lqr_carver_get_ref_height</refname>
3634 <refpurpose>get the reference height of a &carv_obj; object</refpurpose>
3635 </refnamediv>
3636
3637 <refsynopsisdiv>
3638 <funcsynopsis>
3639 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3640 <funcprototype>
3641 <funcdef>gint <function>lqr_carver_get_ref_height</function></funcdef>
3642 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3643 </funcprototype>
3644 </funcsynopsis>
3645 </refsynopsisdiv>
3646
3647 <refsect1>
3648 <title>Description</title>
3649 <para>
3650 The function <function>lqr_carver_get_ref_height</function> returns the internal reference
3651 height of the image contained in the &carv_obj; object pointed to by
3652 <parameter>carver</parameter>, in pixel units.
3653 </para>
3654 <para>
3655 The reference height is set as the original height at carver initialization, and reset any time
3656 the carver gets subsequently flattened, either explicitly through <xref
3657 linkend="ref-lqr-carver-flatten"></xref> or implicitly when the rescale direction changes or
3658 an enlargment beyond the maximum enlargement step is performed.
3659 </para>
3660 </refsect1>
3661
3662 <refsect1>
3663 <title>See also</title>
3664 <para>
3665 <simplelist type="inline">
3666 <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
3667 <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
3668 <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
3669 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
3670 <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
3671 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
3672 <member><xref linkend="ref-lqr-carver-flatten"></xref></member>
3673 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
3674 <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
3675 </simplelist>
3676 </para>
3677 </refsect1>
3678 </refentry>
3679
3680 <refentry id="ref-lqr-carver-get-channels">
3681 <refmeta>
3682 <refentrytitle><function>lqr_carver_get_channels</function></refentrytitle>
3683 <manvolnum>3</manvolnum>
3684 </refmeta>
3685
3686 <refnamediv>
3687 <refname>lqr_carver_get_channels</refname>
3688 <refname>lqr_carver_get_bpp</refname>
3689 <refpurpose>get the number of channels in a &carv_obj; object</refpurpose>
3690 </refnamediv>
3691
3692 <refsynopsisdiv>
3693 <funcsynopsis>
3694 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3695 <funcprototype>
3696 <funcdef>gint <function>lqr_carver_get_channels</function></funcdef>
3697 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3698 </funcprototype>
3699 <funcprototype>
3700 <funcdef>gint <function>lqr_carver_get_bpp</function></funcdef>
3701 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3702 </funcprototype>
3703 </funcsynopsis>
3704 </refsynopsisdiv>
3705
3706 <refsect1>
3707 <title>Description</title>
3708 <para>
3709 The functions <function>lqr_carver_get_channels</function> returns the number of colour channels
3710 of the image contained in the &carv_obj; object pointed to by <parameter>carver</parameter>.
3711 </para>
3712 <para>
3713 The function <function>lqr_carver_get_bpp</function> is an alias for
3714 <function>lqr_carver_get_channels</function>, it is deprecated and it is maintained for backward
3715 compatibility purposes only.
3716 </para>
3717 </refsect1>
3718
3719 <refsect1>
3720 <title>See also</title>
3721 <para>
3722 <simplelist type="inline">
3723 <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
3724 <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
3725 <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
3726 <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
3727 <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
3728 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
3729 <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
3730 </simplelist>
3731 </para>
3732 </refsect1>
3733 </refentry>
3734
3735 <refentry id="ref-lqr-carver-get-col-depth">
3736 <refmeta>
3737 <refentrytitle><function>lqr_carver_get_col_depth</function></refentrytitle>
3738 <manvolnum>3</manvolnum>
3739 </refmeta>
3740
3741 <refnamediv>
3742 <refname>lqr_carver_get_col_depth</refname>
3743 <refpurpose>get the colour depth of a &carv_obj; object</refpurpose>
3744 </refnamediv>
3745
3746 <refsynopsisdiv>
3747 <funcsynopsis>
3748 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3749 <funcprototype>
3750 <funcdef>LqrColDepth <function>lqr_carver_get_col_depth</function></funcdef>
3751 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3752 </funcprototype>
3753 </funcsynopsis>
3754 </refsynopsisdiv>
3755
3756 <refsect1>
3757 <title>Description</title>
3758 <para>
3759 The function <function>lqr_carver_get_col_depth</function> returns the colour depth of the image
3760 contained in the &carv_obj; object pointed to by <parameter>carver</parameter>.
3761 </para>
3762 </refsect1>
3763
3764 <refsect1>
3765 <title>See also</title>
3766 <para>
3767 <simplelist type="inline">
3768 <member><xref linkend="ref-lqr-col-depth"></xref></member>
3769 <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
3770 <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
3771 <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
3772 <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
3773 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
3774 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
3775 <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
3776 </simplelist>
3777 </para>
3778 </refsect1>
3779 </refentry>
3780
3781 <refentry id="ref-lqr-carver-get-image-type">
3782 <refmeta>
3783 <refentrytitle><function>lqr_carver_get_image_type</function></refentrytitle>
3784 <manvolnum>3</manvolnum>
3785 </refmeta>
3786
3787 <refnamediv>
3788 <refname>lqr_carver_get_image_type</refname>
3789 <refpurpose>get the image type of a &carv_obj; object</refpurpose>
3790 </refnamediv>
3791
3792 <refsynopsisdiv>
3793 <funcsynopsis>
3794 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3795 <funcprototype>
3796 <funcdef>LqrImageType <function>lqr_carver_get_image_type</function></funcdef>
3797 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3798 </funcprototype>
3799 </funcsynopsis>
3800 </refsynopsisdiv>
3801
3802 <refsect1>
3803 <title>Description</title>
3804 <para>
3805 The function <function>lqr_carver_get_image_type</function> returns the image type (i.e. colour
3806 model) of the image contained in the &carv_obj; object pointed to by
3807 <parameter>carver</parameter>.
3808 </para>
3809 </refsect1>
3810
3811 <refsect1>
3812 <title>See also</title>
3813 <para>
3814 <simplelist type="inline">
3815 <member><xref linkend="ref-lqr-image-type"></xref></member>
3816 <member><xref linkend="ref-lqr-carver-new"></xref></member>
3817 <member><xref linkend="ref-lqr-carver-set-image-type"></xref></member>
3818 <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
3819 <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
3820 <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
3821 <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
3822 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
3823 <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
3824 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
3825 <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
3826 </simplelist>
3827 </para>
3828 </refsect1>
3829 </refentry>
3830
3831 <refentry id="ref-lqr-carver-get-enl-step">
3832 <refmeta>
3833 <refentrytitle><function>lqr_carver_get_enl_step</function></refentrytitle>
3834 <manvolnum>3</manvolnum>
3835 </refmeta>
3836
3837 <refnamediv>
3838 <refname>lqr_carver_get_enl_step</refname>
3839 <refpurpose>get the enlargement step of a &carv_obj; object</refpurpose>
3840 </refnamediv>
3841
3842 <refsynopsisdiv>
3843 <funcsynopsis>
3844 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3845 <funcprototype>
3846 <funcdef>gfloat <function>lqr_carver_get_enl_step</function></funcdef>
3847 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3848 </funcprototype>
3849 </funcsynopsis>
3850 </refsynopsisdiv>
3851
3852 <refsect1>
3853 <title>Description</title>
3854 <para>
3855 The function <function>lqr_carver_get_enl_step</function> returns the enlargement step of the
3856 &carv_obj; object pointed to by <parameter>carver</parameter>, i.e. the maximum enlargement
3857 allowed in a single step for that carver, expressed as the ratio with respect to its reference
3858 width (for horizontal rescalings) or height (for vertical rescalings). The returned value is
3859 strictly greater than 1 and less than 2.
3860 </para>
3861 </refsect1>
3862
3863 <refsect1>
3864 <title>See also</title>
3865 <para>
3866 <simplelist type="inline">
3867 <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
3868 <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
3869 <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
3870 <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
3871 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
3872 <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
3873 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
3874 <member><xref linkend="ref-lqr-carver-resize"></xref></member>
3875 <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
3876 </simplelist>
3877 </para>
3878 </refsect1>
3879 </refentry>
3880
3881 <refentry id="ref-lqr-carver-get-orientation">
3882 <refmeta>
3883 <refentrytitle><function>lqr_carver_get_orientation</function></refentrytitle>
3884 <manvolnum>3</manvolnum>
3885 </refmeta>
3886
3887 <refnamediv>
3888 <refname>lqr_carver_get_orientation</refname>
3889 <refpurpose>get the orientation of a &carv_obj; object</refpurpose>
3890 </refnamediv>
3891
3892 <refsynopsisdiv>
3893 <funcsynopsis>
3894 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3895 <funcprototype>
3896 <funcdef>gint <function>lqr_carver_get_orientation</function></funcdef>
3897 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3898 </funcprototype>
3899 </funcsynopsis>
3900 </refsynopsisdiv>
3901
3902 <refsect1>
3903 <title>Description</title>
3904 <para>
3905 The function <function>lqr_carver_get_orientation</function> returns the current orientation of
3906 the visibility map internal to the &carv_obj; object pointed to by
3907 <parameter>carver</parameter>, which is <literal>0</literal> if the last rescale operation has
3908 been in the horizontal direction, <literal>1</literal> if it has been in the vertical direction.
3909 </para>
3910 </refsect1>
3911
3912 <refsect1>
3913 <title>See also</title>
3914 <para>
3915 <simplelist type="inline">
3916 <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
3917 <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
3918 <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
3919 <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
3920 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
3921 <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
3922 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
3923 <member><xref linkend="ref-lqr-carver-resize"></xref></member>
3924 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
3925 <member><xref linkend="ref-lqr-vmap-get-orientation"></xref></member>
3926 </simplelist>
3927 </para>
3928 </refsect1>
3929 </refentry>
3930
3931 <refentry id="ref-lqr-carver-get-depth">
3932 <refmeta>
3933 <refentrytitle><function>lqr_carver_get_depth</function></refentrytitle>
3934 <manvolnum>3</manvolnum>
3935 </refmeta>
3936
3937 <refnamediv>
3938 <refname>lqr_carver_get_depth</refname>
3939 <refpurpose>get the depth of a &carv_obj; object</refpurpose>
3940 </refnamediv>
3941
3942 <refsynopsisdiv>
3943 <funcsynopsis>
3944 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3945 <funcprototype>
3946 <funcdef>gint <function>lqr_carver_get_depth</function></funcdef>
3947 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3948 </funcprototype>
3949 </funcsynopsis>
3950 </refsynopsisdiv>
3951
3952 <refsect1>
3953 <title>Description</title>
3954 <para>
3955 The function <function>lqr_carver_get_depth</function> returns the current depth of the
3956 visibility map internal to the &carv_obj; object pointed to by <parameter>vmap</parameter>, i.e.
3957 the maximum amount of scaling which can be performed with respect to the internal reference
3958 sizes in the current orientation without updating the internal map.
3959 </para>
3960 </refsect1>
3961
3962 <refsect1>
3963 <title>See also</title>
3964 <para>
3965 <simplelist type="inline">
3966 <member><xref linkend="ref-lqr-carver-get-width"></xref></member>
3967 <member><xref linkend="ref-lqr-carver-get-height"></xref></member>
3968 <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
3969 <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
3970 <member><xref linkend="ref-lqr-carver-get-channels"></xref></member>
3971 <member><xref linkend="ref-lqr-carver-get-col-depth"></xref></member>
3972 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
3973 <member><xref linkend="ref-lqr-carver-resize"></xref></member>
3974 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
3975 <member><xref linkend="ref-lqr-carver-get-orientation"></xref></member>
3976 <member><xref linkend="ref-lqr-vmap-get-depth"></xref></member>
3977 </simplelist>
3978 </para>
3979 </refsect1>
3980 </refentry>
3981
3982 <refentry id="ref-lqr-carver-set-enl-step">
3983 <refmeta>
3984 <refentrytitle><function>lqr_carver_set_enl_step</function></refentrytitle>
3985 <manvolnum>3</manvolnum>
3986 </refmeta>
3987
3988 <refnamediv>
3989 <refname>lqr_carver_set_enl_step</refname>
3990 <refpurpose>set the enlargement step of a &carv_obj; object</refpurpose>
3991 </refnamediv>
3992
3993 <refsynopsisdiv>
3994 <funcsynopsis>
3995 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
3996 <funcprototype>
3997 <funcdef>LqrRetVal <function>lqr_carver_set_enl_step</function></funcdef>
3998 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
3999 <paramdef>gfloat <parameter>enl_step</parameter></paramdef>
4000 </funcprototype>
4001 </funcsynopsis>
4002 </refsynopsisdiv>
4003
4004 <refsect1>
4005 <title>Description</title>
4006 <para>
4007 The function <function>lqr_carver_set_enl_step</function> sets the enlargement step of the
4008 &carv_obj; object pointed to by <parameter>carver</parameter> to the value specified in
4009 <parameter>enl_step</parameter>, which must be strictly greater than 1 and less than 2.
4010 </para>
4011 <para>
4012 The enlargement step is the maximum enlargement ratio (with respect to either the original width
4013 or original height of <parameter>carver</parameter>) which the function
4014 <function>lqr_carver_resize</function> applies in a single step; if that function is asked a
4015 greater enlargement, it divides the process in multiple steps (and updates the original sizes
4016 accordingly at each new step - these can be readout at any time with
4017 <xref linkend="ref-lqr-carver-get-ref-width"></xref> and
4018 <xref linkend="ref-lqr-carver-get-ref-height"></xref>).
4019 </para>
4020 <para>
4021 The default value for new &carv_obj; objects is 2.0.
4022 </para>
4023 </refsect1>
4024
4025 <refsect1>
4026 <title>Return value</title>
4027 <para>
4028 The return value follows the &lqrl; signalling system. &err_err; is returned if the
4029 <parameter>enl_step</parameter> parameter is out of bounds.
4030 </para>
4031 </refsect1>
4032
4033 <refsect1>
4034 <title>See also</title>
4035 <para>
4036 <simplelist type="inline">
4037 <member><xref linkend="ref-lqr-carver-resize"></xref></member>
4038 <member><xref linkend="ref-lqr-carver-get-enl-step"></xref></member>
4039 <member><xref linkend="ref-lqr-carver-get-ref-width"></xref></member>
4040 <member><xref linkend="ref-lqr-carver-get-ref-height"></xref></member>
4041 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
4042 <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
4043 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
4044 <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
4045 <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
4046 </simplelist>
4047 </para>
4048 </refsect1>
4049 </refentry>
4050
4051 <refentry id="ref-lqr-carver-set-resize-order">
4052 <refmeta>
4053 <refentrytitle><function>lqr_carver_set_resize_order</function></refentrytitle>
4054 <manvolnum>3</manvolnum>
4055 </refmeta>
4056
4057 <refnamediv>
4058 <refname>lqr_carver_set_resize_order</refname>
4059 <refpurpose>set &carv_obj; object resize order</refpurpose>
4060 </refnamediv>
4061
4062 <refsynopsisdiv>
4063 <funcsynopsis>
4064 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4065 <funcprototype>
4066 <funcdef>void <function>lqr_carver_set_resize_order</function></funcdef>
4067 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
4068 <paramdef>LqrResizeOrder <parameter>resize_order</parameter></paramdef>
4069 </funcprototype>
4070 </funcsynopsis>
4071 </refsynopsisdiv>
4072
4073 <refsect1>
4074 <title>Description</title>
4075 <para>
4076 When the function <xref linkend="ref-lqr-carver-resize"></xref> is invoked and both the
4077 horizontal and vertical sizes are different from the current ones, the rescaling occurs first in
4078 one direction and then in the other.
4079 </para>
4080 <para>
4081 The function <function>lqr_carver_set_resize_order</function> can be used to set which direction
4082 to rescale first for the &carv_obj; object pointed to by <parameter>carver</parameter>. The
4083 parameter <parameter>resize_order</parameter> can take either the value
4084 <literal>LQR_RES_ORDER_HOR</literal> (horizontal rescale first) or
4085 <literal>LQR_RES_ORDER_VERT</literal> (vertical rescale first). By default, when an &carv_obj;
4086 object is created, the value is set to <literal>LQR_RES_ORDER_HOR</literal>
4087 </para>
4088 </refsect1>
4089
4090 <refsect1>
4091 <title>See also</title>
4092 <para>
4093 <simplelist type="inline">
4094 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
4095 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
4096 <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
4097 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
4098 <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
4099 <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
4100 </simplelist>
4101 </para>
4102 </refsect1>
4103 </refentry>
4104
4105 <refentry id="ref-lqr-carver-set-dump-vmaps">
4106 <refmeta>
4107 <refentrytitle><function>lqr_carver_set_dump_vmaps</function></refentrytitle>
4108 <manvolnum>3</manvolnum>
4109 </refmeta>
4110
4111 <refnamediv>
4112 <refname>lqr_carver_set_dump_vmaps</refname>
4113 <refname>lqr_carver_set_no_dump_vmaps</refname>
4114 <refpurpose>set the visibility maps autodump for an &carv_obj; object</refpurpose>
4115 </refnamediv>
4116
4117 <refsynopsisdiv>
4118 <funcsynopsis>
4119 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4120 <funcprototype>
4121 <funcdef>void <function>lqr_carver_set_dump_vmaps</function></funcdef>
4122 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
4123 </funcprototype>
4124 <funcprototype>
4125 <funcdef>void <function>lqr_carver_set_no_dump_vmaps</function></funcdef>
4126 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
4127 </funcprototype>
4128 </funcsynopsis>
4129 </refsynopsisdiv>
4130
4131 <refsect1>
4132 <title>Description</title>
4133 <para>
4134 Invoking function <function>lqr_carver_set_dump_vmaps</function> over the &carv_obj; object
4135 pointed to by <parameter>carver</parameter> has the effect of activating the automatic dumping
4136 of visibility maps at each rescale operation (which by default is turned off).
4137 </para>
4138 <para>
4139 Rescale operations involving both directions will dump two maps.
4140 </para>
4141 <para>
4142 The dumped maps will be attached to the &carv_obj; object and can be accessed at any later time
4143 using the functions <xref linkend="ref-lqr-vmap-list-foreach"></xref> or a combination of
4144 <xref linkend="ref-lqr-vmap-list-start"></xref>, <xref linkend="ref-lqr-vmap-list-current"></xref>
4145 and <xref linkend="ref-lqr-vmap-list-next"></xref>.
4146 </para>
4147 <para>
4148 Using this setting is pointless if the &carv_obj; object is not initialised.
4149 </para>
4150 <para>
4151 The function <function>lqr_carver_set_no_dump_vmaps</function> reverts the effect of the
4152 previous one (but the maps dumped so far will be kept).
4153 </para>
4154 <para>
4155 Note that it is also possible to dump the visibility maps manually; however, using the automatic
4156 dump is the only way to get intermidiate maps when the function
4157 <xref linkend="ref-lqr-carver-resize"></xref> performs the rescaling in both directions, or in
4158 more than one step.
4159 </para>
4160 </refsect1>
4161
4162 <refsect1>
4163 <title>See also</title>
4164 <para>
4165 <simplelist type="inline">
4166 <member><xref linkend="ref-lqr-carver-init"></xref></member>
4167 <member><xref linkend="ref-lqr-carver-resize"></xref></member>
4168 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
4169 <member><xref linkend="ref-lqr-carver-set-resize-order"></xref></member>
4170 <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
4171 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
4172 <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
4173 <member><xref linkend="ref-lqr-vmap-list-start"></xref></member>
4174 <member><xref linkend="ref-lqr-vmap-list-current"></xref></member>
4175 <member><xref linkend="ref-lqr-vmap-list-next"></xref></member>
4176 <member><xref linkend="ref-lqr-vmap-list-foreach"></xref></member>
4177 <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
4178 </simplelist>
4179 </para>
4180 </refsect1>
4181 </refentry>
4182
4183 <refentry id="ref-lqr-carver-set-side-switch-frequency">
4184 <refmeta>
4185 <refentrytitle><function>lqr_carver_set_side_switch_frequency</function></refentrytitle>
4186 <manvolnum>3</manvolnum>
4187 </refmeta>
4188
4189 <refnamediv>
4190 <refname>lqr_carver_set_side_switch_frequency</refname>
4191 <refpurpose>set &carv_obj; object side switch frequency</refpurpose>
4192 </refnamediv>
4193
4194 <refsynopsisdiv>
4195 <funcsynopsis>
4196 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4197 <funcprototype>
4198 <funcdef>void <function>lqr_carver_set_side_switch_frequency</function></funcdef>
4199 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
4200 <paramdef>guint <parameter>switch_frequency</parameter></paramdef>
4201 </funcprototype>
4202 </funcsynopsis>
4203 </refsynopsisdiv>
4204
4205 <refsect1>
4206 <title>Description</title>
4207 <para>
4208 When the function <xref linkend="ref-lqr-carver-resize"></xref> is invoked, it computes a
4209 relevance value for each pixel in the image, then chooses the optimal seam to carve based on
4210 such relvance values. However, in the case two seams are equivalent (which may happen when
4211 large portions of the image have the same colour, for example), the algorithm always chooses the
4212 seams from one side.
4213 </para>
4214 <para>
4215 In order to overcome this effect, an option is given to automatically switch the favoured side
4216 during rescaling, at the cost of a slightly worse performance.
4217 </para>
4218 <para>
4219 The function <function>lqr_carver_set_side_switch_frequency</function> sets the side switch
4220 frequency to <parameter>switch_frequency</parameter> for the &carv_obj; object pointed to by
4221 <parameter>carver</parameter>. This will have the effect that, for each rescale operation, the
4222 favoured side will be switched <parameter>switch_frequency</parameter> times (or as much times
4223 as the number of pixels to rescale).
4224 </para>
4225 <para>
4226 The default value for newly created &carv_obj; objects is <literal>0</literal>.
4227 </para>
4228 <para>
4229 As for the final result, a very small value (e.g. <literal>1<literal> to </literal>4</literal>)
4230 will normally suffice to balance the left and right side of the image (or the top and the boddom
4231 sides for vertical rescalings), without noticeable computational costs. However, in order to
4232 obtain a smoother behaviour for the visibiliy map, i.e. for the intermediate steps, higher
4233 values may be required.
4234 </para>
4235 </refsect1>
4236
4237 <refsect1>
4238 <title>See also</title>
4239 <para>
4240 <simplelist type="inline">
4241 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
4242 <member><xref linkend="ref-lqr-carver-set-resize-order"></xref></member>
4243 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
4244 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
4245 <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
4246 <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
4247 </simplelist>
4248 </para>
4249 </refsect1>
4250 </refentry>
4251
4252
4253 <refentry id="ref-lqr-carver-set-progress">
4254 <refmeta>
4255 <refentrytitle><function>lqr_carver_set_progress</function></refentrytitle>
4256 <manvolnum>3</manvolnum>
4257 </refmeta>
4258
4259 <refnamediv>
4260 <refname>lqr_carver_set_progress</refname>
4261 <refpurpose>set the progress report function for an &carv_obj; object</refpurpose>
4262 </refnamediv>
4263
4264 <refsynopsisdiv>
4265 <funcsynopsis>
4266 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4267 <funcprototype>
4268 <funcdef>void <function>lqr_carver_set_progress</function></funcdef>
4269 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
4270 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
4271 </funcprototype>
4272 </funcsynopsis>
4273 </refsynopsisdiv>
4274
4275 <refsect1>
4276 <title>Description</title>
4277 <para>
4278 The function <function>lqr_carver_set_progress</function> associates the progress indicator
4279 pointed to by <parameter>progress</parameter> to the &carv_obj; object pointed to by
4280 <parameter>carver</parameter>. Progress indicators objects are created with the function
4281 <xref linkend="ref-lqr-progress-new"></xref>.
4282 </para>
4283 <para>
4284 By default, no progress indicator is used.
4285 </para>
4286 </refsect1>
4287
4288 <refsect1>
4289 <title>See also</title>
4290 <para>
4291 <simplelist type="inline">
4292 <member><xref linkend="ref-lqr-progress-new"></xref></member>
4293 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
4294 <member><xref linkend="ref-lqr-carver-set-resize-order"></xref></member>
4295 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
4296 <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
4297 <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
4298 <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
4299 </simplelist>
4300 </para>
4301 </refsect1>
4302 </refentry>
4303
4304 <refentry id="ref-lqr-carver-set-preserve-input-image">
4305 <refmeta>
4306 <refentrytitle><function>lqr_carver_set_preserve_input_image</function></refentrytitle>
4307 <manvolnum>3</manvolnum>
4308 </refmeta>
4309
4310 <refnamediv>
4311 <refname>lqr_carver_set_preserve_input_image</refname>
4312 <refpurpose>set a flag to preserve the buffer passed to a &carv_obj; object upon creation</refpurpose>
4313 </refnamediv>
4314
4315 <refsynopsisdiv>
4316 <funcsynopsis>
4317 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4318 <funcprototype>
4319 <funcdef>void <function>lqr_carver_set_preserve_input_image</function></funcdef>
4320 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
4321 </funcprototype>
4322 </funcsynopsis>
4323 </refsynopsisdiv>
4324
4325 <refsect1>
4326 <title>Description</title>
4327 <para>
4328 The function <function>lqr_carver_set_preserve_input_image</function> flags the &carv_obj;
4329 object pointed to by <parameter>carver</parameter> so that it does not alter in any way the
4330 buffer which is passed to it by the constructor. It must be used before any resizing-related
4331 operation takes place, either after the <parameter>carver</parameter> construction or after the
4332 calls to <xref linkend="ref-lqr-carver-init"></xref> or
4333 <xref linkend="ref-lqr-vmap-load"></xref>.
4334 </para>
4335 </refsect1>
4336
4337 <refsect1>
4338 <title>See also</title>
4339 <para>
4340 <simplelist type="inline">
4341 <member><xref linkend="ref-lqr-carver-init"></xref></member>
4342 <member><xref linkend="ref-lqr-vmap-load"></xref></member>
4343 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
4344 <member><xref linkend="ref-lqr-carver-set-resize-order"></xref></member>
4345 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
4346 <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
4347 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
4348 <member><xref linkend="ref-lqr-carver-set-use-cache"></xref></member>
4349 </simplelist>
4350 </para>
4351 </refsect1>
4352 </refentry>
4353
4354 <refentry id="ref-lqr-carver-set-use-cache">
4355 <refmeta>
4356 <refentrytitle><function>lqr_carver_set_use_cache</function></refentrytitle>
4357 <manvolnum>3</manvolnum>
4358 </refmeta>
4359
4360 <refnamediv>
4361 <refname>lqr_carver_set_use_cache</refname>
4362 <refpurpose>enable/disable &carv_obj; object cache</refpurpose>
4363 </refnamediv>
4364
4365 <refsynopsisdiv>
4366 <funcsynopsis>
4367 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4368 <funcprototype>
4369 <funcdef>void <function>lqr_carver_set_use_cache</function></funcdef>
4370 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
4371 <paramdef>gboolean <parameter>use_cache</parameter></paramdef>
4372 </funcprototype>
4373 </funcsynopsis>
4374 </refsynopsisdiv>
4375
4376 <refsect1>
4377 <title>Description</title>
4378 <para>
4379 The function <function>lqr_carver_set_use_cache</function> can be used to disable or enable the
4380 cache for the &carv_obj; object pointed to by <parameter>carver</parameter>.
4381 </para>
4382 <para>
4383 By default, the caching is on.
4384 </para>
4385 </refsect1>
4386
4387 <refsect1>
4388 <title>See also</title>
4389 <para>
4390 <simplelist type="inline">
4391 <member><xref linkend="ref-lqr-carver-set-enl-step"></xref></member>
4392 <member><xref linkend="ref-lqr-carver-set-resize-order"></xref></member>
4393 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
4394 <member><xref linkend="ref-lqr-carver-set-side-switch-frequency"></xref></member>
4395 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
4396 <member><xref linkend="ref-lqr-carver-set-preserve-input-image"></xref></member>
4397 </simplelist>
4398 </para>
4399 </refsect1>
4400 </refentry>
4401
4402 <refentry id="ref-lqr-carver-attach">
4403 <refmeta>
4404 <refentrytitle><function>lqr_carver_attach</function></refentrytitle>
4405 <manvolnum>3</manvolnum>
4406 </refmeta>
4407
4408 <refnamediv>
4409 <refname>lqr_carver_attach</refname>
4410 <refpurpose>attach an &carv_obj; to another &carv_obj;</refpurpose>
4411 </refnamediv>
4412
4413 <refsynopsisdiv>
4414 <funcsynopsis>
4415 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4416 <funcprototype>
4417 <funcdef>LqrRetVal <function>lqr_carver_attach</function></funcdef>
4418 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
4419 <paramdef>LqrCarver* <parameter>aux</parameter></paramdef>
4420 </funcprototype>
4421 </funcsynopsis>
4422 </refsynopsisdiv>
4423
4424 <refsect1>
4425 <title>Description</title>
4426 <para>
4427 The function <function>lqr_carver_attach</function> is used to attach an &carv_obj; object
4428 (pointed to by <parameter>aux</parameter>) to another one (pointed to by
4429 <parameter>carver</parameter>). This will have the effect that each operation performed over
4430 the <parameter>carver</parameter> object will be reflected on <parameter>aux</parameter> (they
4431 will share the same visibility map).
4432 </para>
4433 <para>
4434 This function must not be used after a visibility map was loaded into the base object (the one
4435 pointed to by <parameter>carver</parameter>).
4436 </para>
4437 <para>
4438 The object pointed to by <parameter>aux</parameter> must have the same original size as the base
4439 object. Note that the original size information is reset whenever a flattening operation
4440 occurs, or the rescaling direction changes, so that this function should be called befor
4441 rescaling occurs.
4442 </para>
4443 <para>
4444 There is no limitation on the number of &carv_obj; objects which is possible to attach. Nesting
4445 is also possible. It is irrelevant if the <parameter>aux</parameter> carver is initialised or
4446 not; from the moment of attachment, it will passively undergo all transformations performed over
4447 <parameter>carver</parameter>.
4448 </para>
4449 </refsect1>
4450
4451 <refsect1>
4452 <title>Return value</title>
4453 <para>
4454 The return value follows the &lqrl; signalling system. &err_err; is returned if the sizes of
4455 <parameter>carver</parameter> and <parameter>aux</parameter> don't match.
4456 </para>
4457 </refsect1>
4458
4459 <refsect1>
4460 <title>See also</title>
4461 <para>
4462 <simplelist type="inline">
4463 <member><xref linkend="ref-lqr-ret-val"></xref></member>
4464 <member><xref linkend="ref-lqr-carver-list-start"></xref></member>
4465 <member><xref linkend="ref-lqr-carver-list-current"></xref></member>
4466 <member><xref linkend="ref-lqr-carver-list-next"></xref></member>
4467 <member><xref linkend="ref-lqr-carver-list-foreach"></xref></member>
4468 </simplelist>
4469 </para>
4470 </refsect1>
4471 </refentry>
4472
4473 <refentry id="ref-lqr-carver-list-start">
4474 <refmeta>
4475 <refentrytitle><function>lqr_carver_list_start</function></refentrytitle>
4476 <manvolnum>3</manvolnum>
4477 </refmeta>
4478
4479 <refnamediv>
4480 <refname>lqr_carver_list_start</refname>
4481 <refpurpose>get the staritng point of the attachement list in an &carv_obj; object</refpurpose>
4482 </refnamediv>
4483
4484 <refsynopsisdiv>
4485 <funcsynopsis>
4486 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4487 <funcprototype>
4488 <funcdef>LqrCarverList* <function>lqr_carver_list_start</function></funcdef>
4489 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
4490 </funcprototype>
4491 </funcsynopsis>
4492 </refsynopsisdiv>
4493
4494 <refsect1>
4495 <title>Description</title>
4496 <para>
4497 The function <function>lqr_carver_list_start</function> returns the stating point of the
4498 &carvl_obj; object associated with the &carv_obj; object pointed to by
4499 <parameter>carver</parameter>, which is used to keep track of the &carv_obj; objects attached to
4500 it.
4501 </para>
4502 <para>
4503 The returned value is &ret_null; if there are no attached carvers.
4504 </para>
4505 <para>
4506 Use the functions <xref linkend="ref-lqr-carver-list-current"></xref> and
4507 <xref linkend="ref-lqr-carver-list-next"></xref> to access the list element individually, or the
4508 function <xref linkend="ref-lqr-carver-list-foreach"></xref> to operate on whole lists.
4509 </para>
4510 </refsect1>
4511
4512 <refsect1>
4513 <title>See also</title>
4514 <para>
4515 <simplelist type="inline">
4516 <member><xref linkend="ref-lqr-carver-attach"></xref></member>
4517 <member><xref linkend="ref-lqr-carver-list-current"></xref></member>
4518 <member><xref linkend="ref-lqr-carver-list-next"></xref></member>
4519 <member><xref linkend="ref-lqr-carver-list-foreach"></xref></member>
4520 </simplelist>
4521 </para>
4522 </refsect1>
4523 </refentry>
4524
4525 <refentry id="ref-lqr-carver-list-current">
4526 <refmeta>
4527 <refentrytitle><function>lqr_carver_list_current</function></refentrytitle>
4528 <manvolnum>3</manvolnum>
4529 </refmeta>
4530
4531 <refnamediv>
4532 <refname>lqr_carver_list_current</refname>
4533 <refpurpose>get current &carv_obj; object in a &carvl_obj; object</refpurpose>
4534 </refnamediv>
4535
4536 <refsynopsisdiv>
4537 <funcsynopsis>
4538 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4539 <funcprototype>
4540 <funcdef>LqrCarver* <function>lqr_carver_list_current</function></funcdef>
4541 <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
4542 </funcprototype>
4543 </funcsynopsis>
4544 </refsynopsisdiv>
4545
4546 <refsect1>
4547 <title>Description</title>
4548 <para>
4549 The function <function>lqr_carver_list_current</function> returns a pointer to the &carv_obj;
4550 object corresponding to the current value of the <parameter>list</parameter> parameter, or
4551 &ret_null; in case of errors.
4552 </para>
4553 </refsect1>
4554
4555 <refsect1>
4556 <title>See also</title>
4557 <para>
4558 <simplelist type="inline">
4559 <member><xref linkend="ref-lqr-carver-attach"></xref></member>
4560 <member><xref linkend="ref-lqr-carver-list-start"></xref></member>
4561 <member><xref linkend="ref-lqr-carver-list-next"></xref></member>
4562 <member><xref linkend="ref-lqr-carver-list-foreach"></xref></member>
4563 </simplelist>
4564 </para>
4565 </refsect1>
4566 </refentry>
4567
4568 <refentry id="ref-lqr-carver-list-next">
4569 <refmeta>
4570 <refentrytitle><function>lqr_carver_list_next</function></refentrytitle>
4571 <manvolnum>3</manvolnum>
4572 </refmeta>
4573
4574 <refnamediv>
4575 <refname>lqr_carver_list_next</refname>
4576 <refpurpose>advance the &carvl_obj; object</refpurpose>
4577 </refnamediv>
4578
4579 <refsynopsisdiv>
4580 <funcsynopsis>
4581 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4582 <funcprototype>
4583 <funcdef>LqrCarverList* <function>lqr_carver_list_next</function></funcdef>
4584 <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
4585 </funcprototype>
4586 </funcsynopsis>
4587 </refsynopsisdiv>
4588
4589 <refsect1>
4590 <title>Description</title>
4591 <para>
4592 The function <function>lqr_carver_list_next</function> returns a pointer to the next attached
4593 &carv_obj; object in <parameter>list</parameter>, or &ret_null; if the list has reached the end.
4594 </para>
4595 </refsect1>
4596
4597 <refsect1>
4598 <title>See also</title>
4599 <para>
4600 <simplelist type="inline">
4601 <member><xref linkend="ref-lqr-carver-attach"></xref></member>
4602 <member><xref linkend="ref-lqr-carver-list-start"></xref></member>
4603 <member><xref linkend="ref-lqr-carver-list-current"></xref></member>
4604 <member><xref linkend="ref-lqr-carver-list-foreach"></xref></member>
4605 </simplelist>
4606 </para>
4607 </refsect1>
4608 </refentry>
4609
4610 <refentry id="ref-lqr-carver-list-foreach">
4611 <refmeta>
4612 <refentrytitle><function>lqr_carver_list_foreach</function></refentrytitle>
4613 <manvolnum>3</manvolnum>
4614 </refmeta>
4615
4616 <refnamediv>
4617 <refname>lqr_carver_list_foreach</refname>
4618 <refpurpose>perform operations on all &carv_obj; objects in an &carvl_obj; object</refpurpose>
4619 </refnamediv>
4620
4621 <refsynopsisdiv>
4622 <funcsynopsis>
4623 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4624 <funcprototype>
4625 <funcdef>LqrRetVal <function>lqr_carver_list_foreach</function></funcdef>
4626 <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
4627 <paramdef>LqrCarverFunc <parameter>func</parameter></paramdef>
4628 <paramdef>LqrDataTok <parameter>data</parameter></paramdef>
4629 </funcprototype>
4630 <funcprototype>
4631 <funcdef>LqrRetVal <function>lqr_carver_list_foreach_recursive</function></funcdef>
4632 <paramdef>LqrCarverList* <parameter>list</parameter></paramdef>
4633 <paramdef>LqrCarverFunc <parameter>func</parameter></paramdef>
4634 <paramdef>LqrDataTok <parameter>data</parameter></paramdef>
4635 </funcprototype>
4636 </funcsynopsis>
4637 </refsynopsisdiv>
4638
4639 <refsect1>
4640 <title>Description</title>
4641 <para>
4642 The function <function>lqr_carver_list_foreach</function> can be used to apply the function
4643 <parameter>func</parameter> to all the &carv_obj; objects listed in <parameter>list</parameter>.
4644 The parameter <parameter>data</parameter> is used to pass arguments to the function.
4645 </para>
4646 <para>
4647 The <parameter>list</parameter> value should be obtained through the function
4648 <xref linkend="ref-lqr-carver-list-start"></xref>. The order in the list will then follow the one
4649 in which carver objects were attached.
4650 </para>
4651 <para>
4652 The function <parameter>func</parameter> is of type <classname>LqrCarverFunc</classname>, whose
4653 prototype is defined by:
4654 <programlisting>
4655 typedef LqrRetVal (*LqrCarverFunc) (LqrCarver *carver, LqrDataTok data);
4656 </programlisting>
4657 The <parameter>data</parameter> argument is of type <structname>LqrDataTok</structname>, which
4658 is defined as a union with the following fields:
4659 <itemizedlist>
4660 <listitem>
4661 <para><type>&carv_obj;*</type> <structfield>carver</structfield></para>
4662 </listitem>
4663 <listitem>
4664 <para><type>gint</type> <structfield>integer</structfield></para>
4665 </listitem>
4666 <listitem>
4667 <para><type>gpointer</type> <structfield>data</structfield></para>
4668 </listitem>
4669 </itemizedlist>
4670 </para>
4671 <para>
4672 The function <function>lqr_carver_list_foreach_recursive</function> is equivelant to
4673 <function>lqr_carver_list_foreach</function>, but it works recursively if the &carv_obj; objects
4674 in <parameter>list</parameter> have themselves other attached &carv_obj; objects attached. In
4675 this case, the function <parameter>func</parameter> will be applied to each element of the list
4676 and to each element of the attached list recursively, before moving on to the next element.
4677 </para>
4678 </refsect1>
4679
4680 <refsect1>
4681 <title>See also</title>
4682 <para>
4683 <simplelist type="inline">
4684 <member><xref linkend="ref-lqr-ret-val"></xref></member>
4685 <member><xref linkend="ref-lqr-carver-attach"></xref></member>
4686 <member><xref linkend="ref-lqr-carver-list-start"></xref></member>
4687 <member><xref linkend="ref-lqr-carver-list-current"></xref></member>
4688 <member><xref linkend="ref-lqr-carver-list-next"></xref></member>
4689 </simplelist>
4690 </para>
4691 </refsect1>
4692 </refentry>
4693 </sect1>
4694
4695
4696 <sect1 id="ref-vmaps">
4697 <title>Visibiliy maps</title>
4698
4699 <refentry id="ref-lqr-vmap-new">
4700 <refmeta>
4701 <refentrytitle><function>lqr_vmap_new</function></refentrytitle>
4702 <manvolnum>3</manvolnum>
4703 </refmeta>
4704
4705 <refnamediv>
4706 <refname>lqr_vmap_new</refname>
4707 <refpurpose>the &vmap_obj; object constructor</refpurpose>
4708 </refnamediv>
4709
4710 <refsynopsisdiv>
4711 <funcsynopsis>
4712 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4713 <funcprototype>
4714 <funcdef>LqrVMap* <function>lqr_vmap_new</function></funcdef>
4715 <paramdef>gint* <parameter>buffer</parameter></paramdef>
4716 <paramdef>gint <parameter>width</parameter></paramdef>
4717 <paramdef>gint <parameter>height</parameter></paramdef>
4718 <paramdef>gint <parameter>depth</parameter></paramdef>
4719 <paramdef>gint <parameter>orientation</parameter></paramdef>
4720 </funcprototype>
4721 </funcsynopsis>
4722 </refsynopsisdiv>
4723
4724 <refsect1>
4725 <title>Description</title>
4726 <para>
4727 The function <function>lqr_vmap_new</function> is the constructor for &vmap_obj; objects. It can
4728 be used to convert saved data in a format which can be loaded in an &carv_obj; object.
4729 </para>
4730 <para>
4731 The parameter <parameter>buffer</parameter> must point to an an array of
4732 <literal><parameter>width</parameter> * <parameter>height</parameter></literal>
4733 <type>int</type>s holding the visibility information.
4734 </para>
4735 <para>
4736 The parameter <parameter>depth</parameter> represents the maximum possible amount of rescaling
4737 with the given map.
4738 </para>
4739 <para>
4740 The parameter <parameter>orientation</parameter> must be <literal>0</literal> if the map is to
4741 be used for horizontal rescaling, <literal>1</literal> if it is to be used for vertical
4742 rescaling.
4743 </para>
4744 </refsect1>
4745 <refsect1>
4746 <title>Visibility maps format</title>
4747 <para>
4748 The <parameter>buffer</parameter> must be an array of integers of size
4749 <literal><parameter>width</parameter> * <parameter>height</parameter></literal>. For an
4750 horizontally oriented visibility map, the format is as such: each row must contain all values
4751 between 1 and <parameter>depth</parameter> (included) exactly once, with low values indicating
4752 the pixels which will be operated on first during rescaling. All other pixels must be 0, which
4753 means that they won't be affected by rescaling. Such a map allows for horizontal rescaling in
4754 the range from <literal><parameter>width</parameter> - <parameter>depth</parameter></literal> to
4755 <literal><parameter>width</parameter> + <parameter>depth</parameter></literal>. The same
4756 applies to vertically oriented visibility maps, with columns in place of rows and
4757 <parameter>height</parameter> in place of <parameter>width</parameter>.
4758 </para>
4759 </refsect1>
4760 <refsect1>
4761 <title>Return value</title>
4762 <para>
4763 The function returns the newly created &vmap_obj; if successful, or &ret_null; in case of
4764 insufficient memory.
4765 </para>
4766 </refsect1>
4767
4768 <refsect1>
4769 <title>See also</title>
4770 <para>
4771 <simplelist type="inline">
4772 <member><xref linkend="ref-lqr-vmap-destroy"></xref></member>
4773 <member><xref linkend="ref-lqr-vmap-load"></xref></member>
4774 </simplelist>
4775 </para>
4776 </refsect1>
4777 </refentry>
4778
4779 <refentry id="ref-lqr-vmap-destroy">
4780 <refmeta>
4781 <refentrytitle><function>lqr_vmap_destroy</function></refentrytitle>
4782 <manvolnum>3</manvolnum>
4783 </refmeta>
4784
4785 <refnamediv>
4786 <refname>lqr_vmap_destroy</refname>
4787 <refpurpose>the &vmap_obj; object destructor</refpurpose>
4788 </refnamediv>
4789
4790 <refsynopsisdiv>
4791 <funcsynopsis>
4792 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4793 <funcprototype>
4794 <funcdef>void <function>lqr_vmap_destroy</function></funcdef>
4795 <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
4796 </funcprototype>
4797 </funcsynopsis>
4798 </refsynopsisdiv>
4799
4800 <refsect1>
4801 <title>Description</title>
4802 <para>
4803 The function <function>lqr_vmap_destroy</function> destroys the &vmap_obj; object. It is not
4804 necessary to invoke it over visibility maps which were loaded in &carv_obj; objects, as this is
4805 done already by the carver object destructor.
4806 </para>
4807 </refsect1>
4808
4809 <refsect1>
4810 <title>See also</title>
4811 <para>
4812 <simplelist type="inline">
4813 <member><xref linkend="ref-lqr-vmap-new"></xref></member>
4814 <member><xref linkend="ref-lqr-vmap-load"></xref></member>
4815 </simplelist>
4816 </para>
4817 </refsect1>
4818 </refentry>
4819
4820 <refentry id="ref-lqr-vmap-get-data">
4821 <refmeta>
4822 <refentrytitle><function>lqr_vmap_get_data</function></refentrytitle>
4823 <manvolnum>3</manvolnum>
4824 </refmeta>
4825
4826 <refnamediv>
4827 <refname>lqr_vmap_get_data</refname>
4828 <refpurpose>get varous &vmap_obj; object quantities</refpurpose>
4829 </refnamediv>
4830
4831 <refsynopsisdiv>
4832 <funcsynopsis>
4833 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4834 <funcprototype>
4835 <funcdef>gint* <function>lqr_vmap_get_data</function></funcdef>
4836 <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
4837 </funcprototype>
4838 </funcsynopsis>
4839 </refsynopsisdiv>
4840
4841 <refsect1>
4842 <title>Description</title>
4843 <para>
4844 The function <function>lqr_vmap_get_data</function> returns an array with the data stored into
4845 the &vmap_obj; object pointed to by <parameter>vmap</parameter>, ordered first by row, then by
4846 column.
4847 </para>
4848 <para>
4849 Reading the data requires retrieval of the other quantities, through the functions
4850 <xref linkend="ref-lqr-vmap-get-depth"></xref>,
4851 <xref linkend="ref-lqr-vmap-get-width"></xref>,
4852 <xref linkend="ref-lqr-vmap-get-height"></xref> and
4853 <xref linkend="ref-lqr-vmap-get-orientation"></xref>.
4854 </para>
4855 <para>
4856 See the &vmap_obj; objects format description in the page for
4857 <xref linkend="ref-lqr-vmap-new"></xref>.
4858 </para>
4859 </refsect1>
4860
4861 <refsect1>
4862 <title>See also</title>
4863 <para>
4864 <simplelist type="inline">
4865 <member><xref linkend="ref-lqr-vmap-new"></xref></member>
4866 <member><xref linkend="ref-lqr-vmap-get-depth"></xref></member>
4867 <member><xref linkend="ref-lqr-vmap-get-width"></xref></member>
4868 <member><xref linkend="ref-lqr-vmap-get-height"></xref></member>
4869 <member><xref linkend="ref-lqr-vmap-get-orientation"></xref></member>
4870 </simplelist>
4871 </para>
4872 </refsect1>
4873 </refentry>
4874
4875 <refentry id="ref-lqr-vmap-get-depth">
4876 <refmeta>
4877 <refentrytitle><function>lqr_vmap_get_depth</function></refentrytitle>
4878 <manvolnum>3</manvolnum>
4879 </refmeta>
4880
4881 <refnamediv>
4882 <refname>lqr_vmap_get_depth</refname>
4883 <refpurpose>get the depth of an &vmap_obj; object</refpurpose>
4884 </refnamediv>
4885
4886 <refsynopsisdiv>
4887 <funcsynopsis>
4888 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4889 <funcprototype>
4890 <funcdef>gint <function>lqr_vmap_get_depth</function></funcdef>
4891 <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
4892 </funcprototype>
4893 </funcsynopsis>
4894 </refsynopsisdiv>
4895
4896 <refsect1>
4897 <title>Description</title>
4898 <para>
4899 The function <function>lqr_vmap_get_depth</function> returns the depth of the &vmap_obj; object
4900 pointed to by <parameter>vmap</parameter>, i.e. the maximum scaling allowed by it.
4901 </para>
4902 <para>
4903 See the &vmap_obj; objects format description in the page for
4904 <link linkend="ref-lqr-vmap-new">&vmap_obj; constructor and destructor</link>.
4905 </para>
4906 </refsect1>
4907
4908 <refsect1>
4909 <title>See also</title>
4910 <para>
4911 <simplelist type="inline">
4912 <member><xref linkend="ref-lqr-vmap-new"></xref></member>
4913 <member><xref linkend="ref-lqr-vmap-get-data"></xref></member>
4914 <member><xref linkend="ref-lqr-vmap-get-width"></xref></member>
4915 <member><xref linkend="ref-lqr-vmap-get-height"></xref></member>
4916 <member><xref linkend="ref-lqr-vmap-get-orientation"></xref></member>
4917 </simplelist>
4918 </para>
4919 </refsect1>
4920 </refentry>
4921
4922 <refentry id="ref-lqr-vmap-get-width">
4923 <refmeta>
4924 <refentrytitle><function>lqr_vmap_get_width</function></refentrytitle>
4925 <manvolnum>3</manvolnum>
4926 </refmeta>
4927
4928 <refnamediv>
4929 <refname>lqr_vmap_get_width</refname>
4930 <refpurpose>get the width of an &vmap_obj; object</refpurpose>
4931 </refnamediv>
4932
4933 <refsynopsisdiv>
4934 <funcsynopsis>
4935 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4936 <funcprototype>
4937 <funcdef>gint <function>lqr_vmap_get_width</function></funcdef>
4938 <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
4939 </funcprototype>
4940 </funcsynopsis>
4941 </refsynopsisdiv>
4942
4943 <refsect1>
4944 <title>Description</title>
4945 <para>
4946 The function <function>lqr_vmap_get_width</function> returns the width of the &vmap_obj; object
4947 pointed to by <parameter>vmap</parameter>.
4948 </para>
4949 <para>
4950 See the &vmap_obj; objects format description in the page for
4951 <link linkend="ref-lqr-vmap-new">&vmap_obj; constructor and destructor</link>.
4952 </para>
4953 </refsect1>
4954
4955 <refsect1>
4956 <title>See also</title>
4957 <para>
4958 <simplelist type="inline">
4959 <member><xref linkend="ref-lqr-vmap-new"></xref></member>
4960 <member><xref linkend="ref-lqr-vmap-get-data"></xref></member>
4961 <member><xref linkend="ref-lqr-vmap-get-depth"></xref></member>
4962 <member><xref linkend="ref-lqr-vmap-get-height"></xref></member>
4963 <member><xref linkend="ref-lqr-vmap-get-orientation"></xref></member>
4964 </simplelist>
4965 </para>
4966 </refsect1>
4967 </refentry>
4968
4969 <refentry id="ref-lqr-vmap-get-height">
4970 <refmeta>
4971 <refentrytitle><function>lqr_vmap_get_height</function></refentrytitle>
4972 <manvolnum>3</manvolnum>
4973 </refmeta>
4974
4975 <refnamediv>
4976 <refname>lqr_vmap_get_height</refname>
4977 <refpurpose>get the height of an &vmap_obj; object</refpurpose>
4978 </refnamediv>
4979
4980 <refsynopsisdiv>
4981 <funcsynopsis>
4982 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
4983 <funcprototype>
4984 <funcdef>gint <function>lqr_vmap_get_height</function></funcdef>
4985 <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
4986 </funcprototype>
4987 </funcsynopsis>
4988 </refsynopsisdiv>
4989
4990 <refsect1>
4991 <title>Description</title>
4992 <para>
4993 The function <function>lqr_vmap_get_height</function> returns the height of the &vmap_obj;
4994 object pointed to by <parameter>vmap</parameter>.
4995 </para>
4996 <para>
4997 See the &vmap_obj; objects format description in the page for
4998 <link linkend="ref-lqr-vmap-new">&vmap_obj; constructor and destructor</link>.
4999 </para>
5000 </refsect1>
5001
5002 <refsect1>
5003 <title>See also</title>
5004 <para>
5005 <simplelist type="inline">
5006 <member><xref linkend="ref-lqr-vmap-new"></xref></member>
5007 <member><xref linkend="ref-lqr-vmap-get-data"></xref></member>
5008 <member><xref linkend="ref-lqr-vmap-get-depth"></xref></member>
5009 <member><xref linkend="ref-lqr-vmap-get-width"></xref></member>
5010 <member><xref linkend="ref-lqr-vmap-get-orientation"></xref></member>
5011 </simplelist>
5012 </para>
5013 </refsect1>
5014 </refentry>
5015
5016 <refentry id="ref-lqr-vmap-get-orientation">
5017 <refmeta>
5018 <refentrytitle><function>lqr_vmap_get_orientation</function></refentrytitle>
5019 <manvolnum>3</manvolnum>
5020 </refmeta>
5021
5022 <refnamediv>
5023 <refname>lqr_vmap_get_orientation</refname>
5024 <refpurpose>get the orientation of an &vmap_obj; object</refpurpose>
5025 </refnamediv>
5026
5027 <refsynopsisdiv>
5028 <funcsynopsis>
5029 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5030 <funcprototype>
5031 <funcdef>gint <function>lqr_vmap_get_orientation</function></funcdef>
5032 <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
5033 </funcprototype>
5034 </funcsynopsis>
5035 </refsynopsisdiv>
5036
5037 <refsect1>
5038 <title>Description</title>
5039 <para>
5040 The function <function>lqr_vmap_get_orientation</function> returns the orientation of the
5041 &vmap_obj; object pointed to by <parameter>vmap</parameter>, which is <literal>0</literal> for
5042 horizontally oriented maps, <literal>1</literal> for vertically oriented ones.
5043 </para>
5044 <para>
5045 See the &vmap_obj; objects format description in the page for
5046 <link linkend="ref-lqr-vmap-new">&vmap_obj; constructor and destructor</link>.
5047 </para>
5048 </refsect1>
5049
5050 <refsect1>
5051 <title>See also</title>
5052 <para>
5053 <simplelist type="inline">
5054 <member><xref linkend="ref-lqr-vmap-new"></xref></member>
5055 <member><xref linkend="ref-lqr-vmap-get-data"></xref></member>
5056 <member><xref linkend="ref-lqr-vmap-get-depth"></xref></member>
5057 <member><xref linkend="ref-lqr-vmap-get-width"></xref></member>
5058 <member><xref linkend="ref-lqr-vmap-get-height"></xref></member>
5059 </simplelist>
5060 </para>
5061 </refsect1>
5062 </refentry>
5063
5064 <refentry id="ref-lqr-vmap-dump">
5065 <refmeta>
5066 <refentrytitle><function>lqr_vmap_dump</function></refentrytitle>
5067 <manvolnum>3</manvolnum>
5068 </refmeta>
5069
5070 <refnamediv>
5071 <refname>lqr_vmap_dump</refname>
5072 <refpurpose>dump an &vmap_obj; object</refpurpose>
5073 </refnamediv>
5074
5075 <refsynopsisdiv>
5076 <funcsynopsis>
5077 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5078 <funcprototype>
5079 <funcdef>LqrVMap* <function>lqr_vmap_dump</function></funcdef>
5080 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
5081 </funcprototype>
5082 </funcsynopsis>
5083 </refsynopsisdiv>
5084
5085 <refsect1>
5086 <title>Description</title>
5087 <para>
5088 The function <function>lqr_vmap_dump</function> returns the current visibility map of the
5089 &carv_obj; object pointed to by <parameter>carver</parameter>, or &ret_null; in case of errors.
5090 </para>
5091 </refsect1>
5092
5093 <refsect1>
5094 <title>See also</title>
5095 <para>
5096 <simplelist type="inline">
5097 <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
5098 <member><xref linkend="ref-lqr-vmap-load"></xref></member>
5099 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
5100 </simplelist>
5101 </para>
5102 </refsect1>
5103 </refentry>
5104
5105 <refentry id="ref-lqr-vmap-internal-dump">
5106 <refmeta>
5107 <refentrytitle><function>lqr_vmap_internal_dump</function></refentrytitle>
5108 <manvolnum>3</manvolnum>
5109 </refmeta>
5110
5111 <refnamediv>
5112 <refname>lqr_vmap_internal_dump</refname>
5113 <refpurpose>dump an &vmap_obj; objects into an &carv_obj; object</refpurpose>
5114 </refnamediv>
5115
5116 <refsynopsisdiv>
5117 <funcsynopsis>
5118 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5119 <funcprototype>
5120 <funcdef>LqrRetVal <function>lqr_vmap_internal_dump</function></funcdef>
5121 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
5122 </funcprototype>
5123 </funcsynopsis>
5124 </refsynopsisdiv>
5125
5126 <refsect1>
5127 <title>Description</title>
5128 <para>
5129 The function <function>lqr_vmap_internal_dump</function> dumps the current visibility map of the
5130 &carv_obj; object pointed to by <parameter>carver</parameter> internally to it, attaching it to
5131 the same &vmapl_obj; object list as the one used for automatic dumping (as activated by
5132 <xref linkend="ref-lqr-carver-set-dump-vmaps"></xref>.
5133 </para>
5134 </refsect1>
5135
5136 <refsect1>
5137 <title>See also</title>
5138 <para>
5139 <simplelist type="inline">
5140 <member><xref linkend="ref-lqr-ret-val"></xref></member>
5141 <member><xref linkend="ref-lqr-vmap-dump"></xref></member>
5142 <member><xref linkend="ref-lqr-vmap-load"></xref></member>
5143 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
5144 </simplelist>
5145 </para>
5146 </refsect1>
5147 </refentry>
5148
5149 <refentry id="ref-lqr-vmap-load">
5150 <refmeta>
5151 <refentrytitle><function>lqr_vmap_load</function></refentrytitle>
5152 <manvolnum>3</manvolnum>
5153 </refmeta>
5154
5155 <refnamediv>
5156 <refname>lqr_vmap_load</refname>
5157 <refpurpose>load an &vmap_obj; object into an &carv_obj; object</refpurpose>
5158 </refnamediv>
5159
5160 <refsynopsisdiv>
5161 <funcsynopsis>
5162 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5163 <funcprototype>
5164 <funcdef>LqrRetVal <function>lqr_vmap_load</function></funcdef>
5165 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
5166 <paramdef>LqrVMap* <parameter>vmap</parameter></paramdef>
5167 </funcprototype>
5168 </funcsynopsis>
5169 </refsynopsisdiv>
5170
5171 <refsect1>
5172 <title>Description</title>
5173 <para>
5174 The function <function>lqr_vmap_load</function> loads the visibility map contained in the
5175 &vmap_obj; object pointed to by <parameter>vmap</parameter> in the &carv_obj; object pointed to
5176 by <parameter>carver</parameter>.
5177 </para>
5178 <para>
5179 It can only be called over uninitialised carver objects, therefore care must be taken not to
5180 exceed the loaded map depth when resizing (see the &vmap_obj; objects format description in the
5181 page for <xref linkend="ref-lqr-vmap-new"></xref>).
5182 </para>
5183 <refsect1>
5184
5185 </refsect1>
5186 <title>Return value</title>
5187 <para>
5188 The return value follows the &lqrl; signalling system.
5189 </para>
5190 </refsect1>
5191
5192 <refsect1>
5193 <title>See also</title>
5194 <para>
5195 <simplelist type="inline">
5196 <member><xref linkend="ref-lqr-ret-val"></xref></member>
5197 <member><xref linkend="ref-lqr-vmap-new"></xref></member>
5198 <member><xref linkend="ref-lqr-vmap-dump"></xref></member>
5199 <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
5200 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
5201 </simplelist>
5202 </para>
5203 </refsect1>
5204 </refentry>
5205
5206 <refentry id="ref-lqr-vmap-list-start">
5207 <refmeta>
5208 <refentrytitle><function>lqr_vmap_list_start</function></refentrytitle>
5209 <manvolnum>3</manvolnum>
5210 </refmeta>
5211
5212 <refnamediv>
5213 <refname>lqr_vmap_list_start</refname>
5214 <refpurpose>get the &vmapl_obj; list attached to an &carv_obj;</refpurpose>
5215 </refnamediv>
5216 <refsynopsisdiv>
5217 <funcsynopsis>
5218 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5219 <funcprototype>
5220 <funcdef>LqrVMapList* <function>lqr_vmap_list_start</function></funcdef>
5221 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
5222 </funcprototype>
5223 </funcsynopsis>
5224 </refsynopsisdiv>
5225
5226 <refsect1>
5227 <title>Description</title>
5228 <para>
5229 The function <function>lqr_vmap_list_start</function> returns the stating point of the
5230 &vmapl_obj; object associated with the &carv_obj; object pointed to by
5231 <parameter>carver</parameter>, which is used to keep track of the &vmap_obj; objects internally
5232 dumped by it.
5233 </para>
5234 <para>
5235 The returned value is &ret_null; if there are no dumped visibility maps.
5236 </para>
5237 <para>
5238 The function <function>lqr_vmap_list_current</function> returns the &vmap_obj; object
5239 corresponding to the current value of the <parameter>list</parameter> parameter, or &ret_null;
5240 in case of errors.
5241 </para>
5242 <para>
5243 Use the functions <xref linkend="ref-lqr-vmap-list-current"></xref> and
5244 <xref linkend="ref-lqr-vmap-list-next"></xref> to access the list element individually, or the
5245 function <xref linkend="ref-lqr-vmap-list-foreach"></xref> to operate on whole lists.
5246 </para>
5247 </refsect1>
5248
5249 <refsect1>
5250 <title>See also</title>
5251 <para>
5252 <simplelist type="inline">
5253 <member><xref linkend="ref-lqr-vmap-list-current"></xref></member>
5254 <member><xref linkend="ref-lqr-vmap-list-next"></xref></member>
5255 <member><xref linkend="ref-lqr-vmap-list-foreach"></xref></member>
5256 <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
5257 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
5258 </simplelist>
5259 </para>
5260 </refsect1>
5261 </refentry>
5262
5263 <refentry id="ref-lqr-vmap-list-current">
5264 <refmeta>
5265 <refentrytitle><function>lqr_vmap_list_current</function></refentrytitle>
5266 <manvolnum>3</manvolnum>
5267 </refmeta>
5268
5269 <refnamediv>
5270 <refname>lqr_vmap_list_current</refname>
5271 <refpurpose>get current &vmap_obj; object in a &vmapl_obj; object</refpurpose>
5272 </refnamediv>
5273 <refsynopsisdiv>
5274 <funcsynopsis>
5275 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5276 <funcprototype>
5277 <funcdef>LqrVMap <function>lqr_vmap_list_current</function></funcdef>
5278 <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
5279 </funcprototype>
5280 </funcsynopsis>
5281 </refsynopsisdiv>
5282
5283 <refsect1>
5284 <title>Description</title>
5285 <para>
5286 The function <function>lqr_vmap_list_current</function> returns the &vmap_obj; object
5287 corresponding to the current value of the <parameter>list</parameter> parameter, or &ret_null;
5288 in case of errors.
5289 </para>
5290 </refsect1>
5291
5292 <refsect1>
5293 <title>See also</title>
5294 <para>
5295 <simplelist type="inline">
5296 <member><xref linkend="ref-lqr-vmap-list-start"></xref></member>
5297 <member><xref linkend="ref-lqr-vmap-list-next"></xref></member>
5298 <member><xref linkend="ref-lqr-vmap-list-foreach"></xref></member>
5299 <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
5300 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
5301 </simplelist>
5302 </para>
5303 </refsect1>
5304 </refentry>
5305
5306 <refentry id="ref-lqr-vmap-list-next">
5307 <refmeta>
5308 <refentrytitle><function>lqr_vmap_list_next</function></refentrytitle>
5309 <manvolnum>3</manvolnum>
5310 </refmeta>
5311
5312 <refnamediv>
5313 <refname>lqr_vmap_list_next</refname>
5314 <refpurpose>advance the &vmapl_obj; object</refpurpose>
5315 </refnamediv>
5316 <refsynopsisdiv>
5317 <funcsynopsis>
5318 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5319 <funcprototype>
5320 <funcdef>LqrVMapList <function>lqr_vmap_list_next</function></funcdef>
5321 <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
5322 </funcprototype>
5323 </funcsynopsis>
5324 </refsynopsisdiv>
5325
5326 <refsect1>
5327 <title>Description</title>
5328 <para>
5329 The function <function>lqr_vmap_list_next</function> returns a pointer the next dumped
5330 &vmap_obj; object in <parameter>list</parameter>, or &ret_null; if the list has reached the end.
5331 </para>
5332 </refsect1>
5333
5334 <refsect1>
5335 <title>See also</title>
5336 <para>
5337 <simplelist type="inline">
5338 <member><xref linkend="ref-lqr-vmap-list-start"></xref></member>
5339 <member><xref linkend="ref-lqr-vmap-list-current"></xref></member>
5340 <member><xref linkend="ref-lqr-vmap-list-foreach"></xref></member>
5341 <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
5342 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
5343 </simplelist>
5344 </para>
5345 </refsect1>
5346 </refentry>
5347
5348 <refentry id="ref-lqr-vmap-list-foreach">
5349 <refmeta>
5350 <refentrytitle><function>lqr_vmap_list_foreach</function></refentrytitle>
5351 <manvolnum>3</manvolnum>
5352 </refmeta>
5353
5354 <refnamediv>
5355 <refname>lqr_vmap_list_foreach</refname>
5356 <refpurpose>perform operations on all &vmap_obj; objects in an &vmapl_obj; object</refpurpose>
5357 </refnamediv>
5358 <refsynopsisdiv>
5359 <funcsynopsis>
5360 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5361 <funcprototype>
5362 <funcdef>LqrRetVal <function>lqr_vmap_list_foreach</function></funcdef>
5363 <paramdef>LqrVMapList* <parameter>list</parameter></paramdef>
5364 <paramdef>LqrVMapFunc <parameter>func</parameter></paramdef>
5365 <paramdef>gpointer <parameter>data</parameter></paramdef>
5366 </funcprototype>
5367 </funcsynopsis>
5368 </refsynopsisdiv>
5369
5370 <refsect1>
5371 <title>Description</title>
5372 <para>
5373 The function <function>lqr_vmap_list_foreach</function> can be used to apply the function
5374 <parameter>func</parameter> to all the &vmap_obj; objects listed in <parameter>list</parameter>.
5375 The parameter <parameter>data</parameter> is used to pass arguments to the function.
5376 </para>
5377 <para>
5378 The <parameter>list</parameter> value should be obtained through the function
5379 <xref linkend="ref-lqr-vmap-list-start"></xref>.
5380 </para>
5381 <para>
5382 The function <parameter>func</parameter> is of type <classname>LqrVMapFunc</classname>, whose
5383 prototype is defined by:
5384 <programlisting>
5385 typedef LqrRetVal (*LqrVMapFunc) (LqrVMap *vmap, gpointer data);
5386 </programlisting>
5387 The <parameter>data</parameter> argument is of type <structname>gpointer</structname>, which is
5388 just a pointer to <literal><type>void</type></literal>.
5389 </para>
5390 </refsect1>
5391
5392 <refsect1>
5393 <title>See also</title>
5394 <para>
5395 <simplelist type="inline">
5396 <member><xref linkend="ref-lqr-ret-val"></xref></member>
5397 <member><xref linkend="ref-lqr-vmap-list-start"></xref></member>
5398 <member><xref linkend="ref-lqr-vmap-list-current"></xref></member>
5399 <member><xref linkend="ref-lqr-vmap-list-next"></xref></member>
5400 <member><xref linkend="ref-lqr-vmap-internal-dump"></xref></member>
5401 <member><xref linkend="ref-lqr-carver-set-dump-vmaps"></xref></member>
5402 </simplelist>
5403 </para>
5404 </refsect1>
5405
5406 </refentry>
5407 </sect1>
5408
5409 <sect1 id="ref-energy">
5410 <title>Energy</title>
5411
5412 <refentry id="ref-lqr-carver-set-energy-function-builtin">
5413 <refmeta>
5414 <refentrytitle><function>lqr_carver_set_energy_function_builtin</function></refentrytitle>
5415 <manvolnum>3</manvolnum>
5416 </refmeta>
5417
5418 <refnamediv>
5419 <refname>lqr_carver_bias_set_energy_function_builtin</refname>
5420 <refpurpose>set a builtin energy function for a &carv_obj; object</refpurpose>
5421 </refnamediv>
5422
5423 <refsynopsisdiv>
5424 <funcsynopsis>
5425 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5426 <funcprototype>
5427 <funcdef>LqrRetVal <function>lqr_carver_set_energy_function_builtin</function></funcdef>
5428 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
5429 <paramdef>LqrEnergyFuncBuiltinType <parameter>ef_ind</parameter></paramdef>
5430 </funcprototype>
5431 </funcsynopsis>
5432 </refsynopsisdiv>
5433
5434 <refsect1>
5435 <title>Description</title>
5436
5437 <para>
5438 The function <function>lqr_carver_set_energy_function_builtin</function> allows to pick a
5439 builtin energy function for the &carv_obj; object pointed to by <parameter>carver</parameter>.
5440 </para>
5441 <para>
5442 The possible values for <parameter>ef_ind</parameter> are:
5443 <variablelist>
5444 <varlistentry>
5445 <term><literal>LQR_EF_GRAD_XABS</literal></term>
5446 <listitem>
5447 <para>
5448 absolute value of the brightness gradient in the direction of the rescaling
5449 (this is the default)
5450 </para>
5451 </listitem>
5452 </varlistentry>
5453 <varlistentry>
5454 <term><literal>LQR_EF_GRAD_SUMABS</literal></term>
5455 <listitem>
5456 <para>
5457 sum of absolute values of the brightness gradients in both directions
5458 </para>
5459 </listitem>
5460 </varlistentry>
5461 <varlistentry>
5462 <term><literal>LQR_EF_GRAD_NORM</literal></term>
5463 <listitem>
5464 <para>
5465 norm of the brightness gradient
5466 </para>
5467 </listitem>
5468 </varlistentry>
5469 <varlistentry>
5470 <term><literal>LQR_EF_LUMA_GRAD_XABS</literal></term>
5471 <listitem>
5472 <para>
5473 absolute value of the luma gradient in the direction of the rescaling
5474 </para>
5475 </listitem>
5476 </varlistentry>
5477 <varlistentry>
5478 <term><literal>LQR_EF_LUMA_GRAD_SUMABS</literal></term>
5479 <listitem>
5480 <para>
5481 sum of absolute values of the luma gradients in both directions
5482 </para>
5483 </listitem>
5484 </varlistentry>
5485 <varlistentry>
5486 <term><literal>LQR_EF_LUMA_GRAD_NORM</literal></term>
5487 <listitem>
5488 <para>
5489 norm of the luma gradient
5490 </para>
5491 </listitem>
5492 </varlistentry>
5493 <varlistentry>
5494 <term><literal>LQR_EF_NULL</literal></term>
5495 <listitem>
5496 <para>
5497 null
5498 </para>
5499 </listitem>
5500 </varlistentry>
5501 </variablelist>
5502 </para>
5503 <para>
5504 All of the above gradient functions have a radius of 1 pixel.
5505 </para>
5506 </refsect1>
5507
5508 <refsect1>
5509 <title>Return value</title>
5510 <para>
5511 The return value follows the &lqrl; signalling system.
5512 </para>
5513 </refsect1>
5514
5515 <refsect1>
5516 <title>See also</title>
5517 <para>
5518 <simplelist type="inline">
5519 <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
5520 <member><xref linkend="ref-lqr-carver-get-energy"></xref></member>
5521 </simplelist>
5522 </para>
5523 </refsect1>
5524 </refentry>
5525
5526 <refentry id="ref-lqr-carver-set-energy-function">
5527 <refmeta>
5528 <refentrytitle><function>lqr_carver_set_energy_function</function></refentrytitle>
5529 <manvolnum>3</manvolnum>
5530 </refmeta>
5531
5532 <refnamediv>
5533 <refname>lqr_carver_bias_set_energy_function</refname>
5534 <refpurpose>set a custom energy function for a &carv_obj; object</refpurpose>
5535 </refnamediv>
5536
5537 <refsynopsisdiv>
5538 <funcsynopsis>
5539 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5540 <funcprototype>
5541 <funcdef>LqrRetVal <function>lqr_carver_set_energy_function</function></funcdef>
5542 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
5543 <paramdef>LqrEnergyFunc <parameter>en_func</parameter></paramdef>
5544 <paramdef>gint <parameter>radius</parameter></paramdef>
5545 <paramdef>LqrEnergyReaderType <parameter>reader_type</parameter></paramdef>
5546 <paramdef>gpointer <parameter>extra_data</parameter></paramdef>
5547
5548 </funcprototype>
5549 </funcsynopsis>
5550 </refsynopsisdiv>
5551
5552 <refsect1>
5553 <title>Description</title>
5554
5555 <para>
5556 The function <function>lqr_carver_set_energy_function</function> assigns the energy function
5557 <parameter>en_func</parameter> to the &carv_obj; object pointed to by
5558 <parameter>carver</parameter> (see below for more details on custom functions definitions).
5559 </para>
5560 <para>
5561 The parameter <parameter>radius</parameter> determines the size of the square region which
5562 affects the computation around each pixel (the side of the square will be <literal>2 *
5563 <parameter>radius</parameter> + 1</literal> pixels long).
5564 </para>
5565 <para>
5566 The parameter <parameter>reader_type</parameter> sets the reader type used when reading the
5567 image, and therefore it determines what quantity will be passed on to the function
5568 <parameter>en_func</parameter> (see below for more details on reader types).
5569 </para>
5570 <para>
5571 The parameter <parameter>extra_data</parameter> is a (void) pointer which can be used to pass on
5572 additional values to the function <parameter>ef_func</parameter>.
5573 </para>
5574 </refsect1>
5575
5576 <refsect1>
5577 <title>Custom functions definition</title>
5578
5579 <para>
5580 The function <parameter>en_func</parameter> must be of type
5581 <classname>LqrEnergyFunc</classname>, whose prototype is defined by:
5582 <programlisting>
5583 typedef gfloat (*LqrEnergyFunc) (gint x, gint y, gint img_width, gint img_height, LqrReadingWindow * rwindow, gpointer extra_data);
5584 </programlisting>
5585 Such a function is expected to compute the energy at pixel &param_x;, &param_y; based on the
5586 knowledge of the current image size (obtained from &param_w; and &param_h;) and the content of
5587 the image in a square around that pixel, which is passed through the
5588 <parameter>rwindow</parameter> reading window.
5589 </para>
5590 <para>
5591 In most cases, the parameters &param_x;, &param_y;, &param_w; and &param_h; would only be used
5592 to determine whether the region under consideration is at the image boundary or not.
5593 </para>
5594 <para>
5595 The <parameter>rwindow</parameter> content must be read using the function
5596 <xref linkend="ref-lqr-rwindow-read"></xref>.
5597 </para>
5598 </refsect1>
5599
5600 <refsect1>
5601 <title>Reader types</title>
5602
5603 <para>
5604 The <type><literal>LqrEnergyReaderType</literal></type> is an enum which can take these values
5605 (also noted is the number of channels of the corresponging reading window):
5606 <variablelist>
5607 <varlistentry>
5608 <term><literal>LQR_ER_BRIGHTNESS</literal></term>
5609 <listitem>
5610 <para>
5611 brightness (1 channel)
5612 </para>
5613 </listitem>
5614 </varlistentry>
5615 <varlistentry>
5616 <term><literal>LQR_ER_BRIGHTNESS</literal></term>
5617 <listitem>
5618 <para>
5619 luma (1 channel)
5620 </para>
5621 </listitem>
5622 </varlistentry>
5623 <varlistentry>
5624 <term><literal>LQR_ER_RGBA</literal></term>
5625 <listitem>
5626 <para>
5627 RGBA (4 channels)
5628 </para>
5629 </listitem>
5630 </varlistentry>
5631 <varlistentry>
5632 <term><literal>LQR_ER_CUSTOM</literal></term>
5633 <listitem>
5634 <para>
5635 read the normalised image channels as they are (as many channels as the image has)
5636 </para>
5637 </listitem>
5638 </varlistentry>
5639 </variablelist>
5640 These readouts always return values beetween <literal>0</literal> and <literal>1</literal>.
5641 </para>
5642 <para>
5643 Note that these readouts may have special meanings depending on the image type:
5644 <itemizedlist>
5645 <listitem>
5646 <para>
5647 for <literal>LQR_GREY_IMAGE</literal>, <literal>LQR_GREYA_IMAGE</literal> and
5648 <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_LUMA</literal>
5649 readout will yield the same result as <literal>LQR_ER_BRIGHTNESS</literal>
5650 </para>
5651 </listitem>
5652 <listitem>
5653 <para>
5654 for <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_BRIGHTNESS</literal>
5655 readout will return the average pixel value (additive, i.e. if a black channel is
5656 present the channel values will be inverted and multiplied by the black channel
5657 inverse), multiplied by the alpha channel value.
5658 </para>
5659 </listitem>
5660 <listitem>
5661 <para>
5662 for <literal>LQR_CUSTOM_IMAGE</literal> images, the <literal>LQR_ER_RGBA</literal>
5663 readout <emphasis>cannot be used</emphasis>: it will always return
5664 <literal>0</literal>
5665 </para>
5666 </listitem>
5667 </itemizedlist>
5668 </para>
5669 </refsect1>
5670
5671 <refsect1>
5672 <title>Return value</title>
5673 <para>
5674 The return value follows the &lqrl; signalling system.
5675 </para>
5676 </refsect1>
5677
5678 <refsect1>
5679 <title>See also</title>
5680 <para>
5681 <simplelist type="inline">
5682 <member><xref linkend="ref-lqr-carver-set-energy-function-builtin"></xref></member>
5683 <member><xref linkend="ref-lqr-carver-get-energy"></xref></member>
5684 <member><xref linkend="ref-lqr-rwindow-read"></xref></member>
5685 <member><xref linkend="ref-lqr-rwindow-get-read-t"></xref></member>
5686 <member><xref linkend="ref-lqr-rwindow-get-radius"></xref></member>
5687 <member><xref linkend="ref-lqr-rwindow-get-channels"></xref></member>
5688 </simplelist>
5689 </para>
5690 </refsect1>
5691 </refentry>
5692
5693 <refentry id="ref-lqr-carver-get-energy">
5694 <refmeta>
5695 <refentrytitle><function>lqr_carver_get_energy</function></refentrytitle>
5696 <manvolnum>3</manvolnum>
5697 </refmeta>
5698
5699 <refnamediv>
5700 <refname>lqr_carver_get_energy</refname>
5701 <refname>lqr_carver_get_true_energy</refname>
5702 <refname>lqr_carver_get_energy_image</refname>
5703 <refpurpose>get the energy map for a &carv_obj; object</refpurpose>
5704 </refnamediv>
5705
5706 <refsynopsisdiv>
5707 <funcsynopsis>
5708 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5709 <funcprototype>
5710 <funcdef>LqrRetVal <function>lqr_carver_get_energy</function></funcdef>
5711 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
5712 <paramdef>gfloat * <parameter>buffer</parameter></paramdef>
5713 <paramdef>gint <parameter>orientation</parameter></paramdef>
5714 </funcprototype>
5715 </funcsynopsis>
5716 </refsynopsisdiv>
5717
5718 <refsynopsisdiv>
5719 <funcsynopsis>
5720 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5721 <funcprototype>
5722 <funcdef>LqrRetVal <function>lqr_carver_get_true_energy</function></funcdef>
5723 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
5724 <paramdef>gfloat * <parameter>buffer</parameter></paramdef>
5725 <paramdef>gint <parameter>orientation</parameter></paramdef>
5726 </funcprototype>
5727 </funcsynopsis>
5728 </refsynopsisdiv>
5729
5730 <refsynopsisdiv>
5731 <funcsynopsis>
5732 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5733 <funcprototype>
5734 <funcdef>LqrRetVal <function>lqr_carver_get_energy</function></funcdef>
5735 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
5736 <paramdef>void * <parameter>buffer</parameter></paramdef>
5737 <paramdef>gint <parameter>orientation</parameter></paramdef>
5738 <paramdef>LqrColDepth <parameter>col_depth</parameter></paramdef>
5739 <paramdef>LqrImageType <parameter>image_type</parameter></paramdef>
5740 </funcprototype>
5741 </funcsynopsis>
5742 </refsynopsisdiv>
5743
5744 <refsect1>
5745 <title>Description</title>
5746
5747 <para>
5748 The function <function>lqr_carver_get_energy</function> writes the energy map of the &carv_obj;
5749 object pointed to by <parameter>carver</parameter> to the given <parameter>buffer</parameter>,
5750 in a format suitable for plotting: all values are in the range between <literal>0</literal> and
5751 <literal>1</literal>, and the true values are mapped nonlinearly and stretched on this whole
5752 range, so that the differences between the middle values are enhanced with respect to very high
5753 or very low values.
5754 </para>
5755 <para>
5756 The <parameter>orientation</parameter> parameter must be either <literal>0</literal> to get the
5757 energy map used for horizontal scalings, or <literal>1</literal> to get the map for vertical
5758 scalings.
5759 </para>
5760 <para>
5761 The buffer must be allocated by the user before calling this function, and its size must be at
5762 least <literal>&param_w; * &param_h;</literal>, where &param_w; and &param_h; are the current
5763 width and height of the <parameter>carver</parameter>. The energy values are ordered by row
5764 first, then by column.
5765 </para>
5766 <para>
5767 The outcome will include the effect of the bias added to the <parameter>carver</parameter>, if
5768 any.
5769 </para>
5770 <para>
5771 This function can be called over non-initialised &carv_obj; objects, e.g. to provide previews on
5772 the effect of different energy functions, but it can also be invoked at any later time. Note,
5773 however, that in this latter case the <parameter>carver</parameter> could be flattened if
5774 necessary, therefore the function invocation is potentially destructive of the internal
5775 visibiliy map.
5776 </para>
5777 <para>
5778 The function <function>lqr_carvet_get_true_energy</function> is identical to the previous one,
5779 but the resulting buffer will contain the true energy, not scaled nor shifted.
5780 </para>
5781 <para>
5782 The function <function>lqr_carver_get_energy_image</function> is very similar to the function
5783 <function>lqr_carveR_get_energy</function>, but it can be used to fill directly an image buffer
5784 of the format specified through the additional parameters <parameter>col_depth</parameter> and
5785 <parameter>image_type</parameter> (see <xref linkend="ref-lqr-col-depth"></xref> and
5786 <xref linkend="ref-lqr-image-type"></xref>). The <parameter>buffer</parameter> must be passed as
5787 <type>void*</type>, but it must point to a memory area with sufficient allocated space for the
5788 chosen image type and colour depth. The image type cannot be &img_type_custom;.
5789 </para>
5790 <para>
5791 For any choice of the parameters describing the image, the resulting
5792 <parameter>buffer</parameter> will hold a greyscale image, ranging from black (lowest energy) to
5793 white (highest energy). The opacity (alpha) will be set to <literal>1</literal>, if present. All
5794 the information will be stored in the black channel in &img_type_cmyk; and &img_type_cmyka;
5795 image types.
5796 </para>
5797
5798 </refsect1>
5799
5800 <refsect1>
5801 <title>Return values</title>
5802 <para>
5803 The return values follow the &lqrl; signalling system. The function
5804 <function>lqr_carver_get_energy_image</function> will return an error if
5805 <parameter>image_type</parameter> is &img_type_custom;.
5806 </para>
5807 </refsect1>
5808
5809 <refsect1>
5810 <title>See also</title>
5811 <para>
5812 <simplelist type="inline">
5813 <member><xref linkend="ref-lqr-carver-set-energy-function-builtin"></xref></member>
5814 <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
5815 <member><xref linkend="ref-lqr-carver-bias-add"></xref></member>
5816 </simplelist>
5817 </para>
5818 </refsect1>
5819 </refentry>
5820
5821 <refentry id="ref-lqr-rwindow-read">
5822 <refmeta>
5823 <refentrytitle><function>lqr_rwindow_read</function></refentrytitle>
5824 <manvolnum>3</manvolnum>
5825 </refmeta>
5826
5827 <refnamediv>
5828 <refname>lqr_rwindow_read</refname>
5829 <refpurpose>read the content of a &rwin_obj; object</refpurpose>
5830 </refnamediv>
5831
5832 <refsynopsisdiv>
5833 <funcsynopsis>
5834 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5835 <funcprototype>
5836 <funcdef>gfloat <function>lqr_rwindow_read</function></funcdef>
5837 <paramdef>LqrReadingWindow* <parameter>rwindow</parameter></paramdef>
5838 <paramdef>gint <parameter>x</parameter></paramdef>
5839 <paramdef>gint <parameter>y</parameter></paramdef>
5840 <paramdef>gint <parameter>channel</parameter></paramdef>
5841 </funcprototype>
5842 </funcsynopsis>
5843 </refsynopsisdiv>
5844
5845 <refsect1>
5846 <title>Description</title>
5847
5848 <para>
5849 The function <function>lqr_rwindow_read</function> returns the content of the reading window
5850 <parameter>rwindow</parameter> at point &param_x;, &param_y; and at channel
5851 <parameter>channel</parameter>.
5852 </para>
5853 <para>
5854 The coordinates &param_x; and &param_y; are relative to the <parameter>rwindow</parameter>
5855 centre, and they both can range from <literal>-radius</literal> to <literal>radius</literal>
5856 (extremes included), where <literal>radius</literal> can be obtained with the function
5857 <xref linkend="ref-lqr-rwindow-get-radius"></xref>.
5858 </para>
5859 <para>
5860 The function returns <literal>0</literal> when the coordinates are out of range, either because
5861 they are beyond the <parameter>rwindow</parameter> radius or because they are outside the image
5862 boundary.
5863 </para>
5864 <para>
5865 The <parameter>channel</parameter> parameter specifies which channel to read out; depending on
5866 the <parameter>rwindow</parameter> reader type, the range and meaning of this parameter changes:
5867 for the cases <literal>LQR_ER_BRIGHTNESS</literal> and <literal>LQR_ER_LUMA</literal> it must be
5868 <literal>0</literal>, because the readout consists of a single channel, for
5869 <literal>LQR_ER_RGBA</literal> it must be between <literal>0</literal> and <literal>3</literal>
5870 (and then the readout will contain the RGBA information), while for
5871 <literal>LQR_ER_CUSTOM</literal> it must be one of the original image channels.
5872 </para>
5873 </refsect1>
5874
5875 <refsect1>
5876 <title>See also</title>
5877 <para>
5878 <simplelist type="inline">
5879 <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
5880 <member><xref linkend="ref-lqr-rwindow-get-read-t"></xref></member>
5881 <member><xref linkend="ref-lqr-rwindow-get-radius"></xref></member>
5882 <member><xref linkend="ref-lqr-rwindow-get-channels"></xref></member>
5883 </simplelist>
5884 </para>
5885 </refsect1>
5886 </refentry>
5887
5888 <refentry id="ref-lqr-rwindow-get-read-t">
5889 <refmeta>
5890 <refentrytitle><function>lqr_rwindow_get_read_t</function></refentrytitle>
5891 <manvolnum>3</manvolnum>
5892 </refmeta>
5893
5894 <refnamediv>
5895 <refname>lqr_rwindow_get_read_t</refname>
5896 <refpurpose>get the reader type of a &rwin_obj; object</refpurpose>
5897 </refnamediv>
5898
5899 <refsynopsisdiv>
5900 <funcsynopsis>
5901 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5902 <funcprototype>
5903 <funcdef>LqrEnergyReaderType <function>lqr_rwindow_get_read_t</function></funcdef>
5904 <paramdef>LqrReadingWindow* <parameter>rwindow</parameter></paramdef>
5905 </funcprototype>
5906 </funcsynopsis>
5907 </refsynopsisdiv>
5908
5909 <refsect1>
5910 <title>Description</title>
5911
5912 <para>
5913 The function <function>lqr_rwindow_get_read_t</function> returns the reader type associated with
5914 the reading window <parameter>rwindow</parameter>.
5915 </para>
5916 <para>
5917 The reader types are described in the page for
5918 <xref linkend="ref-lqr-carver-set-energy-function"></xref>.
5919 </para>
5920 </refsect1>
5921
5922 <refsect1>
5923 <title>See also</title>
5924 <para>
5925 <simplelist type="inline">
5926 <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
5927 <member><xref linkend="ref-lqr-rwindow-read"></xref></member>
5928 <member><xref linkend="ref-lqr-rwindow-get-radius"></xref></member>
5929 <member><xref linkend="ref-lqr-rwindow-get-channels"></xref></member>
5930 </simplelist>
5931 </para>
5932 </refsect1>
5933 </refentry>
5934
5935 <refentry id="ref-lqr-rwindow-get-radius">
5936 <refmeta>
5937 <refentrytitle><function>lqr_rwindow_get_radius</function></refentrytitle>
5938 <manvolnum>3</manvolnum>
5939 </refmeta>
5940
5941 <refnamediv>
5942 <refname>lqr_rwindow_get_radius</refname>
5943 <refpurpose>get the size of the region accessible from a &rwin_obj; object</refpurpose>
5944 </refnamediv>
5945
5946 <refsynopsisdiv>
5947 <funcsynopsis>
5948 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5949 <funcprototype>
5950 <funcdef>gint <function>lqr_rwindow_get_radius</function></funcdef>
5951 <paramdef>LqrReadingWindow* <parameter>rwindow</parameter></paramdef>
5952 </funcprototype>
5953 </funcsynopsis>
5954 </refsynopsisdiv>
5955
5956 <refsect1>
5957 <title>Description</title>
5958
5959 <para>
5960 The function <function>lqr_rwindow_get_radius</function> returns the radius of the region
5961 accessible through the reading window <parameter>rwindow</parameter>.
5962 </para>
5963 <para>
5964 The region is a square of size <literal>2 * <parameter>radius</parameter> - 1</literal> pixels.
5965 </para>
5966 </refsect1>
5967
5968 <refsect1>
5969 <title>See also</title>
5970 <para>
5971 <simplelist type="inline">
5972 <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
5973 <member><xref linkend="ref-lqr-rwindow-read"></xref></member>
5974 <member><xref linkend="ref-lqr-rwindow-get-read-t"></xref></member>
5975 <member><xref linkend="ref-lqr-rwindow-get-channels"></xref></member>
5976 </simplelist>
5977 </para>
5978 </refsect1>
5979 </refentry>
5980
5981 <refentry id="ref-lqr-rwindow-get-channels">
5982 <refmeta>
5983 <refentrytitle><function>lqr_rwindow_get_channels</function></refentrytitle>
5984 <manvolnum>3</manvolnum>
5985 </refmeta>
5986
5987 <refnamediv>
5988 <refname>lqr_rwindow_get_channels</refname>
5989 <refpurpose>get the number of channels of a &rwin_obj; object</refpurpose>
5990 </refnamediv>
5991
5992 <refsynopsisdiv>
5993 <funcsynopsis>
5994 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
5995 <funcprototype>
5996 <funcdef>gint <function>lqr_rwindow_get_channels</function></funcdef>
5997 <paramdef>LqrReadingWindow* <parameter>rwindow</parameter></paramdef>
5998 </funcprototype>
5999 </funcsynopsis>
6000 </refsynopsisdiv>
6001
6002 <refsect1>
6003 <title>Description</title>
6004
6005 <para>
6006 The function <function>lqr_rwindow_get_channels</function> returns the number of channels of
6007 reading window <parameter>rwindow</parameter>.
6008 </para>
6009 <para>
6010 This function is actually only necessary when the <parameter>rwindow</parameter> reader type is
6011 <literal>LQR_ER_CUSTOM</literal>.
6012 </para>
6013 <para>
6014 The reader types are described in the page for
6015 <xref linkend="ref-lqr-carver-set-energy-function"></xref>.
6016 </para>
6017 </refsect1>
6018
6019 <refsect1>
6020 <title>See also</title>
6021 <para>
6022 <simplelist type="inline">
6023 <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
6024 <member><xref linkend="ref-lqr-rwindow-read"></xref></member>
6025 <member><xref linkend="ref-lqr-rwindow-get-read-t"></xref></member>
6026 <member><xref linkend="ref-lqr-rwindow-get-radius"></xref></member>
6027 </simplelist>
6028 </para>
6029 </refsect1>
6030 </refentry>
6031
6032 <refentry id="ref-lqr-carver-set-gradient-function">
6033 <refmeta>
6034 <refentrytitle><function>lqr_carver_set_gradient_function</function></refentrytitle>
6035 <manvolnum>3</manvolnum>
6036 </refmeta>
6037
6038 <refnamediv>
6039 <refname>lqr_carver_set_gradient_function</refname>
6040 <refpurpose>set the gradient function for an &carv_obj; object</refpurpose>
6041 </refnamediv>
6042
6043 <refsynopsisdiv>
6044 <funcsynopsis>
6045 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6046 <funcprototype>
6047 <funcdef>void <function>lqr_carver_set_gradient_function</function></funcdef>
6048 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6049 <paramdef>LqrGradFuncType <parameter>gf_ind</parameter></paramdef>
6050 </funcprototype>
6051 </funcsynopsis>
6052 </refsynopsisdiv>
6053
6054 <refsect1>
6055 <title>Description</title>
6056 <para>
6057 The function <function>lqr_carver_set_gradient_function</function> is deprecated and should not
6058 be used in newly written code. The function
6059 <xref linkend="ref-lqr-carver-set-energy-function-builtin"></xref> should be used instead.
6060 </para>
6061 <para>
6062 The function <function>lqr_carver_set_gradient_function</function> is still maintained for
6063 backwards compatibility reasons; its result is equivalent to calling
6064 <function>lqr_carver_set_energy_function_builtin</function>, with the following mapping between
6065 the argument <parameter>gs_ind</parameter> of the former and the argument
6066 <parameter>ef_ind</parameter> of the latter:
6067 <informaltable id="ref-gs-ef-mapping">
6068 <tgroup cols="2">
6069 <thead>
6070 <row>
6071 <entry><type><literal>LqrGradFuncType</literal></type></entry>
6072 <entry><type><literal>LqrEnergyFuncBuiltinType</literal></type></entry>
6073 </row>
6074 </thead>
6075 <tbody>
6076 <row>
6077 <entry><literal>LQR_GF_XABS</literal></entry>
6078 <entry><literal>LQR_EF_GRAD_XABS</literal></entry>
6079 </row>
6080 <row>
6081 <entry><literal>LQR_GF_SUMABS</literal></entry>
6082 <entry><literal>LQR_EF_GRAD_SUMABS</literal></entry>
6083 </row>
6084 <row>
6085 <entry><literal>LQR_GF_NORM</literal></entry>
6086 <entry><literal>LQR_EF_GRAD_NORM</literal></entry>
6087 </row>
6088 <row>
6089 <entry><literal>LQR_GF_NULL</literal></entry>
6090 <entry><literal>LQR_EF_NULL</literal></entry>
6091 </row>
6092 </tbody>
6093 </tgroup>
6094 </informaltable>
6095 </para>
6096 </refsect1>
6097
6098 <refsect1>
6099 <title>See also</title>
6100 <para>
6101 <simplelist type="inline">
6102 <member><xref linkend="ref-lqr-carver-set-energy-function-builtin"></xref></member>
6103 <member><xref linkend="ref-lqr-carver-set-energy-function"></xref></member>
6104 </simplelist>
6105 </para>
6106 </refsect1>
6107 </refentry>
6108 </sect1>
6109
6110
6111 <sect1 id="ref-bias">
6112 <title>Bias</title>
6113
6114 <refentry id="ref-lqr-carver-bias-add">
6115 <refmeta>
6116 <refentrytitle><function>lqr_carver_bias_add</function></refentrytitle>
6117 <manvolnum>3</manvolnum>
6118 </refmeta>
6119
6120 <refnamediv>
6121 <refname>lqr_carver_bias_add_xy</refname>
6122 <refname>lqr_carver_bias_add_area</refname>
6123 <refname>lqr_carver_bias_add</refname>
6124 <refname>lqr_carver_bias_add_rgb_area</refname>
6125 <refname>lqr_carver_bias_add_rgb</refname>
6126 <refpurpose>update an &carv_obj; bias</refpurpose>
6127 </refnamediv>
6128
6129 <refsynopsisdiv>
6130 <funcsynopsis>
6131 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6132 <funcprototype>
6133 <funcdef>LqrRetVal <function>lqr_carver_bias_add_xy</function></funcdef>
6134 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6135 <paramdef>gdouble <parameter>bias</parameter></paramdef>
6136 <paramdef>gint <parameter>x</parameter></paramdef>
6137 <paramdef>gint <parameter>y</parameter></paramdef>
6138 </funcprototype>
6139 <funcprototype>
6140 <funcdef>LqrRetVal <function>lqr_carver_bias_add_area</function></funcdef>
6141 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6142 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
6143 <paramdef>gint <parameter>bias_factor</parameter></paramdef>
6144 <paramdef>gint <parameter>width</parameter></paramdef>
6145 <paramdef>gint <parameter>height</parameter></paramdef>
6146 <paramdef>gint <parameter>x_off</parameter></paramdef>
6147 <paramdef>gint <parameter>y_off</parameter></paramdef>
6148 </funcprototype>
6149 <funcprototype>
6150 <funcdef>LqrRetVal <function>lqr_carver_bias_add</function></funcdef>
6151 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6152 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
6153 <paramdef>gint <parameter>bias_factor</parameter></paramdef>
6154 </funcprototype>
6155 <funcprototype>
6156 <funcdef>LqrRetVal <function>lqr_carver_bias_add_rgb_area</function></funcdef>
6157 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6158 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
6159 <paramdef>gint <parameter>bias_factor</parameter></paramdef>
6160 <paramdef>gint <parameter>channels</parameter></paramdef>
6161 <paramdef>gint <parameter>width</parameter></paramdef>
6162 <paramdef>gint <parameter>height</parameter></paramdef>
6163 <paramdef>gint <parameter>x_off</parameter></paramdef>
6164 <paramdef>gint <parameter>y_off</parameter></paramdef>
6165 </funcprototype>
6166 <funcprototype>
6167 <funcdef>LqrRetVal <function>lqr_carver_bias_add_rgb</function></funcdef>
6168 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6169 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
6170 <paramdef>gint <parameter>bias_factor</parameter></paramdef>
6171 <paramdef>gint <parameter>channels</parameter></paramdef>
6172 </funcprototype>
6173 </funcsynopsis>
6174 </refsynopsisdiv>
6175
6176 <refsect1>
6177 <title>Foreword</title>
6178
6179 <para>
6180 All the functions described in this page are used to add a bias to &carv_obj; objects. A
6181 positive biased pixel will be more likely to be avoided by seams, and thus be preserved during
6182 rescaling, while a negative bias has the opposite effect.
6183 </para>
6184 <para>
6185 All of these functions must be called before <xref linkend="ref-lqr-carver-resize"></xref>. If
6186 called multiple times, the biases added at each call will sum up.
6187 </para>
6188 </refsect1>
6189
6190 <refsect1>
6191 <title>Adding a bias pixel by pixel</title>
6192
6193 <para>
6194 The function <function>lqr_carver_bias_add_xy</function> adds a bias to the &param_x;, &param_y;
6195 pixel of the image loaded into the &carv_obj; object pointed to by <parameter>carver</parameter>
6196 </para>
6197 <para>
6198 A typical value for <parameter>bias_factor</parameter> would be <literal>1000</literal> (in
6199 absolute value).
6200 </para>
6201 </refsect1>
6202
6203 <refsect1>
6204 <title>Adding a bias from a buffer</title>
6205
6206 <para>
6207 The function <function>lqr_carver_bias_add_area</function> adds a bias to an area of the image
6208 loaded into the &carv_obj; object pointed to by <parameter>carver</parameter>.
6209 </para>
6210 <para>
6211 The parameter <parameter>buffer</parameter> must point to an array of <type>doubles</type> of
6212 size <literal><parameter>width</parameter> * <parameter>height</parameter></literal>, ordered
6213 first by rows, then by columns.
6214 </para>
6215 <para>
6216 The offset of the area relative to the image can be specified through
6217 <parameter>x_off</parameter> and <parameter>y_off</parameter>. The bias area can exceed the
6218 boundary of the image, and the offsets can be negative.
6219 </para>
6220 <para>
6221 The parameter <parameter>bias_factor</parameter> is an overall bias scale. A typical value when
6222 the buffer contents are of the order of <literal>1</literal> would be <literal>1000</literal>
6223 (in absolute value).
6224 </para>
6225 <para>
6226 The function <function>lqr_carver_bias_add</function> can be used when the area to add is of the
6227 same size of the image loaded in the &carv_obj; object and the offsets are <literal>0</literal>.
6228 </para>
6229 </refsect1>
6230
6231 <refsect1>
6232 <title>Adding a bias from an image</title>
6233
6234 <para>
6235 The functions <function>lqr_carver_bias_add_rgb_area</function> and
6236 <function>lqr_carver_bias_add_rgb</function> are very similar to
6237 <function>lqr_carver_bias_add_area</function> and <function>lqr_carver_bias_add</function>,
6238 except that they use 8-bit multi-channel images as inputs.
6239 </para>
6240 <para>
6241 The number of channels in the image is passed via the parameter <parameter>channels</parameter>.
6242 The last channel is assumed to be the alpha (opacity) channel if <parameter>channels</parameter>
6243 is equal to <literal>2</literal> or greater than <literal>3</literal> (if this is not the case,
6244 use the previous functions).
6245 </para>
6246 <para>
6247 The bias is computed from the average of the colour channels, multiplied by the value of the
6248 alpha channel if present. For example, in RGBA images a white, nontransparent pixel is
6249 equivalent to a value of <literal>1.0</literal> when using a buffer in
6250 <function>lqr_carver_bias_add_area</function>.
6251 </para>
6252 </refsect1>
6253
6254 <refsect1>
6255 <title>Return values</title>
6256 <para>
6257 The return values follow the &lqrl; signalling system.
6258 </para>
6259 </refsect1>
6260
6261 <refsect1>
6262 <title>See also</title>
6263 <para>
6264 <simplelist type="inline">
6265 <member><xref linkend="ref-lqr-ret-val"></xref></member>
6266 <member><xref linkend="ref-lqr-carver-init"></xref></member>
6267 <member><xref linkend="ref-lqr-carver-rigmask-add"></xref></member>
6268 </simplelist>
6269 </para>
6270 </refsect1>
6271 </refentry>
6272
6273 <refentry id="ref-lqr-carver-bias-clear">
6274 <refmeta>
6275 <refentrytitle><function>lqr_carver_bias_clear</function></refentrytitle>
6276 <manvolnum>3</manvolnum>
6277 </refmeta>
6278
6279 <refnamediv>
6280 <refname>lqr_carver_bias_clear</refname>
6281 <refpurpose>clear an &carv_obj; bias</refpurpose>
6282 </refnamediv>
6283
6284 <refsynopsisdiv>
6285 <funcsynopsis>
6286 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6287 <funcprototype>
6288 <funcdef>void <function>lqr_carver_bias_clear</function></funcdef>
6289 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6290 </funcprototype>
6291 </funcsynopsis>
6292 </refsynopsisdiv>
6293
6294 <refsect1>
6295 <title>Description</title>
6296
6297 <para>
6298 The function <function>lqr_carver_bias_clear</function> clears the bias from the &carv_obj;
6299 object pointed to by <parameter>carver</parameter>
6300 </para>
6301 </refsect1>
6302
6303 <refsect1>
6304 <title>See also</title>
6305 <para>
6306 <simplelist type="inline">
6307 <member><xref linkend="ref-lqr-carver-bias-add"></xref></member>
6308 </simplelist>
6309 </para>
6310 </refsect1>
6311 </refentry>
6312 </sect1>
6313
6314 <sect1 id="ref-rigmask">
6315 <title>Rigidity masks</title>
6316
6317 <refentry id="ref-lqr-carver-rigmask-add">
6318 <refmeta>
6319 <refentrytitle><function>lqr_carver_rigmask_add</function></refentrytitle>
6320 <manvolnum>3</manvolnum>
6321 </refmeta>
6322
6323 <refnamediv>
6324 <refname>lqr_carver_rigmask_add_xy</refname>
6325 <refname>lqr_carver_rigmask_add_area</refname>
6326 <refname>lqr_carver_rigmask_add</refname>
6327 <refname>lqr_carver_rigmask_add_rgb_area</refname>
6328 <refname>lqr_carver_rigmask_add_rgb</refname>
6329 <refpurpose>update an &carv_obj; rigidity mask</refpurpose>
6330 </refnamediv>
6331
6332 <refsynopsisdiv>
6333 <funcsynopsis>
6334 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6335 <funcprototype>
6336 <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_xy</function></funcdef>
6337 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6338 <paramdef>gdouble <parameter>rigidity</parameter></paramdef>
6339 <paramdef>gint <parameter>x</parameter></paramdef>
6340 <paramdef>gint <parameter>y</parameter></paramdef>
6341 </funcprototype>
6342 <funcprototype>
6343 <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_area</function></funcdef>
6344 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6345 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
6346 <paramdef>gint <parameter>width</parameter></paramdef>
6347 <paramdef>gint <parameter>height</parameter></paramdef>
6348 <paramdef>gint <parameter>x_off</parameter></paramdef>
6349 <paramdef>gint <parameter>y_off</parameter></paramdef>
6350 </funcprototype>
6351 <funcprototype>
6352 <funcdef>LqrRetVal <function>lqr_carver_rigmask_add</function></funcdef>
6353 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6354 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
6355 </funcprototype>
6356 <funcprototype>
6357 <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_area</function></funcdef>
6358 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6359 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
6360 <paramdef>gint <parameter>channels</parameter></paramdef>
6361 <paramdef>gint <parameter>width</parameter></paramdef>
6362 <paramdef>gint <parameter>height</parameter></paramdef>
6363 <paramdef>gint <parameter>x_off</parameter></paramdef>
6364 <paramdef>gint <parameter>y_off</parameter></paramdef>
6365 </funcprototype>
6366 <funcprototype>
6367 <funcdef>LqrRetVal <function>lqr_carver_rigmask_add_rgb</function></funcdef>
6368 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6369 <paramdef>gdouble* <parameter>buffer</parameter></paramdef>
6370 <paramdef>gint <parameter>channels</parameter></paramdef>
6371 </funcprototype>
6372 </funcsynopsis>
6373 </refsynopsisdiv>
6374
6375 <refsect1>
6376 <title>Foreword</title>
6377
6378 <para>
6379 All the functions described in this page are used to add a rigidity mask to &carv_obj; objects.
6380 Whenever one of these functions is called, a rigidity mask is activated for the whole image; the
6381 mask contains coefficients which modulate the value of the rigidity (which is set with
6382 <xref linkend="ref-lqr-carver-init"></xref>) in different areas of the image.
6383 </para>
6384 <para>
6385 It is very important to note that using no rigidity masks at all is equivalent to use a rigidity
6386 mask over the whole image with all the values set to <literal>1.0</literal>, but, when first
6387 adding a rigidity mask to a &carv_obj; object, all the pixels outside the affected area will
6388 have their rigidity set to zero; therefore, the functions
6389 <function>lqr_carver_rigmask_add_xy</function>, <function>lqr_carver_rigmask_add_area</function>
6390 and <function>lqr_carver_rigmask_add_rgb_area</function> actually affect the whole image,
6391 despite their name.
6392 </para>
6393 <para>
6394 All the functions must be called after <function>lqr_carver_init</function> and before
6395 <function>lqr_carver_resize</function>. If called multiple times over the same area, new values
6396 will replace the old ones.
6397 </para>
6398 </refsect1>
6399
6400 <refsect1>
6401 <title>Setting the rigidity mask pixel by pixel</title>
6402
6403 <para>
6404 The function <function>lqr_carver_rigmask_add_xy</function> sets the rigidity mask value of the
6405 &param_x;, &param_y; pixel of the image loaded into the &carv_obj; object pointed to by
6406 <parameter>carver</parameter>
6407 </para>
6408 </refsect1>
6409
6410 <refsect1>
6411 <title>Setting the rigidity mask from a buffer</title>
6412
6413 <para>
6414 The function <function>lqr_carver_rigmask_add_area</function> adds a rigidity mask to an area of
6415 the image loaded in the &carv_obj; object pointed to by <parameter>carver</parameter>.
6416 </para>
6417 <para>
6418 The parameter <parameter>buffer</parameter> must point to an array of <type>doubles</type> of
6419 size <literal><parameter>width</parameter> * <parameter>height</parameter></literal>, ordered
6420 first by rows, then by columns.
6421 </para>
6422 <para>
6423 The offset of the area relative to the image are specified through <parameter>x_off</parameter>
6424 and <parameter>y_off</parameter>. The rigidity mask area can exceed the boundary of the image,
6425 and the offsets can be negative.
6426 </para>
6427 <para>
6428 The values in the given <parameter>buffer</parameter> are scaled by the overall
6429 <parameter>rigidity</parameter> value set when calling the function
6430 <function>lqr_carver_init</function>.
6431 </para>
6432 <para>
6433 The function <function>lqr_carver_rigmask_add</function> can be used when the area to add is of
6434 the same size of the image loaded in the &carv_obj; object and the offsets are
6435 <literal>0</literal>.
6436 </para>
6437 </refsect1>
6438
6439 <refsect1>
6440 <title>Setting the rigidity mask from an image</title>
6441
6442 <para>
6443 The functions <function>lqr_carver_rigmask_add_rgb_area</function> and
6444 <function>lqr_carver_rigmask_add_rgb</function> are very similar to
6445 <function>lqr_carver_rigmask_add_area</function> and
6446 <function>lqr_carver_rigmask_add</function>, but use 8-bit multi-channel images as inputs.
6447 </para>
6448 <para>
6449 The number of channels in the image is passed via the parameter <parameter>channels</parameter>.
6450 The last channel is assumed to be the alpha (opacity) channel if <parameter>channels</parameter>
6451 is equal to <literal>2</literal> or greater than <literal>3</literal> (if this is not the case,
6452 use the previous functions).
6453 </para>
6454 <para>
6455 The rigidity value is computed from the average of the colour channels, multiplied by the value
6456 of the alpha channel if present. For example, in RGBA images a white, nontransparent pixel is
6457 equivalent to a value of <literal>1.0</literal> when using a buffer in
6458 <function>lqr_carver_rigmask_add_area</function>.
6459 </para>
6460 </refsect1>
6461
6462 <refsect1>
6463 <title>Return value</title>
6464 <para>
6465 The return values follow the &lqrl; signalling system.
6466 </para>
6467 </refsect1>
6468
6469 <refsect1>
6470 <title>See also</title>
6471 <para>
6472 <simplelist type="inline">
6473 <member><xref linkend="ref-lqr-ret-val"></xref></member>
6474 <member><xref linkend="ref-lqr-carver-init"></xref></member>
6475 <member><xref linkend="ref-lqr-carver-bias-add"></xref></member>
6476 </simplelist>
6477 </para>
6478 </refsect1>
6479 </refentry>
6480
6481 <refentry id="ref-lqr-carver-rigmask-clear">
6482 <refmeta>
6483 <refentrytitle><function>lqr_carver_rigmask_clear</function></refentrytitle>
6484 <manvolnum>3</manvolnum>
6485 </refmeta>
6486
6487 <refnamediv>
6488 <refname>lqr_carver_rigmask_clear</refname>
6489 <refpurpose>clear an &carv_obj; rigidity mask</refpurpose>
6490 </refnamediv>
6491
6492 <refsynopsisdiv>
6493 <funcsynopsis>
6494 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6495 <funcprototype>
6496 <funcdef>void <function>lqr_carver_rigmask_clear</function></funcdef>
6497 <paramdef>LqrCarver* <parameter>carver</parameter></paramdef>
6498 </funcprototype>
6499 </funcsynopsis>
6500 </refsynopsisdiv>
6501
6502 <refsect1>
6503 <title>Description</title>
6504
6505 <para>
6506 The function <function>lqr_carver_rigmask_clear</function> clears the rigidity mask from the
6507 &carv_obj; object pointed to by <parameter>carver</parameter>
6508 </para>
6509 </refsect1>
6510
6511 <refsect1>
6512 <title>See also</title>
6513 <para>
6514 <simplelist type="inline">
6515 <member><xref linkend="ref-lqr-carver-rigmask-add"></xref></member>
6516 </simplelist>
6517 </para>
6518 </refsect1>
6519 </refentry>
6520 </sect1>
6521
6522 <sect1 id="ref-progress">
6523 <title>Progress reports</title>
6524
6525 <refentry id="ref-lqr-progress-new">
6526 <refmeta>
6527 <refentrytitle><function>lqr_progress_new</function></refentrytitle>
6528 <manvolnum>3</manvolnum>
6529 </refmeta>
6530
6531 <refnamediv>
6532 <refname>lqr_progress_new</refname>
6533 <refpurpose>the &prog_obj; object constructor</refpurpose>
6534 </refnamediv>
6535
6536 <refsynopsisdiv>
6537 <funcsynopsis>
6538 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6539 <funcprototype>
6540 <funcdef>LqrProgress* <function>lqr_progress_new</function></funcdef>
6541 <void></void>
6542 </funcprototype>
6543 </funcsynopsis>
6544 </refsynopsisdiv>
6545
6546 <refsect1>
6547 <title>Description</title>
6548 <para>
6549 The function <function>lqr_progress_new</function> is the constructor for &prog_obj; objects. It
6550 can be used to setup a progress report indicator for rescale operations performed through
6551 <xref linkend="ref-lqr-carver-resize"></xref>.
6552 </para>
6553 <para>
6554 Newly created &prog_obj; objects are inactive, and need to be set up using the functions
6555 <xref linkend="ref-lqr-progress-set-init"></xref>,
6556 <xref linkend="ref-lqr-progress-set-update"></xref> and
6557 <xref linkend="ref-lqr-progress-set-end"></xref>.
6558 </para>
6559 <para>
6560 &prog_obj; objects are associated to &carv_obj; objects using the function
6561 <xref linkend="ref-lqr-carver-set-progress"></xref>
6562 </para>
6563 </refsect1>
6564
6565 <refsect1>
6566 <title>Return value</title>
6567 <para>
6568 The function returns the newly created &prog_obj; if successful, or &ret_null; in case of
6569 insufficient memory.
6570 </para>
6571 </refsect1>
6572
6573 <refsect1>
6574 <title>See also</title>
6575 <para>
6576 <simplelist type="inline">
6577 <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
6578 <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
6579 <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
6580 <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
6581 <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
6582 <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
6583 <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
6584 <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
6585 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
6586 </simplelist>
6587 </para>
6588 </refsect1>
6589 </refentry>
6590
6591 <refentry id="ref-lqr-progress-set-init">
6592 <refmeta>
6593 <refentrytitle><function>lqr_progress_set_init</function></refentrytitle>
6594 <manvolnum>3</manvolnum>
6595 </refmeta>
6596
6597 <refnamediv>
6598 <refname>lqr_progress_set_init</refname>
6599 <refpurpose>execude custom code before each rescaling operation</refpurpose>
6600 </refnamediv>
6601
6602 <refsynopsisdiv>
6603 <funcsynopsis>
6604 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6605 <funcprototype>
6606 <funcdef>LqrRetVal <function>lqr_progress_set_init</function></funcdef>
6607 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
6608 <paramdef>LqrProgressFuncInit <parameter>init_func</parameter></paramdef>
6609 </funcprototype>
6610 </funcsynopsis>
6611 </refsynopsisdiv>
6612
6613 <refsect1>
6614 <title>Description</title>
6615 <para>
6616 The function <function>lqr_progress_set_init</function> sets the hook
6617 <parameter>init_func</parameter> to the &prog_obj; object pointed to by
6618 <parameter>p</parameter>.
6619 </para>
6620 <para>
6621 The function <parameter>init_func</parameter> is of type
6622 <classname>LqrProgressFuncInit</classname>, whose prototype is defined by:
6623 <programlisting>
6624 typedef LqrRetVal (*LqrProgressFuncInit) (const gchar* init_message);
6625 </programlisting>
6626 Each time that the function <xref linkend="ref-lqr-carver-resize"></xref> performs a rescale
6627 operation (recall that it can perform more than one rescale operation at each call) this
6628 function will be called first, with a string argument passed through the parameter
6629 <parameter>init_message</parameter>, which is different for horizontal and vertical rescalings.
6630 </para>
6631 <para>
6632 The message arguments can be set with the functions
6633 <xref linkend="ref-lqr-progress-set-init-width-message"></xref> and
6634 <xref linkend="ref-lqr-progress-set-init-height-message"></xref>.
6635 </para>
6636 <para>
6637 The default values for newly created &prog_obj; objects are:
6638 <variablelist>
6639 <varlistentry>
6640 <term>Horizontal:</term>
6641 <listitem>
6642 <para>
6643 &prog_init_w_mess;
6644 </para>
6645 </listitem>
6646 </varlistentry>
6647 <varlistentry>
6648 <term>Vertical:</term>
6649 <listitem>
6650 <para>
6651 &prog_init_h_mess;
6652 </para>
6653 </listitem>
6654 </varlistentry>
6655 </variablelist>
6656 </para>
6657 </refsect1>
6658
6659 <refsect1>
6660 <title>Return value</title>
6661 <para>
6662 The return value follows the &lqrl; signalling system.
6663 </para>
6664 </refsect1>
6665
6666 <refsect1>
6667 <title>See also</title>
6668 <para>
6669 <simplelist type="inline">
6670 <member><xref linkend="ref-lqr-ret-val"></xref></member>
6671 <member><xref linkend="ref-lqr-progress-new"></xref></member>
6672 <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
6673 <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
6674 <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
6675 <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
6676 <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
6677 <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
6678 <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
6679 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
6680 </simplelist>
6681 </para>
6682 </refsect1>
6683 </refentry>
6684
6685 <refentry id="ref-lqr-progress-set-update">
6686 <refmeta>
6687 <refentrytitle><function>lqr_progress_set_update</function></refentrytitle>
6688 <manvolnum>3</manvolnum>
6689 </refmeta>
6690
6691 <refnamediv>
6692 <refname>lqr_progress_set_update</refname>
6693 <refpurpose>execude custom code at regular steps during each rescaling operation</refpurpose>
6694 </refnamediv>
6695
6696 <refsynopsisdiv>
6697 <funcsynopsis>
6698 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6699 <funcprototype>
6700 <funcdef>LqrRetVal <function>lqr_progress_set_update</function></funcdef>
6701 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
6702 <paramdef>LqrProgressFuncUpdate <parameter>update_func</parameter></paramdef>
6703 </funcprototype>
6704 </funcsynopsis>
6705 </refsynopsisdiv>
6706
6707 <refsect1>
6708 <title>Description</title>
6709 <para>
6710 The function <function>lqr_progress_set_update</function> sets the hook
6711 <parameter>update_func</parameter> to the &prog_obj; object pointed to by
6712 <parameter>p</parameter>.
6713 </para>
6714 <para>
6715 The function <parameter>update_func</parameter> is of type
6716 <classname>LqrProgressFuncUpdate</classname>, whose prototype is defined by:
6717 <programlisting>
6718 typedef LqrRetVal (*LqrProgressFuncUpdate) (gdouble completion_percentage);
6719 </programlisting>
6720 Each time that the function <xref linkend="ref-lqr-carver-resize"></xref> performs a rescale
6721 operation (recall that it can perform more than one rescale operation at each call) this
6722 function will be called at regular intervale, with the current completion percentage
6723 <parameter>completion_percentage</parameter> as an argument.
6724 </para>
6725 <para>
6726 The update step can be set with the function
6727 <xref linkend="ref-lqr-progress-set-update-step"></xref>.
6728 </para>
6729 </refsect1>
6730
6731 <refsect1>
6732 <title>Return value</title>
6733 <para>
6734 The return value follows the &lqrl; signalling system.
6735 </para>
6736 </refsect1>
6737
6738 <refsect1>
6739 <title>See also</title>
6740 <para>
6741 <simplelist type="inline">
6742 <member><xref linkend="ref-lqr-ret-val"></xref></member>
6743 <member><xref linkend="ref-lqr-progress-new"></xref></member>
6744 <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
6745 <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
6746 <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
6747 <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
6748 <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
6749 <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
6750 <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
6751 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
6752 </simplelist>
6753 </para>
6754 </refsect1>
6755 </refentry>
6756
6757 <refentry id="ref-lqr-progress-set-end">
6758 <refmeta>
6759 <refentrytitle><function>lqr_progress_set_end</function></refentrytitle>
6760 <manvolnum>3</manvolnum>
6761 </refmeta>
6762
6763 <refnamediv>
6764 <refname>lqr_progress_set_end</refname>
6765 <refpurpose>execude custom code after each rescaling operation</refpurpose>
6766 </refnamediv>
6767
6768 <refsynopsisdiv>
6769 <funcsynopsis>
6770 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6771 <funcprototype>
6772 <funcdef>LqrRetVal <function>lqr_progress_set_end</function></funcdef>
6773 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
6774 <paramdef>LqrProgressFuncEnd <parameter>end_func</parameter></paramdef>
6775 </funcprototype>
6776 </funcsynopsis>
6777 </refsynopsisdiv>
6778
6779 <refsect1>
6780 <title>Description</title>
6781 <para>
6782 The function <function>lqr_progress_set_end</function> sets the hook
6783 <parameter>end_func</parameter> to the &prog_obj; object pointed to by <parameter>p</parameter>.
6784 </para>
6785 <para>
6786 The function <parameter>end_func</parameter> is of type
6787 <classname>LqrProgressFuncEnd</classname>, whose prototype is defined by:
6788 <programlisting>
6789 typedef LqrRetVal (*LqrProgressFuncEnd) (const gchar* end_message);
6790 </programlisting>
6791 Each time that the function <xref linkend="ref-lqr-carver-resize"></xref> performs a rescale
6792 operation (recall that it can perform more than one rescale operation at each call) this
6793 function will be called at the end, with a string argument passed through the parameter
6794 <parameter>end_message</parameter>, which is different for horizontal and vertical rescalings.
6795 </para>
6796 <para>
6797 The message arguments can be set with the functions
6798 <xref linkend="ref-lqr-progress-set-end-width-message"></xref> and
6799 <xref linkend="ref-lqr-progress-set-end-height-message"></xref>.
6800 </para>
6801 </refsect1>
6802
6803 <refsect1>
6804 <title>Return value</title>
6805 <para>
6806 The return value follows the &lqrl; signalling system.
6807 </para>
6808 </refsect1>
6809
6810 <refsect1>
6811 <title>See also</title>
6812 <para>
6813 <simplelist type="inline">
6814 <member><xref linkend="ref-lqr-ret-val"></xref></member>
6815 <member><xref linkend="ref-lqr-progress-new"></xref></member>
6816 <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
6817 <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
6818 <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
6819 <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
6820 <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
6821 <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
6822 <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
6823 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
6824 </simplelist>
6825 </para>
6826 </refsect1>
6827 </refentry>
6828
6829 <refentry id="ref-lqr-progress-set-update-step">
6830 <refmeta>
6831 <refentrytitle><function>lqr_progress_set_update_step</function></refentrytitle>
6832 <manvolnum>3</manvolnum>
6833 </refmeta>
6834
6835 <refnamediv>
6836 <refname>lqr_progress_set_update_step</refname>
6837 <refpurpose>setup update step for &prog_obj; objects</refpurpose>
6838 </refnamediv>
6839
6840 <refsynopsisdiv>
6841 <funcsynopsis>
6842 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6843 <funcprototype>
6844 <funcdef>LqrRetVal <function>lqr_progress_set_update_step</function></funcdef>
6845 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
6846 <paramdef>gfloat <parameter>update_step</parameter></paramdef>
6847 </funcprototype>
6848 </funcsynopsis>
6849 </refsynopsisdiv>
6850
6851 <refsect1>
6852 <title>Description</title>
6853 <para>
6854 The function <function>lqr_progress_set_update_step</function> sets the update step of the
6855 &prog_obj; pointed to by <parameter>p</parameter> to the value
6856 <parameter>update_step</parameter>.
6857 </para>
6858 <para>
6859 The update step must be between <literal>0</literal> and <literal>1</literal>.
6860 </para>
6861 <para>
6862 The default value is <literal>0.02</literal> (i.e. <literal>2%</literal>).
6863 </para>
6864 </refsect1>
6865
6866 <refsect1>
6867 <title>Return value</title>
6868 <para>
6869 The return value follows the &lqrl; signalling system.
6870 </para>
6871 </refsect1>
6872
6873 <refsect1>
6874 <title>See also</title>
6875 <para>
6876 <simplelist type="inline">
6877 <member><xref linkend="ref-lqr-ret-val"></xref></member>
6878 <member><xref linkend="ref-lqr-progress-new"></xref></member>
6879 <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
6880 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
6881 </simplelist>
6882 </para>
6883 </refsect1>
6884 </refentry>
6885
6886 <refentry id="ref-lqr-progress-set-init-width-message">
6887 <refmeta>
6888 <refentrytitle><function>lqr_progress_set_init_width_message</function></refentrytitle>
6889 <manvolnum>3</manvolnum>
6890 </refmeta>
6891
6892 <refnamediv>
6893 <refname>lqr_progress_set_init_width_message</refname>
6894 <refpurpose>setup width message for init hooks in &prog_obj; objects</refpurpose>
6895 </refnamediv>
6896
6897 <refsynopsisdiv>
6898 <funcsynopsis>
6899 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6900 <funcprototype>
6901 <funcdef>LqrRetVal <function>lqr_progress_set_init_width_message</function></funcdef>
6902 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
6903 <paramdef>const guchar* <parameter>message</parameter></paramdef>
6904 </funcprototype>
6905 </funcsynopsis>
6906 </refsynopsisdiv>
6907
6908 <refsect1>
6909 <title>Description</title>
6910 <para>
6911 The function <function>lqr_progress_set_init_width_message</function> sets the string
6912 <parameter>message</parameter> in the &prog_obj; object pointed to by <parameter>p</parameter>
6913 as the argument when rescaling the width for init hooks set with
6914 <xref linkend="ref-lqr-progress-set-init"></xref>
6915 </para>
6916 <para>
6917 The default value for newly created &prog_obj; objects is: &prog_init_w_mess;
6918 </para>
6919 </refsect1>
6920
6921 <refsect1>
6922 <title>Return value</title>
6923 <para>
6924 The return value follows the &lqrl; signalling system.
6925 </para>
6926 </refsect1>
6927
6928 <refsect1>
6929 <title>See also</title>
6930 <para>
6931 <simplelist type="inline">
6932 <member><xref linkend="ref-lqr-ret-val"></xref></member>
6933 <member><xref linkend="ref-lqr-progress-new"></xref></member>
6934 <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
6935 <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
6936 <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
6937 <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
6938 <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
6939 <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
6940 <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
6941 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
6942 </simplelist>
6943 </para>
6944 </refsect1>
6945 </refentry>
6946
6947 <refentry id="ref-lqr-progress-set-init-height-message">
6948 <refmeta>
6949 <refentrytitle><function>lqr_progress_set_init_height_message</function></refentrytitle>
6950 <manvolnum>3</manvolnum>
6951 </refmeta>
6952
6953 <refnamediv>
6954 <refname>lqr_progress_set_init_height_message</refname>
6955 <refpurpose>setup height message for init hooks in &prog_obj; objects</refpurpose>
6956 </refnamediv>
6957
6958 <refsynopsisdiv>
6959 <funcsynopsis>
6960 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
6961 <funcprototype>
6962 <funcdef>LqrRetVal <function>lqr_progress_set_init_height_message</function></funcdef>
6963 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
6964 <paramdef>const guchar* <parameter>message</parameter></paramdef>
6965 </funcprototype>
6966 </funcsynopsis>
6967 </refsynopsisdiv>
6968
6969 <refsect1>
6970 <title>Description</title>
6971 <para>
6972 The function <function>lqr_progress_set_init_height_message</function> sets the string
6973 <parameter>message</parameter> in the &prog_obj; object pointed to by <parameter>p</parameter>
6974 as the argument when rescaling the height for init hooks set with
6975 <xref linkend="ref-lqr-progress-set-init"></xref>
6976 </para>
6977 <para>
6978 The default value for newly created &prog_obj; objects is: &prog_init_h_mess;
6979 </para>
6980 </refsect1>
6981
6982 <refsect1>
6983 <title>Return value</title>
6984 <para>
6985 The return value follows the &lqrl; signalling system.
6986 </para>
6987 </refsect1>
6988
6989 <refsect1>
6990 <title>See also</title>
6991 <para>
6992 <simplelist type="inline">
6993 <member><xref linkend="ref-lqr-ret-val"></xref></member>
6994 <member><xref linkend="ref-lqr-progress-new"></xref></member>
6995 <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
6996 <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
6997 <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
6998 <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
6999 <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
7000 <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
7001 <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
7002 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
7003 </simplelist>
7004 </para>
7005 </refsect1>
7006 </refentry>
7007
7008 <refentry id="ref-lqr-progress-set-end-width-message">
7009 <refmeta>
7010 <refentrytitle><function>lqr_progress_set_end_width_message</function></refentrytitle>
7011 <manvolnum>3</manvolnum>
7012 </refmeta>
7013
7014 <refnamediv>
7015 <refname>lqr_progress_set_end_width_message</refname>
7016 <refpurpose>setup width message for end hooks in &prog_obj; objects</refpurpose>
7017 </refnamediv>
7018
7019 <refsynopsisdiv>
7020 <funcsynopsis>
7021 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
7022 <funcprototype>
7023 <funcdef>LqrRetVal <function>lqr_progress_set_end_width_message</function></funcdef>
7024 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
7025 <paramdef>const guchar* <parameter>message</parameter></paramdef>
7026 </funcprototype>
7027 </funcsynopsis>
7028 </refsynopsisdiv>
7029
7030 <refsect1>
7031 <title>Description</title>
7032 <para>
7033 The function <function>lqr_progress_set_end_width_message</function> sets the string
7034 <parameter>message</parameter> in the &prog_obj; object pointed to by <parameter>p</parameter>
7035 as the argument when rescaling the width for end hooks set with
7036 <xref linkend="ref-lqr-progress-set-end"></xref>
7037 </para>
7038 <para>
7039 The default value for newly created &prog_obj; objects is:
7040 <computeroutput>"done"</computeroutput>.
7041 </para>
7042 </refsect1>
7043
7044 <refsect1>
7045 <title>Return value</title>
7046 <para>
7047 The return value follows the &lqrl; signalling system.
7048 </para>
7049 </refsect1>
7050
7051 <refsect1>
7052 <title>See also</title>
7053 <para>
7054 <simplelist type="inline">
7055 <member><xref linkend="ref-lqr-ret-val"></xref></member>
7056 <member><xref linkend="ref-lqr-progress-new"></xref></member>
7057 <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
7058 <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
7059 <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
7060 <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
7061 <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
7062 <member><xref linkend="ref-lqr-progress-set-end-height-message"></xref></member>
7063 <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
7064 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
7065 </simplelist>
7066 </para>
7067 </refsect1>
7068 </refentry>
7069
7070 <refentry id="ref-lqr-progress-set-end-height-message">
7071 <refmeta>
7072 <refentrytitle><function>lqr_progress_set_end_height_message</function></refentrytitle>
7073 <manvolnum>3</manvolnum>
7074 </refmeta>
7075
7076 <refnamediv>
7077 <refname>lqr_progress_set_end_height_message</refname>
7078 <refpurpose>setup height message for end hooks in &prog_obj; objects</refpurpose>
7079 </refnamediv>
7080
7081 <refsynopsisdiv>
7082 <funcsynopsis>
7083 <funcsynopsisinfo>#include &lt;lqr.h></funcsynopsisinfo>
7084 <funcprototype>
7085 <funcdef>LqrRetVal <function>lqr_progress_set_end_height_message</function></funcdef>
7086 <paramdef>LqrProgress* <parameter>p</parameter></paramdef>
7087 <paramdef>const guchar* <parameter>message</parameter></paramdef>
7088 </funcprototype>
7089 </funcsynopsis>
7090 </refsynopsisdiv>
7091
7092 <refsect1>
7093 <title>Description</title>
7094 <para>
7095 The function <function>lqr_progress_set_end_height_message</function> sets the string
7096 <parameter>message</parameter> in the &prog_obj; object pointed to by <parameter>p</parameter>
7097 as the argument when rescaling the height for end hooks set with
7098 <xref linkend="ref-lqr-progress-set-end"></xref>
7099 </para>
7100 <para>
7101 The default value for newly created &prog_obj; objects is:
7102 <computeroutput>"done"</computeroutput>.
7103 </para>
7104 </refsect1>
7105
7106 <refsect1>
7107 <title>Return value</title>
7108 <para>
7109 The return value follows the &lqrl; signalling system.
7110 </para>
7111 </refsect1>
7112
7113 <refsect1>
7114 <title>See also</title>
7115 <para>
7116 <simplelist type="inline">
7117 <member><xref linkend="ref-lqr-ret-val"></xref></member>
7118 <member><xref linkend="ref-lqr-progress-new"></xref></member>
7119 <member><xref linkend="ref-lqr-progress-set-init"></xref></member>
7120 <member><xref linkend="ref-lqr-progress-set-update"></xref></member>
7121 <member><xref linkend="ref-lqr-progress-set-end"></xref></member>
7122 <member><xref linkend="ref-lqr-progress-set-init-width-message"></xref></member>
7123 <member><xref linkend="ref-lqr-progress-set-init-height-message"></xref></member>
7124 <member><xref linkend="ref-lqr-progress-set-end-width-message"></xref></member>
7125 <member><xref linkend="ref-lqr-progress-set-update-step"></xref></member>
7126 <member><xref linkend="ref-lqr-carver-set-progress"></xref></member>
7127 </simplelist>
7128 </para>
7129 </refsect1>
7130 </refentry>
7131 </sect1>
7132 </chapter>
7133
7134
7135 <chapter id="references">
7136 <title>References</title>
7137
7138 <para>
7139 The library implements the algorithm described in the paper "Seam Carving for Content-Aware Image Resizing"
7140 by Shai Avidan and Ariel Shamir, which can be found at
7141 <ulink url="http://www.faculty.idc.ac.il/arik/imret.pdf">http://www.faculty.idc.ac.il/arik/imret.pdf</ulink>
7142 </para>
7143 </chapter>
7144
7145 <appendix id="app-new">
7146 <title>API changes in new versions of the library</title>
7147
7148 <sect1 id="app-new-0-4">
7149 <title>New symbols in version 0.4</title>
7150 <para>
7151 <simplelist>
7152 <member><link linkend="ref-lqr-image-type"><type>LqrImageType</type></link></member>
7153 <member><link linkend="ref-lqr-carver-set-image-type"><function>lqr_carver_set_image_type</function></link></member>
7154 <member><link linkend="ref-lqr-carver-get-image-type"><function>lqr_carver_get_image_type</function></link></member>
7155 <member><link linkend="ref-lqr-carver-set-alpha-channel"><function>lqr_carver_set_alpha_channel</function></link></member>
7156 <member><link linkend="ref-lqr-carver-set-black-channel"><function>lqr_carver_set_black_channel</function></link></member>
7157 <member><link linkend="ref-lqr-carver-set-preserve-input-image"><function>lqr_carver_set_preserve_input_image</function></link></member>
7158 <member><link linkend="ref-lqr-carver-set-use-cache"><function>lqr_carver_set_use_cache</function></link></member>
7159 <member><link linkend="ref-lqr-carver-list-foreach"><function>lqr_carver_list_foreach_recursive</function></link></member>
7160 <member><link linkend="ref-lqr-carver-set-energy-function-builtin"><function>lqr_carver_set_energy_function_builtin</function></link></member>
7161 <member><link linkend="ref-lqr-carver-set-energy-function"><function>lqr_carver_set_energy_function</function></link></member>
7162 <member><link linkend="ref-lqr-carver-get-energy"><function>lqr_carver_get_energy</function></link></member>
7163 <member><link linkend="ref-lqr-carver-get-energy"><function>lqr_carver_get_true_energy</function></link></member>
7164 <member><link linkend="ref-lqr-carver-get-energy"><function>lqr_carver_get_energy_image</function></link></member>
7165 <member><link linkend="ref-lqr-rwindow-read"><function>lqr_rwindow_read</function></link></member>
7166 <member><link linkend="ref-lqr-rwindow-get-read-t"><function>lqr_rwindow_get_read_t</function></link></member>
7167 <member><link linkend="ref-lqr-rwindow-get-radius"><function>lqr_rwindow_get_radius</function></link></member>
7168 <member><link linkend="ref-lqr-rwindow-get-channels"><function>lqr_rwindow_get_channels</function></link></member>
7169 <member><link linkend="ref-lqr-carver-bias-add"><function>lqr_carver_bias_add_xy</function></link></member>
7170 <member><link linkend="ref-lqr-carver-bias-clear"><function>lqr_carver_bias_clear</function></link></member>
7171 <member><link linkend="ref-lqr-carver-rigmask-add"><function>lqr_carver_rigmask_add_xy</function></link></member>
7172 <member><link linkend="ref-lqr-carver-rigmask-clear"><function>lqr_carver_rigmask_clear</function></link></member>
7173 <member><link linkend="ref-lqr-carver-cancel"><function>lqr_carver_cancel</function></link></member>
7174 </simplelist>
7175 </para>
7176 </sect1>
7177
7178 <sect1 id="app-new-0-3">
7179 <title>New symbols in version 0.3</title>
7180 <para>
7181 <simplelist>
7182 <member><link linkend="ref-lqr-carver-get-enl-step"><function>lqr_carver_get_enl_step</function></link></member>
7183 <member><link linkend="ref-lqr-carver-set-enl-step"><function>lqr_carver_set_enl_step</function></link></member>
7184 <member><link linkend="ref-lqr-carver-get-ref-width"><function>lqr_carver_get_ref_width</function></link></member>
7185 <member><link linkend="ref-lqr-carver-get-ref-height"><function>lqr_carver_get_ref_height</function></link></member>
7186 <member><link linkend="ref-lqr-carver-get-orientation"><function>lqr_carver_get_orientation</function></link></member>
7187 <member><link linkend="ref-lqr-carver-get-depth"><function>lqr_carver_get_depth</function></link></member>
7188 </simplelist>
7189 </para>
7190 </sect1>
7191
7192 <sect1 id="app-new-0-2">
7193 <title>New symbols in version 0.2</title>
7194 <para>
7195 <simplelist>
7196 <member><link linkend="ref-lqr-col-depth"><type>LqrColDepth</type></link></member>
7197 <member><link linkend="ref-lqr-carver-new"><function>lqr_carver_new_ext</function></link></member>
7198 <member><link linkend="ref-lqr-carver-scan"><function>lqr_carver_scan_ext</function></link></member>
7199 <member><link linkend="ref-lqr-carver-scan-line"><function>lqr_carver_scan_line_ext</function></link></member>
7200 <member><link linkend="ref-lqr-carver-get-channels"><function>lqr_carver_get_channels</function></link></member>
7201 <member><link linkend="ref-lqr-carver-get-col-depth"><function>lqr_carver_get_col_depth</function></link></member>
7202 <member><link linkend="ref-lqr-carver-set-side-switch-frequency"><function>lqr_carver_set_side_switch_frequency</function></link></member>
7203 <member><link linkend="ref-lqr-carver-rigmask-add"><function>lqr_carver_rigmask_add</function></link></member>
7204 <member><link linkend="ref-lqr-carver-rigmask-add"><function>lqr_carver_rigmask_add_area</function></link></member>
7205 <member><link linkend="ref-lqr-carver-rigmask-add"><function>lqr_carver_rigmask_add_rgb</function></link></member>
7206 <member><link linkend="ref-lqr-carver-rigmask-add"><function>lqr_carver_rigmask_add_rgb_area</function></link></member>
7207 </simplelist>
7208 </para>
7209 </sect1>
7210
7211 <sect1 id="app-deprecated">
7212 <title>Deprecated symbols</title>
7213 <para>
7214 <simplelist>
7215 <member><link linkend="ref-lqr-carver-get-channels"><function>lqr_carver_get_bpp</function></link></member>
7216 <member><link linkend="ref-lqr-carver-set-gradient-function"><function>lqr_carver_set_gradient_function</function></link></member>
7217 </simplelist>
7218 </para>
7219 </sect1>
7220 </appendix>
7221 </book>