Ignore:
Timestamp:
Dec 23, 2003, 12:08:37 PM (19 years ago)
Author:
Sam Hocevar
Message:
  • More API documentation.
File:
1 edited

Legend:

Unmodified
Added
Removed
  • libcaca/trunk/src/caca.h

    r265 r267  
    4848 *
    4949 *   The complete \e libcaca programming interface is available from the
    50  *   caca.h file.
     50 *   caca.h header.
    5151 *
    5252 *   \section env Environment variables
     
    7979 *       available palette.
    8080 *       - \c none disables dithering.
    81  *       - \c ordered2 uses a 2x2 bayer matrix for dithering.
    82  *       - \c ordered4 uses a 4x4 bayer matrix for dithering. This is the
     81 *       - \c ordered2 uses a 2x2 Bayer matrix for dithering.
     82 *       - \c ordered4 uses a 4x4 Bayer matrix for dithering. This is the
    8383 *         default choice.
    84  *       - \c ordered8 uses a 8x8 bayer matrix for dithering.
     84 *       - \c ordered8 uses a 8x8 Bayer matrix for dithering.
    8585 *       - \c random uses random dithering.
    8686 */
     
    9494#endif
    9595
    96 /**
    97  * The colour definitions to be used with caca_set_color().
     96/** \brief Colour definitions.
     97 *
     98 *  This enum lists all colours that can be used with caca_set_color().
    9899 */
    99100enum caca_color
    100101{
    101     CACA_COLOR_BLACK = 0,
    102     CACA_COLOR_BLUE = 1,
    103     CACA_COLOR_GREEN = 2,
    104     CACA_COLOR_CYAN = 3,
    105     CACA_COLOR_RED = 4,
    106     CACA_COLOR_MAGENTA = 5,
    107     CACA_COLOR_BROWN = 6,
    108     CACA_COLOR_LIGHTGRAY = 7,
    109     CACA_COLOR_DARKGRAY = 8,
    110     CACA_COLOR_LIGHTBLUE = 9,
    111     CACA_COLOR_LIGHTGREEN = 10,
    112     CACA_COLOR_LIGHTCYAN = 11,
    113     CACA_COLOR_LIGHTRED = 12,
    114     CACA_COLOR_LIGHTMAGENTA = 13,
    115     CACA_COLOR_YELLOW = 14,
    116     CACA_COLOR_WHITE = 15
    117 };
    118 
     102    CACA_COLOR_BLACK = 0, /**< The colour index for black. */
     103    CACA_COLOR_BLUE = 1, /**< The colour index for blue. */
     104    CACA_COLOR_GREEN = 2, /**< The colour index for green. */
     105    CACA_COLOR_CYAN = 3, /**< The colour index for cyan. */
     106    CACA_COLOR_RED = 4, /**< The colour index for red. */
     107    CACA_COLOR_MAGENTA = 5, /**< The colour index for magenta. */
     108    CACA_COLOR_BROWN = 6, /**< The colour index for brown. */
     109    CACA_COLOR_LIGHTGRAY = 7, /**< The colour index for light gray. */
     110    CACA_COLOR_DARKGRAY = 8, /**< The colour index for dark gray. */
     111    CACA_COLOR_LIGHTBLUE = 9, /**< The colour index for blue. */
     112    CACA_COLOR_LIGHTGREEN = 10, /**< The colour index for light green. */
     113    CACA_COLOR_LIGHTCYAN = 11, /**< The colour index for light cyan. */
     114    CACA_COLOR_LIGHTRED = 12, /**< The colour index for light red. */
     115    CACA_COLOR_LIGHTMAGENTA = 13, /**< The colour index for light magenta. */
     116    CACA_COLOR_YELLOW = 14, /**< The colour index for yellow. */
     117    CACA_COLOR_WHITE = 15 /**< The colour index for white. */
     118};
     119
     120/** \ingroup convenience */
    119121const char *caca_get_color_name(enum caca_color);
    120122
    121 /**
    122  * The internal libcaca features.
     123/** \brief Internal features.
     124 *
     125 *  This enum lists all possible internal libcaca features such as the
     126 *  rendering method or the dithering mode.
    123127 */
    124128enum caca_feature
    125129{
    126     /* Properties of background characters */
    127     CACA_BACKGROUND       = 0x10,
    128     CACA_BACKGROUND_BLACK = 0x11,
    129     CACA_BACKGROUND_SOLID = 0x12,
    130 #define CACA_BACKGROUND_MIN 0x11
    131 #define CACA_BACKGROUND_MAX 0x12
    132 
    133     /* Antialiasing features */
    134     CACA_ANTIALIASING           = 0x20,
    135     CACA_ANTIALIASING_NONE      = 0x21,
    136     CACA_ANTIALIASING_PREFILTER = 0x22,
    137 #define CACA_ANTIALIASING_MIN     0x21
    138 #define CACA_ANTIALIASING_MAX     0x22
    139 
    140     /* Dithering methods */
    141     CACA_DITHERING          = 0x30,
    142     CACA_DITHERING_NONE     = 0x31,
    143     CACA_DITHERING_ORDERED2 = 0x32,
    144     CACA_DITHERING_ORDERED4 = 0x33,
    145     CACA_DITHERING_ORDERED8 = 0x34,
    146     CACA_DITHERING_RANDOM   = 0x35,
    147 #define CACA_DITHERING_MIN    0x31
    148 #define CACA_DITHERING_MAX    0x35
    149 
    150     /* Unknown feature */
    151     CACA_UNKNOWN_FEATURE = 0xffff
    152 };
    153 
     130    CACA_BACKGROUND       = 0x10, /**< Properties of background characters. */
     131    CACA_BACKGROUND_BLACK = 0x11, /**< Draw only black backgrounds. */
     132    CACA_BACKGROUND_SOLID = 0x12, /**< Draw coloured solid backgorunds. */
     133#define CACA_BACKGROUND_MIN 0x11 /**< First background property */
     134#define CACA_BACKGROUND_MAX 0x12 /**< Last background property */
     135
     136    CACA_ANTIALIASING           = 0x20, /**< Antialiasing features. */
     137    CACA_ANTIALIASING_NONE      = 0x21, /**< No antialiasing. */
     138    CACA_ANTIALIASING_PREFILTER = 0x22, /**< Prefilter antialiasing. */
     139#define CACA_ANTIALIASING_MIN     0x21 /**< First antialiasing feature. */
     140#define CACA_ANTIALIASING_MAX     0x22 /**< Last antialiasing feature. */
     141
     142    CACA_DITHERING          = 0x30, /**< Dithering methods */
     143    CACA_DITHERING_NONE     = 0x31, /**< No dithering. */
     144    CACA_DITHERING_ORDERED2 = 0x32, /**< Ordered 2x2 Bayer dithering. */
     145    CACA_DITHERING_ORDERED4 = 0x33, /**< Ordered 4x4 Bayer dithering. */
     146    CACA_DITHERING_ORDERED8 = 0x34, /**< Ordered 8x8 Bayer dithering. */
     147    CACA_DITHERING_RANDOM   = 0x35, /**< Random dithering. */
     148#define CACA_DITHERING_MIN    0x31 /**< First dithering feature. */
     149#define CACA_DITHERING_MAX    0x35 /**< Last dithering feature. */
     150
     151    CACA_UNKNOWN_FEATURE = 0xffff /**< Unknown feature. */
     152};
     153
     154/** \ingroup convenience */
    154155const char *caca_get_feature_name(enum caca_feature);
    155156
    156 /* Backwards compatibility */
     157/*
     158 * Backwards compatibility macros
     159 */
     160#ifndef _DOXYGEN_SKIP_ME
    157161#define caca_dithering caca_feature
    158162#define caca_set_dithering caca_set_feature
     
    161165#define CACA_DITHER_ORDERED CACA_DITHERING_ORDERED8
    162166#define CACA_DITHER_RANDOM  CACA_DITHERING_RANDOM
    163 
    164 /**
    165  * The event types returned by caca_get_event().
     167#endif
     168
     169/** \brief User events.
     170 *
     171 *  This enum lists all possible event types returned by caca_get_event().
    166172 */
    167173enum caca_event
    168174{
    169     CACA_EVENT_NONE =        0x00000000,
    170     CACA_EVENT_KEY_PRESS =   0x01000000,
    171     CACA_EVENT_KEY_RELEASE = 0x02000000,
    172     CACA_EVENT_MOUSE_CLICK = 0x04000000
    173 };
    174 
    175 /**
    176  * The special key values returned by caca_get_event().
     175    CACA_EVENT_NONE =        0x00000000, /**< No event. */
     176    CACA_EVENT_KEY_PRESS =   0x01000000, /**< A key was pressed. */
     177    CACA_EVENT_KEY_RELEASE = 0x02000000, /**< A key was released. */
     178    CACA_EVENT_MOUSE_CLICK = 0x04000000 /**< A mouse button was clicked. */
     179};
     180
     181/** \brief Special key values.
     182 *
     183 *  This enum lists special key values returned by caca_get_event() for
     184 *  which there is no ASCII equivalent.
    177185 */
    178186enum caca_key
    179187{
    180     CACA_KEY_UP = 273,
    181     CACA_KEY_DOWN = 274,
    182     CACA_KEY_LEFT = 275,
    183     CACA_KEY_RIGHT = 276,
    184 
    185     CACA_KEY_F1 = 282,
    186     CACA_KEY_F2 = 283,
    187     CACA_KEY_F3 = 284,
    188     CACA_KEY_F4 = 285,
    189     CACA_KEY_F5 = 286,
    190     CACA_KEY_F6 = 287,
    191     CACA_KEY_F7 = 288,
    192     CACA_KEY_F8 = 289,
    193     CACA_KEY_F9 = 290,
    194     CACA_KEY_F10 = 291,
    195     CACA_KEY_F11 = 292,
    196     CACA_KEY_F12 = 293,
    197     CACA_KEY_F13 = 294,
    198     CACA_KEY_F14 = 295,
    199     CACA_KEY_F15 = 296
    200 };
    201 
    202 /*
    203  * Basic functions
    204  */
     188    CACA_KEY_UP = 273, /**< The up arrow key. */
     189    CACA_KEY_DOWN = 274, /**< The down arrow key. */
     190    CACA_KEY_LEFT = 275, /**< The left arrow key. */
     191    CACA_KEY_RIGHT = 276, /**< The right arrow key. */
     192
     193    CACA_KEY_F1 = 282, /**< The F1 key. */
     194    CACA_KEY_F2 = 283, /**< The F2 key. */
     195    CACA_KEY_F3 = 284, /**< The F3 key. */
     196    CACA_KEY_F4 = 285, /**< The F4 key. */
     197    CACA_KEY_F5 = 286, /**< The F5 key. */
     198    CACA_KEY_F6 = 287, /**< The F6 key. */
     199    CACA_KEY_F7 = 288, /**< The F7 key. */
     200    CACA_KEY_F8 = 289, /**< The F8 key. */
     201    CACA_KEY_F9 = 290, /**< The F9 key. */
     202    CACA_KEY_F10 = 291, /**< The F10 key. */
     203    CACA_KEY_F11 = 292, /**< The F11 key. */
     204    CACA_KEY_F12 = 293, /**< The F12 key. */
     205    CACA_KEY_F13 = 294, /**< The F13 key. */
     206    CACA_KEY_F14 = 295, /**< The F14 key. */
     207    CACA_KEY_F15 = 296 /**< The F15 key. */
     208};
     209
     210/** \defgroup basic Basic functions
     211 *  \@{ */
    205212int caca_init(void);
    206213void caca_set_delay(unsigned int);
     
    212219void caca_refresh(void);
    213220void caca_end(void);
    214 
    215 /*
    216  * Events
    217  */
     221/** \@} */
     222
     223/** \defgroup event Event handling functions
     224 *  \@{ */
    218225unsigned int caca_get_event(void);
    219 
    220 /*
    221  * Character graphics
    222  */
     226/** \@} */
     227
     228/** \defgroup char Character printing functions
     229 *  \@{ */
    223230void caca_set_color(enum caca_color, enum caca_color);
    224231enum caca_color caca_get_fg_color(void);
     
    228235void caca_printf(int, int, const char *, ...);
    229236void caca_clear(void);
    230 
    231 /*
    232  * Graphics primitives
    233  */
     237/** \@} */
     238
     239/** \defgroup prim Primitives drawing functions
     240 *  \@{ */
    234241void caca_draw_line(int, int, int, int, char);
    235242void caca_draw_polyline(const int x[], const int y[], int, char);
     
    249256void caca_draw_thin_triangle(int, int, int, int, int, int);
    250257void caca_fill_triangle(int, int, int, int, int, int, char);
    251 
    252 /*
    253  * Maths
    254  */
     258/** \@} */
     259
     260/** \defgroup math Mathematical functions
     261 *  \@{ */
    255262int caca_rand(int, int);
    256263unsigned int caca_sqrt(unsigned int);
    257 
    258 /*
    259  * Sprite handling
    260  */
     264/** \@} */
     265
     266/** \defgroup sprite Sprite handling functions
     267 *  \@{ */
    261268struct caca_sprite;
    262269struct caca_sprite * caca_load_sprite(const char *);
     
    268275void caca_draw_sprite(int, int, const struct caca_sprite *, int);
    269276void caca_free_sprite(struct caca_sprite *);
    270 
    271 /*
    272  * Bitmap handling
    273  */
     277/** \@} */
     278
     279/** \defgroup bitmap Bitmap handling functions
     280 *  \@{ */
    274281struct caca_bitmap;
    275282struct caca_bitmap *caca_create_bitmap(unsigned int, unsigned int,
     
    282289void caca_draw_bitmap(int, int, int, int, const struct caca_bitmap *, void *);
    283290void caca_free_bitmap(struct caca_bitmap *);
     291/** \@} */
     292
     293/** \defgroup convenience Convenience functions */
    284294
    285295#ifdef __cplusplus
Note: See TracChangeset for help on using the changeset viewer.