Re: [AD] Mouse cusor documentation

[Evert Glebbeek <eglebbk@xxxxxxxxxx>]

On Sunday 03 October 2004 15:50, Elias Pschernig wrote:
> Well, the docs aren't clear. Will this work?
> 
> show_mouse (screen);
> enable_hardware_cursor ();
> if (gfx_capabilities & GFX_HW_CURSOR) ...

Yes. From mouse.c:

/* enable_hardware_cursor:
 *  enabels the hardware cursor on platforms where this needs to be done
 *  explicitly
 */
void enable_hardware_cursor(void)
{
   if ((mouse_driver) && (mouse_driver->enable_hardware_cursor)) {
      mouse_driver->enable_hardware_cursor(TRUE);
      if (is_same_bitmap(_mouse_screen, screen)) {
         BITMAP *bmp = _mouse_screen;
         show_mouse(NULL);
         show_mouse(bmp);
      }
   }
}

> Ah, ok. So only if you pass screen to show_mouse it will use a hardware
> cursor, is this true?

Yes.

> If yes, I think it is a good idea to mention it in
> the docs.

I thought it was, and at any rate, the concept only makes sense for the 
screen bitmap.
scare_mouse() currently has
"This will temporarily get rid of the pointer, but only if that is really 
required (ie. the mouse is visible, and is displayed on the physical 
screen rather than some other memory surface, and it is not a hardware 
cursor)"
which weakly suggests that the mouse being displayed on the screen is a 
prerequisite for it possibly being a hardware cursor.
Also, the documentation for gfx_capabilities has

"GFX_HW_CURSOR:
Indicates that a hardware mouse cursor is in use. When this flag is set, it 
is safe to draw onto the screen without hiding the mouse pointer first. 
Note that not every cursor graphic can be implemented in hardware: in 
particular VBE/AF only supports 2-color images up to 32x32 in size, where 
the second color is an exact inverse of the first. This means that Allegro 
may need to switch between hardware and software cursors at any point 
during the execution of your program, so you should not assume that this 
flag will remain constant for long periods of time. It only tells you 
whether a hardware cursor is in use at the current time, and may change 
whenever you hide/redisplay the pointer."

I guess we should eliminate Allegro implicitly switching context on the 
mouse and purge the mention of VBE/AF as well (the restriction to 32x32 
bitmaps remains valid in Windows though).

> (And again, I don't like the idea of special casing screen,
> and would like this to be changed.)

I don't see how this can be helped. You can't ask the OS to draw its cursor 
onto an Allegro bitmap, afterall.

Evert