Allegro.cc - Online Community

Allegro.cc Forums » Allegro Development » More clearly explaining acquire_bitmap, and locking in general

This thread is locked; no one can reply to it. rss feed Print
More clearly explaining acquire_bitmap, and locking in general
Thomas Harte
Member #33
April 2000
avatar

First, the preamble I feel I should attach. The following observations are based on trying to fix a bug in a program I have written and as a result trying to navigate the Allegro source - which as ever is very much less than straightforward. So if I am wrong in my reading please do not feel any need to sugarcoat a "you're wrong - function x actually does action y" type response.

To quote in full the current manual text for acquire_bitmap:

Quote:

Locks the specified video memory bitmap prior to drawing onto it. This does not apply to memory bitmaps, and only affects some platforms (Windows needs it, DOS does not). These calls are not strictly required, because the drawing routines will automatically acquire the bitmap before accessing it, but locking a DirectDraw surface is very slow, so you will get much better performance if you acquire the screen just once at the start of your main redraw function, and only release it when the drawing is completely finished. Multiple acquire calls may be nested, and the bitmap will only be truly released when the lock count returns to zero. Be warned that DirectX programs activate a mutex lock whenever a surface is locked, which prevents them from getting any input messages, so you must be sure to release all your bitmaps before using any timer, keyboard, or other non-graphics routines!

Note that if you are using hardware accelerated VRAM->VRAM blits, you should not call acquire_bitmap().

In particular I find the final sentence misleading. It strongly implies that VRAM->VRAM blits are a special case of function that does not want an acquire_bitmap. A quick investigation of wdaccel.c reveals four other functions that are slowed by preceeding calls to acquire_bitmap on an accelerated DirectX target, specifically:

  • clear_to_color

  • rectfill

  • hline

  • vline

It also fails to mention that to work around the Allegro design, these functions forcibly unacquire their acquired surfaces and do not reacquire them. So the following may appear to be "fast":

   acquire_bitmap(buffer_for_page_flipping);
   circle(buffer_for_page_flipping, ...);
   line(buffer_for_page_flipping, ...);
   putpixel(buffer_for_page_flipping, ...);
   release_bitmap(buffer_for_page_flipping);

But if modified just slightly will give the user a dramatic speed degradation for apparently the wrong reason:

   acquire_bitmap(buffer_for_page_flipping);
   clear_to_color(buffer_for_page_flipping, 0);
   circle(buffer_for_page_flipping, ...);
   line(buffer_for_page_flipping, ...);
   putpixel(buffer_for_page_flipping, ...);
   release_bitmap(buffer_for_page_flipping);

An average user if discovering the above will likely ask "why is Allegro's clear function so very slow?" when in fact it is the fastest function of the group. It also means that the statement in the manual "you will get much better performance if you acquire the screen just once at the start of your main redraw function" is false for the probably very large number of users that start their main redraw function by clearing the buffer. It also makes the text "the drawing routines will automatically acquire the bitmap before accessing it" false as some of the drawing routines will do the exact opposite.

In my individual program I found an issue with the result of bmp_write_line, although this problem was almost certainly my own. The manual isn't very clear about how long the value returned by bmp_write_line is valid for. I note that bmp_write_line includes a surface lock. I was, in a roundabout way, expecting the addresses returned by a bmp_write_line to remain valid until the surface was unlocked. I had not figured on Allegro secretly unlocking my surface in some function calls. Of course it was silly of me to think I could preserve a pointer like that, but perhaps the text of bmp_write_line/etc could be tightened up to warn about such pitfalls?

While I'm posting anyway, I am curious about the following text from the "Direct access to video memory" section:

Quote:

This still won't work in banked SVGA modes, however, or on platforms like Windows that do special processing inside the bank switching functions.

Why will that not work on Windows? Microsoft claim to be using exception handlers to make video bitmaps always appear to have linear scanlines, whereas the Allegro manual implies exactly the opposite.

Elias
Member #358
May 2000

Actually, this reminds me, I tried to rewrite the acquire_bitmap docs some time ago: http://sourceforge.net/mailarchive/message.php?msg_id=12939628

I think I didn't apply it back then because I wasn't too sure about the details, but you seem to know more.. would it be better to use the above version than the current?

--
"Either help out or stop whining" - Evert

Thomas Harte
Member #33
April 2000
avatar

Quote:

I wasn't too sure about the details, but you seem to know more..

Not really. I only checked out the DirectX specifics, and there is still the strong possibility that I've misunderstood, especially with some of the Allegro source oddities - e.g. who would have guessed that the API function fastline was implemented internally as fast_line?. I've also not yet figured out what happens after a "hidden unlock" when you enter a function that genuinely does require a lock - so with the accelerate DirectX implementation whether the example I posted above of:

   acquire_bitmap(buffer_for_page_flipping);
   clear_to_color(buffer_for_page_flipping, 0);
   circle(buffer_for_page_flipping, ...);
   line(buffer_for_page_flipping, ...);
   putpixel(buffer_for_page_flipping, ...);
   release_bitmap(buffer_for_page_flipping);

Would result in:

   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 locked
   line(buffer_for_page_flipping, ...);           // ...
   putpixel(buffer_for_page_flipping, ...);       // ...
   release_bitmap(buffer_for_page_flipping);      // bitmap is unlocked

Which would be the case if Allegro separately keeps track of whether it is pretending a bitmap is locked versus whether it actually is, or:

   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 locked and unlocked
   line(buffer_for_page_flipping, ...);           // bitmap is locked and unlocked
   putpixel(buffer_for_page_flipping, ...);       // bitmap is locked and unlocked
   release_bitmap(buffer_for_page_flipping);      // ...

Which would be the case if Allegro only keeps track of actual locks (or relies on the built-in lock count of DirectX in this driver). And I think figuring that out may require better source navigation skills than I possess. Hopefully a cleaned up documentation of the reality of acquire_bitmap would shed some light on this sort of topic.

EDIT: of course I use the ordinary DirectX "lock" and the Allegro specific "acquire" terms interchangably in the above post.

EDIT2: A simple question for the developers that would help enormously - is there anything which may be set in gfx_capabilities on any platform that is helped by first acquiring the target (video) bitmap? If not, is it safe to say that gfx_capabilities can be used as a guide to when acquiring is smart and when it isn't? If it is safe, is it sufficiently safe to add to the docs as an official part of the Allegro specification?

Elias
Member #358
May 2000

Yes, gfx_capabilities indicates if the driver does implement the specified functions using DirectX calls instead of SW drawing. It is determined during set_gfx_mode, and not changed dynamically (that is, the flags we are talking about here like HW_HLINE, e.g. HW_CURSOR apparently is a dynamic flag giving the current mouse state..).

About the locking, I was quite sure until now that each allegro function (except acquire/release and so on) would not alter the global lock state, i.e. it would restore it upon returning to whatever it was before, if it had to change it.

But then, looking at the source, it seems you are right - acquire/release_bitmap are gfx_directx_lock/unlock in src/win/wddlock.c. They simply use the BMP_ID_LOCKED field in the bitmap's "id" field to keep track of locking - but drawing functions don't care much about pairing them in any way.

I would be inclined to change this so allegro functions do not change the lock state. I.e. so your example above behaves like:

/* How I think it should be, not how it is.. */
acquire_bitmap(buffer_for_page_flipping);      // bitmap is locked
clear_to_color(buffer_for_page_flipping, 0);   // bitmap is 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

--
"Either help out or stop whining" - Evert

Neil Walker
Member #210
April 2000
avatar

Sorry to digress, but once we all start using vista what's going to happen to allegro as I guess DX3 support layer will probably be dropped and there will be no pixel based textures (or whatever the DX3 version does)

Neil.
MAME Cabinet Blog / AXL LIBRARY (a games framework) / AXL Documentation and Tutorial

wii:0356-1384-6687-2022, kart:3308-4806-6002. XBOX:chucklepie

HoHo
Member #4,534
April 2004
avatar

By then we should have a working OpenGL driver and I doubt there will be voulenteers who would port Allegro to a later DX version. Of course if there are some nobody will stop them from porting :)

__________
In theory, there is no difference between theory and practice. But, in practice, there is - Jan L.A. van de Snepscheut
MMORPG's...Many Men Online Role Playing Girls - Radagar
"Is Java REALLY slower? Does STL really bloat your exes? Find out with your friendly host, HoHo, and his benchmarking machine!" - Jakub Wasilewski

Evert
Member #794
November 2000
avatar

Quote:

Sorry to digress, but once we all start using vista what's going to happen to allegro as I guess DX3 support layer will probably be dropped and there will be no pixel based textures (or whatever the DX3 version does)

I guess it will depend on wether or not we have a dedicated Windows developer around.
Ironically, I think I've seen more people volunteer to keep the DJGPP port current than the Windows port.

Thomas Harte
Member #33
April 2000
avatar

Quote:

Yes, gfx_capabilities indicates if the driver does implement the specified functions using DirectX calls instead of SW drawing.

gfx_capabilities indicates whether the DirectX driver uses hardware for a particular function, and DirectX doesn't want things acquired - and indeed forcibly releases them - for its hardware drawing. But can the relationship between lacking hardware acceleration and requiring acquirement be abstracted cross platform? Could it be written in to the acquire_bitmap text as a general statement or would it only apply to the DirectX Windows port?

Because I'm only really bothered about Windows, where DirectX is the only current driver, and OS X where nothing is accelerated, I have written this into my code:

  if(gfx_capabilities&GFX_HW_FILL && is_video_bitmap(mytarget))
  {
    clear_bitmap(mytarget);
    acquire_bitmap(mytarget);
  }
  else
  {
    acquire_bitmap(mytarget);
    clear_bitmap(mytarget);
  }
  ... lots of software drawing stuff, completing frame ...
  release_bitmap(mytarget);

That obviously minimises acquires on both of the platforms I care about at this particular moment, but is it "proper" with respect to any arbitrary Allegro driver? Is there any sort of consistent line?

Quote:

I guess it will depend on wether or not we have a dedicated Windows developer around.
Ironically, I think I've seen more people volunteer to keep the DJGPP port current than the Windows port.

I guess the lack of a working optimised build process for MSVC turns a lot of people off. It certainly stopped me ever changing anything in the source when I was more Windows centric than I am now.

HoHo
Member #4,534
April 2004
avatar

Quote:

I guess the lack of a working optimised build process for MSVC turns a lot of people off.

ironically the main reason for not having this is probably the missing windos developer. It is a dead circle.

Anyway, there is a mingw build anyone could use on windows.

__________
In theory, there is no difference between theory and practice. But, in practice, there is - Jan L.A. van de Snepscheut
MMORPG's...Many Men Online Role Playing Girls - Radagar
"Is Java REALLY slower? Does STL really bloat your exes? Find out with your friendly host, HoHo, and his benchmarking machine!" - Jakub Wasilewski

Evert
Member #794
November 2000
avatar

The MSVC build problem should sort itself out (I hope) when the asm code is gone (which reminds me I have to check if that's already been done in the SVN version or not). Of course someone still needs to provide a way to actually build the code.

Elias
Member #358
May 2000

Quote:

gfx_capabilities indicates whether the DirectX driver uses hardware for a particular function, and DirectX doesn't want things acquired - and indeed forcibly releases them - for its hardware drawing. But can the relationship between lacking hardware acceleration and requiring acquirement be abstracted cross platform? Could it be written in to the acquire_bitmap text as a general statement or would it only apply to the DirectX Windows port?

Well, according to the source, 4 drivers provide GFX_HW_FILL: DirectX, XDGA, QNX, VBEAF. VBEAF doesn't exist anymore, i have no idea about QNX, but I'm quite sure we have no QNX users, and DGA never worked right for me and is deprecated. So we could safely specify the DirectX semantics in the documentation.

And the gfx_capabilities documentation should then also accurately list the functions which do auto-unlocking in case the respective GFX_HW_* flags are set..

--
"Either help out or stop whining" - Evert

Thomas Harte
Member #33
April 2000
avatar

Quote:

ironically the main reason for not having this is probably the missing windos developer. It is a dead circle.

Yes, clearly it isn't like anyone is sitting around saying "let's deliberately obstruct the creation of a simple MSVC build process". I guess a related problem is the several orders of magnitude of complexity that the Allegro source tree has built up since WinAllegro etc were directly integrated. Someone with historic DJGPP links is more likely to have been poking around within the source long enough to be able to follow it! Something I don't understand - why are the various VTABLEs commented with function definitions for entries that aren't filled in but completely silent on functions that do exist? I find it very annoying indeed!

Neil Walker said:

Sorry to digress, but once we all start using vista what's going to happen to allegro as I guess DX3 support layer will probably be dropped and there will be no pixel based textures (or whatever the DX3 version does)

As a follow up to this question, how is work on the new API branch going and is it and the new drivers it is presumably designed to make much easier likely to appear - even if only in beta form - close to the launch of Vista?

HoHo
Member #4,534
April 2004
avatar

Quote:

Yes, clearly it isn't like anyone is sitting around saying "let's deliberately obstruct the creation of a simple MSVC build process

Actually there is a discussion about remaking Allegro build process in AD list. So far it seems the current system will stay but there will be a scons alternative that will hopefully be much simplier to modify.

__________
In theory, there is no difference between theory and practice. But, in practice, there is - Jan L.A. van de Snepscheut
MMORPG's...Many Men Online Role Playing Girls - Radagar
"Is Java REALLY slower? Does STL really bloat your exes? Find out with your friendly host, HoHo, and his benchmarking machine!" - Jakub Wasilewski

Evert
Member #794
November 2000
avatar

Quote:

Someone with historic DJGPP links is more likely to have been poking around within the source long enough to be able to follow it!

Actually, I don't think I even looked at Allegro's sources until after I was using MinGW, maybe even after I switched to Linux.
So this has nothing to do with `historic DJGPP links'.

Quote:

Something I don't understand - why are the various VTABLEs commented with function definitions for entries that aren't filled in but completely silent on functions that do exist? I find it very annoying indeed!

The reason the empty entries are commented is so that you can identify which is which in case you want to fill in some of them (it also helps catching errors when inserting new vtable functions). For those that are filled in, then name of the filled in function should tell you what function it is.
If you want to know the function prototype, you should get that from the vtable definition instead.

To add a little background to the MSVC build problem, this is not a case of people not having tried to build one, it's a problem of Allegro's (inline) asm code not working in MSVC, so you need MinGW to compile it.

Quote:

As a follow up to this question, how is work on the new API branch going and is it and the new drivers it is presumably designed to make much easier likely to appear - even if only in beta form - close to the launch of Vista?

When's that (I don't keep up-to-date with Windows news)?
As for how it's going, I've been too busy with other things for the past couple of weeks to do much myself but it's on my (long) list of things to work on around Christmas. I think others have made some good progress with things, but I can't easily keep track since I don't seem to get the SVN commit messages anymore...

HoHo
Member #4,534
April 2004
avatar

Quote:

When's that (I don't keep up-to-date with Windows news)?

Last I heard Vista will be released in August '06 and enters shops sometimes in December. I have no ideas why the launch date and availiability dates are different.

__________
In theory, there is no difference between theory and practice. But, in practice, there is - Jan L.A. van de Snepscheut
MMORPG's...Many Men Online Role Playing Girls - Radagar
"Is Java REALLY slower? Does STL really bloat your exes? Find out with your friendly host, HoHo, and his benchmarking machine!" - Jakub Wasilewski

Thomas Harte
Member #33
April 2000
avatar

Quote:

So this has nothing to do with `historic DJGPP links'.

With all due respect, I suggest there might be a general correlation so providing exactly one counter example does not allow for the absolutely binding conclusion you reach.

Quote:

If you want to know the function prototype, you should get that from the vtable definition instead.

Which is annoying because now I have to look at two source files simultaneously instead of one. Note that I phrased this as something that I find annoying not as a balanced criticism.

Quote:

To add a little background to the MSVC build problem, this is not a case of people not having tried to build one, it's a problem of Allegro's (inline) asm code not working in MSVC, so you need MinGW to compile it.

As I understand it from GCC developer archives, Apple are attempting to provide an MSVC compatible inline assembler for GCC (obviously to make it easy to port big existing applications to the upcoming Intel OS X) so if the assembly is retained then it might make sense to switch format? Not that I can think exactly who would do this!

Quote:

When's that (I don't keep up-to-date with Windows news)?

Checking wikipedia, "general public availability is projected to be around late September to early October 2006" following a Julyish launch for PC manufacturers. That's a lot sooner than I thought, and I wouldn't have asked the question if I had realised. I appreciate that the new API is a gigantic amount of work and am certainly not expecting it in 7 months or anything close to that given the time it took to get to 4.2.0.

HoHo
Member #4,534
April 2004
avatar

Quote:

As I understand it from GCC developer archives, Apple are attempting to provide an MSVC compatible inline assembler for GCC

Is it the Intel syntax? If so then happy-happy :D
I never actually got the syntax that GCC uses atm.

Quote:

so if the assembly is retained then it might make sense to switch format?

Probably not very much because current asm is mostly slower than current C code :)

__________
In theory, there is no difference between theory and practice. But, in practice, there is - Jan L.A. van de Snepscheut
MMORPG's...Many Men Online Role Playing Girls - Radagar
"Is Java REALLY slower? Does STL really bloat your exes? Find out with your friendly host, HoHo, and his benchmarking machine!" - Jakub Wasilewski

Thomas Harte
Member #33
April 2000
avatar

Quote:

Is it the Intel syntax? If so then happy-happy

The thread is long and winding, but is here:

http://gcc.gnu.org/ml/gcc/2004-05/msg00070.html

It seems to revolve around a guy working inside Apple named Stan Shebs who at that time had already added CodeWarrior style asm to the Apple branch of GCC and was asking if that change + planned necessary modifications to support MSVC style assembly would be welcome in the main FSF distribution. The discussion then branches into a lot about whatever complexities might affect implementation. Surprisingly the thread dates from May 2004 - over 13 months before Apple announced a switch to Intel - so either the plan was already in full swing or the MSVC statements are quite speculative and just concern what incorporation of a more flexible assembler would allow.

Go to: