mi: Add a few comments explaining various cursor move functions.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Benjamin Tissoires <tissoire@cena.fr>

1 files changed, 138 insertions, 15 deletions

diff --git a/mi/mipointer.c b/mi/mipointer.c
index 5ee456c71..a3c26d030 100644
--- a/mi/mipointer.c
+++ b/mi/mipointer.c
@@ -23,6 +23,29 @@ used in advertising or otherwise to promote the sale, use or other dealings
 in this Software without prior written authorization from The Open Group.
 */
 
+/**
+ * @file
+ * This file contains functions to move the pointer on the screen and/or
+ * restrict its movement. These functions are divided into two sets:
+ * Screen-specific functions that are used as function pointers from other
+ * parts of the server (and end up heavily wrapped by e.g. animcur and
+ * xfixes):
+ *      miPointerConstrainCursor
+ *      miPointerCursorLimits
+ *      miPointerDisplayCursor
+ *      miPointerRealizeCursor
+ *      miPointerUnrealizeCursor
+ *      miPointerSetCursorPosition
+ *      miRecolorCursor
+ *      miPointerDeviceInitialize
+ *      miPointerDeviceCleanup
+ * If wrapped, these are the last element in the wrapping chain. They may
+ * call into sprite-specific code through further function pointers though.
+ *
+ * The second type of functions are those that are directly called by the
+ * DIX, DDX and some drivers.
+ */
+
 #ifdef HAVE_DIX_CONFIG_H
 #include <dix-config.h>
 #endif
@@ -126,6 +149,12 @@ miPointerInitialize (ScreenPtr                  pScreen,
     return TRUE;
 }
 
+/**
+ * Destroy screen-specific information.
+ *
+ * @param index Screen index of the screen in screenInfo.screens[]
+ * @param pScreen The actual screen pointer
+ */
 static Bool
 miPointerCloseScreen (int index, ScreenPtr pScreen)
 {
@@ -201,6 +230,15 @@ miPointerDisplayCursor (DeviceIntPtr pDev, ScreenPtr pScreen, CursorPtr pCursor)
     return TRUE;
 }
 
+/**
+ * Set up the constraints for the given device. This function does not
+ * actually constrain the cursor but merely copies the given box to the
+ * internal constraint storage.
+ *
+ * @param pDev The device to constrain to the box
+ * @param pBox The rectangle to constrain the cursor to
+ * @param pScreen Used for copying screen confinement
+ */
 static void
 miPointerConstrainCursor (DeviceIntPtr pDev, ScreenPtr pScreen, BoxPtr pBox)
 {
@@ -212,7 +250,17 @@ miPointerConstrainCursor (DeviceIntPtr pDev, ScreenPtr pScreen, BoxPtr pBox)
     pPointer->confined = PointerConfinedToScreen(pDev);
 }
 
-/*ARGSUSED*/
+/**
+ * Should calculate the box for the given cursor, based on screen and the
+ * confinement given. But we assume that whatever box is passed in is valid
+ * anyway.
+ *
+ * @param pDev The device to calculate the cursor limits for
+ * @param pScreen The screen the confinement happens on
+ * @param pCursor The screen the confinement happens on
+ * @param pHotBox The confinement box for the cursor
+ * @param[out] pTopLeftBox The new confinement box, always *pHotBox.
+ */
 static void
 miPointerCursorLimits(DeviceIntPtr pDev, ScreenPtr pScreen, CursorPtr pCursor,
                       BoxPtr pHotBox, BoxPtr pTopLeftBox)
@@ -220,6 +268,27 @@ miPointerCursorLimits(DeviceIntPtr pDev, ScreenPtr pScreen, CursorPtr pCursor,
     *pTopLeftBox = *pHotBox;
 }
 
+/**
+ * Set the device's cursor position to the x/y position on the given screen.
+ * Generates and event if required.
+ *
+ * This function is called from:
+ *    - sprite init code to place onto initial position
+ *    - the various WarpPointer implementations (core, XI, Xinerama, dmx,…)
+ *    - during the cursor update path in CheckMotion
+ *    - in the Xinerama part of NewCurrentScreen
+ *    - when a RandR/RandR1.2 mode was applied (it may have moved the pointer, so
+ *      it's set back to the original pos)
+ *
+ * @param pDev The device to move
+ * @param pScreen The screen the device is on
+ * @param x The x coordinate in per-screen coordinates
+ * @param y The y coordinate in per-screen coordinates
+ * @param generateEvent True if the pointer movement should generate an
+ * event.
+ *
+ * @return TRUE in all cases
+ */
 static Bool
 miPointerSetCursorPosition(DeviceIntPtr pDev, ScreenPtr pScreen,
                            int x, int y, Bool generateEvent)
@@ -236,9 +305,13 @@ miPointerSetCursorPosition(DeviceIntPtr pDev, ScreenPtr pScreen,
     return TRUE;
 }
 
-/* Set up sprite information for the device.
-   This function will be called once for each device after it is initialized
-   in the DIX.
+/**
+ * Set up sprite information for the device.
+ * This function will be called once for each device after it is initialized
+ * in the DIX.
+ *
+ * @param pDev The newly created device
+ * @param pScreen The initial sprite scree.
  */
 static Bool
 miPointerDeviceInitialize(DeviceIntPtr pDev, ScreenPtr pScreen)
@@ -273,8 +346,12 @@ miPointerDeviceInitialize(DeviceIntPtr pDev, ScreenPtr pScreen)
     return TRUE;
 }
 
-/* Clean up after device.
-   This function will be called once before the device is freed in the DIX
+/**
+ * Clean up after device.
+ * This function will be called once before the device is freed in the DIX
+ *
+ * @param pDev The device to be removed from the server
+ * @param pScreen Current screen of the device
  */
 static void
 miPointerDeviceCleanup(DeviceIntPtr pDev, ScreenPtr pScreen)
@@ -290,7 +367,17 @@ miPointerDeviceCleanup(DeviceIntPtr pDev, ScreenPtr pScreen)
 }
 
 
-/* Once signals are ignored, the WarpCursor function can call this */
+/**
+ * Warp the pointer to the given position on the given screen. May generate
+ * an event, depending on whether we're coming from miPointerSetPosition.
+ *
+ * Once signals are ignored, the WarpCursor function can call this
+ *
+ * @param pDev The device to warp
+ * @param pScreen Screen to warp on
+ * @param x The x coordinate in per-screen coordinates
+ * @param y The y coordinate in per-screen coordinates
+ */
 
 void
 miPointerWarpCursor (DeviceIntPtr pDev, ScreenPtr pScreen, int x, int y)
@@ -323,16 +410,11 @@ miPointerWarpCursor (DeviceIntPtr pDev, ScreenPtr pScreen, int x, int y)
         UpdateSpriteForScreen (pDev, pScreen) ;
 }
 
-/*
- * Pointer/CursorDisplay interface routines
- */
-
-/*
- * miPointerUpdateSprite
+/**
+ * Syncronize the sprite with the cursor.
  *
- * Syncronize the sprite with the cursor - called from ProcessInputEvents
+ * @param pDev The device to sync
  */
-
 void
 miPointerUpdateSprite (DeviceIntPtr pDev)
 {
@@ -409,6 +491,14 @@ miPointerUpdateSprite (DeviceIntPtr pDev)
     }
 }
 
+/**
+ * Set the device to the coordinates on the given screen.
+ *
+ * @param pDev The device to move
+ * @param screen_no Index of the screen to move to
+ * @param x The x coordinate in per-screen coordinates
+ * @param y The y coordinate in per-screen coordinates
+ */
 void
 miPointerSetScreen(DeviceIntPtr pDev, int screen_no, int x, int y)
 {
@@ -427,12 +517,18 @@ miPointerSetScreen(DeviceIntPtr pDev, int screen_no, int x, int y)
         pPointer->limits.y2 = pScreen->height;
 }
 
+/**
+ * @return The current screen of the VCP
+ */
 ScreenPtr
 miPointerCurrentScreen (void)
 {
     return miPointerGetScreen(inputInfo.pointer);
 }
 
+/**
+ * @return The current screen of the given device or NULL.
+ */
 ScreenPtr
 miPointerGetScreen(DeviceIntPtr pDev)
 {
@@ -484,6 +580,18 @@ miPointerMoveNoEvent (DeviceIntPtr pDev, ScreenPtr pScreen,
     pPointer->pScreen = pScreen;
 }
 
+/**
+ * Set the devices' cursor position to the given x/y position.
+ *
+ * This function is called during the pointer update path in
+ * GetPointerEvents and friends (and the same in the xwin DDX).
+ *
+ * @param pDev The device to move
+ * @param[in,out] x The x coordiante in screen coordinates (in regards to total
+ * desktop size)
+ * @param[in,out] y The y coordiante in screen coordinates (in regards to total
+ * desktop size)
+ */
 void
 miPointerSetPosition(DeviceIntPtr pDev, int *x, int *y)
 {
@@ -537,6 +645,12 @@ miPointerSetPosition(DeviceIntPtr pDev, int *x, int *y)
     miPointerMoveNoEvent(pDev, pScreen, *x, *y);
 }
 
+/**
+ * Get the current position of the device in desktop coordinates.
+ *
+ * @param x Return value for the current x coordinate in desktop coordiates.
+ * @param y Return value for the current y coordinate in desktop coordiates.
+ */
 void
 miPointerGetPosition(DeviceIntPtr pDev, int *x, int *y)
 {
@@ -550,6 +664,15 @@ void darwinEvents_lock(void);
 void darwinEvents_unlock(void);
 #endif
 
+/**
+ * Move the device's pointer to the x/y coordinates on the given screen.
+ * This function generates and enqueues pointer events.
+ *
+ * @param pDev The device to move
+ * @param pScreen The screen the device is on
+ * @param x The x coordinate in per-screen coordinates
+ * @param y The y coordinate in per-screen coordinates
+ */
 void
 miPointerMove (DeviceIntPtr pDev, ScreenPtr pScreen, int x, int y)
 {