libcaca-migrating man page on Slackware

Man page or keyword search:  
man Server   14563 pages
apropos Keyword Search (all sections)
Output format
Slackware logo
[printable version]

libcaca-migrating(3caca)	    libcaca	      libcaca-migrating(3caca)

NAME
       libcaca-migrating - Migrating from libcaca 0.x to the 1.0 API This
       section will guide you through the migration of a libcaca 0.x
       application to the latest API version.

Overview
       The most important change in the 1.0 API of libcaca is the object-
       oriented design. See these two examples for a rough idea of what
       changed:

       #include <caca.h>

       /* libcaca program - 0.x API */
       int main(void)
       {
	   /* Initialise libcaca */
	   caca_init();
	   /* Set window title */
	   caca_set_window_title('Window');
	   /* Choose drawing colours */
	   caca_set_color(CACA_COLOR_BLACK,
			  CACA_COLOR_WHITE);
	   /* Draw a string at (0, 0) */
	   caca_putstr(0, 0, 'Hello world!');
	   /* Refresh display */
	   caca_refresh();
	   /* Wait for a key press event */
	   caca_wait_event(CACA_EVENT_KEY_PRESS);
	   /* Clean up library */
	   caca_end();

	   return 0;
       }

       #include <caca.h>

       /* libcaca program - 1.0 API */
       int main(void)
       {
	   /* Initialise libcaca */
	   caca_canvas_t *cv;
	   caca_display_t *dp;
	   dp = caca_create_display(NULL);
	   cv = caca_get_canvas(dp);
	   /* Set window title */
	   caca_set_display_title(dp, 'Window');
	   /* Choose drawing colours */
	   caca_set_color_ansi(cv, CACA_BLACK,
				   CACA_WHITE);
	   /* Draw a string at (0, 0) */
	   caca_put_str(cv, 0, 0, 'Hello world!');
	   /* Refresh display */
	   caca_refresh_display();
	   /* Wait for a key press event */
	   caca_get_event(dp, CACA_EVENT_KEY_PRESS,
			  NULL, -1);
	   /* Clean up library */
	   caca_free_display(dp);

	   return 0;
       }

       Note the following important things:

       · Most functions now take an object handle as their first argument.

Migration strategy
       You have two ways to migrate your application to use libcaca 1.x:

       · 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.

	 · Use the legacy compatibility layer.

       Using the compatibility layer is as easy as adding the following three
       lines:

       #include <caca.h>

       /* libcaca program - 0.x API */
       ...

       #include <caca.h>
       #ifdef CACA_API_VERSION_1
       #   include <caca0.h>
       #endif

       /* libcaca program - 0.x API */
       ...

       The modified code is guaranteed to build both with libcaca 0.x and
       libcaca 1.0.

Function equivalence list
   Basic functions
       · caca_init(): use caca_create_canvas() to create a libcaca canvas,
	 followed by caca_create_display() to attach a libcaca display to it.
	 Alternatively, caca_create_display() with a NULL argument will create
	 a canvas automatically.

       · caca_set_delay(): use caca_set_display_time().

       · caca_get_feature(): deprecated.

       · caca_set_feature(): deprecated, see caca_set_dither_antialias(),
	 caca_set_dither_color() and caca_set_dither_mode() instead.

       · caca_get_feature_name(): deprecated, see caca_get_dither_mode_list(),
	 caca_get_dither_antialias_list() and caca_get_dither_color_list()
	 instead.

       · caca_get_rendertime(): use caca_get_display_time().

       · caca_get_width(): use caca_get_canvas_width().

       · caca_get_height(): use caca_get_canvas_height().

       · caca_set_window_title(): use caca_set_display_title().

       · caca_get_window_width(): use caca_get_display_width().

       · caca_get_window_height(): use caca_get_display_height().

       · caca_refresh(): use caca_refresh_display().

       · caca_end(): use caca_free_display() to detach the libcaca display,
	 followed by caca_free_canvas() to free the underlying libcaca canvas.
	 Alternatively, if the canvas was created by caca_create_display(), it
	 will be automatically destroyed by caca_free_display().

   Event handling
       · caca_get_event(): unchanged, but the event information retrieval
	 changed a lot.

       · caca_wait_event(): use caca_get_event() with a timeout argument of
	 -1.

       · caca_get_mouse_x(): unchanged.

       · caca_get_mouse_y(): unchanged.

   Character printing
       · caca_set_color(): use caca_set_color_ansi() or caca_set_color_argb().

       · caca_get_fg_color(): use caca_get_attr().

       · caca_get_bg_color(): use caca_get_attr().

       · caca_get_color_name(): this function is now deprecated due to major
	 uselessness.

       · caca_putchar(): use caca_put_char().

       · caca_putstr(): use caca_put_str().

       · caca_printf(): unchanged.

       · caca_clear(): use caca_clear_canvas().

   Primitives drawing
       These functions are almost unchanged, except for Unicode support and
       the fact that they now act on a given canvas.

       · caca_draw_line(): unchanged.

	 · caca_draw_polyline(): unchanged.

	 · caca_draw_thin_line(): unchanged.

	 · caca_draw_thin_polyline(): unchanged.

       · caca_draw_circle(): unchanged.

	 · caca_draw_ellipse(): unchanged.

	 · caca_draw_thin_ellipse(): unchanged.

	 · caca_fill_ellipse(): unchanged.

       · caca_draw_box(): unchanged, but the argument meaning changed (width
	 and height instead of corner coordinates).

	 · caca_draw_thin_box(): use caca_draw_thin_box() or
	   caca_draw_cp437_box(), also the argument meaning changed (width and
	   height instead of corner coordinates).

	 · caca_fill_box(): unchanged, but the argument meaning changed (width
	   and height instead of corner coordinates).

       · caca_draw_triangle(): unchanged.

	 · caca_draw_thin_triangle(): unchanged.

	 · caca_fill_triangle(): unchanged.

   Mathematical functions
       · caca_rand(): unchanged, but the second argument is different, make
	 sure you take that into account.

       · caca_sqrt(): this function is now deprecated, use your system's
	 sqrt() call instead.

   Sprite handling
       The newly introduced canvases can have several frames. Sprites are
       hence completely deprecated.

       · caca_load_sprite(): use caca_import_file().

	 · caca_get_sprite_frames(): use caca_get_frame_count().

	 · caca_get_sprite_width(): use caca_get_canvas_width().

	 · caca_get_sprite_height(): use caca_get_canvas_height().

	 · caca_get_sprite_dx(): use caca_get_canvas_handle_x().

	 · caca_get_sprite_dy(): use caca_get_canvas_handle_y().

	 · caca_draw_sprite(): use caca_set_frame() and caca_blit().

	 · caca_free_sprite(): use caca_free_canvas().

   Bitmap handling
       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.

       · caca_create_bitmap(): use caca_create_dither().

	 · caca_set_bitmap_palette(): use caca_set_dither_palette().

	 · caca_draw_bitmap(): use caca_dither_bitmap().

	 · caca_free_bitmap(): use caca_free_dither().

Compilation
       The caca-config utility is deprecated in favour of the standard pkg-
       config interface:

       gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
       gcc foobar.o -o foobar `pkg-config --libs caca`

       caca-config is still provided as a convenience tool but may be removed
       in the future.

Version 0.99.beta18		Tue Jun 19 2012	      libcaca-migrating(3caca)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Slackware

List of man pages available for Slackware

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net