Re: [AD] Proposal for first step towards new api

[ Thread Index | Date Index | More lists.liballeg.org/allegro-developers Archives ]


Grzegorz Adam Hankiewicz wrote:
>  http://alleg.sourceforge.net/future/allegro_new_api_draft_one.txt 

Here are some of my thoughts:

A good start, though I agree with Vincent about internals and with Eric
about `init()', `exit()' and platform specific identifiers. I also
disagree with Henrik about using `alvar_' for variables and `aldef_' for
macros (it doesn't add any useful information anyway; see also the ahack
document about hp_q_r2mzw_hungarian notation :-) Also, good idea to
prefix `line()', `arc()' & co with `draw_'.

Why do you want to remove `allegro_init()'? I think it's quite
convenient, as it's a bit confusing to have to type atexit, errno and
system_id manually (atexit and errno are kind of weird, and system_id is
always the same except in very unusual cases AFAIK). Though it needs a
new name; maybe `allegro_init()' --> `al_init()' and 
`install_allegro()' --> `al_init_ex()'?

What should we do about the order of arguments to draw_sprite() & co? It
would be good to always have source before dest IMHO. But I also think
that we should rename (not only prefix) each function that changes
behaviour, because otherwise people will do an automatic search and
replace and not understand why it doesn't work any more.

Another idea I just got is to make a distinction between `al_font_8x8'
(which is the 8x8 font that comes with Allegro and is semantically
read-only) and `al_gui_font' (which defaults to `al_font_8x8' and can be
changed if you want the gui to use another font). This can be
particularly useful for add-ons that need the 8x8 font, plus it seems
more logical.

Does `i_love_bill' still make sense? I remember we discussed this a
while ago but I don't remember if we came to any conclusion.

Is `xor_mode()' still useful? I don't mean we should remove the ability
to draw xor'ed, I mean we should force people who draw xor'ed to use
`drawing_mode()', because I think it is a too uncommon thing to do to
have a shortcut for it.

> extern int os_multitasking;
> extern int al_multitasking_os;

Why? The other os_* variables begin (not end) with os_ so this seems
just inconsistent.

Do you think we should change e.g. `int key[]' to 
`inline int al_key_is_down(int)' or something like that? It seems a bit
more logical because you shouldn't write to it and it's not _that_ time
critical. The full list (I think) of such variables would be:

  DIALOG *active_dialog --> DIALOG *al_active_dialog()
  MENU *active_menu --> AL_MENU *al_active_menu()
  char allegro_id[] --> const char *al_id()
  int cpu_capabilities --> int al_cpu_capabilities()
  int cpu_family --> int al_cpu_family()
  int cpu_model --> int al_cpu_model()
  char cpu_vendor[] --> const char *al_cpu_vendor()
  char empty_string[] --> const char *al_empty_string()
  int fli_bmp_dirty_from --> int al_fli_bmp_dirty_from()
  int fli_bmp_dirty_to --> int al_fli_bmp_dirty_to()
  int fli_frame --> int al_fli_frame()
  int fli_pal_dirty_from --> int al_fli_pal_dirty_from()
  int fli_pal_dirty_to --> int al_fli_pal_dirty_to()
  volatile int fli_timer --> int al_fli_timer()
  int gfx_capabilities --> int al_gfx_capabilities()
  MATRIX identity_matrix --> AL_MATRIX *al_get_identity_matrix()
  MATRIX_f identity_matrix_f --> AL_MATRIX_f *al_get_identity_matrix_f()
  QUAT identity_quat --> AL_QUAT *al_get_identity_quat()
  JOYSTICK_INFO joy[] --> const AL_JOYSTICK_INFO *al_joy()
  volatile char key[] --> int al_key_is_down()
  int key_shifts --> int al_key_shifts()
  int midi_pos --> int al_midi_pos()
  BITMAP *mouse_sprite --> BITMAP *al_mouse_sprite()
  int mouse_[x y z b pos] --> int al_mouse_[x y z b pos]()
  int mouse_[x y]_focus --> int al_mouse_[x y]_focus()
  int num_joystics --> int al_num_joysticks()
  int os_multitasking --> int al_os_multitasking()
  int os_type --> int al_os_type()
  int os_version --> int al_os_version()
  int os_revision --> int al_os_revision()
  volatile int retrace_count --> int al_retrace_count
  BITMAP *screen --> BITMAP *al_screen()

I'm not entirely sure about al_screen, for speed reasons.

volatile int freeze_mouse_flag --> 
  int mouse_is_frozen() + void freeze_mouse() + void unfreeze_mouse()

Given the nasty situation described in the documentation about
midi_loop_start and midi_loop_end, should we also do
  long al_midi_loop_start()
  long al_midi_loop_end()
  void set_midi_loop_range(long start, long end)
?
  
I kept palette_color[] for speed reasons, some PALETTES because it is
awkward to return them, and other variables because they are
semantically read/writable.

I also think it can be good to wait a little more to actually implement
everything, until 4.0 feels more stable, so that we reduce the number of
bugfixes that need to be applied to both prefixed and non-prefixed
versions. Sure, it will be a nice improvement, but if we lived with the
old API for years it can't hurt to keep it a month or so more. It's not
like it seems likely that people are going to forget about it :-) But
it's of course still a good idea to discuss it.

Whoah, this became much longer than I thought, I'd better stop now.

-- 
Sven Sandberg    svsa1977@xxxxxxxxxx    home.student.uu.se/svsa1977



Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/