<!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.6.2-20100208 -->
<div class="contents">
<h1><a class="anchor" id="libcaca-migrating">Migrating from libcaca 0.x to the 1.0 API </a></h1><p>This section will guide you through the migration of a <em>libcaca</em> 0.x application to the latest API version.</p>
<h2><a class="anchor" id="foo1">
Overview</a></h2>
<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"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="caca_8h.html" title="The libcaca public header.">caca.h</a>></span>
<span class="comment">/* libcaca program - 0.x API */</span>
<span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)
{
<span class="comment">/* Initialise libcaca */</span>
caca_init();
<span class="comment">/* Set window title */</span>
caca_set_window_title(<span class="stringliteral">"Window"</span>);
<span class="comment">/* Choose drawing colours */</span>
caca_set_color(CACA_COLOR_BLACK,
CACA_COLOR_WHITE);
<span class="comment">/* Draw a string at (0, 0) */</span>
caca_putstr(0, 0, <span class="stringliteral">"Hello world!"</span>);
<span class="comment">/* Refresh display */</span>
caca_refresh();
<span class="comment">/* Wait for a key press event */</span>
caca_wait_event(<a class="code" href="caca_8h.html#a40754185ca237fc44a95357afba34aeaab1da825755a2ac3593cca73721b77e22">CACA_EVENT_KEY_PRESS</a>);
<span class="comment">/* Clean up library */</span>
caca_end();
<span class="keywordflow">return</span> 0;
}
</pre></div> </td><td><div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="caca_8h.html" title="The libcaca public header.">caca.h</a>></span>
<span class="comment">/* libcaca program - 1.0 API */</span>
<span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)
{
<span class="comment">/* Initialise libcaca */</span>
<a class="code" href="caca_8h.html#aae0f6938d08e6e0abbcd5a8c06504ab8">caca_canvas_t</a> *cv;
<a class="code" href="caca_8h.html#ada5af7a20f3e2f6c103078181b07393e">caca_display_t</a> *dp;
dp = <a class="code" href="group__caca__display.html#gac393d4446d813f6e4ba93d2b583c1edb" title="Attach a caca graphical context to a caca canvas.">caca_create_display</a>(NULL);
cv = <a class="code" href="group__caca__display.html#ga65670cdec61ba57879b893c997cd26da" title="Get the canvas attached to a caca graphical context.">caca_get_canvas</a>(dp);
<span class="comment">/* Set window title */</span>
<a class="code" href="group__caca__display.html#gadab2bf1e8d0bf5c3cfb3e29ab07d5641" title="Set the display title.">caca_set_display_title</a>(dp, <span class="stringliteral">"Window"</span>);
<span class="comment">/* Choose drawing colours */</span>
<a class="code" href="group__caca__attributes.html#ga1cd39df80cc6b537a4df18415a8605cf" title="Set the default colour pair for text (ANSI version).">caca_set_color_ansi</a>(cv, <a class="code" href="group__caca__attr.html#gga9db83488c6f07a5f7d773c380b3126a9a9280adda765037612d94743bdc3f346d">CACA_BLACK</a>,
<a class="code" href="group__caca__attr.html#gga9db83488c6f07a5f7d773c380b3126a9a1bd1244f952d10b9599fb314e41862ad">CACA_WHITE</a>);
<span class="comment">/* Draw a string at (0, 0) */</span>
<a class="code" href="group__caca__canvas.html#gac9370c0854f358b88d0cb8caf07fb6d3" title="Print a string.">caca_put_str</a>(cv, 0, 0, <span class="stringliteral">"Hello world!"</span>);
<span class="comment">/* Refresh display */</span>
<a class="code" href="group__caca__display.html#ga8c710eac721d05d807491a1534d1cbe7" title="Flush pending changes and redraw the screen.">caca_refresh_display</a>();
<span class="comment">/* Wait for a key press event */</span>
<a class="code" href="group__caca__event.html#ga98e74dedbe1629c0fc9460761696e050" title="Get the next mouse or keyboard input event.">caca_get_event</a>(dp, <a class="code" href="caca_8h.html#a40754185ca237fc44a95357afba34aeaab1da825755a2ac3593cca73721b77e22">CACA_EVENT_KEY_PRESS</a>,
NULL, -1);
<span class="comment">/* Clean up library */</span>
<a class="code" href="group__caca__display.html#gac1b5b4540a500dd59eaa673d784fab1f" title="Detach a caca graphical context from a caca backend context.">caca_free_display</a>(dp);
<span class="keywordflow">return</span> 0;
}
</pre></div> </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>
<h2><a class="anchor" id="foo2">
Migration strategy</a></h2>
<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"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="caca_8h.html" title="The libcaca public header.">caca.h</a>></span>
<span class="comment">/* libcaca program - 0.x API */</span>
...
</pre></div> </td><td><div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="caca_8h.html" title="The libcaca public header.">caca.h</a>></span>
<span class="preprocessor">#ifdef CACA_API_VERSION_1</span>
<span class="preprocessor"></span><span class="preprocessor"># include <caca0.h></span>
<span class="preprocessor">#endif</span>
<span class="preprocessor"></span>
<span class="comment">/* libcaca program - 0.x API */</span>
...
</pre></div> </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>
<h2><a class="anchor" id="foo3">
Function equivalence list</a></h2>
<h3><a class="anchor" id="bar1">
Basic functions</a></h3>
<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>
<h3><a class="anchor" id="bar2">
Event handling</a></h3>
<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>
<h3><a class="anchor" id="bar3">
Character printing</a></h3>
<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>
<h3><a class="anchor" id="bar4">
Primitives drawing</a></h3>
<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>
</ul>
<ul>
<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>
</ul>
<ul>
<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>
</ul>
<ul>
<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>
<h3><a class="anchor" id="bar5">
Mathematical functions</a></h3>
<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>
<h3><a class="anchor" id="bar6">
Sprite handling</a></h3>
<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>
<h3><a class="anchor" id="bar7">
Bitmap handling</a></h3>
<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>
<h2><a class="anchor" id="foo4">
Compilation</a></h2>
<p>The <code>caca-config</code> utility is deprecated in favour of the standard <code>pkg-config</code> interface:</p>
<div class="fragment"><pre class="fragment">gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
gcc foobar.o -o foobar `pkg-config --libs caca`
</pre></div><p><code>caca-config</code> is still provided as a convenience tool but may be removed in the future. </p>
</div>
</body>
</html>
