1@html_text_substitution=readme.txt|<a href="readme.html">readme.txt</a>
2@external-css=allegro.css
3@document_title=API compatibility information
4@<pre>
5@!indent
6     ______   ___    ___
7    /\  _  \ /\_ \  /\_ \
8    \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___
9     \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
10      \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
11       \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
12        \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
13                                       /\____/
14                                       \_/__/
15
16
17                API compatibility information.
18
19         See readme.txt for a more general overview.
20@indent
21@</pre>
22
23
24
25@heading
26Introduction
27
28   Once Allegro 4.0 is released, we plan to maintain backward compatibility
29   at the Application Programming Interface level for the subsequent stable
30   releases of the 4.x series, that is for the releases with an even minor
31   version number. For example, that means you will be able to compile your
32   program written for version 4.0.0 with version 4.0.23 or version 4.2.1 of
33   the library. However, in order to fix some minor inconsistencies of the
34   original 4.0 API, we may make exceptions to the rule and break strict
35   backward compatibility in a few cases. But this is guaranteed to never
36   happen in a stable series for which major and minor version numbers are
37   fixed; in other words, two stable versions that differ from each other
38   only by the revision (3rd) number will be strictly backward compatible.
39
40
41@heading
42Changes between 4.2.x and 4.4.x series
43<ul><li>
44   The output parameters to gfx_mode_select should be initialized in
45   4.4.x as they are used for the initial selection now.
46</ul>
47
48
49@heading
50Changes between 4.0.x and 4.2.x series
51<ul><li>
52   The 'aspect' parameter of get_camera_matrix() and get_camera_matrix_f()
53   strictly conforms to the documentation; in particular, setting it to 1
54   instructs the functions to do no scaling. This was not the case before,
55   because the functions multiplied this aspect ratio by 4/3.
56<li>
57   Menus created from a DIALOG array (by using d_menu_proc for the proc pointer)
58   now correctly use the w and h fields as a minimum for their inclusive
59   dimensions (in the same way as all other GUI elements). Before, they would
60   draw the border outside of this dimension (1 pixel overdraw with other GUI
61   elements), and also add an additional 'shadow' to the right and the bottom
62   (2 pixels overdraw with other GUI elements).
63<li>
64   The 'retrace_count' variable and the 'retrace_proc' callback function
65   take into account the refresh rate (if it is known) when the retrace
66   simulator is not installed. This was not the case before, except under
67   Windows.
68<li>
69   The default value for the mouse configuration variable 'emulate_three'
70   has been changed to 'no' in all cases (even if you have a 2-button mouse).
71<li>
72   The COLORCONV_KEEP_TRANS flag strictly conforms to the documentation now.
73   This was not the case before, because it was ignored when loading bitmaps
74   from datafiles. fixup_datafile() was modified to preserve transparency
75   when this flag is set, which was not guaranteed before in rare cases.
76<li>
77   create_sub_bitmap() is now less tolerant about receiving bad arguments.
78   For example, it used to compensate for negative values for the origin
79   and return NULL if the parent bitmap was NULL. These cases are now
80   ASSERTed in the debug version, but unchecked in the release version.
81<li>
82   install_allegro() and allegro_init() now return an error code if unable to
83   initialise a system driver. Previously they would have aborted the program
84   in such cases. Consequently you should check their return values.
85<li>
86   The preprocessor symbol USE_CONSOLE is deprecated. Define instead the
87   symbol ALLEGRO_USE_CONSOLE prior to including Allegro headers in order
88   to set up Allegro for building a console application.
89<li>
90   The constructors of the fix class from integer and floating point values
91   are now explicit.
92<li>
93   All BeOS gfx driver IDs and constants have been replaced by more meaningful
94   ones. You may have to modify your allegro.cfg to reflect the change, or
95   update and recompile your programs if you used BeOS specific gfx drivers.
96<li>
97   The behaviour of the GFX_SAFE driver has changed: it doesn't try to first
98   set up GFX_AUTODETECTed drivers anymore and is now guaranteed to be a
99   windowed driver when the platform has got a windowing system.
100<li>
101   A datafile object returned by load_datafile_object() used not to contain
102   the properties attached to the object. This has been fixed.
103<li>
104   object_message() now takes care of scaring and unscaring the mouse if the
105   message to be sent is MSG_DRAW.
106<li>
107   file_select_ex() now treats '(+)d' as it does for any other attributes in
108   the extension string which is passed to it: only directories are included
109   and, among them, only those with the correct set of attributes.
110<li>
111   d_ctext_proc() now behaves like d_text_proc() and d_rtext_proc(), that is
112   it takes into account the bounding box to calculate the position which the
113   string is centered around. It previously used only the x field. And, as a
114   consequence, gui_ctext_proc is now expected to behave the same.
115<li>
116   dialog_message() now passes user messages to hidden objects.
117<li>
118   set_volume() doesn't use the hardware mixer anymore to alter the global
119   volume. Use set_hardware_volume() instead to get the old behaviour.
120<li>
121   The default sound volume of Allegro was raised, since there no longer is
122   the risk of wrapping with the new mixer. To restore the volume level to
123   that of previous versions, look at the set_volume_per_voice function.
124   Programs already using set_volume_per_voice are not affected.
125<li>
126   The semantics of rest are clarified so rest(0) does yielding when
127   possible.
128<li>
129   The get_align_matrix[_f] functions would return mirrored matrices in some
130   cases, this was fixed.
131<li>
132   In many places 'unsigned long' variables were used to hold memory
133   addresses. These have been changed to use the 'uintptr_t' type instead.
134<li>
135   15-bit and 16-bit bitmaps used to be arrays of unsigned shorts, and 32-bit
136   bitmaps used to be arrays of unsigned longs. They have been changed to be
137   arrays of 16-bit and 32-bit integers respectively. This makes a difference
138   on platforms where an unsigned long is not 32-bits wide (e.g. some 64-bit
139   platforms).
140</ul>
141
142@heading
143Deprecated materials
144
145   The following items have been deprecated and the main documentation was
146   purged of any references to them. If you are still using any of those, now
147   might be a good time to get rid of them (within parentheses is the symbol
148   most likely to be a replacement for the obsolete one, if any). However
149   they are still supported for the sake of backwards compatibility, unless
150   you define the symbol ALLEGRO_NO_COMPATIBILITY prior to including Allegro
151   headers.
152
153<ul><li>
154   clear (clear_bitmap).
155<li>
156   cpu_fpu (cpu_capabilities, in combination with CPU_FPU).
157<li>
158   cpu_mmx (cpu_capabilities, in combination with CPU_MMX).
159<li>
160   cpu_3dnow (cpu_capabilities, in combination with CPU_3DNOW).
161<li>
162   cpu_cpuid (cpu_capabilities, in combination with CPU_ID).
163<li>
164   draw_character (draw_character_ex, passing the mode you would have passed
165   to text_mode() as the 'bg' parameter).
166<li>
167   fadd (fixadd).
168<li>
169   fsub (fixsub).
170<li>
171   fmul (fixmul).
172<li>
173   fdiv (fixdiv).
174<li>
175   fceil (fixceil).
176<li>
177   ffloor (fixfloor).
178<li>
179   fcos (fixcos).
180<li>
181   fsin (fixsin).
182<li>
183   ftan (fixtan).
184<li>
185   facos (fixacos).
186<li>
187   fasin (fixasin).
188<li>
189   fatan (fixatan).
190<li>
191   fatan2 (fixatan2).
192<li>
193   fsqrt (fixsqrt).
194<li>
195   fhypot (fixhypot).
196<li>
197   file_size (file_size_ex)
198<li>
199   file_select (file_select_ex, passing the two constants OLD_FILESEL_WIDTH
200   and OLD_FILESEL_HEIGHT if you want the file selector to be displayed with
201   the dimensions of the old file selector).
202<li>
203   fix_filename_path (canonicalize_filename).
204<li>
205   for_each_file (for_each_file_ex).
206<li>
207   gui_textout (gui_textout_ex, passing the mode you would have passed to
208   text_mode() as the 'bg' parameter).
209<li>
210   initialise_joystick (install_joystick).
211<li>
212   joy_x (joy).
213<li>
214   joy_y (joy).
215<li>
216   joy_left (joy).
217<li>
218   joy_right (joy).
219<li>
220   joy_up (joy).
221<li>
222   joy_down (joy).
223<li>
224   joy_b1 (joy).
225<li>
226   joy_b2 (joy).
227<li>
228   joy_b3 (joy).
229<li>
230   joy_b4 (joy).
231<li>
232   joy_b5 (joy).
233<li>
234   joy_b6 (joy).
235<li>
236   joy_b7 (joy).
237<li>
238   joy_b8 (joy).
239<li>
240   joy2_x (joy).
241<li>
242   joy2_y (joy).
243<li>
244   joy2_left (joy).
245<li>
246   joy2_right (joy).
247<li>
248   joy2_up (joy).
249<li>
250   joy2_down (joy).
251<li>
252   joy2_b1 (joy).
253<li>
254   joy2_b2 (joy).
255<li>
256   joy_throttle (joy).
257<li>
258   joy_hat (joy).
259<li>
260   JOY_HAT_CENTER.
261<li>
262   JOY_HAT_CENTRE.
263<li>
264   JOY_HAT_LEFT.
265<li>
266   JOY_HAT_RIGHT.
267<li>
268   JOY_HAT_DOWN.
269<li>
270   JOY_HAT_UP.
271<li>
272   KB_EXTENDED.
273<li>
274   KB_NORMAL.
275<li>
276   SEND_MESSAGE (object_message).
277<li>
278   set_window_close_button.
279<li>
280   set_window_close_hook (set_close_button_callback).
281<li>
282   text_mode.
283<li>
284   textout (textout_ex, passing the mode you would have passed to text_mode()
285   as the 'bg' parameter).
286<li>
287   textout_centre (textout_centre_ex, passing the mode you would have passed
288   to text_mode() as the 'bg' parameter).
289<li>
290   textout_right (textout_right_ex, passing the mode you would have passed to
291   text_mode() as the 'bg' parameter).
292<li>
293   textout_justify (textout_justify_ex, passing the mode you would have
294   passed to text_mode() as the 'bg' parameter).
295<li>
296   textprintf (textprintf_ex, passing the mode you would have passed to
297   text_mode() as the 'bg' parameter).
298<li>
299   textprintf_centre (textprintf_centre_ex, passing the mode you would have
300   passed to text_mode() as the 'bg' parameter).
301<li>
302   textprintf_right (textprintf_right_ex, passing the mode you would have
303   passed to text_mode() as the 'bg' parameter).
304<li>
305   textprintf_justify (textprintf_justify_ex, passing the mode you would have
306   passed to text_mode() as the 'bg' parameter).
307<li>
308   PALLETE (PALETTE).
309<li>
310   DAT_PALLETE (DAT_PALETTE).
311<li>
312   black_pallete (black_palette).
313<li>
314   desktop_pallete (desktop_palette)
315<li>
316   get_pallete (get_palette).
317<li>
318   set_pallete (set_palette).
319<li>
320   get_pallete_range (get_palette_range)
321<li>
322   set_pallete_range (set_palette_range).
323<li>
324   fli_pallete (fli_palette).
325<li>
326   pallete_color (palette_color).
327<li>
328   select_pallete (select_palette).
329<li>
330   set_clip (set_clip_rect).
331<li>
332   unselect_pallete (unselect_palette).
333<li>
334   generate_332_pallete (generate_332_palette).
335<li>
336   generate_optimized_pallete (generate_optimized_palette).
337<li>
338   yield_timeslice (rest, passing 0 as parameter)
339<li>
340   retrace_proc (retrace_count or install_int).
341<li>
342   timer_can_simulate_retrace.
343<li>
344   timer_is_using_retrace.
345<li>
346   timer_simulate_retrace (when enable_triple_buffer is called, the mode-X
347   driver still enables retrace simulation automatically where possible).
348<li>
349   split_modex_screen.
350</ul>
351