Re: [AD] Function parameter ordering conventions

["Stephen Apostolopoulos" <stapostol@xxxxxxxxxx>]

On Thu, 21 Jun 2007 09:38:14 +0300, Elias Pschernig <elias@xxxxxxxxxx>  
wrote:

> al_draw_bitmap(AL_BITMAP *bitmap, int x, int y)
> and
> al_put_pixel(int x, int y, AL_COLOR *color)

Eh, this is just asking for trouble! You want an interface to be  
consistent: a new user using al_draw_bitmap should be right to assume that  
similar functions would work roughly the same (al_put_pixel is similar  
enough, three parameter, one is a pointer). If the above syntax was used,  
he would have to make a round-trip to the manual for every single  
function, because he'd never be sure what the parameter order would be  
like - not good!

OpenGL shares some of these problems, too, with its 20 year old API, and  
this is why they are making sure no such inconsistencies exist in the new  
one (3.0).

In this case, both:

al_draw_bitmap(AL_BITMAP *bitmap, int x, int y)
al_put_pixel(AL_COLOR *color, int x, int y)
"Draw bitmap at x y"
"Put color at x y"

and

al_draw_bitmap(int x, int y, AL_BITMAP *bitmap)
al_put_pixel(int x, int y, AL_COLOR *color)
"at x y draw bitmap"
"at x y put color"

are good. I'm no Allegro dev, so my opinion has little weight, but I think  
the second one implies a (missing) dest parameter ("at x y {of what?} draw  
bitmap"), while the first one would be more suited to a state-based API.  
That said, both are fine, as long as they are consistent.

Just curious, was a state-based API actually agreed upon? Meaning  
something like:
al_set_render_target(bmp);
al_draw_bitmap(bmp2, 0, 0);  // This draws bmp2 on the bmp above.

(because I thought this had been dismissed on earlier proposals;  
off-topic, but I think OpenGL is moving away from this with the new API)


Best regards,
- Stephen A