[AD] Rationale behind al_lock_bitmap* parameters

[Paul Suntsov <siegelords_abode@xxxxxxxxxx>]

Why does al_lock_bitmap_region and al_lock_bitmap require a ALLEGRO_LOCKED_REGION* to be passed to it? This is also puzzling as the two functions return this very region after they are done filling it out (one imagine the return type to be a void in this case). I would think it be more logical to have a persistent ALLEGRO_LOCKED_REGION that is always attached to the bitmap (I think this is the case already), rather than forcing a user to pass a new region that simply gets copied to the ALLEGRO_BITMAP's region member variable.

On a similar note, the region parameter should be optional, as the primary usage of al_lock_bitmap* is to speed up the memory functions, and not to manually alter the bitmap memory, in my mind. In such uses the current setup requires a dummy ALLEGRO_LOCKED_REGION whose only purpose is to be filled out by the function.

In my mind, the function signature should look like this for the al_lock_bitmap function:

ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap, int flags)

(analogously for the _region variety), with same call semantics, i.e. return 0 on failure. The pointer would point to the bitmap's locked region member variable. The vtable lock functions would look the same, but will fill out the bitmap's locked region member variable instead.

-SiegeLord