[AD] Renamed API second draft

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

Hi.

A diff was practically half the size, so available files now are:

 http://alleg.sourceforge.net/future/allegro_renamed_api_draft_one.txt (60Kb)
 http://alleg.sourceforge.net/future/allegro_renamed_api_draft_two.txt (72Kb)

Note the text file name: most of the commends following my proposal were
not about API renaming but about API changing, which should come some
time later, so please keep those ideas safe somewhere. Now, answers to
the previous thread:

On Tue, Dec 18, 2001 at 01:08:28AM +0100, Eric Botcazou wrote:
>     al_findfirst unchanged

Done.

> - keeping an init() and an exit() function, whatever name they get:
> init() is a convenient way to avoid the complex prototype of install()
> and al_remove() is IMHO not a very evocative name for an exit function,

Yes, but al_exit_mouse is not very normal either (is the mouse
exitting from where? are you exitting from the mouse? how did you get
inside?), so I've chosen al_close_xxx for all the remove functions,
except for al_remove_display_switch_callback, where maybe it should
be left like that or renamed to al_unset_xxx, since you set it with
al_set_display_switch_callback(int dir, void (*cb)()); Or remove the
function and let the user pass NULL as cb to al_set_display_xxx.

>     win_get_window --> alwin_get_window
>     qnx_get_window --> alqnx_get_window

Done.

On Tue, Dec 18, 2001 at 12:30:58PM +0000, Laurence Withers wrote:
>  symbol_name           ->   al_symbol_name
>  _symbol_name          ->   _al_symbol_name
>  STRUCT_NAME           ->   AL_STRUCT_NAME
>  _STRUCT_NAME          ->   _AL_STRUCT_NAME

Yes, I agree. I discovered however that I have not dealt with this
problem :) My concern was about how to rename _getpixel, but it is
renamed logically to al_get_pixel_(depth). So feel free to discuss
whatever internal name format you prefer for allegro.

On Tue, Dec 18, 2001 at 10:59:50PM +0100, Sven Sandberg wrote:
> What should we do about the order of arguments to draw_sprite() & co?

Things like that should be done in a following phase. My idea about the
process is: first rename the api to sensible names, change the parameters
to something logical (easier to do once the api is renamed, otherwise I
would have included it in the first step), and finally the BIG slaughter
(ie: remove 3d/flic routines or do an even more aggressive API rename
where it needs to).

> > extern int al_multitasking_os;
> 
> Why? The other os_* variables begin (not end) with os_ so this seems
> just inconsistent.

Yep, renamed to al_os_is_multitasking.

> 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:

This is a behaviour change, so let's discuss this later. However I
can advance my opinion that replacing global variables with functions
doesn't clean up anything from the API, so it should be done only where
it doesn't affect performance, where it's logical, or where we could
see problems with reentrancy.

On Tue, Dec 18, 2001 at 06:43:51PM -0500, Bob wrote:
> What about removing draw_*_sprite and using blit() for everything? This
> would mean that blit would also hanble RLE & compiled bitmaps (which
> is more consistent). We could also add a al_blit_trans() function,
> which would be equivalent to draw_trans_sprite(), but have the extra
> clipping parameters.

That would be nice, but C can not overload functions. All of these have
the same parameters: draw_sprite, draw_trans_sprite, draw_lit_sprite,
etc, and collapsing draw_sprite, draw_rle_sprite and draw_compiled_sprite
together creates the same problem.

On Wed, Dec 19, 2001 at 11:49:37AM +1100, Peter Wang wrote:
> Also, would a separate CVS module for 5.0 be better than to branch off
> 4.0?

Hmmm... I've changed slightly my mind and now I believe it would be
bad to start another branch or module before we had decided what deep
changes are to be done with the API.

> I don't like how there are both `al_exists' and `al_file_exists'.
> (I know I said being lazy is good, but that's excessive :-)

I believe that's because al_exists was written first, and later someone
needed to check with attributes. Removed.

> I prefer `al_file_select' to `al_show_file_selector'.  It would match
> `al_gfx_mode_select' better (as it does now).

Better change both to al_select_file/gfx_mode.

> `al_gfx_mode_select' and `al_gfx_mode_select_ex' can be collapsed into
> one, by checking if the `color_depth' parameter is NULL.

Done.

Laurence Withers wrote:
> char* get_filename(char* path);
> const char* get_filename_const(const char* path);
> 
>    We have to treat `char*' and `const char*' as separate types.

I've reflected this in get_filename and get_extension. Tell me if there
are more cases like this.

Ok. Please take a look at the API with eyes on what names are "natural":
are they understood? Do they use confusing abbreviations? Do they map
easily to natural language sentences? Examples:

   al_put_text(..., al_get_filename(full_path),...);
   al_draw_polygon(..., al_make_col(255, 129, 43));

-- 
 Grzegorz Adam Hankiewicz   gradha@xxxxxxxxxx   http://gradha.infierno.org/