Re: [AD] X hardware cursors fix

[Elias Pschernig <elias@xxxxxxxxxx>]

On Mon, 2005-03-28 at 14:38 +0200, Evert Glebbeek wrote:

> I have commited the patch, in hope that it doesn't break what work Elias is 
> doing on this at the moment.
> I'll wait with the example program until it is more complete or Elias' 
> proposed changes come through.
> 

Well, there's probably no need to have an example of show_os_cursor at
all, it should be quite self-explanatory. I attached another version of
my initial patch, this time taking a much simpler route - I just labeled
it a low level function, which is not to be used together with the other
API. Yes, I'm lazy.

But actually, there's nothing to be gained by figuring out what's the
best thing to do if they are mixed in certain ways, and setting various
internal variables and flags - the function works and is useful, but the
preferred way should be the normal show_mouse API (which just currently
is not generally useful due to the asynchronous drawing from a timer
thread, agnostic of the current update method used by the program).

-- 
Elias Pschernig

Index: src/mouse.c
===================================================================
RCS file: /cvsroot/alleg/allegro/src/mouse.c,v
retrieving revision 1.34
diff -u -p -r1.34 mouse.c
--- src/mouse.c	17 Mar 2005 07:27:52 -0000	1.34
+++ src/mouse.c	28 Mar 2005 19:31:47 -0000
@@ -520,6 +520,56 @@ void set_mouse_sprite_focus(int x, int y
 
 
 
+/* show_os_cursor:
+ *  Tries to display the OS cursor. Returns 0 if a cursor is displayed after the
+ *  function returns, else -1. This is similar to calling show_mouse(screen)
+ *  after calling enable_hardware_cursor and checking gfx_capabilities for
+ *  GFX_HW_CURSOR, but is easier to use in cases where you don't need Allegro's
+ *  software cursor even if no os cursor is available.
+ */
+int show_os_cursor(int cursor)
+{
+   if (!mouse_driver)
+      return -1;
+
+   if (cursor != MOUSE_CURSOR_NONE) {
+
+      if (mouse_driver->enable_hardware_cursor) {
+         mouse_driver->enable_hardware_cursor(TRUE);
+      }
+
+      /* default system cursor? */
+      if (cursor != MOUSE_CURSOR_ALLEGRO) {
+         if (mouse_driver->select_system_cursor) {
+            return !mouse_driver->select_system_cursor(cursor);
+         }
+         return -1;
+      }
+      else {
+         /* set custom hardware cursor */
+         if (gfx_driver) {
+            if (gfx_driver->set_mouse_sprite) {
+               if (gfx_driver->set_mouse_sprite(mouse_sprite, mouse_x_focus, mouse_y_focus))
+                  return -1;
+            }
+            if (gfx_driver->show_mouse) {
+               if (gfx_driver->show_mouse(screen, mouse_x, mouse_y))
+                  return -1;
+            }
+            return 0;
+         }
+      }
+   }
+   else {
+      if (gfx_driver && gfx_driver->hide_mouse)
+         gfx_driver->hide_mouse();
+   }
+
+   return -1;
+}
+
+
+
 /* show_mouse:
  *  Tells Allegro to display a mouse pointer. This only works when the timer 
  *  module is active. The mouse pointer will be drawn onto the bitmap bmp, 
Index: include/allegro/mouse.h
===================================================================
RCS file: /cvsroot/alleg/allegro/include/allegro/mouse.h,v
retrieving revision 1.6
diff -u -p -r1.6 mouse.h
--- include/allegro/mouse.h	7 Mar 2005 22:55:22 -0000	1.6
+++ include/allegro/mouse.h	28 Mar 2005 19:31:47 -0000
@@ -107,6 +107,7 @@ AL_FUNC(void, set_mouse_cursor_bitmap, (
 AL_FUNC(void, set_mouse_sprite_focus, (int x, int y));
 AL_FUNC(void, get_mouse_mickeys, (int *mickeyx, int *mickeyy));
 AL_FUNC(void, set_mouse_sprite, (struct BITMAP *sprite));
+AL_FUNC(int, show_os_cursor, (int cursor));
 #ifdef __cplusplus
    }
 #endif
Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.309
diff -u -p -r1.309 allegro._tx
--- docs/src/allegro._tx	22 Mar 2005 20:23:29 -0000	1.309
+++ docs/src/allegro._tx	28 Mar 2005 19:32:31 -0000
@@ -2406,19 +2406,21 @@ Standard Allegro cursor<br>
 <li>
 Custom operating system cursor (hardware cursor)<br>
    Allegro will let the operating system draw the mouse cursor. Use
-   set_mouse_sprite() and show_mouse() to define your own cursor and display
-   it on the screen. Not all graphics drivers are capable of this and some
-   may only be able to display cursors upto a certain size. Allegro will fall
-   back on its own cursor drawing if it cannot let the OS handle this. On some
-   platforms, the hardware cursor is incompatible with get_mouse_mickeys()
-   and it is therefor disabled by default. In such cases you need to call
-   enable_hardware_cursor() to enable it explicitly.
+   set_mouse_sprite() and show_mouse() (or show_os_cursor) to define your
+   own cursor and display it on the screen. Not all graphics drivers are
+   capable of this and some may only be able to display cursors upto a
+   certain size. Allegro will fall back on its own cursor drawing if it
+   cannot let the OS handle this. On some platforms, the hardware cursor
+   is incompatible with get_mouse_mickeys() and it is therefor disabled by
+   default. In such cases you need to call enable_hardware_cursor() to
+   enable it explicitly.
 <li>
 Default operating system cursor<br>
    Allegro will not draw its own cursor, but use the operating system default
    cursor. You can use the select_mouse_cursor() function to select the cursor
    shape to display. As with custom operating system cursors, you need to call 
-   enable_hardware_cursor() before you can use this.
+   enable_hardware_cursor() before you can use this. Or you can use the
+   low level show_os_cursor() function.
 </ul>
 Not all drivers will support all functionality. See the platform specific
 information for more details.
@@ -2476,7 +2478,7 @@ information for more details.
 
 @@void @enable_hardware_cursor(void);
 @xref install_mouse, show_mouse, set_mouse_sprite, get_mouse_mickeys
-@domain.hid gfx_capabilities, disable_hardware_cursor
+@xref gfx_capabilities, disable_hardware_cursor, show_os_cursor
 @shortdesc Enables the OS hardware cursor.
    After calling this function, Allegro will let the operating system draw the
    mouse cursor instead of doing it itself. This is not possible with all
@@ -2498,7 +2500,7 @@ information for more details.
 
 @@void @select_mouse_cursor(int cursor);
 @xref install_mouse, show_mouse, set_mouse_sprite, gfx_capabilities
-@domain.hid enable_hardware_cursor, set_mouse_cursor_bitmap
+@xref enable_hardware_cursor, set_mouse_cursor_bitmap, show_os_cursor
 @shortdesc Tells Allegro to select software or hardware cursor drawing.
    This function allows you to use the operating system's native mouse
    cursors rather than some custom cursor. You will need to enable this
@@ -2555,7 +2557,7 @@ information for more details.
 
 @@void @set_mouse_cursor_bitmap(int cursor, BITMAP *bmp);
 @xref install_mouse, show_mouse, set_mouse_sprite, gfx_capabilities
-@domain.hid enable_hardware_cursor
+@xref enable_hardware_cursor, show_os_cursor
 @shortdesc Changes the image Allegro uses for mouse cursors.
    This function changes the cursor image Allegro uses if
    select_mouse_cursor() is called but no native operating system cursor
@@ -2631,7 +2633,7 @@ information for more details.
 
 @@void @show_mouse(BITMAP *bmp);
 @xref install_mouse, install_timer, set_mouse_sprite, scare_mouse
-@domain.hid freeze_mouse_flag
+@xref freeze_mouse_flag, show_os_cursor
 @eref exmouse, expal, exshade, exspline
 @shortdesc Tells Allegro to display a mouse pointer on the screen.
    Tells Allegro to display a mouse pointer on the screen. This will only 
@@ -2671,6 +2673,34 @@ information for more details.
    Undoes the effect of a previous call to scare_mouse() or 
    scare_mouse_area(), restoring the original pointer state.
 
+@@int @show_os_cursor(int cursor);
+@xref show_mouse, set_mouse_cursor_bitmap, select_mouse_cursor
+@shortdesc Low level function to display the operating system cursor.
+   In case you do not need Allegro's mouse cursor API, which automatically
+   emulates a cursor in software if no other cursor is available, you can
+   use this low level function to try to display or hide the system cursor
+   directly. The cursor parameter takes the same values as
+   select_mouse_cursor. This function is very similar to calling
+   enable_hardware_cursor, select_mouse_cursor and show_mouse, but will
+   not try to do anything if no system cursor is available.
+
+   The most common use for this function is to just call it once at the
+   beginning of the program to tell it to display the system cursor inside
+   the Alllegro window. The return value can be used to see if this
+   suceeded or not. On some systems (e.g. DirectX fullscreen) this is not
+   supported and the function will always fail, and in other cases only
+   some of the cursors will work, or in the case of MOUSE_CURSOR_ALLEGRO,
+   only certain bitmap sizes may be supported.
+
+   You never should use show_os_cursor together with the function
+   show_mouse and other functions affecting it (select_mouse_cursor,
+   enable_hardware_cursor, disable_hardware_cursor, scare_mouse,
+   unscare_mouse). They implement the standard high level mouse API, and
+   don't work together with this low level function.
+@retval
+   Returns 0 if a system cursor is being displayed after the function
+   returns, or -1 otherwise.
+
 @@extern volatile int @freeze_mouse_flag;
 @xref show_mouse
 @shortdesc Flag to avoid redrawing the mouse pointer.