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.0 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220
  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 changes in the 1.0 API of \e libcaca are the
  7. \e libcaca / \e libcucul split and the object-oriented design. See these
  8. two examples for a rough idea of 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 <cucul.h>
  36. #include <caca.h>
  37. /* libcaca program - 1.0 API */
  38. int main(void)
  39. {
  40. /* Initialise libcaca */
  41. cucul_canvas_t *cv;
  42. caca_display_t *dp;
  43. dp = caca_create_display(cv);
  44. cv = caca_get_canvas(dp);
  45. /* Set window title */
  46. caca_set_display_title(dp, "Window");
  47. /* Choose drawing colours */
  48. cucul_set_color_ansi(cv, CUCUL_BLACK,
  49. CUCUL_WHITE);
  50. /* Draw a string at (0, 0) */
  51. cucul_put_str(cv, 0, 0, "Hello world!");
  52. /* Refresh display */
  53. caca_refresh_display();
  54. /* Wait for a key press event */
  55. caca_get_event(dp, CACA_EVENT_KEY_PRESS,
  56. NULL, -1);
  57. /* Clean up library */
  58. caca_free_display(dp);
  59. return 0;
  60. }
  61. \endcode
  62. </td></tr></table>
  63. Note the following important things:
  64. - Functions now take an object handle as their first argument.
  65. - All input/output functions start with \b caca_ and all
  66. drawing and text handling functions start with \b cucul_ .
  67. \section foo2 Migration strategy
  68. You have two ways to migrate your application to use \e libcaca 1.x:
  69. - Port your code using the function equivalence list. This is the preferred
  70. way because new functions are thread safe and offer much more features
  71. to both the programmer and the end user.
  72. - Use the legacy compatibility layer.
  73. Using the compatibility layer is as easy as adding the following three lines:
  74. <table border="0"><tr><td valign="top">
  75. \code
  76. #include <caca.h>
  77. /* libcaca program - 0.x API */
  78. ...
  79. \endcode
  80. </td><td>
  81. \code
  82. #include <caca.h>
  83. #ifdef CACA_API_VERSION_1
  84. # include <caca0.h>
  85. #endif
  86. /* libcaca program - 0.x API */
  87. ...
  88. \endcode
  89. </td></tr></table>
  90. \section foo3 Function equivalence list
  91. \subsection bar1 Basic functions
  92. - \b caca_init(): use cucul_create_canvas() to create a \e libcucul canvas,
  93. followed by caca_create_display() to attach a \e libcaca display to it.
  94. - \b caca_set_delay(): use caca_set_display_time().
  95. - \b caca_get_feature(): deprecated.
  96. - \b caca_set_feature(): deprecated, see cucul_set_dither_antialias(),
  97. cucul_set_dither_color() and cucul_set_dither_mode() instead.
  98. - \b caca_get_feature_name(): deprecated, see cucul_get_dither_mode_list(),
  99. cucul_get_dither_antialias_list() and cucul_get_dither_color_list()
  100. instead.
  101. - \b caca_get_rendertime(): use caca_get_display_time().
  102. - \b caca_get_width(): use cucul_get_canvas_width().
  103. - \b caca_get_height(): use cucul_get_canvas_height().
  104. - \b caca_set_window_title(): use caca_set_display_title().
  105. - \b caca_get_window_width(): use caca_get_display_width().
  106. - \b caca_get_window_height(): use caca_get_display_height().
  107. - \b caca_refresh(): use caca_refresh_display().
  108. - \b caca_end(): use caca_free_display() to detach the \e libcaca display,
  109. followed by cucul_free_canvas() to free the underlying \e libcucul canvas.
  110. \subsection bar2 Event handling
  111. - \b caca_get_event(): unchanged, but the event information retrieval
  112. changed a lot.
  113. - \b caca_wait_event(): use caca_get_event() with a \c timeout argument
  114. of \b -1.
  115. - \b caca_get_mouse_x(): unchanged.
  116. - \b caca_get_mouse_y(): unchanged.
  117. \subsection bar3 Character printing
  118. - \b caca_set_color(): use cucul_set_color_ansi() or cucul_set_color_argb().
  119. - \b caca_get_fg_color(): use cucul_get_attr().
  120. - \b caca_get_bg_color(): use cucul_get_attr().
  121. - \b caca_get_color_name(): this function is now deprecated due to major
  122. uselessness.
  123. - \b caca_putchar(): use cucul_put_char().
  124. - \b caca_putstr(): use cucul_put_str().
  125. - \b caca_printf(): use cucul_printf().
  126. - \b caca_clear(): use cucul_clear_canvas().
  127. \subsection bar4 Primitives drawing
  128. These functions are almost unchanged, except for Unicode support and the
  129. fact that they now act on a given canvas.
  130. - \b caca_draw_line(): use cucul_draw_line().
  131. - \b caca_draw_polyline(): use cucul_draw_polyline().
  132. - \b caca_draw_thin_line(): use cucul_draw_thin_line().
  133. - \b caca_draw_thin_polyline(): use cucul_draw_thin_polyline().
  134. - \b caca_draw_circle(): use cucul_draw_circle().
  135. - \b caca_draw_ellipse(): use cucul_draw_ellipse().
  136. - \b caca_draw_thin_ellipse(): use cucul_draw_thin_ellipse().
  137. - \b caca_fill_ellipse(): use cucul_fill_ellipse().
  138. - \b caca_draw_box(): use cucul_draw_box().
  139. - \b caca_draw_thin_box(): use cucul_draw_thin_box() or cucul_draw_cp437_box().
  140. - \b caca_fill_box(): use cucul_fill_box().
  141. - \b caca_draw_triangle(): use cucul_draw_triangle().
  142. - \b caca_draw_thin_triangle(): use cucul_draw_thin_triangle().
  143. - \b caca_fill_triangle(): use cucul_fill_triangle().
  144. \subsection bar5 Mathematical functions
  145. - \b caca_rand(): use cucul_rand(). The second argument is different, make
  146. sure you take that into account.
  147. - \b caca_sqrt(): this function is now deprecated, use your system's
  148. \b sqrt() call instead.
  149. \subsection bar6 Sprite handling
  150. The newly introduced canvases can have several frames. Sprites are hence
  151. completely deprecated.
  152. - \b caca_load_sprite(): use cucul_import_file().
  153. - \b caca_get_sprite_frames(): use cucul_get_frame_count().
  154. - \b caca_get_sprite_width(): use cucul_get_canvas_width().
  155. - \b caca_get_sprite_height(): use cucul_get_canvas_height().
  156. - \b caca_get_sprite_dx(): use cucul_get_canvas_handle_x().
  157. - \b caca_get_sprite_dy(): use cucul_get_canvas_handle_y().
  158. - \b caca_draw_sprite(): use cucul_set_frame() and cucul_blit().
  159. - \b caca_free_sprite(): use cucul_free_canvas().
  160. \subsection bar7 Bitmap handling
  161. Bitmaps have been renamed to dithers, because these objects do not in fact
  162. store any pixels, they just have information on how bitmaps will be dithered.
  163. - \b caca_create_bitmap(): use cucul_create_dither().
  164. - \b caca_set_bitmap_palette(): use cucul_set_dither_palette().
  165. - \b caca_draw_bitmap(): use cucul_dither_bitmap().
  166. - \b caca_free_bitmap(): use cucul_free_dither().
  167. \section foo4 Compilation
  168. The \c caca-config utility is deprecated in favour of the standard
  169. \c pkg-config interface:
  170. \code
  171. gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
  172. gcc foobar.o -o foobar `pkg-config --libs caca`
  173. \endcode
  174. \c caca-config is still provided as a convenience tool but may be removed
  175. in the future.
  176. */