/* * libcaca ASCII-Art library * Copyright (c) 2002, 2003 Sam Hocevar * All Rights Reserved * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA * 02111-1307 USA */ /** \file caca.h * \version \$Id$ * \author Sam Hocevar * \brief The \e libcaca public header. * * This header contains the public types and functions that applications * using \e libcaca may use. */ /** \mainpage libcaca developer documentation * * \section intro Introduction * * \e libcaca is a graphics library that outputs text instead of pixels, * so that it can work on older video cards or text terminals. It is not * unlike the famous AAlib library. libcaca needs a terminal to work, * thus it should work on all Unix systems (including Mac OS X) using * either the slang library or the ncurses library, on DOS using the conio * library, and on Windows systems using either slang or ncurses (through * Cygwin emulation) or conio. * * \e libcaca is free software, released under the GNU Lesser General * Public License. This ensures that \e libcaca will always remain free * software. * * \section api The libcaca API * * The complete \e libcaca programming interface is available from the * caca.h file. * * \section env Environment variables * * Some environment variables can be used to change the behaviour of * \e libcaca without having to modify the program which uses it. 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. * * \li \b CACA_BACKGROUND: set the background type. * - \c solid uses solid coloured backgrounds for all characters. This * feature does not work with all terminal emulators. This is the * default choice. * - \c black uses only black backgrounds to render characters. * * \li \b CACA_ANTIALIASING: set the antialiasing mode. Antialiasing * smoothens the rendered image and avoids the commonly seen staircase * effect. * - \c none disables antialiasing. * - \c prefilter uses a simple prefilter antialiasing method. This is * the default choice. * * \li \b CACA_DITHERING: set the dithering mode. Dithering is necessary * when rendering a picture that has more colours than the usually * available palette. * - \c none disables dithering. * - \c ordered2 uses a 2x2 bayer matrix for dithering. * - \c ordered4 uses a 4x4 bayer matrix for dithering. This is the * default choice. * - \c ordered8 uses a 8x8 bayer matrix for dithering. * - \c random uses random dithering. */ #ifndef __CACA_H__ #define __CACA_H__ #ifdef __cplusplus extern "C" { #endif /** * The colour definitions to be used with caca_set_color(). */ enum caca_color { CACA_COLOR_BLACK = 0, CACA_COLOR_BLUE = 1, CACA_COLOR_GREEN = 2, CACA_COLOR_CYAN = 3, CACA_COLOR_RED = 4, CACA_COLOR_MAGENTA = 5, CACA_COLOR_BROWN = 6, CACA_COLOR_LIGHTGRAY = 7, CACA_COLOR_DARKGRAY = 8, CACA_COLOR_LIGHTBLUE = 9, CACA_COLOR_LIGHTGREEN = 10, CACA_COLOR_LIGHTCYAN = 11, CACA_COLOR_LIGHTRED = 12, CACA_COLOR_LIGHTMAGENTA = 13, CACA_COLOR_YELLOW = 14, CACA_COLOR_WHITE = 15 }; const char *caca_get_color_name(enum caca_color); /** * The internal libcaca features. */ enum caca_feature { /* Properties of background characters */ CACA_BACKGROUND = 0x10, CACA_BACKGROUND_BLACK = 0x11, CACA_BACKGROUND_SOLID = 0x12, #define CACA_BACKGROUND_MIN 0x11 #define CACA_BACKGROUND_MAX 0x12 /* Antialiasing features */ CACA_ANTIALIASING = 0x20, CACA_ANTIALIASING_NONE = 0x21, CACA_ANTIALIASING_PREFILTER = 0x22, #define CACA_ANTIALIASING_MIN 0x21 #define CACA_ANTIALIASING_MAX 0x22 /* Dithering methods */ CACA_DITHERING = 0x30, CACA_DITHERING_NONE = 0x31, CACA_DITHERING_ORDERED2 = 0x32, CACA_DITHERING_ORDERED4 = 0x33, CACA_DITHERING_ORDERED8 = 0x34, CACA_DITHERING_RANDOM = 0x35, #define CACA_DITHERING_MIN 0x31 #define CACA_DITHERING_MAX 0x35 /* Unknown feature */ CACA_UNKNOWN_FEATURE = 0xffff }; const char *caca_get_feature_name(enum caca_feature); /* Backwards compatibility */ #define caca_dithering caca_feature #define caca_set_dithering caca_set_feature #define caca_get_dithering_name caca_get_feature_name #define CACA_DITHER_NONE CACA_DITHERING_NONE #define CACA_DITHER_ORDERED CACA_DITHERING_ORDERED8 #define CACA_DITHER_RANDOM CACA_DITHERING_RANDOM /** * The event types returned by caca_get_event(). */ enum caca_event { CACA_EVENT_NONE = 0x00000000, CACA_EVENT_KEY_PRESS = 0x01000000, CACA_EVENT_KEY_RELEASE = 0x02000000, CACA_EVENT_MOUSE_CLICK = 0x04000000 }; /** * The special key values returned by caca_get_event(). */ enum caca_key { CACA_KEY_UP = 273, CACA_KEY_DOWN = 274, CACA_KEY_LEFT = 275, CACA_KEY_RIGHT = 276, CACA_KEY_F1 = 282, CACA_KEY_F2 = 283, CACA_KEY_F3 = 284, CACA_KEY_F4 = 285, CACA_KEY_F5 = 286, CACA_KEY_F6 = 287, CACA_KEY_F7 = 288, CACA_KEY_F8 = 289, CACA_KEY_F9 = 290, CACA_KEY_F10 = 291, CACA_KEY_F11 = 292, CACA_KEY_F12 = 293, CACA_KEY_F13 = 294, CACA_KEY_F14 = 295, CACA_KEY_F15 = 296 }; /* * Basic functions */ int caca_init(void); void caca_set_delay(unsigned int); enum caca_feature caca_get_feature(enum caca_feature); void caca_set_feature(enum caca_feature); unsigned int caca_get_rendertime(void); unsigned int caca_get_width(void); unsigned int caca_get_height(void); void caca_refresh(void); void caca_end(void); /* * Events */ unsigned int caca_get_event(void); /* * Character graphics */ void caca_set_color(enum caca_color, enum caca_color); enum caca_color caca_get_fg_color(void); enum caca_color caca_get_bg_color(void); void caca_putchar(int, int, char); void caca_putstr(int, int, const char *); void caca_printf(int, int, const char *, ...); void caca_clear(void); /* * Graphics primitives */ void caca_draw_line(int, int, int, int, char); void caca_draw_polyline(const int x[], const int y[], int, char); void caca_draw_thin_line(int, int, int, int); void caca_draw_thin_polyline(const int x[], const int y[], int); void caca_draw_circle(int, int, int, char); void caca_draw_ellipse(int, int, int, int, char); void caca_draw_thin_ellipse(int, int, int, int); void caca_fill_ellipse(int, int, int, int, char); void caca_draw_box(int, int, int, int, char); void caca_draw_thin_box(int, int, int, int); void caca_fill_box(int, int, int, int, char); void caca_draw_triangle(int, int, int, int, int, int, char); void caca_draw_thin_triangle(int, int, int, int, int, int); void caca_fill_triangle(int, int, int, int, int, int, char); /* * Maths */ int caca_rand(int, int); unsigned int caca_sqrt(unsigned int); /* * Sprite handling */ struct caca_sprite; struct caca_sprite * caca_load_sprite(const char *); int caca_get_sprite_frames(const struct caca_sprite *); int caca_get_sprite_width(const struct caca_sprite *, int); int caca_get_sprite_height(const struct caca_sprite *, int); int caca_get_sprite_dx(const struct caca_sprite *, int); int caca_get_sprite_dy(const struct caca_sprite *, int); void caca_draw_sprite(int, int, const struct caca_sprite *, int); void caca_free_sprite(struct caca_sprite *); /* * Bitmap handling */ struct caca_bitmap; struct caca_bitmap *caca_create_bitmap(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, unsigned int); void caca_set_bitmap_palette(struct caca_bitmap *, unsigned int r[], unsigned int g[], unsigned int b[], unsigned int a[]); void caca_draw_bitmap(int, int, int, int, const struct caca_bitmap *, void *); void caca_free_bitmap(struct caca_bitmap *); #ifdef __cplusplus } #endif #endif /* __CACA_H__ */