[AD] acquire_bitmap weirdness

[Elias Pschernig <elias@xxxxxxxxxx>]

I was just trying to update a docs patch from some time ago for
acquire_bitmap, in response to the mouse freezing thread, but I'm not
sure if that is enough.. acquire_bitmap just seems really weird.

As discovered by Thomas Harte in this thread,
http://www.allegro.cc/forums/thread/554054 , some HW accelerated
functions under DirectX do release an acquired bitmap implicitly.
Therefore, the current docs are wrong, they say this:

"the bitmap will only be truly released when the lock count returns to
zero"

But apparently, the "only" there is sort of wrong.. also those HW
accelerated functions will unlock the bitmap (And the "true" release in
release_bitmap may only set the reference count to 0, but does nothing
besides that). I see some ways to deal with it:

a) Update the documentation to reflect the behavior under DirectX, and
mention that this is platform specific behavior.

b) Update the documentation like above, but make the following behavior
part of the API under all platforms: If gfx_capabilities indicates that
certain drawing functions are HW accelerated, then those functions
implicitly unlock the bitmap, and you need to re-lock it afterwards.

c) Make the behavior sane. What I mean is shown by the example code
sequence from allegro.cc:

// Behavior in 4.2.0
acquire_bitmap(buffer_for_page_flipping);      // bitmap is locked
clear_to_color(buffer_for_page_flipping, 0);   // bitmap is unlocked
circle(buffer_for_page_flipping, ...);         // bitmap is implicitly locked and unlocked
line(buffer_for_page_flipping, ...);           // bitmap is implicitly locked and unlocked
putpixel(buffer_for_page_flipping, ...);       // bitmap is implicitly locked and unlocked
release_bitmap(buffer_for_page_flipping);      // -

I would change the behavior to this:

// My proposed behavior
acquire_bitmap(buffer_for_page_flipping);      // bitmap is locked
clear_to_color(buffer_for_page_flipping, 0);   // bitmap is implicitly unlocked and locked
circle(buffer_for_page_flipping, ...);         // -
line(buffer_for_page_flipping, ...);           // -
putpixel(buffer_for_page_flipping, ...);       // -
release_bitmap(buffer_for_page_flipping);      // bitmap is unlocked

I.e., acquire_bitmap would be the *only* way to permanently lock a
bitmap, and release_bitmap would be the *only* way to permanently unlock
a bitmap.



Personally, I'd tend to go for c). I'm slightly worried about
compatibility with existing code - but in the worst case it can decrease
performance in existing code. Next best would probably be b).. since DX
is the only useful driver to advertize hw accel in gfx_capabilities, I
believe we would not need any code changes with it.

-- 
Elias Pschernig