Re: [AD] 4.9.20

[Pavel Sountsov <slabode@xxxxxxxxxx>]

> Just remembered something we discussed in #allegro some time ago - 
there's a bit of an API ambiguity with transformation order:
> al_identity_transform(t);
> al_translate_transform(t, 100, 0);
> al_rotate_transform(t, deg2rad(90));
> al_use_transform(t);
> al_draw_pixel(100, 0, red);
>
> Someone who did not use any other libraries before Allegro might 
expect something like this:

Direct3D does it that way too. Also, it follows the order of function 
calls. There is a call to translate, then a call to rotate. The point 
gets translated first, and then rotated. It couldn't be simpler to 
understand.

> The pixel is drawn at 100/0, but first gets translated to 200/0, then 
gets rotated to 0/200.
> Everyone else probably will expect that the pixel first gets rotated 
to 0/100 and is then translated to 100/100. It's also what makes more 
sense usually. For example:
> draw_ship() {
>    *backup = *t;
>    al_translate_transform(t, ship.x, ship.y);
>    al_rotate_transform(t, ship.angle);
>    al_use_transform(t);
>    al_draw_triangle(...);
>    *t = *backup;
> }
>
> draw_scene() {
>    al_translate_transform(t, cam.x, cam.y);
>    al_rotate_transform(t, cam.angle);
>    draw_ship();
> }

And here's the way it works with the current functions:

draw_ship(ALLEGRO_TRANSFORM camera_t) {
  ALLEGRO_TRANSFORM t;
  al_identity_transform(&t);
  al_rotate_transform(&t, ship.angle);
  al_translate_transform(&t, ship.x, ship.y);
  al_transform_transform(&camera_t, &t);
  al_use_transform(&t);
  al_draw_triangle(...);
}

draw_scene() {
  ALLEGRO_TRANSFORM t;
  al_identity_transform(&t);
  al_rotate_transform(&t, cam.angle);
  al_translate_transform(&t, cam.x, cam.y);
  draw_ship(t);
}

Pretty much the same.

> So I think best will be to rename the functions:
>
> al_translate_transform -> al_pre_translate_transform
> al_rotate_transform -> al_pre_rotate_transform
> al_scale_transform -> al_pre_scale_transform
> al_transform_transform -> al_pre_transform_transform
>
> This makes clear that whatever transformation is applied to the 
passed transformation will be done *before* the existing transformation.

This is just a matter of documenting it. And again, the order the 
transformations are applied follows the order the functions are called, 
I think the prefix would only be a source of confusion.

> And maybe we can also have the _post_ versions.

-SiegeLord