Você não pode selecionar mais de 25 tópicos Os tópicos devem começar com uma letra ou um número, podem incluir traços ('-') e podem ter até 35 caracteres.

migrating.dox 7.3 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228
  1. /* $Id$ */
  2. /** \page libcaca-migrating Migrating from libcaca 0.x to the 1.0 API
  3. This section will guide you through the migration of a \e libcaca 0.x
  4. application to the latest API version.
  5. \section foo1 Overview
  6. The most important change in the 1.0 API of \e libcaca is the
  7. object-oriented design. See these two examples for a rough idea of
  8. what changed:
  9. <table border="0"><tr><td valign="top">
  10. \code
  11. #include <caca.h>
  12. /* libcaca program - 0.x API */
  13. int main(void)
  14. {
  15. /* Initialise libcaca */
  16. caca_init();
  17. /* Set window title */
  18. caca_set_window_title("Window");
  19. /* Choose drawing colours */
  20. caca_set_color(CACA_COLOR_BLACK,
  21. CACA_COLOR_WHITE);
  22. /* Draw a string at (0, 0) */
  23. caca_putstr(0, 0, "Hello world!");
  24. /* Refresh display */
  25. caca_refresh();
  26. /* Wait for a key press event */
  27. caca_wait_event(CACA_EVENT_KEY_PRESS);
  28. /* Clean up library */
  29. caca_end();
  30. return 0;
  31. }
  32. \endcode
  33. </td><td>
  34. \code
  35. #include <caca.h>
  36. /* libcaca program - 1.0 API */
  37. int main(void)
  38. {
  39. /* Initialise libcaca */
  40. caca_canvas_t *cv;
  41. caca_display_t *dp;
  42. dp = caca_create_display(NULL);
  43. cv = caca_get_canvas(dp);
  44. /* Set window title */
  45. caca_set_display_title(dp, "Window");
  46. /* Choose drawing colours */
  47. caca_set_color_ansi(cv, CACA_BLACK,
  48. CACA_WHITE);
  49. /* Draw a string at (0, 0) */
  50. caca_put_str(cv, 0, 0, "Hello world!");
  51. /* Refresh display */
  52. caca_refresh_display();
  53. /* Wait for a key press event */
  54. caca_get_event(dp, CACA_EVENT_KEY_PRESS,
  55. NULL, -1);
  56. /* Clean up library */
  57. caca_free_display(dp);
  58. return 0;
  59. }
  60. \endcode
  61. </td></tr></table>
  62. Note the following important things:
  63. - Most functions now take an object handle as their first argument.
  64. \section foo2 Migration strategy
  65. You have two ways to migrate your application to use \e libcaca 1.x:
  66. - Port your code using the function equivalence list. This is the preferred
  67. way because new functions are thread safe and offer much more features
  68. to both the programmer and the end user.
  69. - Use the legacy compatibility layer.
  70. Using the compatibility layer is as easy as adding the following three lines:
  71. <table border="0"><tr><td valign="top">
  72. \code
  73. #include <caca.h>
  74. /* libcaca program - 0.x API */
  75. ...
  76. \endcode
  77. </td><td>
  78. \code
  79. #include <caca.h>
  80. #ifdef CACA_API_VERSION_1
  81. # include <caca0.h>
  82. #endif
  83. /* libcaca program - 0.x API */
  84. ...
  85. \endcode
  86. </td></tr></table>
  87. The modified code is guaranteed to build both with \e libcaca 0.x and
  88. \e libcaca 1.0.
  89. \section foo3 Function equivalence list
  90. \subsection bar1 Basic functions
  91. - \b caca_init(): use caca_create_canvas() to create a \e libcaca canvas,
  92. followed by caca_create_display() to attach a \e libcaca display to it.
  93. Alternatively, caca_create_display() with a NULL argument will create a
  94. canvas automatically.
  95. - \b caca_set_delay(): use caca_set_display_time().
  96. - \b caca_get_feature(): deprecated.
  97. - \b caca_set_feature(): deprecated, see caca_set_dither_antialias(),
  98. caca_set_dither_color() and caca_set_dither_mode() instead.
  99. - \b caca_get_feature_name(): deprecated, see caca_get_dither_mode_list(),
  100. caca_get_dither_antialias_list() and caca_get_dither_color_list()
  101. instead.
  102. - \b caca_get_rendertime(): use caca_get_display_time().
  103. - \b caca_get_width(): use caca_get_canvas_width().
  104. - \b caca_get_height(): use caca_get_canvas_height().
  105. - \b caca_set_window_title(): use caca_set_display_title().
  106. - \b caca_get_window_width(): use caca_get_display_width().
  107. - \b caca_get_window_height(): use caca_get_display_height().
  108. - \b caca_refresh(): use caca_refresh_display().
  109. - \b caca_end(): use caca_free_display() to detach the \e libcaca display,
  110. followed by caca_free_canvas() to free the underlying \e libcaca canvas.
  111. Alternatively, if the canvas was created by caca_create_display(), it
  112. will be automatically destroyed by caca_free_display().
  113. \subsection bar2 Event handling
  114. - \b caca_get_event(): unchanged, but the event information retrieval
  115. changed a lot.
  116. - \b caca_wait_event(): use caca_get_event() with a \c timeout argument
  117. of \b -1.
  118. - \b caca_get_mouse_x(): unchanged.
  119. - \b caca_get_mouse_y(): unchanged.
  120. \subsection bar3 Character printing
  121. - \b caca_set_color(): use caca_set_color_ansi() or caca_set_color_argb().
  122. - \b caca_get_fg_color(): use caca_get_attr().
  123. - \b caca_get_bg_color(): use caca_get_attr().
  124. - \b caca_get_color_name(): this function is now deprecated due to major
  125. uselessness.
  126. - \b caca_putchar(): use caca_put_char().
  127. - \b caca_putstr(): use caca_put_str().
  128. - \b caca_printf(): unchanged.
  129. - \b caca_clear(): use caca_clear_canvas().
  130. \subsection bar4 Primitives drawing
  131. These functions are almost unchanged, except for Unicode support and the
  132. fact that they now act on a given canvas.
  133. - \b caca_draw_line(): unchanged.
  134. - \b caca_draw_polyline(): unchanged.
  135. - \b caca_draw_thin_line(): unchanged.
  136. - \b caca_draw_thin_polyline(): unchanged.
  137. - \b caca_draw_circle(): unchanged.
  138. - \b caca_draw_ellipse(): unchanged.
  139. - \b caca_draw_thin_ellipse(): unchanged.
  140. - \b caca_fill_ellipse(): unchanged.
  141. - \b caca_draw_box(): unchanged, but the argument meaning changed (width
  142. and height instead of corner coordinates).
  143. - \b caca_draw_thin_box(): use caca_draw_thin_box() or caca_draw_cp437_box(),
  144. also the argument meaning changed (width
  145. and height instead of corner coordinates).
  146. - \b caca_fill_box(): unchanged, but the argument meaning changed (width
  147. and height instead of corner coordinates).
  148. - \b caca_draw_triangle(): unchanged.
  149. - \b caca_draw_thin_triangle(): unchanged.
  150. - \b caca_fill_triangle(): unchanged.
  151. \subsection bar5 Mathematical functions
  152. - \b caca_rand(): unchanged, but the second argument is different, make
  153. sure you take that into account.
  154. - \b caca_sqrt(): this function is now deprecated, use your system's
  155. \b sqrt() call instead.
  156. \subsection bar6 Sprite handling
  157. The newly introduced canvases can have several frames. Sprites are hence
  158. completely deprecated.
  159. - \b caca_load_sprite(): use caca_import_file().
  160. - \b caca_get_sprite_frames(): use caca_get_frame_count().
  161. - \b caca_get_sprite_width(): use caca_get_canvas_width().
  162. - \b caca_get_sprite_height(): use caca_get_canvas_height().
  163. - \b caca_get_sprite_dx(): use caca_get_canvas_handle_x().
  164. - \b caca_get_sprite_dy(): use caca_get_canvas_handle_y().
  165. - \b caca_draw_sprite(): use caca_set_frame() and caca_blit().
  166. - \b caca_free_sprite(): use caca_free_canvas().
  167. \subsection bar7 Bitmap handling
  168. Bitmaps have been renamed to dithers, because these objects do not in fact
  169. store any pixels, they just have information on how bitmaps will be dithered.
  170. - \b caca_create_bitmap(): use caca_create_dither().
  171. - \b caca_set_bitmap_palette(): use caca_set_dither_palette().
  172. - \b caca_draw_bitmap(): use caca_dither_bitmap().
  173. - \b caca_free_bitmap(): use caca_free_dither().
  174. \section foo4 Compilation
  175. The \c caca-config utility is deprecated in favour of the standard
  176. \c pkg-config interface:
  177. \code
  178. gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
  179. gcc foobar.o -o foobar `pkg-config --libs caca`
  180. \endcode
  181. \c caca-config is still provided as a convenience tool but may be removed
  182. in the future.
  183. */