Changeset 773


Ignore:
Timestamp:
Apr 14, 2006, 2:10:18 PM (14 years ago)
Author:
Sam Hocevar
Message:
  • Improved documentation in many places.
Location:
libcaca/trunk
Files:
15 edited

Legend:

Unmodified
Added
Removed
  • libcaca/trunk/caca/caca.c

    r769 r773  
    9999 *  attached to it afterwards.
    100100 *
    101  *  \param qq The caca graphical context.
     101 *  \param kk The libcaca graphical context.
    102102 */
    103103void caca_detach(caca_t *kk)
  • libcaca/trunk/caca/caca.h

    r769 r773  
    7878#define __CACA_H__
    7979
     80/** libcaca API version */
    8081#define CACA_API_VERSION_1
    8182
  • libcaca/trunk/caca/event.c

    r769 r773  
    5151 *  function to wait indefinitely until a matching event is received.
    5252 *
    53  * \param event_mask Bitmask of requested events.
    54  * \param timeout A timeout value in microseconds
    55  * \return The next matching event in the queue, or 0 if no event is pending.
     53 *  \param kk The libcaca graphical context.
     54 *  \param event_mask Bitmask of requested events.
     55 *  \param timeout A timeout value in microseconds
     56 *  \param ev A pointer to a caca_event structure.
     57 *  \return The next matching event in the queue, or 0 if no event is pending.
    5658 */
    5759int caca_get_event(caca_t *kk, unsigned int event_mask,
     
    107109 *  the mouse is clicked. Other drivers such as X11 work well.
    108110 *
     111 *  \param kk The libcaca graphical context.
    109112 *  \return The X mouse coordinate.
    110113 */
     
    124127 *  the mouse is clicked. Other drivers such as X11 work well.
    125128 *
     129 *  \param kk The libcaca graphical context.
    126130 *  \return The Y mouse coordinate.
    127131 */
  • libcaca/trunk/caca/graphics.c

    r769 r773  
    2828 *  the X11 and Win32 drivers.
    2929 *
     30 *  \param kk The libcaca graphical context.
    3031 *  \param title The desired window title.
    3132 *  \return 0 upon success, a non-zero value if an error occurs.
     
    4344 *  6x10 font is being used. Note that the units are not necessarily pixels.
    4445 *
     46 *  \param kk The libcaca graphical context.
    4547 *  \return The window width.
    4648 */
     
    5759 *  used. Note that the units are not necessarily pixels.
    5860 *
     61 *  \param kk The libcaca graphical context.
    5962 *  \return The window height.
    6063 */
     
    7376 *  default behaviour.
    7477 *
     78 *  \param kk The libcaca graphical context.
    7579 *  \param usec The refresh delay in microseconds.
    7680 */
     
    8892 *  even if the real rendering time was shorter.
    8993 *
     94 *  \param kk The libcaca graphical context.
    9095 *  \return The render time in microseconds.
    9196 */
     
    106111 *  set with caca_set_delay(), the second call will wait a bit before
    107112 *  performing the screen refresh.
     113 *
     114 *  \param kk The libcaca graphical context.
    108115 */
    109116void caca_display(caca_t *kk)
     
    147154 *  support it.
    148155 *
     156 *  \param kk The libcaca graphical context.
    149157 *  \param flag 0 hides the pointer, 1 shows the system's default pointer
    150158 *              (usually an arrow). Other values are reserved for future use.
  • libcaca/trunk/cucul/box.c

    r769 r773  
    2525#include "cucul_internals.h"
    2626
    27 /**
    28  * \brief Draw a box on the screen using the given character.
     27/** \brief Draw a box on the canvas using the given character.
    2928 *
    30  * \param x1 X coordinate of the upper-left corner of the box.
    31  * \param y1 Y coordinate of the upper-left corner of the box.
    32  * \param x2 X coordinate of the lower-right corner of the box.
    33  * \param y2 Y coordinate of the lower-right corner of the box.
    34  * \param str UTF-8 string containing the character to use to draw the box.
    35  * \return void
     29 *  \param qq The handle to the libcucul canvas.
     30 *  \param x1 X coordinate of the upper-left corner of the box.
     31 *  \param y1 Y coordinate of the upper-left corner of the box.
     32 *  \param x2 X coordinate of the lower-right corner of the box.
     33 *  \param y2 Y coordinate of the lower-right corner of the box.
     34 *  \param str UTF-8 string containing the character to use to draw the box.
     35 *  \return void
    3636 */
    3737void cucul_draw_box(cucul_t *qq, int x1, int y1, int x2, int y2,
     
    4444}
    4545
    46 /**
    47  * \brief Draw a thin box on the screen.
     46/** \brief Draw a thin box on the canvas.
    4847 *
    49  * \param x1 X coordinate of the upper-left corner of the box.
    50  * \param y1 Y coordinate of the upper-left corner of the box.
    51  * \param x2 X coordinate of the lower-right corner of the box.
    52  * \param y2 Y coordinate of the lower-right corner of the box.
    53  * \return void
     48 *  \param qq The handle to the libcucul canvas.
     49 *  \param x1 X coordinate of the upper-left corner of the box.
     50 *  \param y1 Y coordinate of the upper-left corner of the box.
     51 *  \param x2 X coordinate of the lower-right corner of the box.
     52 *  \param y2 Y coordinate of the lower-right corner of the box.
     53 *  \return void
    5454 */
    5555void cucul_draw_thin_box(cucul_t *qq, int x1, int y1, int x2, int y2)
     
    106106}
    107107
    108 /**
    109  * \brief Fill a box on the screen using the given character.
     108/** \brief Fill a box on the canvas using the given character.
    110109 *
    111  * \param x1 X coordinate of the upper-left corner of the box.
    112  * \param y1 Y coordinate of the upper-left corner of the box.
    113  * \param x2 X coordinate of the lower-right corner of the box.
    114  * \param y2 Y coordinate of the lower-right corner of the box.
    115  * \param str UTF-8 string containing the character to fill the box with.
    116  * \return void
     110 *  \param qq The handle to the libcucul canvas.
     111 *  \param x1 X coordinate of the upper-left corner of the box.
     112 *  \param y1 Y coordinate of the upper-left corner of the box.
     113 *  \param x2 X coordinate of the lower-right corner of the box.
     114 *  \param y2 Y coordinate of the lower-right corner of the box.
     115 *  \param str UTF-8 string containing the character to fill the box with.
     116 *  \return void
    117117 */
    118118void cucul_fill_box(cucul_t *qq, int x1, int y1, int x2, int y2,
  • libcaca/trunk/cucul/canvas.c

    r769 r773  
    4444 *  will use these colour pairs.
    4545 *
     46 *  \param qq A handle to the libcucul canvas.
    4647 *  \param fgcolor The requested foreground colour.
    4748 *  \param bgcolor The requested background colour.
     
    6162 *  This function prints an ASCII character at the given coordinates, using
    6263 *  the default foreground and background values. If the coordinates are
    63  *  outside the screen boundaries, nothing is printed. If the character
     64 *  outside the canvas boundaries, nothing is printed. If the character
    6465 *  value is a non-printable character or is outside the ASCII range, it is
    6566 *  replaced with a space. To print a sequence of bytes forming an UTF-8
    6667 *  character, use cucul_putstr() instead.
    6768 *
     69 *  \param qq A handle to the libcucul canvas.
    6870 *  \param x X coordinate.
    6971 *  \param y Y coordinate.
     
    8789 *  This function prints an UTF-8 string at the given coordinates, using the
    8890 *  default foreground and background values. The coordinates may be outside
    89  *  the screen boundaries (eg. a negative Y coordinate) and the string will
     91 *  the canvas boundaries (eg. a negative Y coordinate) and the string will
    9092 *  be cropped accordingly if it is too long.
    9193 *
     94 *  \param qq A handle to the libcucul canvas.
    9295 *  \param x X coordinate.
    9396 *  \param y Y coordinate.
     
    129132}
    130133
    131 /** \brief Format a string.
     134/** \brief Print a formated string.
    132135 *
    133136 *  This function formats a string at the given coordinates, using the
    134137 *  default foreground and background values. The coordinates may be outside
    135  *  the screen boundaries (eg. a negative Y coordinate) and the string will
     138 *  the canvas boundaries (eg. a negative Y coordinate) and the string will
    136139 *  be cropped accordingly if it is too long. The syntax of the format
    137140 *  string is the same as for the C printf() function.
    138141 *
     142 *  \param qq A handle to the libcucul canvas.
    139143 *  \param x X coordinate.
    140144 *  \param y Y coordinate.
     
    169173}
    170174
    171 /** \brief Clear the screen.
    172  *
    173  *  This function clears the screen using a black background.
     175/** \brief Clear the canvas.
     176 *
     177 *  This function clears the canvas using a black background.
    174178 */
    175179void cucul_clear(cucul_t *qq)
  • libcaca/trunk/cucul/conic.c

    r769 r773  
    2828static void ellipsepoints(cucul_t *, int, int, int, int, uint32_t);
    2929
    30 /**
    31  * \brief Draw a circle on the screen using the given character.
    32  *
    33  * \param x Center X coordinate.
    34  * \param y Center Y coordinate.
    35  * \param r Circle radius.
    36  * \param c Character to draw the circle outline with.
    37  * \return void
     30/** \brief Draw a circle on the canvas using the given character.
     31 *
     32 *  \param qq The handle to the libcucul canvas.
     33 *  \param x Center X coordinate.
     34 *  \param y Center Y coordinate.
     35 *  \param r Circle radius.
     36 *  \param str UTF-8 string representing the character that should be used
     37 *         to draw the circle outline.
     38 *  \return void
    3839 */
    3940void cucul_draw_circle(cucul_t *qq, int x, int y, int r, char const *str)
     
    5253}
    5354
    54 /**
    55  * \brief Fill an ellipse on the screen using the given character.
    56  *
    57  * \param xo Center X coordinate.
    58  * \param yo Center Y coordinate.
    59  * \param a Ellipse X radius.
    60  * \param b Ellipse Y radius.
    61  * \param c Character to fill the ellipse with.
    62  * \return void
     55/** \brief Fill an ellipse on the canvas using the given character.
     56 *
     57 *  \param qq The handle to the libcucul canvas.
     58 *  \param xo Center X coordinate.
     59 *  \param yo Center Y coordinate.
     60 *  \param a Ellipse X radius.
     61 *  \param b Ellipse Y radius.
     62 *  \param str UTF-8 string representing the character that should be used
     63 *         to fill the ellipse.
     64 *  \return void
    6365 */
    6466void cucul_fill_ellipse(cucul_t *qq, int xo, int yo, int a, int b,
     
    108110}
    109111
    110 /**
    111  * \brief Draw an ellipse on the screen using the given character.
    112  *
    113  * \param xo Center X coordinate.
    114  * \param yo Center Y coordinate.
    115  * \param a Ellipse X radius.
    116  * \param b Ellipse Y radius.
    117  * \param c Character to draw the ellipse outline with.
    118  * \return void
     112/** \brief Draw an ellipse on the canvas using the given character.
     113 *
     114 *  \param qq The handle to the libcucul canvas.
     115 *  \param xo Center X coordinate.
     116 *  \param yo Center Y coordinate.
     117 *  \param a Ellipse X radius.
     118 *  \param b Ellipse Y radius.
     119 *  \param str UTF-8 string representing the character that should be used
     120 *         to draw the ellipse outline.
     121 *  \return void
    119122 */
    120123void cucul_draw_ellipse(cucul_t *qq, int xo, int yo, int a, int b,
     
    162165}
    163166
    164 /**
    165  * \brief Draw a thin ellipse on the screen.
    166  *
    167  * \param xo Center X coordinate.
    168  * \param yo Center Y coordinate.
    169  * \param a Ellipse X radius.
    170  * \param b Ellipse Y radius.
    171  * \return void
     167/** \brief Draw a thin ellipse on the canvas.
     168 *
     169 *  \param qq The handle to the libcucul canvas.
     170 *  \param xo Center X coordinate.
     171 *  \param yo Center Y coordinate.
     172 *  \param a Ellipse X radius.
     173 *  \param b Ellipse Y radius.
     174 *  \return void
    172175 */
    173176void cucul_draw_thin_ellipse(cucul_t *qq, int xo, int yo, int a, int b)
  • libcaca/trunk/cucul/cucul.c

    r769 r773  
    4040 *  \param width The desired canvas width
    4141 *  \param height The desired canvas height
    42  *  \return 0 upon success, a non-zero value if an error occurs.
     42 *  \return A libcucul canvas handle upon success, NULL if an error occurred.
    4343 */
    4444cucul_t * cucul_create(unsigned int width, unsigned int height)
     
    135135 *  for more about this.
    136136 *
     137 *  \param qq A libcucul canvas
    137138 *  \param width The desired canvas width
    138139 *  \param height The desired canvas height
     
    150151 *  This function returns the current canvas width, in character cells.
    151152 *
     153 *  \param qq A libcucul canvas
    152154 *  \return The canvas width.
    153155 */
     
    161163 *  This function returns the current canvas height, in character cells.
    162164 *
     165 *  \param qq A libcucul canvas
    163166 *  \return The canvas height.
    164167 */
     
    209212 *  cucul_free() has been called, no other \e libcucul functions may be used
    210213 *  unless a new call to cucul_create() is done.
     214 *
     215 *  \param qq A libcucul canvas
    211216 */
    212217void cucul_free(cucul_t *qq)
     
    250255}
    251256
    252 /**
    253  * \brief Get available export formats
    254  *
    255  * Return a list of available export formats. The list is a NULL-terminated
    256  * array of strings, interleaving a string containing the internal value for
    257  * the export format, to be used with \e cucul_create_export(), and a string
    258  * containing the natural language description for that export format.
    259  *
    260  * \return An array of strings.
     257/** \brief Get available export formats
     258 *
     259 *  Return a list of available export formats. The list is a NULL-terminated
     260 *  array of strings, interleaving a string containing the internal value for
     261 *  the export format, to be used with \e cucul_create_export(), and a string
     262 *  containing the natural language description for that export format.
     263 *
     264 *  \return An array of strings.
    261265 */
    262266char const * const * cucul_get_export_list(void)
  • libcaca/trunk/cucul/cucul.h

    r769 r773  
    2424#define __CUCUL_H__
    2525
     26/** libcucul API version */
    2627#define CUCUL_API_VERSION_1
    2728
     
    145146 *  @{ */
    146147struct cucul_sprite;
    147 struct cucul_sprite * cucul_load_sprite(cucul_t *, char const *);
    148 int cucul_get_sprite_frames(cucul_t *, struct cucul_sprite const *);
    149 int cucul_get_sprite_width(cucul_t *, struct cucul_sprite const *, int);
    150 int cucul_get_sprite_height(cucul_t *, struct cucul_sprite const *, int);
    151 int cucul_get_sprite_dx(cucul_t *, struct cucul_sprite const *, int);
    152 int cucul_get_sprite_dy(cucul_t *, struct cucul_sprite const *, int);
     148struct cucul_sprite * cucul_load_sprite(char const *);
     149int cucul_get_sprite_frames(struct cucul_sprite const *);
     150int cucul_get_sprite_width(struct cucul_sprite const *, int);
     151int cucul_get_sprite_height(struct cucul_sprite const *, int);
     152int cucul_get_sprite_dx(struct cucul_sprite const *, int);
     153int cucul_get_sprite_dy(struct cucul_sprite const *, int);
    153154void cucul_draw_sprite(cucul_t *, int, int, struct cucul_sprite const *, int);
    154155void cucul_free_sprite(struct cucul_sprite *);
  • libcaca/trunk/cucul/dither.c

    r769 r773  
    228228}
    229229
    230 /**
    231  * \brief Create an internal dither object.
    232  *
    233  * Create a dither structure from its coordinates (depth, width, height and
    234  * pitch) and pixel mask values. If the depth is 8 bits per pixel, the mask
    235  * values are ignored and the colour palette should be set using the
    236  * cucul_set_dither_palette() function. For depths greater than 8 bits per
    237  * pixel, a zero alpha mask causes the alpha values to be ignored.
    238  *
    239  * \param bpp Bitmap depth in bits per pixel.
    240  * \param w Bitmap width in pixels.
    241  * \param h Bitmap height in pixels.
    242  * \param pitch Bitmap pitch in bytes.
    243  * \param rmask Bitmask for red values.
    244  * \param gmask Bitmask for green values.
    245  * \param bmask Bitmask for blue values.
    246  * \param amask Bitmask for alpha values.
    247  * \return Dither object, or NULL upon error.
     230/** \brief Create an internal dither object.
     231 *
     232 *  Create a dither structure from its coordinates (depth, width, height and
     233 *  pitch) and pixel mask values. If the depth is 8 bits per pixel, the mask
     234 *  values are ignored and the colour palette should be set using the
     235 *  cucul_set_dither_palette() function. For depths greater than 8 bits per
     236 *  pixel, a zero alpha mask causes the alpha values to be ignored.
     237 *
     238 *  \param bpp Bitmap depth in bits per pixel.
     239 *  \param w Bitmap width in pixels.
     240 *  \param h Bitmap height in pixels.
     241 *  \param pitch Bitmap pitch in bytes.
     242 *  \param rmask Bitmask for red values.
     243 *  \param gmask Bitmask for green values.
     244 *  \param bmask Bitmask for blue values.
     245 *  \param amask Bitmask for alpha values.
     246 *  \return Dither object, or NULL upon error.
    248247 */
    249248struct cucul_dither *cucul_create_dither(unsigned int bpp, unsigned int w,
     
    321320}
    322321
    323 /**
    324  * \brief Set the palette of an 8bpp dither object.
    325  *
    326  * Set the palette of an 8 bits per pixel bitmap. Values should be between
    327  * 0 and 4095 (0xfff).
    328  *
    329  * \param dither Dither object.
    330  * \param red Array of 256 red values.
    331  * \param green Array of 256 green values.
    332  * \param blue Array of 256 blue values.
    333  * \param alpha Array of 256 alpha values.
     322/** \brief Set the palette of an 8bpp dither object.
     323 *
     324 *  Set the palette of an 8 bits per pixel bitmap. Values should be between
     325 *  0 and 4095 (0xfff).
     326 *
     327 *  \param d Dither object.
     328 *  \param red Array of 256 red values.
     329 *  \param green Array of 256 green values.
     330 *  \param blue Array of 256 blue values.
     331 *  \param alpha Array of 256 alpha values.
    334332 */
    335333void cucul_set_dither_palette(struct cucul_dither *d,
     
    363361}
    364362
    365 /**
    366  * \brief Set the brightness of a dither object.
    367  *
    368  * Set the brightness of dither.
    369  *
    370  * \param dither Dither object.
    371  * \param brightness brightness value.
     363/** \brief Set the brightness of a dither object.
     364 *
     365 *  Set the brightness of dither.
     366 *
     367 *  \param d Dither object.
     368 *  \param brightness brightness value.
    372369 */
    373370void cucul_set_dither_brightness(struct cucul_dither *d, float brightness)
     
    376373}
    377374
    378 /**
    379  * \brief Set the gamma of a dither object.
    380  *
    381  * Set the gamma of dither.
    382  *
    383  * \param dither Dither object.
    384  * \param gamma Gamma value.
     375/** \brief Set the gamma of a dither object.
     376 *
     377 *  Set the gamma of dither.
     378 *
     379 *  \param d Dither object.
     380 *  \param gamma Gamma value.
    385381 */
    386382void cucul_set_dither_gamma(struct cucul_dither *d, float gamma)
     
    400396}
    401397
    402 /**
    403  * \brief Invert colors of dither
    404  *
    405  * Invert colors of dither
    406  *
    407  * \param dither Dither object.
    408  * \param value 0 for normal behaviour, 1 for invert
     398/** \brief Invert colors of dither
     399 *
     400 *  Invert colors of dither
     401 *
     402 *  \param d Dither object.
     403 *  \param value 0 for normal behaviour, 1 for invert
    409404 */
    410405void cucul_set_dither_invert(struct cucul_dither *d, int value)
     
    413408}
    414409
    415 /**
    416  * \brief Set the contrast of a dither object.
    417  *
    418  * Set the contrast of dither.
    419  *
    420  * \param dither Dither object.
    421  * \param contrast contrast value.
     410/** \brief Set the contrast of a dither object.
     411 *
     412 *  Set the contrast of dither.
     413 *
     414 *  \param d Dither object.
     415 *  \param contrast contrast value.
    422416 */
    423417void cucul_set_dither_contrast(struct cucul_dither *d, float contrast)
     
    426420}
    427421
    428 /**
    429  * \brief Set dither antialiasing
    430  *
    431  * Tell the renderer whether to antialias the dither. Antialiasing smoothen
    432  * the rendered image and avoids the commonly seen staircase effect.
    433  *
    434  * \li \e "none": no antialiasing.
    435  *
    436  * \li \e "prefilter": simple prefilter antialiasing. This is the default
    437  *     value.
    438  *
    439  * \param dither Dither object.
    440  * \param str A string describing the antialiasing method that will be used
    441  *        for the dithering.
     422/** \brief Set dither antialiasing
     423 *
     424 *  Tell the renderer whether to antialias the dither. Antialiasing smoothen
     425 *  the rendered image and avoids the commonly seen staircase effect.
     426 *
     427 *  \li \e "none": no antialiasing.
     428 *
     429 *  \li \e "prefilter": simple prefilter antialiasing. This is the default
     430 *      value.
     431 *
     432 *  \param d Dither object.
     433 *  \param str A string describing the antialiasing method that will be used
     434 *         for the dithering.
    442435 */
    443436void cucul_set_dither_antialias(struct cucul_dither *d, char const *str)
     
    449442}
    450443
    451 /**
    452  * \brief Get available antialiasing methods
    453  *
    454  * Return a list of available antialiasing methods for a given dither. The
    455  * list is a NULL-terminated array of strings, interleaving a string
    456  * containing the internal value for the antialiasing method to be used with
    457  * \e cucul_set_dither_antialias(), and a string containing the natural
    458  * language description for that antialiasing method.
    459  *
    460  * \param dither Dither object.
    461  * \return An array of strings.
     444/** \brief Get available antialiasing methods
     445 *
     446 *  Return a list of available antialiasing methods for a given dither. The
     447 *  list is a NULL-terminated array of strings, interleaving a string
     448 *  containing the internal value for the antialiasing method to be used with
     449 *  \e cucul_set_dither_antialias(), and a string containing the natural
     450 *  language description for that antialiasing method.
     451 *
     452 *  \param d Dither object.
     453 *  \return An array of strings.
    462454 */
    463455char const * const *
     
    474466}
    475467
    476 /**
    477  * \brief Choose colours used for dithering
    478  *
    479  * Tell the renderer which colours should be used to render the
    480  * bitmap. Valid values for \e str are:
    481  *
    482  * \li \e "mono": use light gray on a black background.
    483  *
    484  * \li \e "gray": use white and two shades of gray on a black background.
    485  *
    486  * \li \e "8": use the 8 ANSI colours on a black background.
    487  *
    488  * \li \e "16": use the 16 ANSI colours on a black background.
    489  *
    490  * \li \e "fullgray": use black, white and two shades of gray for both the
    491  *     characters and the background.
    492  *
    493  * \li \e "full8": use the 8 ANSI colours for both the characters and the
    494  *     background.
    495  *
    496  * \li \e "full16": use the 16 ANSI colours for both the characters and the
    497  *     background. This is the default value.
    498  *
    499  * \param dither Dither object.
    500  * \param str A string describing the colour set that will be used
    501  *        for the dithering.
     468/** \brief Choose colours used for dithering
     469 *
     470 *  Tell the renderer which colours should be used to render the
     471 *  bitmap. Valid values for \e str are:
     472 *
     473 *  \li \e "mono": use light gray on a black background.
     474 *
     475 *  \li \e "gray": use white and two shades of gray on a black background.
     476 *
     477 *  \li \e "8": use the 8 ANSI colours on a black background.
     478 *
     479 *  \li \e "16": use the 16 ANSI colours on a black background.
     480 *
     481 *  \li \e "fullgray": use black, white and two shades of gray for both the
     482 *      characters and the background.
     483 *
     484 *  \li \e "full8": use the 8 ANSI colours for both the characters and the
     485 *      background.
     486 *
     487 *  \li \e "full16": use the 16 ANSI colours for both the characters and the
     488 *      background. This is the default value.
     489 *
     490 *  \param d Dither object.
     491 *  \param str A string describing the colour set that will be used
     492 *         for the dithering.
    502493 */
    503494void cucul_set_dither_color(struct cucul_dither *d, char const *str)
     
    519510}
    520511
    521 /**
    522  * \brief Get available colour modes
    523  *
    524  * Return a list of available colour modes for a given dither. The list
    525  * is a NULL-terminated array of strings, interleaving a string containing
    526  * the internal value for the colour mode, to be used with
    527  * \e cucul_set_dither_color(), and a string containing the natural
    528  * language description for that colour mode.
    529  *
    530  * \param dither Dither object.
    531  * \return An array of strings.
     512/** \brief Get available colour modes
     513 *
     514 *  Return a list of available colour modes for a given dither. The list
     515 *  is a NULL-terminated array of strings, interleaving a string containing
     516 *  the internal value for the colour mode, to be used with
     517 *  \e cucul_set_dither_color(), and a string containing the natural
     518 *  language description for that colour mode.
     519 *
     520 *  \param d Dither object.
     521 *  \return An array of strings.
    532522 */
    533523char const * const *
     
    549539}
    550540
    551 /**
    552  * \brief Choose characters used for dithering
    553  *
    554  * Tell the renderer which characters should be used to render the
    555  * dither. Valid values for \e str are:
    556  *
    557  * \li \e "ascii": use only ASCII characters. This is the default value.
    558  *
    559  * \li \e "shades": use Unicode characters "U+2591 LIGHT SHADE", "U+2592
    560  *     MEDIUM SHADE" and "U+2593 DARK SHADE". These characters are also
    561  *     present in the CP437 codepage available on DOS and VGA.
    562  *
    563  * \li \e "blocks": use Unicode quarter-cell block combinations. These
    564  *     characters are only found in the Unicode set.
    565  *
    566  * \param dither Dither object.
    567  * \param str A string describing the characters that need to be used
    568  *        for the dithering.
     541/** \brief Choose characters used for dithering
     542 *
     543 *  Tell the renderer which characters should be used to render the
     544 *  dither. Valid values for \e str are:
     545 *
     546 *  \li \e "ascii": use only ASCII characters. This is the default value.
     547 *
     548 *  \li \e "shades": use Unicode characters "U+2591 LIGHT SHADE", "U+2592
     549 *      MEDIUM SHADE" and "U+2593 DARK SHADE". These characters are also
     550 *      present in the CP437 codepage available on DOS and VGA.
     551 *
     552 *  \li \e "blocks": use Unicode quarter-cell block combinations. These
     553 *      characters are only found in the Unicode set.
     554 *
     555 *  \param d Dither object.
     556 *  \param str A string describing the characters that need to be used
     557 *         for the dithering.
    569558 */
    570559void cucul_set_dither_charset(struct cucul_dither *d, char const *str)
     
    587576}
    588577
    589 /**
    590  * \brief Get available dither character sets
    591  *
    592  * Return a list of available character sets for a given dither. The list
    593  * is a NULL-terminated array of strings, interleaving a string containing
    594  * the internal value for the character set, to be used with
    595  * \e cucul_set_dither_charset(), and a string containing the natural
    596  * language description for that character set.
    597  *
    598  * \param dither Dither object.
    599  * \return An array of strings.
     578/** \brief Get available dither character sets
     579 *
     580 *  Return a list of available character sets for a given dither. The list
     581 *  is a NULL-terminated array of strings, interleaving a string containing
     582 *  the internal value for the character set, to be used with
     583 *  \e cucul_set_dither_charset(), and a string containing the natural
     584 *  language description for that character set.
     585 *
     586 *  \param d Dither object.
     587 *  \return An array of strings.
    600588 */
    601589char const * const *
     
    613601}
    614602
    615 /**
    616  * \brief Set dithering method
    617  *
    618  * Tell the renderer which dithering method should be used. Dithering is
    619  * necessary because the picture being rendered has usually far more colours
    620  * than the available palette. Valid values for \e str are:
    621  *
    622  * \li \e "none": no dithering is used, the nearest matching colour is used.
    623  *
    624  * \li \e "ordered2": use a 2x2 Bayer matrix for dithering.
    625  *
    626  * \li \e "ordered4": use a 4x4 Bayer matrix for dithering.
    627  *
    628  * \li \e "ordered8": use a 8x8 Bayer matrix for dithering.
    629  *
    630  * \li \e "random": use random dithering.
    631  *
    632  * \li \e "fstein": use Floyd-Steinberg dithering. This is the default value.
    633  *
    634  * \param dither Dither object.
    635  * \param str A string describing the method that needs to be used
    636  *        for the dithering.
     603/** \brief Set dithering method
     604 *
     605 *  Tell the renderer which dithering method should be used. Dithering is
     606 *  necessary because the picture being rendered has usually far more colours
     607 *  than the available palette. Valid values for \e str are:
     608 *
     609 *  \li \e "none": no dithering is used, the nearest matching colour is used.
     610 *
     611 *  \li \e "ordered2": use a 2x2 Bayer matrix for dithering.
     612 *
     613 *  \li \e "ordered4": use a 4x4 Bayer matrix for dithering.
     614 *
     615 *  \li \e "ordered8": use a 8x8 Bayer matrix for dithering.
     616 *
     617 *  \li \e "random": use random dithering.
     618 *
     619 *  \li \e "fstein": use Floyd-Steinberg dithering. This is the default value.
     620 *
     621 *  \param d Dither object.
     622 *  \param str A string describing the method that needs to be used
     623 *         for the dithering.
    637624 */
    638625void cucul_set_dither_mode(struct cucul_dither *d, char const *str)
     
    676663}
    677664
    678 /**
    679  * \brief Get dithering methods
    680  *
    681  * Return a list of available dithering methods for a given dither. The list
    682  * is a NULL-terminated array of strings, interleaving a string containing
    683  * the internal value for the dithering method, to be used with
    684  * \e cucul_set_dither_dithering(), and a string containing the natural
    685  * language description for that dithering method.
    686  *
    687  * \param dither Dither object.
    688  * \return An array of strings.
     665/** \brief Get dithering methods
     666 *
     667 *  Return a list of available dithering methods for a given dither. The list
     668 *  is a NULL-terminated array of strings, interleaving a string containing
     669 *  the internal value for the dithering method, to be used with
     670 *  \e cucul_set_dither_dithering(), and a string containing the natural
     671 *  language description for that dithering method.
     672 *
     673 *  \param d Dither object.
     674 *  \return An array of strings.
    689675 */
    690676char const * const *
     
    705691}
    706692
    707 /**
    708  * \brief Draw a dither on the screen.
    709  *
    710  * Draw a dither at the given coordinates. The dither can be of any size and
    711  * will be stretched to the text area.
    712  *
    713  * \param x1 X coordinate of the upper-left corner of the drawing area.
    714  * \param y1 Y coordinate of the upper-left corner of the drawing area.
    715  * \param x2 X coordinate of the lower-right corner of the drawing area.
    716  * \param y2 Y coordinate of the lower-right corner of the drawing area.
    717  * \param dither Dither object to be drawn.
    718  * \param pixels Bitmap's pixels.
     693/** \brief Draw a dither on the screen.
     694 *
     695 *  Draw a dither at the given coordinates. The dither can be of any size and
     696 *  will be stretched to the text area.
     697 *
     698 *  \param qq A handle to the libcucul canvas.
     699 *  \param x1 X coordinate of the upper-left corner of the drawing area.
     700 *  \param y1 Y coordinate of the upper-left corner of the drawing area.
     701 *  \param x2 X coordinate of the lower-right corner of the drawing area.
     702 *  \param y2 Y coordinate of the lower-right corner of the drawing area.
     703 *  \param d Dither object to be drawn.
     704 *  \param pixels Bitmap's pixels.
    719705 */
    720706void cucul_dither_bitmap(cucul_t *qq, int x1, int y1, int x2, int y2,
     
    964950}
    965951
    966 /**
    967  * \brief Free the memory associated with a dither.
    968  *
    969  * Free the memory allocated by cucul_create_dither().
    970  *
    971  * \param dither Dither object.
     952/** \brief Free the memory associated with a dither.
     953 *
     954 *  Free the memory allocated by cucul_create_dither().
     955 *
     956 *  \param d Dither object.
    972957 */
    973958void cucul_free_dither(struct cucul_dither *d)
  • libcaca/trunk/cucul/font.c

    r771 r773  
    3535#include "font_monobold12.h"
    3636
    37 /* Helper structure for font loading */
     37/* Helper structures for font loading */
     38#if !defined(_DOXYGEN_SKIP_ME)
    3839struct font_header
    3940{
     
    6566    uint8_t *private;
    6667};
     68#endif
    6769
    6870#define DECLARE_UNPACKGLYPH(bpp) \
     
    193195}
    194196
    195 /**
    196  * \brief Get available builtin fonts
    197  *
    198  * Return a list of available builtin fonts. The list is a NULL-terminated
    199  * array of strings.
    200  *
    201  * \return An array of strings.
     197/** \brief Get available builtin fonts
     198 *
     199 *  Return a list of available builtin fonts. The list is a NULL-terminated
     200 *  array of strings.
     201 *
     202 *  \return An array of strings.
    202203 */
    203204char const * const * cucul_get_font_list(void)
  • libcaca/trunk/cucul/line.c

    r769 r773  
    4141static void draw_thin_line(cucul_t*, struct line*);
    4242
    43 /**
    44  * \brief Draw a line on the screen using the given character.
    45  *
    46  * \param x1 X coordinate of the first point.
    47  * \param y1 Y coordinate of the first point.
    48  * \param x2 X coordinate of the second point.
    49  * \param y2 Y coordinate of the second point.
    50  * \param str UTF-8 string containing the character to use to draw the line.
    51  * \return void
     43/** \brief Draw a line on the canvas using the given character.
     44 *
     45 *  \param qq The handle to the libcucul canvas.
     46 *  \param x1 X coordinate of the first point.
     47 *  \param y1 Y coordinate of the first point.
     48 *  \param x2 X coordinate of the second point.
     49 *  \param y2 Y coordinate of the second point.
     50 *  \param str UTF-8 string containing the character to use to draw the line.
     51 *  \return void
    5252 */
    5353void cucul_draw_line(cucul_t *qq, int x1, int y1, int x2, int y2,
     
    6464}
    6565
    66 /**
    67  * \brief Draw a polyline on the screen using the given character and
    68  *       coordinate arrays. The first and last points are not connected,
    69  *       so in order to draw a polygon you need to specify the starting
    70  *       point at the end of the list as well.
    71  *
    72  * \param x Array of X coordinates. Must have \p n + 1 elements.
    73  * \param y Array of Y coordinates. Must have \p n + 1 elements.
    74  * \param n Number of lines to draw.
    75  * \param str UTF-8 string containing the character to use to draw the lines.
    76  * \return void
     66/** \brief Draw a polyline.
     67 *
     68 *  Draw a plyline on the canvas using the given character and coordinate
     69 *  arrays. The first and last points are not connected, hence in order to
     70 *  draw a polygon you need to specify the starting point at the end of the
     71 *  list as well.
     72 *
     73 *  \param qq The handle to the libcucul canvas.
     74 *  \param x Array of X coordinates. Must have \p n + 1 elements.
     75 *  \param y Array of Y coordinates. Must have \p n + 1 elements.
     76 *  \param n Number of lines to draw.
     77 *  \param str UTF-8 string containing the character to use to draw the lines.
     78 *  \return void
    7779 */
    7880void cucul_draw_polyline(cucul_t *qq, int const x[], int const y[], int n,
     
    9496}
    9597
    96 /**
    97  * \brief Draw a thin line on the screen, using ASCII art.
    98  *
    99  * \param x1 X coordinate of the first point.
    100  * \param y1 Y coordinate of the first point.
    101  * \param x2 X coordinate of the second point.
    102  * \param y2 Y coordinate of the second point.
    103  * \return void
     98/** \brief Draw a thin line on the canvas, using ASCII art.
     99 *
     100 *  \param qq The handle to the libcucul canvas.
     101 *  \param x1 X coordinate of the first point.
     102 *  \param y1 Y coordinate of the first point.
     103 *  \param x2 X coordinate of the second point.
     104 *  \param y2 Y coordinate of the second point.
     105 *  \return void
    104106 */
    105107void cucul_draw_thin_line(cucul_t *qq, int x1, int y1, int x2, int y2)
     
    114116}
    115117
    116 /**
    117  * \brief Draw a thin polyline on the screen using the given coordinate
    118  *       arrays and with ASCII art. The first and last points are not
    119  *       connected, so in order to draw a polygon you need to specify the
    120  *       starting point at the end of the list as well.
    121  *
    122  * \param x Array of X coordinates. Must have \p n + 1 elements.
    123  * \param y Array of Y coordinates. Must have \p n + 1 elements.
    124  * \param n Number of lines to draw.
    125  * \return void
     118/** \brief Draw an ASCII art thin polyline.
     119 *
     120 *  Draw a thin polyline on the canvas using the given coordinate arrays and
     121 *  with ASCII art. The first and last points are not connected, so in order
     122 *  to draw a polygon you need to specify the starting point at the end of
     123 *  the list as well.
     124 *
     125 *  \param qq The handle to the libcucul canvas.
     126 *  \param x Array of X coordinates. Must have \p n + 1 elements.
     127 *  \param y Array of Y coordinates. Must have \p n + 1 elements.
     128 *  \param n Number of lines to draw.
     129 *  \return void
    126130 */
    127131void cucul_draw_thin_polyline(cucul_t *qq, int const x[], int const y[], int n)
     
    145149 */
    146150
    147 /**
    148  * \brief Generic Cohen-Sutherland line clipping function.
    149  *
    150  * \param s a line structure
    151  * \return void
    152  */
     151/* Generic Cohen-Sutherland line clipping function. */
    153152static void clip_line(cucul_t *qq, struct line* s)
    154153{
     
    202201}
    203202
    204 /**
    205  * \brief Helper function for clip_line().
    206  *
    207  * \param x X coordinate of the point.
    208  * \param y Y coordinate of the point.
    209  * \return The clipping bits for the given point.
    210  */
     203/* Helper function for clip_line(). */
    211204static uint8_t clip_bits(cucul_t *qq, int x, int y)
    212205{
     
    226219}
    227220
    228 /**
    229  * \brief Solid line drawing function, using Bresenham's mid-point line
    230  *       scan-conversion algorithm.
    231  *
    232  * \param s a line structure
    233  * \return void
    234  */
     221/* Solid line drawing function, using Bresenham's mid-point line
     222 * scan-conversion algorithm. */
    235223static void draw_solid_line(cucul_t *qq, struct line* s)
    236224{
     
    293281}
    294282
    295 /**
    296  * \brief Thin line drawing function, using Bresenham's mid-point line
    297  *        scan-conversion algorithm and ASCII art graphics.
    298  *
    299  * \param s a line structure
    300  * \return void
    301  */
     283/* Thin line drawing function, using Bresenham's mid-point line
     284 * scan-conversion algorithm and ASCII art graphics. */
    302285static void draw_thin_line(cucul_t *qq, struct line* s)
    303286{
  • libcaca/trunk/cucul/math.c

    r769 r773  
    2525#include "cucul_internals.h"
    2626
    27 /**
    28  * \brief Generate a random integer within a range.
     27/** \brief Generate a random integer within a range.
    2928 *
    30  * \param min The lower bound of the integer range.
    31  * \param max The upper bound of the integer range.
    32  * \return A random integer comprised between \p min and \p max, inclusive.
     29 *  \param min The lower bound of the integer range.
     30 *  \param max The upper bound of the integer range.
     31 *  \return A random integer comprised between \p min and \p max, inclusive.
    3332 */
    3433int cucul_rand(int min, int max)
     
    3736}
    3837
    39 /**
    40  * \brief Approximate a square root, using Newton's method to avoid
    41  *        costly floating point calculations.
     38/** \brief Approximate a square root, using Newton's method to avoid
     39 *         costly floating point calculations.
    4240 *
    43  * \param a A positive integer.
    44  * \return The approximate square root of \p a.
     41 *  \param a A positive integer.
     42 *  \return The approximate square root of \p a.
    4543 */
    4644unsigned int cucul_sqrt(unsigned int a)
  • libcaca/trunk/cucul/sprite.c

    r769 r773  
    4343#endif
    4444
    45 /**
    46  * \brief Allocate a sprite loaded from a file.
    47  *
    48  * \param file The filename.
    49  * \return The sprite, or NULL if an error occured.
    50  */
    51 struct cucul_sprite *cucul_load_sprite(cucul_t *qq, char const *file)
     45/** \brief Allocate a sprite loaded from a file.
     46 *
     47 *  \param file The filename.
     48 *  \return The sprite, or NULL if an error occured.
     49 */
     50struct cucul_sprite *cucul_load_sprite(char const *file)
    5251{
    5352    char buf[BUFSIZ];
     
    164163}
    165164
    166 /**
    167  * \brief Return the number of frames in a sprite.
    168  *
    169  * \param sprite The sprite.
    170  * \return The number of frames.
    171  */
    172 int cucul_get_sprite_frames(cucul_t *qq, struct cucul_sprite const *sprite)
     165/** \brief Return the number of frames in a sprite.
     166 *
     167 *  \param sprite The sprite.
     168 *  \return The number of frames.
     169 */
     170int cucul_get_sprite_frames(struct cucul_sprite const *sprite)
    173171{
    174172    if(sprite == NULL)
     
    178176}
    179177
    180 /**
    181  * \brief Return the width of a sprite.
    182  *
    183  * \param sprite The sprite.
    184  * \param f The frame index.
    185  * \return The width of the given frame of the sprite.
    186  */
    187 int cucul_get_sprite_width(cucul_t *qq, struct cucul_sprite const *sprite, int f)
     178/** \brief Return the width of a sprite.
     179 *
     180 *  \param sprite The sprite.
     181 *  \param f The frame index.
     182 *  \return The width of the given frame of the sprite.
     183 */
     184int cucul_get_sprite_width(struct cucul_sprite const *sprite, int f)
    188185{
    189186    if(sprite == NULL)
     
    196193}
    197194
    198 /**
    199  * \brief Return the height of a sprite.
    200  *
    201  * \param sprite The sprite.
    202  * \param f The frame index.
    203  * \return The height of the given frame of the sprite.
    204  */
    205 int cucul_get_sprite_height(cucul_t *qq, struct cucul_sprite const *sprite, int f)
     195/** \brief Return the height of a sprite.
     196 *
     197 *  \param sprite The sprite.
     198 *  \param f The frame index.
     199 *  \return The height of the given frame of the sprite.
     200 */
     201int cucul_get_sprite_height(struct cucul_sprite const *sprite, int f)
    206202{
    207203    if(sprite == NULL)
     
    214210}
    215211
    216 /**
    217  * \brief Return the X coordinate of a sprite's handle.
    218  *
    219  * \param sprite The sprite.
    220  * \param f The frame index.
    221  * \return The X coordinate of the given frame's handle.
    222  */
    223 int cucul_get_sprite_dx(cucul_t *qq, struct cucul_sprite const *sprite, int f)
     212/** \brief Return the X coordinate of a sprite's handle.
     213 *
     214 *  \param sprite The sprite.
     215 *  \param f The frame index.
     216 *  \return The X coordinate of the given frame's handle.
     217 */
     218int cucul_get_sprite_dx(struct cucul_sprite const *sprite, int f)
    224219{
    225220    if(sprite == NULL)
     
    232227}
    233228
    234 /**
    235  * \brief Return the Y coordinate of a sprite's handle.
    236  *
    237  * \param sprite The sprite.
    238  * \param f The frame index.
    239  * \return The Y coordinate of the given frame's handle.
    240  */
    241 int cucul_get_sprite_dy(cucul_t *qq, struct cucul_sprite const *sprite, int f)
     229/** \brief Return the Y coordinate of a sprite's handle.
     230 *
     231 *  \param sprite The sprite.
     232 *  \param f The frame index.
     233 *  \return The Y coordinate of the given frame's handle.
     234 */
     235int cucul_get_sprite_dy(struct cucul_sprite const *sprite, int f)
    242236{
    243237    if(sprite == NULL)
     
    250244}
    251245
    252 /**
    253  * \brief Draw a sprite's specific frame at the given coordinates. If the
    254  *        frame does not exist, nothing is displayed.
    255  *
    256  * \param x The X coordinate.
    257  * \param y The Y coordinate.
    258  * \param sprite The sprite.
    259  * \param f The frame index.
    260  * \return void
     246/** \brief Draw a sprite's specific frame at the given coordinates. If the
     247 *         frame does not exist, nothing is displayed.
     248 *
     249 *  \param qq A libcucul canvas
     250 *  \param x The X coordinate.
     251 *  \param y The Y coordinate.
     252 *  \param sprite The sprite.
     253 *  \param f The frame index.
     254 *  \return void
    261255 */
    262256void cucul_draw_sprite(cucul_t *qq, int x, int y, struct cucul_sprite const *sprite, int f)
     
    294288}
    295289
    296 /**
    297  * \brief Free the memory associated with a sprite.
    298  *
    299  * \param sprite The sprite to be freed.
    300  * \return void
     290/** \brief Free the memory associated with a sprite.
     291 *
     292 *  \param sprite The sprite to be freed.
     293 *  \return void
    301294 */
    302295void cucul_free_sprite(struct cucul_sprite *sprite)
  • libcaca/trunk/cucul/triangle.c

    r769 r773  
    2525#include "cucul_internals.h"
    2626
    27 /**
    28  * \brief Draw a triangle on the screen using the given character.
     27/** \brief Draw a triangle on the canvas using the given character.
    2928 *
    30  * \param x1 X coordinate of the first point.
    31  * \param y1 Y coordinate of the first point.
    32  * \param x2 X coordinate of the second point.
    33  * \param y2 Y coordinate of the second point.
    34  * \param x3 X coordinate of the third point.
    35  * \param y3 Y coordinate of the third point.
    36  * \param c Character to draw the triangle outline with.
    37  * \return void
     29 *  \param qq The handle to the libcucul canvas.
     30 *  \param x1 X coordinate of the first point.
     31 *  \param y1 Y coordinate of the first point.
     32 *  \param x2 X coordinate of the second point.
     33 *  \param y2 Y coordinate of the second point.
     34 *  \param x3 X coordinate of the third point.
     35 *  \param y3 Y coordinate of the third point.
     36 *  \param str UTF-8 string representing the character that should be used
     37 *         to draw the triangle outline.
     38 *  \return void
    3839 */
    3940void cucul_draw_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
     
    4546}
    4647
    47 /**
    48  * \brief Draw a thin triangle on the screen.
     48/** \brief Draw a thin triangle on the canvas.
    4949 *
    50  * \param x1 X coordinate of the first point.
    51  * \param y1 Y coordinate of the first point.
    52  * \param x2 X coordinate of the second point.
    53  * \param y2 Y coordinate of the second point.
    54  * \param x3 X coordinate of the third point.
    55  * \param y3 Y coordinate of the third point.
    56  * \return void
     50 *  \param qq The handle to the libcucul canvas.
     51 *  \param x1 X coordinate of the first point.
     52 *  \param y1 Y coordinate of the first point.
     53 *  \param x2 X coordinate of the second point.
     54 *  \param y2 Y coordinate of the second point.
     55 *  \param x3 X coordinate of the third point.
     56 *  \param y3 Y coordinate of the third point.
     57 *  \return void
    5758 */
    5859void cucul_draw_thin_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
     
    6465}
    6566
    66 /**
    67  * \brief Fill a triangle on the screen using the given character.
     67/** \brief Fill a triangle on the canvas using the given character.
    6868 *
    69  * \param x1 X coordinate of the first point.
    70  * \param y1 Y coordinate of the first point.
    71  * \param x2 X coordinate of the second point.
    72  * \param y2 Y coordinate of the second point.
    73  * \param x3 X coordinate of the third point.
    74  * \param y3 Y coordinate of the third point.
    75  * \param c Character to fill the triangle with.
    76  * \return void
     69 *  \param qq The handle to the libcucul canvas.
     70 *  \param x1 X coordinate of the first point.
     71 *  \param y1 Y coordinate of the first point.
     72 *  \param x2 X coordinate of the second point.
     73 *  \param y2 Y coordinate of the second point.
     74 *  \param x3 X coordinate of the third point.
     75 *  \param y3 Y coordinate of the third point.
     76 *  \param str UTF-8 string representing the character that should be used
     77 *         to fill the triangle.
     78 *  \return void
    7779 */
    7880void cucul_fill_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
Note: See TracChangeset for help on using the changeset viewer.