/usr/share/doc/libcaca-dev/html/libcaca-migrating.html is in libcaca-dev 0.99.beta18-1ubuntu5.
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 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>libcaca documentation</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head>
<body>
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Migrating from libcaca 0.x to the 1.0 API </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This section will guide you through the migration of a <em>libcaca</em> 0.x application to the latest API version.</p>
<h1><a class="anchor" id="foo1"></a>
Overview</h1>
<p>The most important change in the 1.0 API of <em>libcaca</em> is the object-oriented design. See these two examples for a rough idea of what changed:</p>
<table border="0">
<tr>
<td valign="top"><div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="caca_8h.html">caca.h</a>></span></div>
<div class="line"></div>
<div class="line"><span class="comment">/* libcaca program - 0.x API */</span></div>
<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)</div>
<div class="line">{</div>
<div class="line"> <span class="comment">/* Initialise libcaca */</span></div>
<div class="line"> caca_init();</div>
<div class="line"> <span class="comment">/* Set window title */</span></div>
<div class="line"> caca_set_window_title(<span class="stringliteral">"Window"</span>);</div>
<div class="line"> <span class="comment">/* Choose drawing colours */</span></div>
<div class="line"> caca_set_color(CACA_COLOR_BLACK,</div>
<div class="line"> CACA_COLOR_WHITE);</div>
<div class="line"> <span class="comment">/* Draw a string at (0, 0) */</span></div>
<div class="line"> caca_putstr(0, 0, <span class="stringliteral">"Hello world!"</span>);</div>
<div class="line"> <span class="comment">/* Refresh display */</span></div>
<div class="line"> caca_refresh();</div>
<div class="line"> <span class="comment">/* Wait for a key press event */</span></div>
<div class="line"> caca_wait_event(<a class="code" href="caca_8h.html#a40754185ca237fc44a95357afba34aeaab1da825755a2ac3593cca73721b77e22">CACA_EVENT_KEY_PRESS</a>);</div>
<div class="line"> <span class="comment">/* Clean up library */</span></div>
<div class="line"> caca_end();</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
</div><!-- fragment --> </td><td><div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="caca_8h.html">caca.h</a>></span></div>
<div class="line"></div>
<div class="line"><span class="comment">/* libcaca program - 1.0 API */</span></div>
<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)</div>
<div class="line">{</div>
<div class="line"> <span class="comment">/* Initialise libcaca */</span></div>
<div class="line"> <a class="code" href="caca_8h.html#aae0f6938d08e6e0abbcd5a8c06504ab8">caca_canvas_t</a> *cv;</div>
<div class="line"> <a class="code" href="caca_8h.html#ada5af7a20f3e2f6c103078181b07393e">caca_display_t</a> *dp;</div>
<div class="line"> dp = <a class="code" href="group__caca__display.html#gac393d4446d813f6e4ba93d2b583c1edb">caca_create_display</a>(NULL);</div>
<div class="line"> cv = <a class="code" href="group__caca__display.html#ga65670cdec61ba57879b893c997cd26da">caca_get_canvas</a>(dp);</div>
<div class="line"> <span class="comment">/* Set window title */</span></div>
<div class="line"> <a class="code" href="group__caca__display.html#gadab2bf1e8d0bf5c3cfb3e29ab07d5641">caca_set_display_title</a>(dp, <span class="stringliteral">"Window"</span>);</div>
<div class="line"> <span class="comment">/* Choose drawing colours */</span></div>
<div class="line"> <a class="code" href="group__caca__attributes.html#ga1cd39df80cc6b537a4df18415a8605cf">caca_set_color_ansi</a>(cv, <a class="code" href="group__caca__attr.html#gga9db83488c6f07a5f7d773c380b3126a9a9280adda765037612d94743bdc3f346d">CACA_BLACK</a>,</div>
<div class="line"> <a class="code" href="group__caca__attr.html#gga9db83488c6f07a5f7d773c380b3126a9a1bd1244f952d10b9599fb314e41862ad">CACA_WHITE</a>);</div>
<div class="line"> <span class="comment">/* Draw a string at (0, 0) */</span></div>
<div class="line"> <a class="code" href="group__caca__canvas.html#gac9370c0854f358b88d0cb8caf07fb6d3">caca_put_str</a>(cv, 0, 0, <span class="stringliteral">"Hello world!"</span>);</div>
<div class="line"> <span class="comment">/* Refresh display */</span></div>
<div class="line"> <a class="code" href="group__caca__display.html#ga8c710eac721d05d807491a1534d1cbe7">caca_refresh_display</a>();</div>
<div class="line"> <span class="comment">/* Wait for a key press event */</span></div>
<div class="line"> <a class="code" href="group__caca__event.html#ga98e74dedbe1629c0fc9460761696e050">caca_get_event</a>(dp, <a class="code" href="caca_8h.html#a40754185ca237fc44a95357afba34aeaab1da825755a2ac3593cca73721b77e22">CACA_EVENT_KEY_PRESS</a>,</div>
<div class="line"> NULL, -1);</div>
<div class="line"> <span class="comment">/* Clean up library */</span></div>
<div class="line"> <a class="code" href="group__caca__display.html#gac1b5b4540a500dd59eaa673d784fab1f">caca_free_display</a>(dp);</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
</div><!-- fragment --> </td></tr>
</table>
<p>Note the following important things:</p>
<ul>
<li>Most functions now take an object handle as their first argument.</li>
</ul>
<h1><a class="anchor" id="foo2"></a>
Migration strategy</h1>
<p>You have two ways to migrate your application to use <em>libcaca</em> 1.x:</p>
<ul>
<li>Port your code using the function equivalence list. This is the preferred way because new functions are thread safe and offer much more features to both the programmer and the end user.</li>
<li>Use the legacy compatibility layer.</li>
</ul>
<p>Using the compatibility layer is as easy as adding the following three lines:</p>
<table border="0">
<tr>
<td valign="top"><div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="caca_8h.html">caca.h</a>></span></div>
<div class="line"></div>
<div class="line"><span class="comment">/* libcaca program - 0.x API */</span></div>
<div class="line">...</div>
</div><!-- fragment --> </td><td><div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="caca_8h.html">caca.h</a>></span></div>
<div class="line"><span class="preprocessor">#ifdef CACA_API_VERSION_1</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor"># include <caca0.h></span></div>
<div class="line"><span class="preprocessor">#endif</span></div>
<div class="line"><span class="preprocessor"></span></div>
<div class="line"><span class="comment">/* libcaca program - 0.x API */</span></div>
<div class="line">...</div>
</div><!-- fragment --> </td></tr>
</table>
<p>The modified code is guaranteed to build both with <em>libcaca</em> 0.x and <em>libcaca</em> 1.0.</p>
<h1><a class="anchor" id="foo3"></a>
Function equivalence list</h1>
<h2><a class="anchor" id="bar1"></a>
Basic functions</h2>
<ul>
<li><b>caca_init()</b>: use <a class="el" href="group__libcaca.html#ga00caafb33b9d7033d064a642bcad83da" title="Initialise a libcaca canvas. ">caca_create_canvas()</a> to create a <em>libcaca</em> canvas, followed by <a class="el" href="group__caca__display.html#gac393d4446d813f6e4ba93d2b583c1edb" title="Attach a caca graphical context to a caca canvas. ">caca_create_display()</a> to attach a <em>libcaca</em> display to it. Alternatively, <a class="el" href="group__caca__display.html#gac393d4446d813f6e4ba93d2b583c1edb" title="Attach a caca graphical context to a caca canvas. ">caca_create_display()</a> with a NULL argument will create a canvas automatically.</li>
<li><b>caca_set_delay()</b>: use <a class="el" href="group__caca__display.html#ga0340d64c3e7f23e11af749c4da83dfde" title="Set the refresh delay. ">caca_set_display_time()</a>.</li>
<li><b>caca_get_feature()</b>: deprecated.</li>
<li><b>caca_set_feature()</b>: deprecated, see <a class="el" href="group__caca__dither.html#ga6e11d68966e0b2d709b377385fbcabd4" title="Set dither antialiasing. ">caca_set_dither_antialias()</a>, <a class="el" href="group__caca__dither.html#gae4a7a941295c958221d9010070f0c35c" title="Choose colours used for dithering. ">caca_set_dither_color()</a> and caca_set_dither_mode() instead.</li>
<li><b>caca_get_feature_name()</b>: deprecated, see caca_get_dither_mode_list(), <a class="el" href="group__caca__dither.html#ga6e0986062cb064bf7bcef0105233857e" title="Get available antialiasing methods. ">caca_get_dither_antialias_list()</a> and <a class="el" href="group__caca__dither.html#ga973d84c24e352d3da09f02a49b79ebf0" title="Get available colour modes. ">caca_get_dither_color_list()</a> instead.</li>
<li><b>caca_get_rendertime()</b>: use <a class="el" href="group__caca__display.html#ga74339a36233beeee2ca5fe531885538a" title="Get the display's average rendering time. ">caca_get_display_time()</a>.</li>
<li><b>caca_get_width()</b>: use <a class="el" href="group__libcaca.html#gad85b2ff4c7f952b3cc32f117343a6375" title="Get the canvas width. ">caca_get_canvas_width()</a>.</li>
<li><b>caca_get_height()</b>: use <a class="el" href="group__libcaca.html#gaa529140e8cf31379a6b57af7c37c9d2f" title="Get the canvas height. ">caca_get_canvas_height()</a>.</li>
<li><b>caca_set_window_title()</b>: use <a class="el" href="group__caca__display.html#gadab2bf1e8d0bf5c3cfb3e29ab07d5641" title="Set the display title. ">caca_set_display_title()</a>.</li>
<li><b>caca_get_window_width()</b>: use <a class="el" href="group__caca__display.html#gae0cc5bc7835df240b242929cc77024ac" title="Get the display width. ">caca_get_display_width()</a>.</li>
<li><b>caca_get_window_height()</b>: use <a class="el" href="group__caca__display.html#gaf540716e9e5faa22a3dc5d0c68761a1f" title="Get the display height. ">caca_get_display_height()</a>.</li>
<li><b>caca_refresh()</b>: use <a class="el" href="group__caca__display.html#ga8c710eac721d05d807491a1534d1cbe7" title="Flush pending changes and redraw the screen. ">caca_refresh_display()</a>.</li>
<li><b>caca_end()</b>: use <a class="el" href="group__caca__display.html#gac1b5b4540a500dd59eaa673d784fab1f" title="Detach a caca graphical context from a caca backend context. ">caca_free_display()</a> to detach the <em>libcaca</em> display, followed by <a class="el" href="group__libcaca.html#ga12394c16c9ca94b61198be929ef8580d" title="Free a libcaca canvas. ">caca_free_canvas()</a> to free the underlying <em>libcaca</em> canvas. Alternatively, if the canvas was created by <a class="el" href="group__caca__display.html#gac393d4446d813f6e4ba93d2b583c1edb" title="Attach a caca graphical context to a caca canvas. ">caca_create_display()</a>, it will be automatically destroyed by <a class="el" href="group__caca__display.html#gac1b5b4540a500dd59eaa673d784fab1f" title="Detach a caca graphical context from a caca backend context. ">caca_free_display()</a>.</li>
</ul>
<h2><a class="anchor" id="bar2"></a>
Event handling</h2>
<ul>
<li><b><a class="el" href="group__caca__event.html#ga98e74dedbe1629c0fc9460761696e050" title="Get the next mouse or keyboard input event. ">caca_get_event()</a></b>: unchanged, but the event information retrieval changed a lot.</li>
<li><b>caca_wait_event()</b>: use <a class="el" href="group__caca__event.html#ga98e74dedbe1629c0fc9460761696e050" title="Get the next mouse or keyboard input event. ">caca_get_event()</a> with a <code>timeout</code> argument of <b>-1</b>.</li>
<li><b><a class="el" href="group__caca__event.html#gaf01ff2ff5f63e38eed2052b53181da2d" title="Return the X mouse coordinate. ">caca_get_mouse_x()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__event.html#gac3310eaf44cc95e46be5c3e9a8a6818e" title="Return the Y mouse coordinate. ">caca_get_mouse_y()</a></b>: unchanged.</li>
</ul>
<h2><a class="anchor" id="bar3"></a>
Character printing</h2>
<ul>
<li><b>caca_set_color()</b>: use <a class="el" href="group__caca__attributes.html#ga1cd39df80cc6b537a4df18415a8605cf" title="Set the default colour pair for text (ANSI version). ">caca_set_color_ansi()</a> or <a class="el" href="group__caca__attributes.html#gac031e1af3a6bce86128bb1a3050550bc" title="Set the default colour pair for text (truecolor version). ">caca_set_color_argb()</a>.</li>
<li><b>caca_get_fg_color()</b>: use <a class="el" href="group__caca__attributes.html#gafb35087f212d75b431fc501b3a777b6b" title="Get the text attribute at the given coordinates. ">caca_get_attr()</a>.</li>
<li><b>caca_get_bg_color()</b>: use <a class="el" href="group__caca__attributes.html#gafb35087f212d75b431fc501b3a777b6b" title="Get the text attribute at the given coordinates. ">caca_get_attr()</a>.</li>
<li><b>caca_get_color_name()</b>: this function is now deprecated due to major uselessness.</li>
<li><b>caca_putchar()</b>: use <a class="el" href="group__caca__canvas.html#ga21864614dada3ee29f10987a6e0d3064" title="Print an ASCII or Unicode character. ">caca_put_char()</a>.</li>
<li><b>caca_putstr()</b>: use <a class="el" href="group__caca__canvas.html#gac9370c0854f358b88d0cb8caf07fb6d3" title="Print a string. ">caca_put_str()</a>.</li>
<li><b><a class="el" href="group__caca__canvas.html#gaa68d5ce7e429e58798b13af51d51c8f1" title="Print a formated string. ">caca_printf()</a></b>: unchanged.</li>
<li><b>caca_clear()</b>: use <a class="el" href="group__caca__canvas.html#ga6e4271568497c86d3b9969b767f21424" title="Clear the canvas. ">caca_clear_canvas()</a>.</li>
</ul>
<h2><a class="anchor" id="bar4"></a>
Primitives drawing</h2>
<p>These functions are almost unchanged, except for Unicode support and the fact that they now act on a given canvas.</p>
<ul>
<li><b><a class="el" href="group__caca__primitives.html#gabc71affc6ade0542027ae550b3c9414d" title="Draw a line on the canvas using the given character. ">caca_draw_line()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__primitives.html#ga9d2dc277a68be01c2b9a9ae451502c93" title="Draw a polyline. ">caca_draw_polyline()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__primitives.html#ga582390717ed8ba5ed74add57f77dd904" title="Draw a thin line on the canvas, using ASCII art. ">caca_draw_thin_line()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__primitives.html#ga96e467999ef078a0f3fe13c3ed33cec2" title="Draw an ASCII art thin polyline. ">caca_draw_thin_polyline()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__primitives.html#ga1474b9e0c8d9acf560fbe9520ef1ce52" title="Draw a circle on the canvas using the given character. ">caca_draw_circle()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__primitives.html#gae176d4b61002fda77a36cb2197e270ef" title="Draw an ellipse on the canvas using the given character. ">caca_draw_ellipse()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__primitives.html#ga33e443efb0d644bd0f7169859c44c034" title="Draw a thin ellipse on the canvas. ">caca_draw_thin_ellipse()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__primitives.html#ga88999baf4328c454b32c1d2e186fab5a" title="Fill an ellipse on the canvas using the given character. ">caca_fill_ellipse()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__primitives.html#ga11447c3e8ec6d5248218b7bd3bbd0cb9" title="Draw a box on the canvas using the given character. ">caca_draw_box()</a></b>: unchanged, but the argument meaning changed (width and height instead of corner coordinates).</li>
<li><b><a class="el" href="group__caca__primitives.html#ga1b59640c7fef61e5d785f5cc3d19e244" title="Draw a thin box on the canvas. ">caca_draw_thin_box()</a></b>: use <a class="el" href="group__caca__primitives.html#ga1b59640c7fef61e5d785f5cc3d19e244" title="Draw a thin box on the canvas. ">caca_draw_thin_box()</a> or <a class="el" href="group__caca__primitives.html#ga5b40ca2e8c098cb75e678503363c070f" title="Draw a box on the canvas using CP437 characters. ">caca_draw_cp437_box()</a>, also the argument meaning changed (width and height instead of corner coordinates).</li>
<li><b><a class="el" href="group__caca__primitives.html#ga864247612376401090a5ab8e9f716d78" title="Fill a box on the canvas using the given character. ">caca_fill_box()</a></b>: unchanged, but the argument meaning changed (width and height instead of corner coordinates).</li>
<li><b><a class="el" href="group__caca__primitives.html#ga558ad62d3d2a73a19fca4c684121e91a" title="Draw a triangle on the canvas using the given character. ">caca_draw_triangle()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__primitives.html#ga2cb07d94aa4f5ff90795795ce6a364b8" title="Draw a thin triangle on the canvas. ">caca_draw_thin_triangle()</a></b>: unchanged.</li>
<li><b><a class="el" href="group__caca__primitives.html#gaf7639315e8de3e0c1f3aa7fc557e155f" title="Fill a triangle on the canvas using the given character. ">caca_fill_triangle()</a></b>: unchanged.</li>
</ul>
<h2><a class="anchor" id="bar5"></a>
Mathematical functions</h2>
<ul>
<li><b><a class="el" href="group__libcaca.html#ga685374ff836369f58a5c32a414096f2e" title="Generate a random integer within a range. ">caca_rand()</a></b>: unchanged, but the second argument is different, make sure you take that into account.</li>
<li><b>caca_sqrt()</b>: this function is now deprecated, use your system's <b>sqrt()</b> call instead.</li>
</ul>
<h2><a class="anchor" id="bar6"></a>
Sprite handling</h2>
<p>The newly introduced canvases can have several frames. Sprites are hence completely deprecated.</p>
<ul>
<li><b>caca_load_sprite()</b>: use caca_import_file().</li>
<li><b>caca_get_sprite_frames()</b>: use <a class="el" href="group__caca__frame.html#ga7dca169ceb67f3ea770a8aaaf7214957" title="Get the number of frames in a canvas. ">caca_get_frame_count()</a>.</li>
<li><b>caca_get_sprite_width()</b>: use <a class="el" href="group__libcaca.html#gad85b2ff4c7f952b3cc32f117343a6375" title="Get the canvas width. ">caca_get_canvas_width()</a>.</li>
<li><b>caca_get_sprite_height()</b>: use <a class="el" href="group__libcaca.html#gaa529140e8cf31379a6b57af7c37c9d2f" title="Get the canvas height. ">caca_get_canvas_height()</a>.</li>
<li><b>caca_get_sprite_dx()</b>: use <a class="el" href="group__caca__canvas.html#ga4d79ed0406204f209c6afb3182c17bae" title="Get X handle position. ">caca_get_canvas_handle_x()</a>.</li>
<li><b>caca_get_sprite_dy()</b>: use <a class="el" href="group__caca__canvas.html#ga21f39ab1806b05bd15521eaee63558b8" title="Get Y handle position. ">caca_get_canvas_handle_y()</a>.</li>
<li><b>caca_draw_sprite()</b>: use <a class="el" href="group__caca__frame.html#ga6a09db01455121e5e58d081b71c55e81" title="Activate a given canvas frame. ">caca_set_frame()</a> and <a class="el" href="group__caca__canvas.html#ga9cad4c6bc9bc7f43cb8403cf26ee7d0a" title="Blit a canvas onto another one. ">caca_blit()</a>.</li>
<li><b>caca_free_sprite()</b>: use <a class="el" href="group__libcaca.html#ga12394c16c9ca94b61198be929ef8580d" title="Free a libcaca canvas. ">caca_free_canvas()</a>.</li>
</ul>
<h2><a class="anchor" id="bar7"></a>
Bitmap handling</h2>
<p>Bitmaps have been renamed to dithers, because these objects do not in fact store any pixels, they just have information on how bitmaps will be dithered.</p>
<ul>
<li><b>caca_create_bitmap()</b>: use <a class="el" href="group__caca__dither.html#ga08c338d4fb79aff467f4056c857b12df" title="Create an internal dither object. ">caca_create_dither()</a>.</li>
<li><b>caca_set_bitmap_palette()</b>: use <a class="el" href="group__caca__dither.html#gaee20b3233a6dbe8147c36f82039e481a" title="Set the palette of an 8bpp dither object. ">caca_set_dither_palette()</a>.</li>
<li><b>caca_draw_bitmap()</b>: use <a class="el" href="group__caca__dither.html#gae7e10436664deb729029918c6275edb6" title="Dither a bitmap on the canvas. ">caca_dither_bitmap()</a>.</li>
<li><b>caca_free_bitmap()</b>: use <a class="el" href="group__caca__dither.html#ga5b23aea21bcbbcec02e45383721a00f6" title="Free the memory associated with a dither. ">caca_free_dither()</a>.</li>
</ul>
<h1><a class="anchor" id="foo4"></a>
Compilation</h1>
<p>The <code>caca-config</code> utility is deprecated in favour of the standard <code>pkg-config</code> interface:</p>
<div class="fragment"><div class="line">gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`</div>
<div class="line">gcc foobar.o -o foobar `pkg-config --libs caca`</div>
</div><!-- fragment --><p><code>caca-config</code> is still provided as a convenience tool but may be removed in the future. </p>
</div></div><!-- contents -->
</body>
</html>
|