Browse Source

* Improved documentation in many places.

tags/v0.99.beta14
Sam Hocevar sam 19 years ago
parent
commit
2c5ccb65e6
15 changed files with 365 additions and 378 deletions
  1. +1
    -1
      caca/caca.c
  2. +1
    -0
      caca/caca.h
  3. +7
    -3
      caca/event.c
  4. +8
    -0
      caca/graphics.c
  5. +23
    -23
      cucul/box.c
  6. +10
    -6
      cucul/canvas.c
  7. +33
    -30
      cucul/conic.c
  8. +12
    -8
      cucul/cucul.c
  9. +7
    -6
      cucul/cucul.h
  10. +134
    -149
      cucul/dither.c
  11. +7
    -6
      cucul/font.c
  12. +44
    -61
      cucul/line.c
  13. +8
    -10
      cucul/math.c
  14. +39
    -46
      cucul/sprite.c
  15. +31
    -29
      cucul/triangle.c

+ 1
- 1
caca/caca.c View File

@@ -98,7 +98,7 @@ caca_t * caca_attach(cucul_t * qq)
* libcucul canvas continues to exist and other graphical contexts can be
* attached to it afterwards.
*
* \param qq The caca graphical context.
* \param kk The libcaca graphical context.
*/
void caca_detach(caca_t *kk)
{


+ 1
- 0
caca/caca.h View File

@@ -77,6 +77,7 @@
#ifndef __CACA_H__
#define __CACA_H__

/** libcaca API version */
#define CACA_API_VERSION_1

#include <cucul.h>


+ 7
- 3
caca/event.c View File

@@ -50,9 +50,11 @@ static int _lowlevel_event(caca_t *, struct caca_event *);
* if no more events are pending in the queue. A negative value causes the
* function to wait indefinitely until a matching event is received.
*
* \param event_mask Bitmask of requested events.
* \param timeout A timeout value in microseconds
* \return The next matching event in the queue, or 0 if no event is pending.
* \param kk The libcaca graphical context.
* \param event_mask Bitmask of requested events.
* \param timeout A timeout value in microseconds
* \param ev A pointer to a caca_event structure.
* \return The next matching event in the queue, or 0 if no event is pending.
*/
int caca_get_event(caca_t *kk, unsigned int event_mask,
struct caca_event *ev, int timeout)
@@ -106,6 +108,7 @@ int caca_get_event(caca_t *kk, unsigned int event_mask,
* drivers are being used, because mouse position is only detected when
* the mouse is clicked. Other drivers such as X11 work well.
*
* \param kk The libcaca graphical context.
* \return The X mouse coordinate.
*/
unsigned int caca_get_mouse_x(caca_t *kk)
@@ -123,6 +126,7 @@ unsigned int caca_get_mouse_x(caca_t *kk)
* drivers are being used, because mouse position is only detected when
* the mouse is clicked. Other drivers such as X11 work well.
*
* \param kk The libcaca graphical context.
* \return The Y mouse coordinate.
*/
unsigned int caca_get_mouse_y(caca_t *kk)


+ 8
- 0
caca/graphics.c View File

@@ -27,6 +27,7 @@
* If libcaca runs in a window, try to change its title. This works with
* the X11 and Win32 drivers.
*
* \param kk The libcaca graphical context.
* \param title The desired window title.
* \return 0 upon success, a non-zero value if an error occurs.
*/
@@ -42,6 +43,7 @@ int caca_set_window_title(caca_t *kk, char const *title)
* or if there is no way to know the font size, most drivers will assume a
* 6x10 font is being used. Note that the units are not necessarily pixels.
*
* \param kk The libcaca graphical context.
* \return The window width.
*/
unsigned int caca_get_window_width(caca_t *kk)
@@ -56,6 +58,7 @@ unsigned int caca_get_window_width(caca_t *kk)
* or if there is no way to know the font size, assume a 6x10 font is being
* used. Note that the units are not necessarily pixels.
*
* \param kk The libcaca graphical context.
* \return The window height.
*/
unsigned int caca_get_window_height(caca_t *kk)
@@ -72,6 +75,7 @@ unsigned int caca_get_window_height(caca_t *kk)
* If the argument is zero, constant framerate is disabled. This is the
* default behaviour.
*
* \param kk The libcaca graphical context.
* \param usec The refresh delay in microseconds.
*/
void caca_set_delay(caca_t *kk, unsigned int usec)
@@ -87,6 +91,7 @@ void caca_set_delay(caca_t *kk, unsigned int usec)
* rendering time will not be considerably shorter than the requested delay
* even if the real rendering time was shorter.
*
* \param kk The libcaca graphical context.
* \return The render time in microseconds.
*/
unsigned int caca_get_rendertime(caca_t *kk)
@@ -105,6 +110,8 @@ unsigned int caca_get_rendertime(caca_t *kk)
* calls to caca_display() are within a time range shorter than the value
* set with caca_set_delay(), the second call will wait a bit before
* performing the screen refresh.
*
* \param kk The libcaca graphical context.
*/
void caca_display(caca_t *kk)
{
@@ -146,6 +153,7 @@ void caca_display(caca_t *kk)
* This function shows or hides the mouse pointer, for devices that
* support it.
*
* \param kk The libcaca graphical context.
* \param flag 0 hides the pointer, 1 shows the system's default pointer
* (usually an arrow). Other values are reserved for future use.
*/


+ 23
- 23
cucul/box.c View File

@@ -24,15 +24,15 @@
#include "cucul.h"
#include "cucul_internals.h"

/**
* \brief Draw a box on the screen using the given character.
/** \brief Draw a box on the canvas using the given character.
*
* \param x1 X coordinate of the upper-left corner of the box.
* \param y1 Y coordinate of the upper-left corner of the box.
* \param x2 X coordinate of the lower-right corner of the box.
* \param y2 Y coordinate of the lower-right corner of the box.
* \param str UTF-8 string containing the character to use to draw the box.
* \return void
* \param qq The handle to the libcucul canvas.
* \param x1 X coordinate of the upper-left corner of the box.
* \param y1 Y coordinate of the upper-left corner of the box.
* \param x2 X coordinate of the lower-right corner of the box.
* \param y2 Y coordinate of the lower-right corner of the box.
* \param str UTF-8 string containing the character to use to draw the box.
* \return void
*/
void cucul_draw_box(cucul_t *qq, int x1, int y1, int x2, int y2,
char const *str)
@@ -43,14 +43,14 @@ void cucul_draw_box(cucul_t *qq, int x1, int y1, int x2, int y2,
cucul_draw_line(qq, x2, y1, x1, y1, str);
}

/**
* \brief Draw a thin box on the screen.
/** \brief Draw a thin box on the canvas.
*
* \param x1 X coordinate of the upper-left corner of the box.
* \param y1 Y coordinate of the upper-left corner of the box.
* \param x2 X coordinate of the lower-right corner of the box.
* \param y2 Y coordinate of the lower-right corner of the box.
* \return void
* \param qq The handle to the libcucul canvas.
* \param x1 X coordinate of the upper-left corner of the box.
* \param y1 Y coordinate of the upper-left corner of the box.
* \param x2 X coordinate of the lower-right corner of the box.
* \param y2 Y coordinate of the lower-right corner of the box.
* \return void
*/
void cucul_draw_thin_box(cucul_t *qq, int x1, int y1, int x2, int y2)
{
@@ -105,15 +105,15 @@ void cucul_draw_thin_box(cucul_t *qq, int x1, int y1, int x2, int y2)
_cucul_putchar32(qq, x2, y2, (uint32_t)'\'');
}

/**
* \brief Fill a box on the screen using the given character.
/** \brief Fill a box on the canvas using the given character.
*
* \param x1 X coordinate of the upper-left corner of the box.
* \param y1 Y coordinate of the upper-left corner of the box.
* \param x2 X coordinate of the lower-right corner of the box.
* \param y2 Y coordinate of the lower-right corner of the box.
* \param str UTF-8 string containing the character to fill the box with.
* \return void
* \param qq The handle to the libcucul canvas.
* \param x1 X coordinate of the upper-left corner of the box.
* \param y1 Y coordinate of the upper-left corner of the box.
* \param x2 X coordinate of the lower-right corner of the box.
* \param y2 Y coordinate of the lower-right corner of the box.
* \param str UTF-8 string containing the character to fill the box with.
* \return void
*/
void cucul_fill_box(cucul_t *qq, int x1, int y1, int x2, int y2,
char const *str)


+ 10
- 6
cucul/canvas.c View File

@@ -43,6 +43,7 @@
* caca_printf() and graphical primitive functions such as caca_draw_line()
* will use these colour pairs.
*
* \param qq A handle to the libcucul canvas.
* \param fgcolor The requested foreground colour.
* \param bgcolor The requested background colour.
*/
@@ -60,11 +61,12 @@ void cucul_set_color(cucul_t *qq, unsigned int fgcolor, unsigned int bgcolor)
*
* This function prints an ASCII character at the given coordinates, using
* the default foreground and background values. If the coordinates are
* outside the screen boundaries, nothing is printed. If the character
* outside the canvas boundaries, nothing is printed. If the character
* value is a non-printable character or is outside the ASCII range, it is
* replaced with a space. To print a sequence of bytes forming an UTF-8
* character, use cucul_putstr() instead.
*
* \param qq A handle to the libcucul canvas.
* \param x X coordinate.
* \param y Y coordinate.
* \param c The character to print.
@@ -86,9 +88,10 @@ void cucul_putchar(cucul_t *qq, int x, int y, char c)
*
* This function prints an UTF-8 string at the given coordinates, using the
* default foreground and background values. The coordinates may be outside
* the screen boundaries (eg. a negative Y coordinate) and the string will
* the canvas boundaries (eg. a negative Y coordinate) and the string will
* be cropped accordingly if it is too long.
*
* \param qq A handle to the libcucul canvas.
* \param x X coordinate.
* \param y Y coordinate.
* \param s The string to print.
@@ -128,14 +131,15 @@ void cucul_putstr(cucul_t *qq, int x, int y, char const *s)
}
}

/** \brief Format a string.
/** \brief Print a formated string.
*
* This function formats a string at the given coordinates, using the
* default foreground and background values. The coordinates may be outside
* the screen boundaries (eg. a negative Y coordinate) and the string will
* the canvas boundaries (eg. a negative Y coordinate) and the string will
* be cropped accordingly if it is too long. The syntax of the format
* string is the same as for the C printf() function.
*
* \param qq A handle to the libcucul canvas.
* \param x X coordinate.
* \param y Y coordinate.
* \param format The format string to print.
@@ -168,9 +172,9 @@ void cucul_printf(cucul_t *qq, int x, int y, char const *format, ...)
free(buf);
}

/** \brief Clear the screen.
/** \brief Clear the canvas.
*
* This function clears the screen using a black background.
* This function clears the canvas using a black background.
*/
void cucul_clear(cucul_t *qq)
{


+ 33
- 30
cucul/conic.c View File

@@ -27,14 +27,15 @@

static void ellipsepoints(cucul_t *, int, int, int, int, uint32_t);

/**
* \brief Draw a circle on the screen using the given character.
/** \brief Draw a circle on the canvas using the given character.
*
* \param x Center X coordinate.
* \param y Center Y coordinate.
* \param r Circle radius.
* \param c Character to draw the circle outline with.
* \return void
* \param qq The handle to the libcucul canvas.
* \param x Center X coordinate.
* \param y Center Y coordinate.
* \param r Circle radius.
* \param str UTF-8 string representing the character that should be used
* to draw the circle outline.
* \return void
*/
void cucul_draw_circle(cucul_t *qq, int x, int y, int r, char const *str)
{
@@ -51,15 +52,16 @@ void cucul_draw_circle(cucul_t *qq, int x, int y, int r, char const *str)
}
}

/**
* \brief Fill an ellipse on the screen using the given character.
/** \brief Fill an ellipse on the canvas using the given character.
*
* \param xo Center X coordinate.
* \param yo Center Y coordinate.
* \param a Ellipse X radius.
* \param b Ellipse Y radius.
* \param c Character to fill the ellipse with.
* \return void
* \param qq The handle to the libcucul canvas.
* \param xo Center X coordinate.
* \param yo Center Y coordinate.
* \param a Ellipse X radius.
* \param b Ellipse Y radius.
* \param str UTF-8 string representing the character that should be used
* to fill the ellipse.
* \return void
*/
void cucul_fill_ellipse(cucul_t *qq, int xo, int yo, int a, int b,
char const *str)
@@ -107,15 +109,16 @@ void cucul_fill_ellipse(cucul_t *qq, int xo, int yo, int a, int b,
}
}

/**
* \brief Draw an ellipse on the screen using the given character.
/** \brief Draw an ellipse on the canvas using the given character.
*
* \param xo Center X coordinate.
* \param yo Center Y coordinate.
* \param a Ellipse X radius.
* \param b Ellipse Y radius.
* \param c Character to draw the ellipse outline with.
* \return void
* \param qq The handle to the libcucul canvas.
* \param xo Center X coordinate.
* \param yo Center Y coordinate.
* \param a Ellipse X radius.
* \param b Ellipse Y radius.
* \param str UTF-8 string representing the character that should be used
* to draw the ellipse outline.
* \return void
*/
void cucul_draw_ellipse(cucul_t *qq, int xo, int yo, int a, int b,
char const *str)
@@ -161,14 +164,14 @@ void cucul_draw_ellipse(cucul_t *qq, int xo, int yo, int a, int b,
}
}

/**
* \brief Draw a thin ellipse on the screen.
/** \brief Draw a thin ellipse on the canvas.
*
* \param xo Center X coordinate.
* \param yo Center Y coordinate.
* \param a Ellipse X radius.
* \param b Ellipse Y radius.
* \return void
* \param qq The handle to the libcucul canvas.
* \param xo Center X coordinate.
* \param yo Center Y coordinate.
* \param a Ellipse X radius.
* \param b Ellipse Y radius.
* \return void
*/
void cucul_draw_thin_ellipse(cucul_t *qq, int xo, int yo, int a, int b)
{


+ 12
- 8
cucul/cucul.c View File

@@ -39,7 +39,7 @@
*
* \param width The desired canvas width
* \param height The desired canvas height
* \return 0 upon success, a non-zero value if an error occurs.
* \return A libcucul canvas handle upon success, NULL if an error occurred.
*/
cucul_t * cucul_create(unsigned int width, unsigned int height)
{
@@ -134,6 +134,7 @@ cucul_t *cucul_load(void *data, unsigned int size)
* resize through user interaction. See the caca_event() documentation
* for more about this.
*
* \param qq A libcucul canvas
* \param width The desired canvas width
* \param height The desired canvas height
*/
@@ -149,6 +150,7 @@ void cucul_set_size(cucul_t *qq, unsigned int width, unsigned int height)
*
* This function returns the current canvas width, in character cells.
*
* \param qq A libcucul canvas
* \return The canvas width.
*/
unsigned int cucul_get_width(cucul_t *qq)
@@ -160,6 +162,7 @@ unsigned int cucul_get_width(cucul_t *qq)
*
* This function returns the current canvas height, in character cells.
*
* \param qq A libcucul canvas
* \return The canvas height.
*/
unsigned int cucul_get_height(cucul_t *qq)
@@ -208,6 +211,8 @@ char const *cucul_get_color_name(unsigned int color)
* This function frees all resources allocated by cucul_create(). After
* cucul_free() has been called, no other \e libcucul functions may be used
* unless a new call to cucul_create() is done.
*
* \param qq A libcucul canvas
*/
void cucul_free(cucul_t *qq)
{
@@ -249,15 +254,14 @@ struct cucul_buffer * cucul_create_export(cucul_t *qq, char const *format)
return ex;
}

/**
* \brief Get available export formats
/** \brief Get available export formats
*
* Return a list of available export formats. The list is a NULL-terminated
* array of strings, interleaving a string containing the internal value for
* the export format, to be used with \e cucul_create_export(), and a string
* containing the natural language description for that export format.
* Return a list of available export formats. The list is a NULL-terminated
* array of strings, interleaving a string containing the internal value for
* the export format, to be used with \e cucul_create_export(), and a string
* containing the natural language description for that export format.
*
* \return An array of strings.
* \return An array of strings.
*/
char const * const * cucul_get_export_list(void)
{


+ 7
- 6
cucul/cucul.h View File

@@ -23,6 +23,7 @@
#ifndef __CUCUL_H__
#define __CUCUL_H__

/** libcucul API version */
#define CUCUL_API_VERSION_1

#ifdef __cplusplus
@@ -144,12 +145,12 @@ unsigned int cucul_sqrt(unsigned int);
*
* @{ */
struct cucul_sprite;
struct cucul_sprite * cucul_load_sprite(cucul_t *, char const *);
int cucul_get_sprite_frames(cucul_t *, struct cucul_sprite const *);
int cucul_get_sprite_width(cucul_t *, struct cucul_sprite const *, int);
int cucul_get_sprite_height(cucul_t *, struct cucul_sprite const *, int);
int cucul_get_sprite_dx(cucul_t *, struct cucul_sprite const *, int);
int cucul_get_sprite_dy(cucul_t *, struct cucul_sprite const *, int);
struct cucul_sprite * cucul_load_sprite(char const *);
int cucul_get_sprite_frames(struct cucul_sprite const *);
int cucul_get_sprite_width(struct cucul_sprite const *, int);
int cucul_get_sprite_height(struct cucul_sprite const *, int);
int cucul_get_sprite_dx(struct cucul_sprite const *, int);
int cucul_get_sprite_dy(struct cucul_sprite const *, int);
void cucul_draw_sprite(cucul_t *, int, int, struct cucul_sprite const *, int);
void cucul_free_sprite(struct cucul_sprite *);
/* @} */


+ 134
- 149
cucul/dither.c View File

@@ -227,24 +227,23 @@ static inline void rgb2hsv_default(int r, int g, int b,
}
}

/**
* \brief Create an internal dither object.
/** \brief Create an internal dither object.
*
* Create a dither structure from its coordinates (depth, width, height and
* pitch) and pixel mask values. If the depth is 8 bits per pixel, the mask
* values are ignored and the colour palette should be set using the
* cucul_set_dither_palette() function. For depths greater than 8 bits per
* pixel, a zero alpha mask causes the alpha values to be ignored.
* Create a dither structure from its coordinates (depth, width, height and
* pitch) and pixel mask values. If the depth is 8 bits per pixel, the mask
* values are ignored and the colour palette should be set using the
* cucul_set_dither_palette() function. For depths greater than 8 bits per
* pixel, a zero alpha mask causes the alpha values to be ignored.
*
* \param bpp Bitmap depth in bits per pixel.
* \param w Bitmap width in pixels.
* \param h Bitmap height in pixels.
* \param pitch Bitmap pitch in bytes.
* \param rmask Bitmask for red values.
* \param gmask Bitmask for green values.
* \param bmask Bitmask for blue values.
* \param amask Bitmask for alpha values.
* \return Dither object, or NULL upon error.
* \param bpp Bitmap depth in bits per pixel.
* \param w Bitmap width in pixels.
* \param h Bitmap height in pixels.
* \param pitch Bitmap pitch in bytes.
* \param rmask Bitmask for red values.
* \param gmask Bitmask for green values.
* \param bmask Bitmask for blue values.
* \param amask Bitmask for alpha values.
* \return Dither object, or NULL upon error.
*/
struct cucul_dither *cucul_create_dither(unsigned int bpp, unsigned int w,
unsigned int h, unsigned int pitch,
@@ -320,17 +319,16 @@ struct cucul_dither *cucul_create_dither(unsigned int bpp, unsigned int w,
return d;
}

/**
* \brief Set the palette of an 8bpp dither object.
/** \brief Set the palette of an 8bpp dither object.
*
* Set the palette of an 8 bits per pixel bitmap. Values should be between
* 0 and 4095 (0xfff).
* Set the palette of an 8 bits per pixel bitmap. Values should be between
* 0 and 4095 (0xfff).
*
* \param dither Dither object.
* \param red Array of 256 red values.
* \param green Array of 256 green values.
* \param blue Array of 256 blue values.
* \param alpha Array of 256 alpha values.
* \param d Dither object.
* \param red Array of 256 red values.
* \param green Array of 256 green values.
* \param blue Array of 256 blue values.
* \param alpha Array of 256 alpha values.
*/
void cucul_set_dither_palette(struct cucul_dither *d,
unsigned int red[], unsigned int green[],
@@ -362,26 +360,24 @@ void cucul_set_dither_palette(struct cucul_dither *d,
d->has_alpha = has_alpha;
}

/**
* \brief Set the brightness of a dither object.
/** \brief Set the brightness of a dither object.
*
* Set the brightness of dither.
* Set the brightness of dither.
*
* \param dither Dither object.
* \param brightness brightness value.
* \param d Dither object.
* \param brightness brightness value.
*/
void cucul_set_dither_brightness(struct cucul_dither *d, float brightness)
{
/* FIXME */
}

/**
* \brief Set the gamma of a dither object.
/** \brief Set the gamma of a dither object.
*
* Set the gamma of dither.
* Set the gamma of dither.
*
* \param dither Dither object.
* \param gamma Gamma value.
* \param d Dither object.
* \param gamma Gamma value.
*/
void cucul_set_dither_gamma(struct cucul_dither *d, float gamma)
{
@@ -399,46 +395,43 @@ void cucul_set_dither_gamma(struct cucul_dither *d, float gamma)
d->gammatab[i] = 4096.0 * gammapow((float)i / 4096.0, 1.0 / gamma);
}

/**
* \brief Invert colors of dither
/** \brief Invert colors of dither
*
* Invert colors of dither
* Invert colors of dither
*
* \param dither Dither object.
* \param value 0 for normal behaviour, 1 for invert
* \param d Dither object.
* \param value 0 for normal behaviour, 1 for invert
*/
void cucul_set_dither_invert(struct cucul_dither *d, int value)
{
d->invert = value ? 1 : 0;
}

/**
* \brief Set the contrast of a dither object.
/** \brief Set the contrast of a dither object.
*
* Set the contrast of dither.
* Set the contrast of dither.
*
* \param dither Dither object.
* \param contrast contrast value.
* \param d Dither object.
* \param contrast contrast value.
*/
void cucul_set_dither_contrast(struct cucul_dither *d, float contrast)
{
/* FIXME */
}

/**
* \brief Set dither antialiasing
/** \brief Set dither antialiasing
*
* Tell the renderer whether to antialias the dither. Antialiasing smoothen
* the rendered image and avoids the commonly seen staircase effect.
* Tell the renderer whether to antialias the dither. Antialiasing smoothen
* the rendered image and avoids the commonly seen staircase effect.
*
* \li \e "none": no antialiasing.
* \li \e "none": no antialiasing.
*
* \li \e "prefilter": simple prefilter antialiasing. This is the default
* value.
* \li \e "prefilter": simple prefilter antialiasing. This is the default
* value.
*
* \param dither Dither object.
* \param str A string describing the antialiasing method that will be used
* for the dithering.
* \param d Dither object.
* \param str A string describing the antialiasing method that will be used
* for the dithering.
*/
void cucul_set_dither_antialias(struct cucul_dither *d, char const *str)
{
@@ -448,17 +441,16 @@ void cucul_set_dither_antialias(struct cucul_dither *d, char const *str)
d->antialias = 1;
}

/**
* \brief Get available antialiasing methods
/** \brief Get available antialiasing methods
*
* Return a list of available antialiasing methods for a given dither. The
* list is a NULL-terminated array of strings, interleaving a string
* containing the internal value for the antialiasing method to be used with
* \e cucul_set_dither_antialias(), and a string containing the natural
* language description for that antialiasing method.
* Return a list of available antialiasing methods for a given dither. The
* list is a NULL-terminated array of strings, interleaving a string
* containing the internal value for the antialiasing method to be used with
* \e cucul_set_dither_antialias(), and a string containing the natural
* language description for that antialiasing method.
*
* \param dither Dither object.
* \return An array of strings.
* \param d Dither object.
* \return An array of strings.
*/
char const * const *
cucul_get_dither_antialias_list(struct cucul_dither const *d)
@@ -473,32 +465,31 @@ char const * const *
return list;
}

/**
* \brief Choose colours used for dithering
/** \brief Choose colours used for dithering
*
* Tell the renderer which colours should be used to render the
* bitmap. Valid values for \e str are:
* Tell the renderer which colours should be used to render the
* bitmap. Valid values for \e str are:
*
* \li \e "mono": use light gray on a black background.
* \li \e "mono": use light gray on a black background.
*
* \li \e "gray": use white and two shades of gray on a black background.
* \li \e "gray": use white and two shades of gray on a black background.
*
* \li \e "8": use the 8 ANSI colours on a black background.
* \li \e "8": use the 8 ANSI colours on a black background.
*
* \li \e "16": use the 16 ANSI colours on a black background.
* \li \e "16": use the 16 ANSI colours on a black background.
*
* \li \e "fullgray": use black, white and two shades of gray for both the
* characters and the background.
* \li \e "fullgray": use black, white and two shades of gray for both the
* characters and the background.
*
* \li \e "full8": use the 8 ANSI colours for both the characters and the
* background.
* \li \e "full8": use the 8 ANSI colours for both the characters and the
* background.
*
* \li \e "full16": use the 16 ANSI colours for both the characters and the
* background. This is the default value.
* \li \e "full16": use the 16 ANSI colours for both the characters and the
* background. This is the default value.
*
* \param dither Dither object.
* \param str A string describing the colour set that will be used
* for the dithering.
* \param d Dither object.
* \param str A string describing the colour set that will be used
* for the dithering.
*/
void cucul_set_dither_color(struct cucul_dither *d, char const *str)
{
@@ -518,17 +509,16 @@ void cucul_set_dither_color(struct cucul_dither *d, char const *str)
d->color_mode = COLOR_MODE_FULL16;
}

/**
* \brief Get available colour modes
/** \brief Get available colour modes
*
* Return a list of available colour modes for a given dither. The list
* is a NULL-terminated array of strings, interleaving a string containing
* the internal value for the colour mode, to be used with
* \e cucul_set_dither_color(), and a string containing the natural
* language description for that colour mode.
* Return a list of available colour modes for a given dither. The list
* is a NULL-terminated array of strings, interleaving a string containing
* the internal value for the colour mode, to be used with
* \e cucul_set_dither_color(), and a string containing the natural
* language description for that colour mode.
*
* \param dither Dither object.
* \return An array of strings.
* \param d Dither object.
* \return An array of strings.
*/
char const * const *
cucul_get_dither_color_list(struct cucul_dither const *d)
@@ -548,24 +538,23 @@ char const * const *
return list;
}

/**
* \brief Choose characters used for dithering
/** \brief Choose characters used for dithering
*
* Tell the renderer which characters should be used to render the
* dither. Valid values for \e str are:
* Tell the renderer which characters should be used to render the
* dither. Valid values for \e str are:
*
* \li \e "ascii": use only ASCII characters. This is the default value.
* \li \e "ascii": use only ASCII characters. This is the default value.
*
* \li \e "shades": use Unicode characters "U+2591 LIGHT SHADE", "U+2592
* MEDIUM SHADE" and "U+2593 DARK SHADE". These characters are also
* present in the CP437 codepage available on DOS and VGA.
* \li \e "shades": use Unicode characters "U+2591 LIGHT SHADE", "U+2592
* MEDIUM SHADE" and "U+2593 DARK SHADE". These characters are also
* present in the CP437 codepage available on DOS and VGA.
*
* \li \e "blocks": use Unicode quarter-cell block combinations. These
* characters are only found in the Unicode set.
* \li \e "blocks": use Unicode quarter-cell block combinations. These
* characters are only found in the Unicode set.
*
* \param dither Dither object.
* \param str A string describing the characters that need to be used
* for the dithering.
* \param d Dither object.
* \param str A string describing the characters that need to be used
* for the dithering.
*/
void cucul_set_dither_charset(struct cucul_dither *d, char const *str)
{
@@ -586,17 +575,16 @@ void cucul_set_dither_charset(struct cucul_dither *d, char const *str)
}
}

/**
* \brief Get available dither character sets
/** \brief Get available dither character sets
*
* Return a list of available character sets for a given dither. The list
* is a NULL-terminated array of strings, interleaving a string containing
* the internal value for the character set, to be used with
* \e cucul_set_dither_charset(), and a string containing the natural
* language description for that character set.
* Return a list of available character sets for a given dither. The list
* is a NULL-terminated array of strings, interleaving a string containing
* the internal value for the character set, to be used with
* \e cucul_set_dither_charset(), and a string containing the natural
* language description for that character set.
*
* \param dither Dither object.
* \return An array of strings.
* \param d Dither object.
* \return An array of strings.
*/
char const * const *
cucul_get_dither_charset_list(struct cucul_dither const *d)
@@ -612,28 +600,27 @@ char const * const *
return list;
}

/**
* \brief Set dithering method
/** \brief Set dithering method
*
* Tell the renderer which dithering method should be used. Dithering is
* necessary because the picture being rendered has usually far more colours
* than the available palette. Valid values for \e str are:
* Tell the renderer which dithering method should be used. Dithering is
* necessary because the picture being rendered has usually far more colours
* than the available palette. Valid values for \e str are:
*
* \li \e "none": no dithering is used, the nearest matching colour is used.
* \li \e "none": no dithering is used, the nearest matching colour is used.
*
* \li \e "ordered2": use a 2x2 Bayer matrix for dithering.
* \li \e "ordered2": use a 2x2 Bayer matrix for dithering.
*
* \li \e "ordered4": use a 4x4 Bayer matrix for dithering.
* \li \e "ordered4": use a 4x4 Bayer matrix for dithering.
*
* \li \e "ordered8": use a 8x8 Bayer matrix for dithering.
* \li \e "ordered8": use a 8x8 Bayer matrix for dithering.
*
* \li \e "random": use random dithering.
* \li \e "random": use random dithering.
*
* \li \e "fstein": use Floyd-Steinberg dithering. This is the default value.
* \li \e "fstein": use Floyd-Steinberg dithering. This is the default value.
*
* \param dither Dither object.
* \param str A string describing the method that needs to be used
* for the dithering.
* \param d Dither object.
* \param str A string describing the method that needs to be used
* for the dithering.
*/
void cucul_set_dither_mode(struct cucul_dither *d, char const *str)
{
@@ -675,17 +662,16 @@ void cucul_set_dither_mode(struct cucul_dither *d, char const *str)
}
}

/**
* \brief Get dithering methods
/** \brief Get dithering methods
*
* Return a list of available dithering methods for a given dither. The list
* is a NULL-terminated array of strings, interleaving a string containing
* the internal value for the dithering method, to be used with
* \e cucul_set_dither_dithering(), and a string containing the natural
* language description for that dithering method.
* Return a list of available dithering methods for a given dither. The list
* is a NULL-terminated array of strings, interleaving a string containing
* the internal value for the dithering method, to be used with
* \e cucul_set_dither_dithering(), and a string containing the natural
* language description for that dithering method.
*
* \param dither Dither object.
* \return An array of strings.
* \param d Dither object.
* \return An array of strings.
*/
char const * const *
cucul_get_dither_mode_list(struct cucul_dither const *d)
@@ -704,18 +690,18 @@ char const * const *
return list;
}

/**
* \brief Draw a dither on the screen.
/** \brief Draw a dither on the screen.
*
* Draw a dither at the given coordinates. The dither can be of any size and
* will be stretched to the text area.
* Draw a dither at the given coordinates. The dither can be of any size and
* will be stretched to the text area.
*
* \param x1 X coordinate of the upper-left corner of the drawing area.
* \param y1 Y coordinate of the upper-left corner of the drawing area.
* \param x2 X coordinate of the lower-right corner of the drawing area.
* \param y2 Y coordinate of the lower-right corner of the drawing area.
* \param dither Dither object to be drawn.
* \param pixels Bitmap's pixels.
* \param qq A handle to the libcucul canvas.
* \param x1 X coordinate of the upper-left corner of the drawing area.
* \param y1 Y coordinate of the upper-left corner of the drawing area.
* \param x2 X coordinate of the lower-right corner of the drawing area.
* \param y2 Y coordinate of the lower-right corner of the drawing area.
* \param d Dither object to be drawn.
* \param pixels Bitmap's pixels.
*/
void cucul_dither_bitmap(cucul_t *qq, int x1, int y1, int x2, int y2,
struct cucul_dither const *d, void *pixels)
@@ -963,12 +949,11 @@ void cucul_dither_bitmap(cucul_t *qq, int x1, int y1, int x2, int y2,
free(floyd_steinberg);
}

/**
* \brief Free the memory associated with a dither.
/** \brief Free the memory associated with a dither.
*
* Free the memory allocated by cucul_create_dither().
* Free the memory allocated by cucul_create_dither().
*
* \param dither Dither object.
* \param d Dither object.
*/
void cucul_free_dither(struct cucul_dither *d)
{


+ 7
- 6
cucul/font.c View File

@@ -34,7 +34,8 @@
#include "font_mono9.h"
#include "font_monobold12.h"

/* Helper structure for font loading */
/* Helper structures for font loading */
#if !defined(_DOXYGEN_SKIP_ME)
struct font_header
{
uint32_t control_size, data_size;
@@ -64,6 +65,7 @@ struct cucul_font

uint8_t *private;
};
#endif

#define DECLARE_UNPACKGLYPH(bpp) \
static inline void \
@@ -192,13 +194,12 @@ struct cucul_font *cucul_load_font(void const *data, unsigned int size)
return f;
}

/**
* \brief Get available builtin fonts
/** \brief Get available builtin fonts
*
* Return a list of available builtin fonts. The list is a NULL-terminated
* array of strings.
* Return a list of available builtin fonts. The list is a NULL-terminated
* array of strings.
*
* \return An array of strings.
* \return An array of strings.
*/
char const * const * cucul_get_font_list(void)
{


+ 44
- 61
cucul/line.c View File

@@ -40,15 +40,15 @@ static uint8_t clip_bits(cucul_t*, int, int);
static void draw_solid_line(cucul_t*, struct line*);
static void draw_thin_line(cucul_t*, struct line*);

/**
* \brief Draw a line on the screen using the given character.
/** \brief Draw a line on the canvas using the given character.
*
* \param x1 X coordinate of the first point.
* \param y1 Y coordinate of the first point.
* \param x2 X coordinate of the second point.
* \param y2 Y coordinate of the second point.
* \param str UTF-8 string containing the character to use to draw the line.
* \return void
* \param qq The handle to the libcucul canvas.
* \param x1 X coordinate of the first point.
* \param y1 Y coordinate of the first point.
* \param x2 X coordinate of the second point.
* \param y2 Y coordinate of the second point.
* \param str UTF-8 string containing the character to use to draw the line.
* \return void
*/
void cucul_draw_line(cucul_t *qq, int x1, int y1, int x2, int y2,
char const *str)
@@ -63,17 +63,19 @@ void cucul_draw_line(cucul_t *qq, int x1, int y1, int x2, int y2,
clip_line(qq, &s);
}

/**
* \brief Draw a polyline on the screen using the given character and
* coordinate arrays. The first and last points are not connected,
* so in order to draw a polygon you need to specify the starting
* point at the end of the list as well.
/** \brief Draw a polyline.
*
* \param x Array of X coordinates. Must have \p n + 1 elements.
* \param y Array of Y coordinates. Must have \p n + 1 elements.
* \param n Number of lines to draw.
* \param str UTF-8 string containing the character to use to draw the lines.
* \return void
* Draw a plyline on the canvas using the given character and coordinate
* arrays. The first and last points are not connected, hence in order to
* draw a polygon you need to specify the starting point at the end of the
* list as well.
*
* \param qq The handle to the libcucul canvas.
* \param x Array of X coordinates. Must have \p n + 1 elements.
* \param y Array of Y coordinates. Must have \p n + 1 elements.
* \param n Number of lines to draw.
* \param str UTF-8 string containing the character to use to draw the lines.
* \return void
*/
void cucul_draw_polyline(cucul_t *qq, int const x[], int const y[], int n,
char const *str)
@@ -93,14 +95,14 @@ void cucul_draw_polyline(cucul_t *qq, int const x[], int const y[], int n,
}
}

/**
* \brief Draw a thin line on the screen, using ASCII art.
/** \brief Draw a thin line on the canvas, using ASCII art.
*
* \param x1 X coordinate of the first point.
* \param y1 Y coordinate of the first point.
* \param x2 X coordinate of the second point.
* \param y2 Y coordinate of the second point.
* \return void
* \param qq The handle to the libcucul canvas.
* \param x1 X coordinate of the first point.
* \param y1 Y coordinate of the first point.
* \param x2 X coordinate of the second point.
* \param y2 Y coordinate of the second point.
* \return void
*/
void cucul_draw_thin_line(cucul_t *qq, int x1, int y1, int x2, int y2)
{
@@ -113,16 +115,18 @@ void cucul_draw_thin_line(cucul_t *qq, int x1, int y1, int x2, int y2)
clip_line(qq, &s);
}

/**
* \brief Draw a thin polyline on the screen using the given coordinate
* arrays and with ASCII art. The first and last points are not
* connected, so in order to draw a polygon you need to specify the
* starting point at the end of the list as well.
/** \brief Draw an ASCII art thin polyline.
*
* Draw a thin polyline on the canvas using the given coordinate arrays and
* with ASCII art. The first and last points are not connected, so in order
* to draw a polygon you need to specify the starting point at the end of
* the list as well.
*
* \param x Array of X coordinates. Must have \p n + 1 elements.
* \param y Array of Y coordinates. Must have \p n + 1 elements.
* \param n Number of lines to draw.
* \return void
* \param qq The handle to the libcucul canvas.
* \param x Array of X coordinates. Must have \p n + 1 elements.
* \param y Array of Y coordinates. Must have \p n + 1 elements.
* \param n Number of lines to draw.
* \return void
*/
void cucul_draw_thin_polyline(cucul_t *qq, int const x[], int const y[], int n)
{
@@ -144,12 +148,7 @@ void cucul_draw_thin_polyline(cucul_t *qq, int const x[], int const y[], int n)
* XXX: The following functions are local.
*/

/**
* \brief Generic Cohen-Sutherland line clipping function.
*
* \param s a line structure
* \return void
*/
/* Generic Cohen-Sutherland line clipping function. */
static void clip_line(cucul_t *qq, struct line* s)
{
uint8_t bits1, bits2;
@@ -201,13 +200,7 @@ static void clip_line(cucul_t *qq, struct line* s)
clip_line(qq, s);
}

/**
* \brief Helper function for clip_line().
*
* \param x X coordinate of the point.
* \param y Y coordinate of the point.
* \return The clipping bits for the given point.
*/
/* Helper function for clip_line(). */
static uint8_t clip_bits(cucul_t *qq, int x, int y)
{
uint8_t b = 0;
@@ -225,13 +218,8 @@ static uint8_t clip_bits(cucul_t *qq, int x, int y)
return b;
}

/**
* \brief Solid line drawing function, using Bresenham's mid-point line
* scan-conversion algorithm.
*
* \param s a line structure
* \return void
*/
/* Solid line drawing function, using Bresenham's mid-point line
* scan-conversion algorithm. */
static void draw_solid_line(cucul_t *qq, struct line* s)
{
int x1, y1, x2, y2;
@@ -292,13 +280,8 @@ static void draw_solid_line(cucul_t *qq, struct line* s)
}
}

/**
* \brief Thin line drawing function, using Bresenham's mid-point line
* scan-conversion algorithm and ASCII art graphics.
*
* \param s a line structure
* \return void
*/
/* Thin line drawing function, using Bresenham's mid-point line
* scan-conversion algorithm and ASCII art graphics. */
static void draw_thin_line(cucul_t *qq, struct line* s)
{
uint32_t charmapx[2], charmapy[2];


+ 8
- 10
cucul/math.c View File

@@ -24,24 +24,22 @@
#include "cucul.h"
#include "cucul_internals.h"

/**
* \brief Generate a random integer within a range.
/** \brief Generate a random integer within a range.
*
* \param min The lower bound of the integer range.
* \param max The upper bound of the integer range.
* \return A random integer comprised between \p min and \p max, inclusive.
* \param min The lower bound of the integer range.
* \param max The upper bound of the integer range.
* \return A random integer comprised between \p min and \p max, inclusive.
*/
int cucul_rand(int min, int max)
{
return min + (int)((1.0*(max-min+1)) * rand() / (RAND_MAX+1.0));
}

/**
* \brief Approximate a square root, using Newton's method to avoid
* costly floating point calculations.
/** \brief Approximate a square root, using Newton's method to avoid
* costly floating point calculations.
*
* \param a A positive integer.
* \return The approximate square root of \p a.
* \param a A positive integer.
* \return The approximate square root of \p a.
*/
unsigned int cucul_sqrt(unsigned int a)
{


+ 39
- 46
cucul/sprite.c View File

@@ -42,13 +42,12 @@ struct cucul_sprite
};
#endif

/**
* \brief Allocate a sprite loaded from a file.
/** \brief Allocate a sprite loaded from a file.
*
* \param file The filename.
* \return The sprite, or NULL if an error occured.
* \param file The filename.
* \return The sprite, or NULL if an error occured.
*/
struct cucul_sprite *cucul_load_sprite(cucul_t *qq, char const *file)
struct cucul_sprite *cucul_load_sprite(char const *file)
{
char buf[BUFSIZ];
struct cucul_sprite *sprite;
@@ -163,13 +162,12 @@ sprite_alloc_failed:
return NULL;
}

/**
* \brief Return the number of frames in a sprite.
/** \brief Return the number of frames in a sprite.
*
* \param sprite The sprite.
* \return The number of frames.
* \param sprite The sprite.
* \return The number of frames.
*/
int cucul_get_sprite_frames(cucul_t *qq, struct cucul_sprite const *sprite)
int cucul_get_sprite_frames(struct cucul_sprite const *sprite)
{
if(sprite == NULL)
return 0;
@@ -177,14 +175,13 @@ int cucul_get_sprite_frames(cucul_t *qq, struct cucul_sprite const *sprite)
return sprite->nf;
}

/**
* \brief Return the width of a sprite.
/** \brief Return the width of a sprite.
*
* \param sprite The sprite.
* \param f The frame index.
* \return The width of the given frame of the sprite.
* \param sprite The sprite.
* \param f The frame index.
* \return The width of the given frame of the sprite.
*/
int cucul_get_sprite_width(cucul_t *qq, struct cucul_sprite const *sprite, int f)
int cucul_get_sprite_width(struct cucul_sprite const *sprite, int f)
{
if(sprite == NULL)
return 0;
@@ -195,14 +192,13 @@ int cucul_get_sprite_width(cucul_t *qq, struct cucul_sprite const *sprite, int f
return sprite->frames[f].w;
}

/**
* \brief Return the height of a sprite.
/** \brief Return the height of a sprite.
*
* \param sprite The sprite.
* \param f The frame index.
* \return The height of the given frame of the sprite.
* \param sprite The sprite.
* \param f The frame index.
* \return The height of the given frame of the sprite.
*/
int cucul_get_sprite_height(cucul_t *qq, struct cucul_sprite const *sprite, int f)
int cucul_get_sprite_height(struct cucul_sprite const *sprite, int f)
{
if(sprite == NULL)
return 0;
@@ -213,14 +209,13 @@ int cucul_get_sprite_height(cucul_t *qq, struct cucul_sprite const *sprite, int
return sprite->frames[f].h;
}

/**
* \brief Return the X coordinate of a sprite's handle.
/** \brief Return the X coordinate of a sprite's handle.
*
* \param sprite The sprite.
* \param f The frame index.
* \return The X coordinate of the given frame's handle.
* \param sprite The sprite.
* \param f The frame index.
* \return The X coordinate of the given frame's handle.
*/
int cucul_get_sprite_dx(cucul_t *qq, struct cucul_sprite const *sprite, int f)
int cucul_get_sprite_dx(struct cucul_sprite const *sprite, int f)
{
if(sprite == NULL)
return 0;
@@ -231,14 +226,13 @@ int cucul_get_sprite_dx(cucul_t *qq, struct cucul_sprite const *sprite, int f)
return sprite->frames[f].dx;
}

/**
* \brief Return the Y coordinate of a sprite's handle.
/** \brief Return the Y coordinate of a sprite's handle.
*
* \param sprite The sprite.
* \param f The frame index.
* \return The Y coordinate of the given frame's handle.
* \param sprite The sprite.
* \param f The frame index.
* \return The Y coordinate of the given frame's handle.
*/
int cucul_get_sprite_dy(cucul_t *qq, struct cucul_sprite const *sprite, int f)
int cucul_get_sprite_dy(struct cucul_sprite const *sprite, int f)
{
if(sprite == NULL)
return 0;
@@ -249,15 +243,15 @@ int cucul_get_sprite_dy(cucul_t *qq, struct cucul_sprite const *sprite, int f)
return sprite->frames[f].dy;
}

/**
* \brief Draw a sprite's specific frame at the given coordinates. If the
* frame does not exist, nothing is displayed.
/** \brief Draw a sprite's specific frame at the given coordinates. If the
* frame does not exist, nothing is displayed.
*
* \param x The X coordinate.
* \param y The Y coordinate.
* \param sprite The sprite.
* \param f The frame index.
* \return void
* \param qq A libcucul canvas
* \param x The X coordinate.
* \param y The Y coordinate.
* \param sprite The sprite.
* \param f The frame index.
* \return void
*/
void cucul_draw_sprite(cucul_t *qq, int x, int y, struct cucul_sprite const *sprite, int f)
{
@@ -293,11 +287,10 @@ void cucul_draw_sprite(cucul_t *qq, int x, int y, struct cucul_sprite const *spr
cucul_set_color(qq, oldfg, oldbg);
}

/**
* \brief Free the memory associated with a sprite.
/** \brief Free the memory associated with a sprite.
*
* \param sprite The sprite to be freed.
* \return void
* \param sprite The sprite to be freed.
* \return void
*/
void cucul_free_sprite(struct cucul_sprite *sprite)
{


+ 31
- 29
cucul/triangle.c View File

@@ -24,17 +24,18 @@
#include "cucul.h"
#include "cucul_internals.h"

/**
* \brief Draw a triangle on the screen using the given character.
/** \brief Draw a triangle on the canvas using the given character.
*
* \param x1 X coordinate of the first point.
* \param y1 Y coordinate of the first point.
* \param x2 X coordinate of the second point.
* \param y2 Y coordinate of the second point.
* \param x3 X coordinate of the third point.
* \param y3 Y coordinate of the third point.
* \param c Character to draw the triangle outline with.
* \return void
* \param qq The handle to the libcucul canvas.
* \param x1 X coordinate of the first point.
* \param y1 Y coordinate of the first point.
* \param x2 X coordinate of the second point.
* \param y2 Y coordinate of the second point.
* \param x3 X coordinate of the third point.
* \param y3 Y coordinate of the third point.
* \param str UTF-8 string representing the character that should be used
* to draw the triangle outline.
* \return void
*/
void cucul_draw_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
int x3, int y3, char const *str)
@@ -44,16 +45,16 @@ void cucul_draw_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
cucul_draw_line(qq, x3, y3, x1, y1, str);
}

/**
* \brief Draw a thin triangle on the screen.
/** \brief Draw a thin triangle on the canvas.
*
* \param x1 X coordinate of the first point.
* \param y1 Y coordinate of the first point.
* \param x2 X coordinate of the second point.
* \param y2 Y coordinate of the second point.
* \param x3 X coordinate of the third point.
* \param y3 Y coordinate of the third point.
* \return void
* \param qq The handle to the libcucul canvas.
* \param x1 X coordinate of the first point.
* \param y1 Y coordinate of the first point.
* \param x2 X coordinate of the second point.
* \param y2 Y coordinate of the second point.
* \param x3 X coordinate of the third point.
* \param y3 Y coordinate of the third point.
* \return void
*/
void cucul_draw_thin_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
int x3, int y3)
@@ -63,17 +64,18 @@ void cucul_draw_thin_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
cucul_draw_thin_line(qq, x3, y3, x1, y1);
}

/**
* \brief Fill a triangle on the screen using the given character.
/** \brief Fill a triangle on the canvas using the given character.
*
* \param x1 X coordinate of the first point.
* \param y1 Y coordinate of the first point.
* \param x2 X coordinate of the second point.
* \param y2 Y coordinate of the second point.
* \param x3 X coordinate of the third point.
* \param y3 Y coordinate of the third point.
* \param c Character to fill the triangle with.
* \return void
* \param qq The handle to the libcucul canvas.
* \param x1 X coordinate of the first point.
* \param y1 Y coordinate of the first point.
* \param x2 X coordinate of the second point.
* \param y2 Y coordinate of the second point.
* \param x3 X coordinate of the third point.
* \param y3 Y coordinate of the third point.
* \param str UTF-8 string representing the character that should be used
* to fill the triangle.
* \return void
*/
void cucul_fill_triangle(cucul_t *qq, int x1, int y1, int x2, int y2,
int x3, int y3, char const *str)


Loading…
Cancel
Save