/usr/share/doc/liblqr-1-0-dev/html/vmaps.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 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Dealing with the visibility maps (the seams)</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="tuning.html" title="Tuning"><link rel="next" href="attach-images.html" title="Attaching extra images"></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">Dealing with the visibility maps (the seams)</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="tuning.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="attach-images.html">Next</a></td></tr></table><hr></div><div class="sect1" title="Dealing with the visibility maps (the seams)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vmaps"></a>Dealing with the visibility maps (the seams)</h2></div></div></div><div class="toc"><dl><dt><span class="sect2"><a href="vmaps.html#vmap-dump">Dumping the visibility map</a></span></dt><dt><span class="sect2"><a href="vmaps.html#activate-dump">Storing the visibility maps</a></span></dt><dt><span class="sect2"><a href="vmaps.html#access-vmap">Accessing the internally attached visibility maps</a></span></dt><dt><span class="sect2"><a href="vmaps.html#vmaps-objs">The visibility map objects</a></span></dt><dt><span class="sect2"><a href="vmaps.html#import-vmap">Importing a visibility map in a carver</a></span></dt><dt><span class="sect2"><a href="vmaps.html#save-load-vmaps">Saving and loading visibility maps to/from files</a></span></dt></dl></div><div class="sect2" title="Dumping the visibility map"><div class="titlepage"><div><div><h3 class="title"><a name="vmap-dump"></a>Dumping the visibility map</h3></div></div></div><p>
The visibility map can be saved at any moment by calling the function:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">LqrVMap* <b class="fsfunc">lqr_vmap_dump</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
This function will return a pointer to a newly allocated <code class="classname">LqrVMap</code> object, or <code class="literal"><span class="returnvalue">NULL</span></code> in case of
failure. See also the section "<a class="link" href="vmaps.html#vmaps-objs" title="The visibility map objects">The visibility map objects</a>".
</p></div><div class="sect2" title="Storing the visibility maps"><div class="titlepage"><div><div><h3 class="title"><a name="activate-dump"></a>Storing the visibility maps</h3></div></div></div><p>
By default, the computed visibility maps are wasted. Instead of saving them individually, it is
possible to automatically dump them at the end of the carving process, attaching them to their
associated <code class="classname">LqrCarver</code>. In order to activate this feature, the following function has to be called:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">lqr_carver_set_dump_vmaps</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
This will have the effect of dumping the visibility map each time
<code class="function">lqr_carver_resize</code> is invoked, and storing it internally. When resizing along
both directions, two maps will be dumped, one for each direction.
</p><p>
In order to revert the effect of <code class="function">lqr_carver_set_dump_vmaps</code>, thus stopping the
automatic dumping, use the function
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">lqr_carver_set_no_dump_vmaps</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
Alternatively, the internal storage mechanism can be called over the current visibility map at any
given moment by calling 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_vmap_internal_dump</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
The dumped maps are stored inside <code class="classname">LqrVMap</code> objects, and these are attached to their corresponing
<code class="classname">LqrCarver</code> object through a linked list, whose type is <code class="classname">LqrVMapList</code>
</p></div><div class="sect2" title="Accessing the internally attached visibility maps"><div class="titlepage"><div><div><h3 class="title"><a name="access-vmap"></a>Accessing the internally attached visibility maps</h3></div></div></div><p>
To access the maps attached to a carver one has first to obtain the pointer to the list, with the
function:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">LqrVMapList* <b class="fsfunc">lqr_vmap_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 maps 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">LqrVMap* <b class="fsfunc">lqr_vmap_list_current</b>(</code></td><td>LqrVMapList* <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">LqrVMapList* <b class="fsfunc">lqr_vmap_list_next</b>(</code></td><td>LqrVMapList* <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-vmaplist1"></a><p class="title"><b>Example 2.7. Accessing visibility maps #1</b></p><div class="example-contents"><pre class="programlisting">
LqrVMap *vmap;
LqrVMapList *list;
list = lqr_vmap_list_start (carver);
while (list) {
vmap = lqr_vmap_list_current (list);
/* ... do something on vmap ... */
list = lqr_vmap_list_next (list);
}
</pre></div></div><p><br class="example-break">
</p><p>
The maps will always be accessed in the order in which they were dumped.
</p><p>
Alternatively, one can apply a function to all the elements of the list, 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_vmap_list_foreach</b>(</code></td><td>LqrVMapList* <var class="pdparam">list</var>, </td></tr><tr><td> </td><td>LqrVMapFunc <var class="pdparam">func</var>, </td></tr><tr><td> </td><td>gpointer <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 this sample code:
</p><div class="example"><a name="ex-vmaplist2"></a><p class="title"><b>Example 2.8. Accessing visibility maps #2</b></p><div class="example-contents"><pre class="programlisting">
LqrRetVal my_func (LqrVMap vmap, gpointer data)
{
/* ... do something on vmap ... */
return LQR_OK;
}
LqrVMapList *list;
list = lqr_vmap_list_start (carver);
lqr_vmap_list_foreach (list, my_func, NULL);
</pre></div></div><p><br class="example-break">
</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_vmap_list_foreach</code> should be protected to
test its return value, which is <code class="literal"><span class="errorcode">LQR_OK</span></code> if all <code class="function">my_func</code> calls have been
successful, or it will hold the first non-successful return value from
<code class="function">my_func</code>.
</p></div></div><div class="sect2" title="The visibility map objects"><div class="titlepage"><div><div><h3 class="title"><a name="vmaps-objs"></a>The visibility map objects</h3></div></div></div><p>
The <code class="classname">LqrVMap</code> objects contain an int buffer with the actual map data (plain array, ordered by row),
plus all the information needed to be able to recover it from scratch.
</p><p>
The information can be extracted with these functions:
</p><pre class="programlisting">
gint* <code class="function">lqr_vmap_get_data</code> (<code class="classname">LqrVMap</code>* <em class="parameter"><code>vmap</code></em>);
gint <code class="function">lqr_vmap_get_width</code> (<code class="classname">LqrVMap</code>* <em class="parameter"><code>vmap</code></em>);
gint <code class="function">lqr_vmap_get_height</code> (<code class="classname">LqrVMap</code>* <em class="parameter"><code>vmap</code></em>);
gint <code class="function">lqr_vmap_get_orientation</code> (<code class="classname">LqrVMap</code>* <em class="parameter"><code>vmap</code></em>);
gint <code class="function">lqr_vmap_get_depth</code> (<code class="classname">LqrVMap</code>* <em class="parameter"><code>vmap</code></em>);
</pre><p>
</p><p>
The first one returns a pointer to the data buffer.
</p><p>
The orientation of the map is 0 if the map is to be used for horizontal rescaling, 1 otherwise.
</p><p>
The depth of the map is the maximum amount of rescaling possible with that map, either shrinking or
enlarging.
</p><p>
</p><div class="example"><a name="vmap-data"></a><p class="title"><b>Example 2.9. Reading visibility maps data</b></p><div class="example-contents"><p>
If we have a <code class="classname">LqrVMap</code> pointer called <em class="parameter"><code>vmap</code></em>, we could access the
value at <code class="literal">(<span class="symbol">x</span>,<span class="symbol">y</span>)</code> by:
</p><pre class="programlisting">
gint *buffer;
gint width;
gint vis;
buffer = lqr_vmap_get_data (vmap);
width = lqr_vmap_get_width (vmap);
vis = buffer[y * width + x];
</pre><p>
Uninitialised points will yield <code class="literal"><span class="symbol">vis</span> = 0</code>. For
initialised points, <span class="symbol">vis</span> will store a positive value between
<code class="literal">1</code> (least visible points, the first to be carved away or to be duplicated)
and <code class="literal">(<em class="parameter"><code>depth</code></em> + 1)</code> (most visible points, the last to be carved away
or to be duplicated).
</p><p>
If the orientation is 0, the map allows resizing in the whole range form <code class="literal">(<em class="parameter"><code>width</code></em>
- <em class="parameter"><code>depth</code></em>)</code> to <code class="literal">(<em class="parameter"><code>width</code></em> + <em class="parameter"><code>depth</code></em>)</code>. If the
orientation is 1, the analogue formula holds with <em class="parameter"><code>height</code></em> in place of <em class="parameter"><code>width</code></em>.
</p></div></div><p><br class="example-break">
</p></div><div class="sect2" title="Importing a visibility map in a carver"><div class="titlepage"><div><div><h3 class="title"><a name="import-vmap"></a>Importing a visibility map in a carver</h3></div></div></div><p>
Having an <code class="classname">LqrVMap</code> object, one can load it in an <code class="classname">LqrCarver</code> simply by calling 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_vmap_load</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td>LqrVMap* <var class="pdparam">vmap</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
The carver must not to be initialised, neither before nor after invoking this function.
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
This implies that the map cannot be updated, and that it will only be possible to resize the
carver by an amount <em class="parameter"><code>depth</code></em> along the orientation given by
<code class="function">lqr_vmap_orientation</code>. The enlargment step is also set to its maximum, 2.0.
Invoking <code class="function">lqr_carver_resize</code> with an out-of-bounds argument results in a
<span class="errortype">fatal</span> error (i.e. it returns <code class="literal"><span class="errorcode">LQR_ERROR</span></code>).
</p></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Do not attach other carvers after you have loaded a visibility map (see also the
<a class="link" href="attach-images.html" title="Attaching extra images">Attaching extra images</a> section).
</p></div></div><div class="sect2" title="Saving and loading visibility maps to/from files"><div class="titlepage"><div><div><h3 class="title"><a name="save-load-vmaps"></a>Saving and loading visibility maps to/from files</h3></div></div></div><p>
The library does not include methods to load/save visibility maps to/from files. However, a way to
do so is shown in the demo program `<span class="application">liquidrescale</span>' in the
`<code class="filename">examples</code>' directory.
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tuning.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="attach-images.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Tuning </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Attaching extra images</td></tr></table></div></body></html>
|