From d0dd70b64cd8fd769d1f2cfc140962da0194d79d Mon Sep 17 00:00:00 2001 From: Sam Hocevar Date: Fri, 21 Apr 2006 18:03:22 +0000 Subject: [PATCH] * Documentation improvements. Wrote a small migration guide and added the skeleton of a tutorial for Jylam. --- TODO | 32 --------- caca/caca.h | 4 +- cucul/cucul.h | 20 +++--- doc/Makefile.am | 3 +- doc/libcaca.dox | 34 ++++------ doc/migrating.dox | 165 ++++++++++++++++++++++++++++++++++++++++++++++ doc/user.dox | 26 ++++++++ 7 files changed, 218 insertions(+), 66 deletions(-) create mode 100644 doc/migrating.dox create mode 100644 doc/user.dox diff --git a/TODO b/TODO index 903ec42..fd89882 100644 --- a/TODO +++ b/TODO @@ -7,39 +7,27 @@ - all the sprite stuff (loading, saving, blitting, transparency support, background colour support, thinking of a storage format, etc.) - - Or maybe, instead of doing shit with the sprites, just allow canvases to have several buffers, allow to change the active buffer, and treat sprites like that. - - ASCII/ANSI art loading functions (maybe load them as sprites) - \subsection indep API-independent stuff - support for transparency (CUCUL_COLOR_TRANSPARENT) - - Brightness, contrast support for bitmaps (the functions are here, we just need to fill them) - - Error distribution dithering - - Add a random factor to the random ditherer. No need to change the API for that, we can just pass "random:10" instead of "random" to the cucul_set_bitmap_dithering() function. - - Implement the colour modes set in cucul_set_bitmap_color(). For the moment only "full16" and "16" are implemented. - - Fix the thin ellipse rendering (currently it's only |s and -s, we could make them smoother by using ' ` , etc). - - support for double width glyphs (also needs some libcaca changes) - - better mask support in cucul_blit() - - factor internal Unicode character conversions, especially UCS4 -> UTF-8 - - optimise exporters so that they do not allocate huge blocks of memory when they only need half of it. @@ -51,20 +39,14 @@ - text edit widget with cursor support (I'm unsure about this, it seems pretty difficult) - \subsection indep API-independent stuff - Write a Linux console output - - Better keyboard driver in an X terminal, see http://groups.yahoo.com/group/zepp/message/381 - - Unicode support for X11 (maybe through Xft) - - fix Unicode support for ncurses - - Unicode support for GL - - and Jylam wants a framebuffer output @@ -73,35 +55,27 @@ \subsection needed Needed - Fix Python - - Fix Perl - - C# (it's the next big thing, believe me) - - PHP (together with the HTML output it would allow for nice web applications) - \subsection notimp Not that important - Ruby - - Java \section kernel Kernel mode - keyboard support - - printf/fprintf are missing - - Improve malloc/free so that we can reuse freed memory \section doc Documentation - Write a tutorial. - - Draw a nicer logo @@ -110,25 +84,19 @@ \section cacaview cacaview - File browser - - open ANSI files - - save in different formats - \section cacadraw cacadraw - Does not exist yet, but I want it. A modern ANSI editor that can also do Unicode. - \section cuculet CUCUlet - Does not exist yet, but I want it. A replacement for FIGlet that can also do Unicode - - Colour support, of course: outputs to IRC, ANSI, HTML... - - Can open FIGlet fonts */ diff --git a/caca/caca.h b/caca/caca.h index f009f2e..d4b544c 100644 --- a/caca/caca.h +++ b/caca/caca.h @@ -143,7 +143,7 @@ enum caca_key CACA_KEY_F15 = 0x128 /**< The F15 key. */ }; -/** \defgroup caca Basic libcaca functions +/** \defgroup caca libcaca basic functions * * These functions provide the basic \e libcaca routines for driver * initialisation, system information retrieval and configuration. @@ -159,7 +159,7 @@ unsigned int caca_get_display_height(caca_display_t *); int caca_set_display_title(caca_display_t *, char const *); /* @} */ -/** \defgroup event Event handling +/** \defgroup event libcaca event handling * * These functions handle user events such as keyboard input and mouse * clicks. diff --git a/cucul/cucul.h b/cucul/cucul.h index 7f7b25f..73ba454 100644 --- a/cucul/cucul.h +++ b/cucul/cucul.h @@ -42,7 +42,7 @@ typedef struct cucul_buffer cucul_buffer_t; /** font structure */ typedef struct cucul_font cucul_font_t; -/** \defgroup colour Colour definitions +/** \defgroup colour libcucul colour definitions * * Colours that can be used with cucul_set_color(). * @@ -67,7 +67,7 @@ typedef struct cucul_font cucul_font_t; #define CUCUL_COLOR_TRANSPARENT 0x20 /**< The transparent colour. */ /* @} */ -/** \defgroup cucul Basic libcucul functions +/** \defgroup cucul libcucul basic functions * * These functions provide the basic \e libcaca routines for library * initialisation, system information retrieval and configuration. @@ -82,7 +82,7 @@ void cucul_free_canvas(cucul_canvas_t *); int cucul_rand(int, int); /* @} */ -/** \defgroup buffer Buffer handling +/** \defgroup buffer libcucul buffer handling * * These functions provide methods to handle libcucul buffers. * @@ -92,7 +92,7 @@ void * cucul_get_buffer_data(cucul_buffer_t *); void cucul_free_buffer(cucul_buffer_t *); /* @} */ -/** \defgroup canvas Canvas drawing +/** \defgroup canvas libcucul canvas drawing * * These functions provide low-level character printing routines and * higher level graphics functions. @@ -108,7 +108,7 @@ void cucul_clear_canvas(cucul_canvas_t *, unsigned char); void cucul_blit(cucul_canvas_t *, int, int, cucul_canvas_t const *, cucul_canvas_t const *); /* @} */ -/** \defgroup transform Canvas transformation +/** \defgroup transform libcucul canvas transformation * * These functions perform horizontal and vertical canvas flipping. * @@ -119,7 +119,7 @@ void cucul_flop(cucul_canvas_t *); void cucul_rotate(cucul_canvas_t *); /* @} */ -/** \defgroup prim Primitives drawing +/** \defgroup prim libcucul primitives drawing * * These functions provide routines for primitive drawing, such as lines, * boxes, triangles and ellipses. @@ -144,7 +144,7 @@ void cucul_draw_thin_triangle(cucul_canvas_t *, int, int, int, int, int, int); void cucul_fill_triangle(cucul_canvas_t *, int, int, int, int, int, int, char const *); /* @} */ -/** \defgroup sprite Sprite handling +/** \defgroup sprite libcucul sprite handling * * These functions provide high level routines for sprite loading, animation * and rendering. @@ -160,7 +160,7 @@ void cucul_draw_sprite(cucul_canvas_t *, int, int, cucul_sprite_t const *, int); void cucul_free_sprite(cucul_sprite_t *); /* @} */ -/** \defgroup dither Bitmap dithering +/** \defgroup dither libcucul bitmap dithering * * These functions provide high level routines for dither allocation and * rendering. @@ -190,7 +190,7 @@ void cucul_dither_bitmap(cucul_canvas_t *, int, int, int, int, void cucul_free_dither(cucul_dither_t *); /* @} */ -/** \defgroup font Font handling +/** \defgroup font libcucul font handling * * These functions provide font handling routines and high quality * canvas to bitmap rendering. @@ -205,7 +205,7 @@ void cucul_render_canvas(cucul_canvas_t *, cucul_font_t *, void *, void cucul_free_font(cucul_font_t *); /* @} */ -/** \defgroup exporter Exporters to various formats +/** \defgroup exporter libcucul exporters to various formats * * These functions export the current canvas to various text formats. It * is necessary to call cucul_free_buffer() to dispose of the data. diff --git a/doc/Makefile.am b/doc/Makefile.am index 0822634..4e930c1 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,7 @@ # $Id$ -EXTRA_DIST = doxygen.cfg.in footer.html header.html libcaca.dox $(man_MANS) +EXTRA_DIST = doxygen.cfg.in footer.html header.html $(man_MANS) \ + libcaca.dox user.dox migrating.dox tutorial.dox man_MANS = caca-config.1 cacafire.1 cacaview.1 diff --git a/doc/libcaca.dox b/doc/libcaca.dox index a56add5..3949589 100644 --- a/doc/libcaca.dox +++ b/doc/libcaca.dox @@ -21,7 +21,7 @@ software. It used to be licensed under the GNU Lesser General Public License, but that was not free enough. - \section api The libcaca API + \section devel Developer's documentation \e libcaca relies on a low-level, device independent library, called \e libcucul. \e libcucul can be used alone as a simple ASCII and/or @@ -30,34 +30,26 @@ The complete \e libcucul and \e libcaca programming interface is available from the cucul.h and caca.h headers. - \section env Environment variables + Some other topics are covered by specific sections: - Some environment variables can be used to change the behaviour of - \e libcaca without having to modify the program which uses them. These - variables are: + - \subpage tutorial + - \subpage migrating - \li \b CACA_DRIVER: set the backend video driver. In order of preference: - - \c conio uses the DOS conio.h interface. - - \c ncurses uses the ncurses library. - - \c slang uses the S-Lang library. - - \c x11 uses the native X11 driver. - - \c gl uses freeglut and opengl libraries. - - \c raw outputs to the standard output instead of rendering the - canvas. This is can be used together with cacaserver. + \section user User's documentation - \li \b CACA_GEOMETRY: set the video display size. The format of this - variable must be XxY, with X and Y being integer values. This option - currently works with the network, X11 and GL drivers. + - \subpage env - \li \b CACA_FONT: set the rendered font. The format of this variable is - implementation dependent, but since it currently only works with the - X11 driver, an X11 font name such as "fixed" or "5x7" is expected. - - \section Misc + \section misc Misc - \subpage news - \subpage authors - \subpage thanks - \subpage todo + \section license License + + Permission is granted to copy, distribute and/or modify this document + under the terms of the Do What The Fuck You Want To Public License, version + 2 as published by Sam Hocevar. For details see http://sam.zoy.org/wtfpl/ . + */ diff --git a/doc/migrating.dox b/doc/migrating.dox new file mode 100644 index 0000000..c36bd07 --- /dev/null +++ b/doc/migrating.dox @@ -0,0 +1,165 @@ +/* $Id$ */ + +/** \page migrating Migrating from libcaca 0.9 to the 1.0 API + + This section will guide you through the migration of a \e libcaca 0.9 + application to the latest API version. + + \section foo1 Overview + + The most important changes in the 1.0 API of \e libcaca are the + \e libcaca / \e libcucul split and the object-oriented design. Where + you used to do: + +\code +#include + +int main(void) +{ + /* Initialise libcaca */ + caca_init(); + /* Set window title */ + caca_set_window_title("Hello!"); + /* Choose drawing colours */ + caca_set_color(CACA_COLOR_BLACK, CACA_COLOR_WHITE); + /* Draw a string at coordinates (0, 0) */ + caca_putstr(0, 0, "This is a message"); + /* Refresh display */ + caca_refresh(); + /* Wait for a key press event */ + caca_wait_event(CACA_EVENT_KEY_PRESS); + /* Clean up library */ + caca_end(); + + return 0; +} +\endcode + + You now do: + +\code +#include +#include + +int main(void) +{ + /* Initialise libcaca */ + cucul_canvas_t *cv; caca_display_t *dp; caca_event_t ev; + cv = cucul_create_canvas(0, 0); + dp = caca_create_display(cv); + /* Set window title */ + caca_set_display_title(dp, "Hello!"); + /* Choose drawing colours */ + cucul_set_color(cv, CUCUL_COLOR_BLACK, CUCUL_COLOR_WHITE); + /* Draw a string at coordinates (0, 0) */ + cucul_putstr(cv, 0, 0, "This is a message"); + /* Refresh display */ + caca_refresh_display(); + /* Wait for a key press event */ + caca_get_event(dp, CACA_EVENT_KEY_PRESS, &ev, -1); + /* Clean up library */ + caca_free_display(dp); + cucul_free_canvas(cv); + + return 0; +} +\endcode + + Note the following important things: + + - Functions now take an object handle as their first argument. + - All input/output functions start with \b caca_ and all + drawing and text handling functions start with \b cucul_ . + + \section foo2 Function equivalence list + + \subsection bar1 Basic functions + + - \b caca_init(): use cucul_create_canvas() to create a \e libcucul canvas, + followed by caca_create_display() to attach a \e libcaca display to it. + - \b caca_set_delay(): unchanged. + - \b caca_get_feature(): deprecated. + - \b caca_set_feature(): deprecated, see cucul_set_dither_antialias(), + cucul_set_dither_color() and cucul_set_dither_mode() instead. + - \b caca_get_feature_name(): deprecated, see cucul_get_dither_mode_list(), + cucul_get_dither_antialias_list() and cucul_get_dither_color_list() + instead. + - \b caca_get_rendertime(): unchanged. + - \b caca_get_width(): use cucul_get_canvas_width(). + - \b caca_get_height(): use cucul_get_canvas_height(). + - \b caca_set_window_title(): use caca_set_display_title(). + - \b caca_get_window_width(): use caca_get_display_width(). + - \b caca_get_window_height(): use caca_get_display_height(). + - \b caca_refresh(): use caca_refresh_display(). + - \b caca_end(): use caca_free_display() to detach the \e libcaca display, + followed by cucul_free_canvas() to free the underlying \e libcucul canvas. + + \subsection bar2 Event handling + + - \b caca_get_event(): unchanged. + - \b caca_wait_event(): use caca_get_event() with a \c timeout argument + of \b -1. + - \b caca_get_mouse_x(): unchanged. + - \b caca_get_mouse_y(): unchanged. + + \subsection bar3 Character printing + + - \b caca_set_color(): use cucul_set_color() or cucul_set_truecolor(). + - \b caca_get_fg_color(): deprecated. + - \b caca_get_bg_color(): deprecated. + - \b caca_get_color_name(): use cucul_get_color_name(). + - \b caca_putchar(): use cucul_putchar(). + - \b caca_putstr(): use cucul_putstr(). + - \b caca_printf(): use cucul_printf(). + - \b caca_clear(): use cucul_clear_canvas(). + + \subsection bar4 Primitives drawing + + - \b caca_draw_line(): use cucul_draw_line(). + - \b caca_draw_polyline(): use cucul_draw_polyline(). + - \b caca_draw_thin_line(): use cucul_draw_thin_line(). + - \b caca_draw_thin_polyline(): use cucul_draw_thin_polyline(). + + - \b caca_draw_circle(): use cucul_draw_circle(). + - \b caca_draw_ellipse(): use cucul_draw_ellipse(). + - \b caca_draw_thin_ellipse(): use cucul_draw_thin_ellipse(). + - \b caca_fill_ellipse(): use cucul_fill_ellipse(). + + - \b caca_draw_box(): use cucul_draw_box(). + - \b caca_draw_thin_box(): use cucul_draw_thin_box(). + - \b caca_fill_box(): use cucul_fill_box(). + + - \b caca_draw_triangle(): use cucul_draw_triangle(). + - \b caca_draw_thin_triangle(): use cucul_draw_thin_triangle(). + - \b caca_fill_triangle(): use cucul_fill_triangle(). + + \subsection bar5 Mathematical functions + + - \b caca_rand(): use cucul_rand() + - \b caca_sqrt(): this function is now deprecated + + \subsection bar6 Sprite handling + + The sprite handling functions are currently being reworked. + + \subsection bar7 Bitmap handling + + - \b caca_create_bitmap(): use cucul_create_dither(). + - \b caca_set_bitmap_palette(): use cucul_set_dither_palette(). + - \b caca_draw_bitmap(): use cucul_dither_bitmap(). + - \b caca_free_bitmap(): use cucul_free_dither(). + + \section foo3 Compilation + + The \c caca-config utility is deprecated in favour of the standard + \c pkg-config interface: + +\code +gcc -c foobar.c -o foobar.o `pkg-config --cflags caca` +gcc foobar.o -o foobar `pkg-config --libs caca` +\endcode + + \c caca-config is still provided as a convenience tool but will be removed + in the future. + +*/ diff --git a/doc/user.dox b/doc/user.dox new file mode 100644 index 0000000..9e51b81 --- /dev/null +++ b/doc/user.dox @@ -0,0 +1,26 @@ +/* $Id$ */ + +/** \page env Environment variables + + Some environment variables can be used to change the behaviour of + \e libcaca without having to modify the program which uses them. These + variables are: + + \li \b CACA_DRIVER: set the backend video driver. In order of preference: + - \c conio uses the DOS conio.h interface. + - \c ncurses uses the ncurses library. + - \c slang uses the S-Lang library. + - \c x11 uses the native X11 driver. + - \c gl uses freeglut and opengl libraries. + - \c raw outputs to the standard output instead of rendering the + canvas. This is can be used together with cacaserver. + + \li \b CACA_GEOMETRY: set the video display size. The format of this + variable must be \c XxY, with \c X and \c Y being integer values. This + option currently works with the X11 and GL drivers. + + \li \b CACA_FONT: set the rendered font. The format of this variable is + implementation dependent, but since it currently only works with the + X11 driver, an X11 font name such as \c fixed or \c 5x7 is expected. + +*/