<!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>
<!-- $Id$ -->
<!-- Generated by Doxygen 1.5.9 -->
<div class="contents">
<h1><a class="anchor" name="libcaca-migrating">Migrating from libcaca 0.x to the 1.0 API </a></h1>This section will guide you through the migration of a <em>libcaca</em> 0.x application to the latest API version.<h2><a class="anchor" name="foo1">
Overview</a></h2>
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" cellspacing="3" cellpadding="3">
<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#40754185ca237fc44a95357afba34aeab1da825755a2ac3593cca73721b77e22">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#ae0f6938d08e6e0abbcd5a8c06504ab8">caca_canvas_t</a> *cv;
<a class="code" href="caca_8h.html#da5af7a20f3e2f6c103078181b07393e">caca_display_t</a> *dp;
dp = <a class="code" href="group__caca__display.html#gc393d4446d813f6e4ba93d2b583c1edb" title="Attach a caca graphical context to a caca canvas.">caca_create_display</a>(cv);
cv = <a class="code" href="group__caca__display.html#g65670cdec61ba57879b893c997cd26da" 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#gdab2bf1e8d0bf5c3cfb3e29ab07d5641" 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#g1cd39df80cc6b537a4df18415a8605cf" title="Set the default colour pair for text (ANSI version).">caca_set_color_ansi</a>(cv, <a class="code" href="group__caca__attr.html#g14a182c346372cdd6fcaa54cf2a84f05">CACA_BLACK</a>,
<a class="code" href="group__caca__attr.html#gdf659290c774e7aa588cfad292dae73f">CACA_WHITE</a>);
<span class="comment">/* Draw a string at (0, 0) */</span>
<a class="code" href="group__caca__canvas.html#gc9370c0854f358b88d0cb8caf07fb6d3" 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#g8c710eac721d05d807491a1534d1cbe7" 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#g98e74dedbe1629c0fc9460761696e050" title="Get the next mouse or keyboard input event.">caca_get_event</a>(dp, <a class="code" href="caca_8h.html#40754185ca237fc44a95357afba34aeab1da825755a2ac3593cca73721b77e22">CACA_EVENT_KEY_PRESS</a>,
NULL, -1);
<span class="comment">/* Clean up library */</span>
<a class="code" href="group__caca__display.html#gc1b5b4540a500dd59eaa673d784fab1f" 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>Functions now take an object handle as their first argument.</li><li>All input/output functions start with <b>caca_</b> and all drawing and text handling functions start with <b>caca_</b> .</li></ul>
<h2><a class="anchor" name="foo2">
Migration strategy</a></h2>
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" cellspacing="3" cellpadding="3">
<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>
<h2><a class="anchor" name="foo3">
Function equivalence list</a></h2>
<h3><a class="anchor" name="bar1">
Basic functions</a></h3>
<ul>
<li><b>caca_init()</b>: use <a class="el" href="group__libcaca.html#g00caafb33b9d7033d064a642bcad83da" 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#gc393d4446d813f6e4ba93d2b583c1edb" title="Attach a caca graphical context to a caca canvas.">caca_create_display()</a> to attach a <em>libcaca</em> display to it.</li><li><b>caca_set_delay()</b>: use <a class="el" href="group__caca__display.html#g0340d64c3e7f23e11af749c4da83dfde" 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#g6e11d68966e0b2d709b377385fbcabd4" title="Set dither antialiasing.">caca_set_dither_antialias()</a>, <a class="el" href="group__caca__dither.html#ge4a7a941295c958221d9010070f0c35c" 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#g6e0986062cb064bf7bcef0105233857e" title="Get available antialiasing methods.">caca_get_dither_antialias_list()</a> and <a class="el" href="group__caca__dither.html#g973d84c24e352d3da09f02a49b79ebf0" 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#g74339a36233beeee2ca5fe531885538a" 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#gd85b2ff4c7f952b3cc32f117343a6375" 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#ga529140e8cf31379a6b57af7c37c9d2f" 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#gdab2bf1e8d0bf5c3cfb3e29ab07d5641" 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#ge0cc5bc7835df240b242929cc77024ac" 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#gf540716e9e5faa22a3dc5d0c68761a1f" 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#g8c710eac721d05d807491a1534d1cbe7" 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#gc1b5b4540a500dd59eaa673d784fab1f" 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#g12394c16c9ca94b61198be929ef8580d" title="Uninitialise libcaca.">caca_free_canvas()</a> to free the underlying <em>libcaca</em> canvas.</li></ul>
<h3><a class="anchor" name="bar2">
Event handling</a></h3>
<ul>
<li><b><a class="el" href="group__caca__event.html#g98e74dedbe1629c0fc9460761696e050" 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#g98e74dedbe1629c0fc9460761696e050" 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#gf01ff2ff5f63e38eed2052b53181da2d" title="Return the X mouse coordinate.">caca_get_mouse_x()</a></b>: unchanged.</li><li><b><a class="el" href="group__caca__event.html#gc3310eaf44cc95e46be5c3e9a8a6818e" title="Return the Y mouse coordinate.">caca_get_mouse_y()</a></b>: unchanged.</li></ul>
<h3><a class="anchor" name="bar3">
Character printing</a></h3>
<ul>
<li><b>caca_set_color()</b>: use <a class="el" href="group__caca__attributes.html#g1cd39df80cc6b537a4df18415a8605cf" title="Set the default colour pair for text (ANSI version).">caca_set_color_ansi()</a> or <a class="el" href="group__caca__attributes.html#gc031e1af3a6bce86128bb1a3050550bc" 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#gfb35087f212d75b431fc501b3a777b6b" 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#gfb35087f212d75b431fc501b3a777b6b" 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#g21864614dada3ee29f10987a6e0d3064" 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#gc9370c0854f358b88d0cb8caf07fb6d3" title="Print a string.">caca_put_str()</a>.</li><li><b><a class="el" href="group__caca__canvas.html#ga68d5ce7e429e58798b13af51d51c8f1" title="Print a formated string.">caca_printf()</a></b>: use <a class="el" href="group__caca__canvas.html#ga68d5ce7e429e58798b13af51d51c8f1" title="Print a formated string.">caca_printf()</a>.</li><li><b>caca_clear()</b>: use <a class="el" href="group__caca__canvas.html#g6e4271568497c86d3b9969b767f21424" title="Clear the canvas.">caca_clear_canvas()</a>.</li></ul>
<h3><a class="anchor" name="bar4">
Primitives drawing</a></h3>
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#gbc71affc6ade0542027ae550b3c9414d" title="Draw a line on the canvas using the given character.">caca_draw_line()</a></b>: use <a class="el" href="group__caca__primitives.html#gbc71affc6ade0542027ae550b3c9414d" title="Draw a line on the canvas using the given character.">caca_draw_line()</a>.</li><li><b><a class="el" href="group__caca__primitives.html#g9d2dc277a68be01c2b9a9ae451502c93" title="Draw a polyline.">caca_draw_polyline()</a></b>: use <a class="el" href="group__caca__primitives.html#g9d2dc277a68be01c2b9a9ae451502c93" title="Draw a polyline.">caca_draw_polyline()</a>.</li><li><b><a class="el" href="group__caca__primitives.html#g582390717ed8ba5ed74add57f77dd904" title="Draw a thin line on the canvas, using ASCII art.">caca_draw_thin_line()</a></b>: use <a class="el" href="group__caca__primitives.html#g582390717ed8ba5ed74add57f77dd904" title="Draw a thin line on the canvas, using ASCII art.">caca_draw_thin_line()</a>.</li><li><b><a class="el" href="group__caca__primitives.html#g96e467999ef078a0f3fe13c3ed33cec2" title="Draw an ASCII art thin polyline.">caca_draw_thin_polyline()</a></b>: use <a class="el" href="group__caca__primitives.html#g96e467999ef078a0f3fe13c3ed33cec2" title="Draw an ASCII art thin polyline.">caca_draw_thin_polyline()</a>.</li></ul>
<p>
<ul>
<li><b><a class="el" href="group__caca__primitives.html#g1474b9e0c8d9acf560fbe9520ef1ce52" title="Draw a circle on the canvas using the given character.">caca_draw_circle()</a></b>: use <a class="el" href="group__caca__primitives.html#g1474b9e0c8d9acf560fbe9520ef1ce52" title="Draw a circle on the canvas using the given character.">caca_draw_circle()</a>.</li><li><b><a class="el" href="group__caca__primitives.html#ge176d4b61002fda77a36cb2197e270ef" title="Draw an ellipse on the canvas using the given character.">caca_draw_ellipse()</a></b>: use <a class="el" href="group__caca__primitives.html#ge176d4b61002fda77a36cb2197e270ef" title="Draw an ellipse on the canvas using the given character.">caca_draw_ellipse()</a>.</li><li><b><a class="el" href="group__caca__primitives.html#g33e443efb0d644bd0f7169859c44c034" title="Draw a thin ellipse on the canvas.">caca_draw_thin_ellipse()</a></b>: use <a class="el" href="group__caca__primitives.html#g33e443efb0d644bd0f7169859c44c034" title="Draw a thin ellipse on the canvas.">caca_draw_thin_ellipse()</a>.</li><li><b><a class="el" href="group__caca__primitives.html#g88999baf4328c454b32c1d2e186fab5a" title="Fill an ellipse on the canvas using the given character.">caca_fill_ellipse()</a></b>: use <a class="el" href="group__caca__primitives.html#g88999baf4328c454b32c1d2e186fab5a" title="Fill an ellipse on the canvas using the given character.">caca_fill_ellipse()</a>.</li></ul>
<p>
<ul>
<li><b><a class="el" href="group__caca__primitives.html#g11447c3e8ec6d5248218b7bd3bbd0cb9" title="Draw a box on the canvas using the given character.">caca_draw_box()</a></b>: use <a class="el" href="group__caca__primitives.html#g11447c3e8ec6d5248218b7bd3bbd0cb9" title="Draw a box on the canvas using the given character.">caca_draw_box()</a>.</li><li><b><a class="el" href="group__caca__primitives.html#g1b59640c7fef61e5d785f5cc3d19e244" title="Draw a thin box on the canvas.">caca_draw_thin_box()</a></b>: use <a class="el" href="group__caca__primitives.html#g1b59640c7fef61e5d785f5cc3d19e244" title="Draw a thin box on the canvas.">caca_draw_thin_box()</a> or <a class="el" href="group__caca__primitives.html#g5b40ca2e8c098cb75e678503363c070f" title="Draw a box on the canvas using CP437 characters.">caca_draw_cp437_box()</a>.</li><li><b><a class="el" href="group__caca__primitives.html#g864247612376401090a5ab8e9f716d78" title="Fill a box on the canvas using the given character.">caca_fill_box()</a></b>: use <a class="el" href="group__caca__primitives.html#g864247612376401090a5ab8e9f716d78" title="Fill a box on the canvas using the given character.">caca_fill_box()</a>.</li></ul>
<p>
<ul>
<li><b><a class="el" href="group__caca__primitives.html#g558ad62d3d2a73a19fca4c684121e91a" title="Draw a triangle on the canvas using the given character.">caca_draw_triangle()</a></b>: use <a class="el" href="group__caca__primitives.html#g558ad62d3d2a73a19fca4c684121e91a" title="Draw a triangle on the canvas using the given character.">caca_draw_triangle()</a>.</li><li><b><a class="el" href="group__caca__primitives.html#g2cb07d94aa4f5ff90795795ce6a364b8" title="Draw a thin triangle on the canvas.">caca_draw_thin_triangle()</a></b>: use <a class="el" href="group__caca__primitives.html#g2cb07d94aa4f5ff90795795ce6a364b8" title="Draw a thin triangle on the canvas.">caca_draw_thin_triangle()</a>.</li><li><b><a class="el" href="group__caca__primitives.html#gf7639315e8de3e0c1f3aa7fc557e155f" title="Fill a triangle on the canvas using the given character.">caca_fill_triangle()</a></b>: use <a class="el" href="group__caca__primitives.html#gf7639315e8de3e0c1f3aa7fc557e155f" title="Fill a triangle on the canvas using the given character.">caca_fill_triangle()</a>.</li></ul>
<h3><a class="anchor" name="bar5">
Mathematical functions</a></h3>
<ul>
<li><b><a class="el" href="group__libcaca.html#g685374ff836369f58a5c32a414096f2e" title="Generate a random integer within a range.">caca_rand()</a></b>: use <a class="el" href="group__libcaca.html#g685374ff836369f58a5c32a414096f2e" title="Generate a random integer within a range.">caca_rand()</a>. 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" name="bar6">
Sprite handling</a></h3>
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#g7dca169ceb67f3ea770a8aaaf7214957" 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#gd85b2ff4c7f952b3cc32f117343a6375" 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#ga529140e8cf31379a6b57af7c37c9d2f" 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#g4d79ed0406204f209c6afb3182c17bae" 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#g21f39ab1806b05bd15521eaee63558b8" 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#g6a09db01455121e5e58d081b71c55e81" title="Activate a given canvas frame.">caca_set_frame()</a> and <a class="el" href="group__caca__canvas.html#g9cad4c6bc9bc7f43cb8403cf26ee7d0a" 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#g12394c16c9ca94b61198be929ef8580d" title="Uninitialise libcaca.">caca_free_canvas()</a>.</li></ul>
<h3><a class="anchor" name="bar7">
Bitmap handling</a></h3>
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#g08c338d4fb79aff467f4056c857b12df" 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#gee20b3233a6dbe8147c36f82039e481a" 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#gd0fdcb7254d1e7dfc44fb6822372fa01" 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#g5b23aea21bcbbcec02e45383721a00f6" title="Free the memory associated with a dither.">caca_free_dither()</a>.</li></ul>
<h2><a class="anchor" name="foo4">
Compilation</a></h2>
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. </div>
<!-- $Id$ -->
</body>
</html>
