/usr/share/doc/liblqr-1-0-dev/html/attach-images.html is in liblqr-1-0-dev 0.4.1-1.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Attaching extra images</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="The Liquid Rescale library Manual"><link rel="up" href="api-manual.html" title="Chapter 2. LqR library API user manual"><link rel="prev" href="vmaps.html" title="Dealing with the visibility maps (the seams)"><link rel="next" href="progress.html" title="Progress indicators"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Attaching extra images</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="vmaps.html">Prev</a> </td><th width="60%" align="center">Chapter 2. LqR library API user manual</th><td width="20%" align="right"> <a accesskey="n" href="progress.html">Next</a></td></tr></table><hr></div><div class="sect1" title="Attaching extra images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="attach-images"></a>Attaching extra images</h2></div></div></div><div class="toc"><dl><dt><span class="sect2"><a href="attach-images.html#attach-carver">Attaching a carver</a></span></dt><dt><span class="sect2"><a href="attach-images.html#access-attached">Accessing attached carvers</a></span></dt></dl></div><div class="sect2" title="Attaching a carver"><div class="titlepage"><div><div><h3 class="title"><a name="attach-carver"></a>Attaching a carver</h3></div></div></div><p>
Given an <code class="classname">LqrCarver</code> object, it is possible to attach an arbitrary number of extra carvers to it:
these will passively undergo the same carving process as the root carver. In order for this to be
possible, the carvers must be all of the same size.
</p><p>
The function to use is simply:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">LqrRetVal <b class="fsfunc">lqr_carver_attach</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td>LqrCarver* <var class="pdparam">aux</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
This attaches <em class="parameter"><code>aux</code></em> to <em class="parameter"><code>carver</code></em>.
</p><p>
It is not necessary that the parent <code class="classname">LqrCarver</code> is activated. In fact, a carver can be attached to a
carver which is itself attached to another one.
</p><p>
Needless to say, no resizing operation should be done directly on an <code class="classname">LqrCarver</code> once it has been
attached to another <code class="classname">LqrCarver</code>, and neither should the cancel method be invoked directly on them.
</p><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>
The carvers always have to be attached <span class="emphasis"><em>before</em></span> loading visibility maps.
</p></div></div><div class="sect2" title="Accessing attached carvers"><div class="titlepage"><div><div><h3 class="title"><a name="access-attached"></a>Accessing attached carvers</h3></div></div></div><p>
Attached carvers can be read-out in the same way as their parents. There are however also methods
to span all them, in a way very similar to that in which internally dumped <code class="classname">LqrVMap</code>'s are
accessed, but <code class="classname">LqrVMapList</code> objects are substitued in this case by <code class="classname">LqrCarverList</code> objects.
</p><p>
First, the starting point of the list has to be retreived through:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">LqrCarverList* <b class="fsfunc">lqr_carver_list_start</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
Then, one can iterate through the attached carvers by using these two functions:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">LqrCarver* <b class="fsfunc">lqr_carver_list_current</b>(</code></td><td>LqrCarverList* <var class="pdparam">list</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">LqrCarverList* <b class="fsfunc">lqr_carver_list_next</b>(</code></td><td>LqrCarverList* <var class="pdparam">list</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
Here is a sample code usage:
</p><div class="example"><a name="ex-attach-list1"></a><p class="title"><b>Example 2.10. Accessing attached carvers #1</b></p><div class="example-contents"><pre class="programlisting">
LqrCarver *aux;
LqrCarverList *list;
list = lqr_carver_list_start (carver);
while (list) {
aux = lqr_carver_list_current (list);
/* ... do something on aux ... */
list = lqr_carver_list_next (list);
}
</pre></div></div><p><br class="example-break">
</p><p>
The carvers will always be accessed in the order in which they were attached.
</p><p>
Alternatively, one can apply a function to all the elements of the list (and recursively to all the
elements of their attached lists, if there are any), through this function:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">LqrRetVal <b class="fsfunc">lqr_carver_list_foreach_recursive</b>(</code></td><td>LqrCarverList* <var class="pdparam">list</var>, </td></tr><tr><td> </td><td>LqrCarverFunc <var class="pdparam">func</var>, </td></tr><tr><td> </td><td>LqrDataTok <var class="pdparam">data</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
To use this second method, you'll need to define a function first, as in the following sample code:
</p><div class="example"><a name="ex-attach-list2"></a><p class="title"><b>Example 2.11. Accessing attached carvers #2</b></p><div class="example-contents"><pre class="programlisting">
LqrRetVal my_func (LqrCarver *aux, LqrDataTok data)
{
/* ... do something on aux ... */
return LQR_OK;
}
LqrCarverList *list;
LqrDataTok data_tok;
list = lqr_carver_list_start (carver);
data_tok->data = NULL;
lqr_carver_list_foreach_recursive (list, my_func, data_tok);
</pre></div></div><p><br class="example-break">
</p><p>
The data to be passed on to the LqrCarverFunc is of type <span class="structname">LqrDataTok</span>. This
is defined as a union, with the following fields:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="classname">LqrCarver</code>* <em class="structfield"><code>carver</code></em></p></li><li class="listitem"><p><span class="type">gint</span> <em class="structfield"><code>integer</code></em></p></li><li class="listitem"><p><span class="type">gpointer</span> <em class="structfield"><code>data</code></em></p></li></ul></div><p>
</p><p>
In the above example, no data is actually passed on to the function.
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
In actual code, the call to <code class="function">lqr_carver_list_foreach_recursive</code> should be
protected to test its return value, which is <code class="literal"><span class="errorcode">LQR_OK</span></code> if all my_func calls have been successful
(or if the list is empty), or it will hold the first non-successful return value from
<code class="function">my_func</code>.
</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="vmaps.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="api-manual.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="progress.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Dealing with the visibility maps (the seams) </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Progress indicators</td></tr></table></div></body></html>
|