You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

преди 19 години
преди 21 години
преди 21 години
преди 21 години
преди 19 години
преди 21 години
преди 21 години
преди 21 години
преди 20 години
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231
  1. /*
  2. * libcaca Colour ASCII-Art library
  3. * Copyright (c) 2002-2006 Sam Hocevar <sam@zoy.org>
  4. * All Rights Reserved
  5. *
  6. * $Id$
  7. *
  8. * This library is free software; you can redistribute it and/or
  9. * modify it under the terms of the Do What The Fuck You Want To
  10. * Public License, Version 2, as published by Sam Hocevar. See
  11. * http://sam.zoy.org/wtfpl/COPYING for more details.
  12. */
  13. /** \file caca.h
  14. * \version \$Id$
  15. * \author Sam Hocevar <sam@zoy.org>
  16. * \brief The \e libcaca public header.
  17. *
  18. * This header contains the public types and functions that applications
  19. * using \e libcaca may use.
  20. */
  21. /** \mainpage libcaca developer documentation
  22. *
  23. * \section intro Introduction
  24. *
  25. * \e libcaca is a graphics library that outputs text instead of pixels,
  26. * so that it can work on older video cards or text terminals. It is not
  27. * unlike the famous AAlib library. \e libcaca can use almost any virtual
  28. * terminal to work, thus it should work on all Unix systems (including
  29. * Mac OS X) using either the slang library or the ncurses library, on DOS
  30. * using the conio library, and on Windows systems using either slang or
  31. * ncurses (through Cygwin emulation) or conio. There is also a native X11
  32. * driver, and an OpenGL driver (through freeglut) that does not require a
  33. * text terminal. For machines without a screen, the raw driver can be used
  34. * to send the output to another machine, using for instance cacaserver.
  35. *
  36. * \e libcaca is free software, released under the Do What The Fuck You
  37. * Want To Public License. This ensures that no one, not even the \e libcaca
  38. * developers, will ever have anything to say about what you do with the
  39. * software. It used to be licensed under the GNU Lesser General Public
  40. * License, but that was not free enough.
  41. *
  42. * \section api The libcaca API
  43. *
  44. * \e libcaca relies on a low-level, device independent library, called
  45. * \e libcucul. \e libcucul can be used alone as a simple ASCII and/or
  46. * Unicode compositing canvas.
  47. *
  48. * The complete \e libcucul and \e libcaca programming interface is
  49. * available from the cucul.h and caca.h headers.
  50. *
  51. * \section env Environment variables
  52. *
  53. * Some environment variables can be used to change the behaviour of
  54. * \e libcaca without having to modify the program which uses them. These
  55. * variables are:
  56. *
  57. * \li \b CACA_DRIVER: set the backend video driver. In order of preference:
  58. * - \c conio uses the DOS conio.h interface.
  59. * - \c ncurses uses the ncurses library.
  60. * - \c slang uses the S-Lang library.
  61. * - \c x11 uses the native X11 driver.
  62. * - \c gl uses freeglut and opengl libraries.
  63. * - \c raw outputs to the standard output instead of rendering the
  64. * canvas. This is can be used together with cacaserver.
  65. *
  66. * \li \b CACA_GEOMETRY: set the video display size. The format of this
  67. * variable must be XxY, with X and Y being integer values. This option
  68. * currently works with the network, X11 and GL drivers.
  69. *
  70. * \li \b CACA_FONT: set the rendered font. The format of this variable is
  71. * implementation dependent, but since it currently only works with the
  72. * X11 driver, an X11 font name such as "fixed" or "5x7" is expected.
  73. */
  74. #ifndef __CACA_H__
  75. #define __CACA_H__
  76. /** libcaca API version */
  77. #define CACA_API_VERSION_1
  78. #include <cucul.h>
  79. #ifdef __cplusplus
  80. extern "C"
  81. {
  82. #endif
  83. /** \brief User event types.
  84. *
  85. * Event types returned by caca_get_event().
  86. */
  87. enum caca_event_type
  88. {
  89. CACA_EVENT_NONE = 0x0000, /**< No event. */
  90. CACA_EVENT_KEY_PRESS = 0x0001, /**< A key was pressed. */
  91. CACA_EVENT_KEY_RELEASE = 0x0002, /**< A key was released. */
  92. CACA_EVENT_MOUSE_PRESS = 0x0004, /**< A mouse button was pressed. */
  93. CACA_EVENT_MOUSE_RELEASE = 0x0008, /**< A mouse button was released. */
  94. CACA_EVENT_MOUSE_MOTION = 0x0010, /**< The mouse was moved. */
  95. CACA_EVENT_RESIZE = 0x0020, /**< The window was resized. */
  96. CACA_EVENT_ANY = 0xffff /**< Bitmask for any event. */
  97. };
  98. /** \brief User events.
  99. *
  100. * This structure is filled by caca_get_event() when an event is received.
  101. * The \e type field is always valid. The validity of the \e data union
  102. * depends on the value of the \e type field:
  103. *
  104. * \li \b CACA_EVENT_NONE: no other field is valid.
  105. *
  106. * \li \b CACA_EVENT_KEY_PRESS, \b CACA_EVENT_KEY_RELEASE: the \e data.key.c
  107. * field is valid and contains either the ASCII value for the key, or
  108. * an \e enum \e caca_key value. If the value is a printable ASCII
  109. * character, the \e data.key.ucs4 and \e data.key.utf8 fields are
  110. * also filled and contain respectively the UCS-4/UTF-32 and the UTF-8
  111. * representations of the character. Otherwise, their content is
  112. * undefined.
  113. *
  114. * \li \b CACA_EVENT_MOUSE_PRESS, \b CACA_EVENT_MOUSE_RELEASE: the
  115. * \e data.mouse.button field is valid and contains the index of the
  116. * mouse button that was pressed.
  117. *
  118. * \li \b CACA_EVENT_MOUSE_MOTION: the \e data.mouse.x and \e data.mouse.y
  119. * fields are valid and contain the mouse coordinates in character
  120. * cells.
  121. *
  122. * \li \b CACA_EVENT_RESIZE: the \e data.resize.w and \e data.resize.h
  123. * fields are valid and contain the new width and height values of
  124. * the \e libcucul canvas attached to \e libcaca.
  125. *
  126. * The result of accessing data members outside the above conditions is
  127. * undefined.
  128. */
  129. struct caca_event
  130. {
  131. enum caca_event_type type;
  132. union
  133. {
  134. struct { unsigned int x, y, button; } mouse;
  135. struct { unsigned int w, h; } resize;
  136. struct { unsigned int c; unsigned long int ucs4; char utf8[8]; } key;
  137. } data;
  138. };
  139. /** \brief Special key values.
  140. *
  141. * Special key values returned by caca_get_event() for which there is no
  142. * ASCII equivalent.
  143. */
  144. enum caca_key
  145. {
  146. CACA_KEY_UNKNOWN = 0x00, /**< Unknown key. */
  147. /* The following keys have ASCII equivalents */
  148. CACA_KEY_BACKSPACE = 0x08, /**< The backspace key. */
  149. CACA_KEY_TAB = 0x09, /**< The tabulation key. */
  150. CACA_KEY_RETURN = 0x0d, /**< The return key. */
  151. CACA_KEY_PAUSE = 0x13, /**< The pause key. */
  152. CACA_KEY_ESCAPE = 0x1b, /**< The escape key. */
  153. CACA_KEY_DELETE = 0x7f, /**< The delete key. */
  154. /* The following keys do not have ASCII equivalents but have been
  155. * chosen to match the SDL equivalents */
  156. CACA_KEY_UP = 0x111, /**< The up arrow key. */
  157. CACA_KEY_DOWN = 0x112, /**< The down arrow key. */
  158. CACA_KEY_LEFT = 0x113, /**< The left arrow key. */
  159. CACA_KEY_RIGHT = 0x114, /**< The right arrow key. */
  160. CACA_KEY_INSERT = 0x115, /**< The insert key. */
  161. CACA_KEY_HOME = 0x116, /**< The home key. */
  162. CACA_KEY_END = 0x117, /**< The end key. */
  163. CACA_KEY_PAGEUP = 0x118, /**< The page up key. */
  164. CACA_KEY_PAGEDOWN = 0x119, /**< The page down key. */
  165. CACA_KEY_F1 = 0x11a, /**< The F1 key. */
  166. CACA_KEY_F2 = 0x11b, /**< The F2 key. */
  167. CACA_KEY_F3 = 0x11c, /**< The F3 key. */
  168. CACA_KEY_F4 = 0x11d, /**< The F4 key. */
  169. CACA_KEY_F5 = 0x11e, /**< The F5 key. */
  170. CACA_KEY_F6 = 0x11f, /**< The F6 key. */
  171. CACA_KEY_F7 = 0x120, /**< The F7 key. */
  172. CACA_KEY_F8 = 0x121, /**< The F8 key. */
  173. CACA_KEY_F9 = 0x122, /**< The F9 key. */
  174. CACA_KEY_F10 = 0x123, /**< The F10 key. */
  175. CACA_KEY_F11 = 0x124, /**< The F11 key. */
  176. CACA_KEY_F12 = 0x125, /**< The F12 key. */
  177. CACA_KEY_F13 = 0x126, /**< The F13 key. */
  178. CACA_KEY_F14 = 0x127, /**< The F14 key. */
  179. CACA_KEY_F15 = 0x128 /**< The F15 key. */
  180. };
  181. typedef struct caca_context caca_t;
  182. /** \defgroup basic Basic functions
  183. *
  184. * These functions provide the basic \e libcaca routines for driver
  185. * initialisation, system information retrieval and configuration.
  186. *
  187. * @{ */
  188. caca_t * caca_attach(cucul_t *qq);
  189. void caca_detach(caca_t *kk);
  190. void caca_set_delay(caca_t *kk, unsigned int);
  191. void caca_display(caca_t *kk);
  192. unsigned int caca_get_rendertime(caca_t *kk);
  193. unsigned int caca_get_window_width(caca_t *kk);
  194. unsigned int caca_get_window_height(caca_t *kk);
  195. int caca_set_window_title(caca_t *kk, char const *);
  196. /* @} */
  197. /** \defgroup event Event handling
  198. *
  199. * These functions handle user events such as keyboard input and mouse
  200. * clicks.
  201. *
  202. * @{ */
  203. int caca_get_event(caca_t *kk, unsigned int, struct caca_event *, int);
  204. unsigned int caca_get_mouse_x(caca_t *kk);
  205. unsigned int caca_get_mouse_y(caca_t *kk);
  206. void caca_set_mouse(caca_t *kk, int);
  207. /* @} */
  208. #ifdef __cplusplus
  209. }
  210. #endif
  211. #endif /* __CACA_H__ */