Re: [AD] 4.9.20

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


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




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