Ignore:
Timestamp:
Dec 23, 2003, 2:27:40 PM (19 years ago)
Author:
Sam Hocevar
Message:
  • src/io.c: + Added caca_wait_event(), a blocking caca_get_event().
  • src/ examples/: + More documentation.
  • doc/doxygen.cfg.in: + doc/doxygen.cfg is now generated by configure, so that we can use

@top_srcdir@ and we no longer need to hardcode PROJECT_NUMBER.

+ Create manpages.

File:
1 edited

Legend:

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

    r267 r268  
    11/*
    2  *   libcaca       ASCII-Art library
    3  *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
    4  *                 All Rights Reserved
    5  *
    6  *   This library is free software; you can redistribute it and/or
    7  *   modify it under the terms of the GNU Lesser General Public
    8  *   License as published by the Free Software Foundation; either
    9  *   version 2 of the License, or (at your option) any later version.
    10  *
    11  *   This library is distributed in the hope that it will be useful,
    12  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
    13  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    14  *   Lesser General Public License for more details.
    15  *
    16  *   You should have received a copy of the GNU Lesser General Public
    17  *   License along with this library; if not, write to the Free Software
    18  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
    19  *   02111-1307  USA
    20  */
    21 
    22 /**  \file caca.h
    23  *   \version \$Id$
    24  *   \author Sam Hocevar <sam@zoy.org>
    25  *   \brief The \e libcaca public header.
    26  *
    27  *   This header contains the public types and functions that applications
    28  *   using \e libcaca may use.
    29  */
    30 
    31 /**  \mainpage libcaca developer documentation
    32  *
    33  *   \section intro Introduction
    34  *
    35  *   \e libcaca is a graphics library that outputs text instead of pixels,
    36  *   so that it can work on older video cards or text terminals. It is not
    37  *   unlike the famous AAlib library. libcaca needs a terminal to work,
    38  *   thus it should work on all Unix systems (including Mac OS X) using
    39  *   either the slang library or the ncurses library, on DOS using the conio
    40  *   library, and on Windows systems using either slang or ncurses (through
    41  *   Cygwin emulation) or conio.
    42  *
    43  *   \e libcaca is free software, released under the GNU Lesser General
    44  *   Public License. This ensures that \e libcaca will always remain free
    45  *   software.
    46  *
    47  *   \section api The libcaca API
    48  *
    49  *   The complete \e libcaca programming interface is available from the
    50  *   caca.h header.
    51  *
    52  *   \section env Environment variables
    53  *
    54  *   Some environment variables can be used to change the behaviour of
    55  *   \e libcaca without having to modify the program which uses it. These
    56  *   variables are:
    57  *
    58  *   \li \b CACA_DRIVER: set the backend video driver. In order of preference:
    59  *       - \c conio uses the DOS conio.h interface.
    60  *       - \c ncurses uses the ncurses library.
    61  *       - \c slang uses the S-Lang library.
    62  *       - \c x11 uses the native X11 driver.
    63  *
    64  *   \li \b CACA_BACKGROUND: set the background type.
    65  *       - \c solid uses solid coloured backgrounds for all characters. This
    66  *         feature does not work with all terminal emulators. This is the
    67  *         default choice.
    68  *       - \c black uses only black backgrounds to render characters.
    69  *
    70  *   \li \b CACA_ANTIALIASING: set the antialiasing mode. Antialiasing
    71  *       smoothens the rendered image and avoids the commonly seen staircase
    72  *       effect.
    73  *       - \c none disables antialiasing.
    74  *       - \c prefilter uses a simple prefilter antialiasing method. This is
    75  *         the default choice.
    76  *
    77  *   \li \b CACA_DITHERING: set the dithering mode. Dithering is necessary
    78  *       when rendering a picture that has more colours than the usually
    79  *       available palette.
    80  *       - \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
    83  *         default choice.
    84  *       - \c ordered8 uses a 8x8 Bayer matrix for dithering.
    85  *       - \c random uses random dithering.
     2 *  libcaca       ASCII-Art library
     3 *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
     4 *                All Rights Reserved
     5 *
     6 *  This library is free software; you can redistribute it and/or
     7 *  modify it under the terms of the GNU Lesser General Public
     8 *  License as published by the Free Software Foundation; either
     9 *  version 2 of the License, or (at your option) any later version.
     10 *
     11 *  This library is distributed in the hope that it will be useful,
     12 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
     13 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     14 *  Lesser General Public License for more details.
     15 *
     16 *  You should have received a copy of the GNU Lesser General Public
     17 *  License along with this library; if not, write to the Free Software
     18 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
     19 *  02111-1307  USA
     20 */
     21
     22/** \file caca.h
     23 *  \version \$Id$
     24 *  \author Sam Hocevar <sam@zoy.org>
     25 *  \brief The \e libcaca public header.
     26 *
     27 *  This header contains the public types and functions that applications
     28 *  using \e libcaca may use.
     29 */
     30
     31/** \mainpage libcaca developer documentation
     32 *
     33 *  \section intro Introduction
     34 *
     35 *  \e libcaca is a graphics library that outputs text instead of pixels,
     36 *  so that it can work on older video cards or text terminals. It is not
     37 *  unlike the famous AAlib library. \e libcaca can use almost any virtual
     38 *  terminal to work, thus it should work on all Unix systems (including
     39 *  Mac OS X) using either the slang library or the ncurses library, on DOS
     40 *  using the conio library, and on Windows systems using either slang or
     41 *  ncurses (through Cygwin emulation) or conio. There is also a native X11
     42 *  driver that does not require a text terminal.
     43 *
     44 *  \e libcaca is free software, released under the GNU Lesser General
     45 *  Public License. This ensures that \e libcaca will always remain free
     46 *  software.
     47 *
     48 *  \section api The libcaca API
     49 *
     50 *  The complete \e libcaca programming interface is available from the
     51 *  caca.h header.
     52 *
     53 *  \section env Environment variables
     54 *
     55 *  Some environment variables can be used to change the behaviour of
     56 *  \e libcaca without having to modify the program which uses it. These
     57 *  variables are:
     58 *
     59 *  \li \b CACA_DRIVER: set the backend video driver. In order of preference:
     60 *      - \c conio uses the DOS conio.h interface.
     61 *      - \c ncurses uses the ncurses library.
     62 *      - \c slang uses the S-Lang library.
     63 *      - \c x11 uses the native X11 driver.
     64 *
     65 *  \li \b CACA_BACKGROUND: set the background type.
     66 *      - \c solid uses solid coloured backgrounds for all characters. This
     67 *        feature does not work with all terminal emulators. This is the
     68 *        default choice.
     69 *      - \c black uses only black backgrounds to render characters.
     70 *
     71 *  \li \b CACA_ANTIALIASING: set the antialiasing mode. Antialiasing
     72 *      smoothens the rendered image and avoids the commonly seen staircase
     73 *      effect.
     74 *      - \c none disables antialiasing.
     75 *      - \c prefilter uses a simple prefilter antialiasing method. This is
     76 *        the default choice.
     77 *
     78 *  \li \b CACA_DITHERING: set the dithering mode. Dithering is necessary
     79 *      when rendering a picture that has more colours than the usually
     80 *      available palette.
     81 *      - \c none disables dithering.
     82 *      - \c ordered2 uses a 2x2 Bayer matrix for dithering.
     83 *      - \c ordered4 uses a 4x4 Bayer matrix for dithering. This is the
     84 *        default choice.
     85 *      - \c ordered8 uses a 8x8 Bayer matrix for dithering.
     86 *      - \c random uses random dithering.
    8687 */
    8788
     
    118119};
    119120
    120 /** \ingroup convenience */
    121 const char *caca_get_color_name(enum caca_color);
    122 
    123121/** \brief Internal features.
    124122 *
     
    151149    CACA_UNKNOWN_FEATURE = 0xffff /**< Unknown feature. */
    152150};
    153 
    154 /** \ingroup convenience */
    155 const char *caca_get_feature_name(enum caca_feature);
    156151
    157152/*
     
    209204
    210205/** \defgroup basic Basic functions
    211  *  \@{ */
     206 *
     207 *  These functions provide the basic \e libcaca routines for library
     208 *  initialisation, system information retrieval and configuration.
     209 *
     210 *  @{ */
    212211int caca_init(void);
    213212void caca_set_delay(unsigned int);
    214213enum caca_feature caca_get_feature(enum caca_feature);
    215214void caca_set_feature(enum caca_feature);
     215const char *caca_get_feature_name(enum caca_feature);
    216216unsigned int caca_get_rendertime(void);
    217217unsigned int caca_get_width(void);
     
    219219void caca_refresh(void);
    220220void caca_end(void);
    221 /** \@} */
     221/*  @} */
    222222
    223223/** \defgroup event Event handling functions
    224  *  \@{ */
     224 *
     225 *  These functions handle user events such as keyboard input and mouse
     226 *  clicks.
     227 *
     228 *  @{ */
    225229unsigned int caca_get_event(void);
    226 /** \@} */
     230unsigned int caca_wait_event(void);
     231/*  @} */
    227232
    228233/** \defgroup char Character printing functions
    229  *  \@{ */
     234 *
     235 *  These functions provide low-level character printing routines.
     236 *
     237 *  @{ */
    230238void caca_set_color(enum caca_color, enum caca_color);
    231239enum caca_color caca_get_fg_color(void);
    232240enum caca_color caca_get_bg_color(void);
     241const char *caca_get_color_name(enum caca_color);
    233242void caca_putchar(int, int, char);
    234243void caca_putstr(int, int, const char *);
    235244void caca_printf(int, int, const char *, ...);
    236245void caca_clear(void);
    237 /** \@} */
     246/*  @} */
    238247
    239248/** \defgroup prim Primitives drawing functions
    240  *  \@{ */
     249 *
     250 *  These functions provide routines for primitive drawing, such as lines,
     251 *  boxes, triangles and ellipses.
     252 *
     253 *  @{ */
    241254void caca_draw_line(int, int, int, int, char);
    242255void caca_draw_polyline(const int x[], const int y[], int, char);
     
    256269void caca_draw_thin_triangle(int, int, int, int, int, int);
    257270void caca_fill_triangle(int, int, int, int, int, int, char);
    258 /** \@} */
     271/*  @} */
    259272
    260273/** \defgroup math Mathematical functions
    261  *  \@{ */
     274 *
     275 *  These functions provide a few useful math-related routines.
     276 *
     277 *  @{ */
    262278int caca_rand(int, int);
    263279unsigned int caca_sqrt(unsigned int);
    264 /** \@} */
     280/*  @} */
    265281
    266282/** \defgroup sprite Sprite handling functions
    267  *  \@{ */
     283 *
     284 *  These functions provide high level routines for sprite loading, animation
     285 *  and rendering.
     286 *
     287 *  @{ */
    268288struct caca_sprite;
    269289struct caca_sprite * caca_load_sprite(const char *);
     
    275295void caca_draw_sprite(int, int, const struct caca_sprite *, int);
    276296void caca_free_sprite(struct caca_sprite *);
    277 /** \@} */
     297/*  @} */
    278298
    279299/** \defgroup bitmap Bitmap handling functions
    280  *  \@{ */
     300 *
     301 *  These functions provide high level routines for bitmap allocation and
     302 *  rendering.
     303 *
     304 *  @{ */
    281305struct caca_bitmap;
    282306struct caca_bitmap *caca_create_bitmap(unsigned int, unsigned int,
     
    289313void caca_draw_bitmap(int, int, int, int, const struct caca_bitmap *, void *);
    290314void caca_free_bitmap(struct caca_bitmap *);
    291 /** \@} */
    292 
    293 /** \defgroup convenience Convenience functions */
     315/*  @} */
    294316
    295317#ifdef __cplusplus
Note: See TracChangeset for help on using the changeset viewer.