Changeset 32828 in vbox

Timestamp:

Sep 29, 2010 7:21:53 PM (14 years ago)

Author:

vboxsync

Message:

Main/Mouse: actually comment things

Location:

trunk/src/VBox/Main

Files:

• MouseImpl.cpp (modified) (17 diffs)
• include/MouseImpl.h (modified) (2 diffs)

trunk/src/VBox/Main/MouseImpl.cpp

@@ -149 +149 @@
 /////////////////////////////////////////////////////////////////////////////
 
+/** Query the VMM device for the Guest Additions's (and the host front-end's)
+ * mouse handling capabilities.
+ * @note all calls out of this object are made with no locks held! */
 HRESULT Mouse::getVMMDevMouseCaps(uint32_t *pfCaps)
 {
@@ -163 +166 @@
 }
 
+/** Report the front-end's mouse handling capabilities to the VMM device and
+ * thus to the guest.
+ * @note all calls out of this object are made with no locks held! */
 HRESULT Mouse::setVMMDevMouseCaps(uint32_t fCaps)
 {
@@ -175 +181 @@
 
 /**
- * Returns whether the current setup can accept absolute mouse
- * events.
+ * Returns whether the current setup can accept absolute mouse events, either
+ * because an emulated absolute pointing device is active or because the Guest
+ * Additions are.
  *
  * @returns COM status code
@@ -204 +211 @@
 
 /**
- * Returns whether the current setup can accept relative mouse
- * events.
+ * Returns whether the current setup can accept relative mouse events, that is,
+ * whether an emulated relative pointing device is active.
  *
  * @returns COM status code
@@ -230 +237 @@
 
 /**
- * Returns whether the guest can currently draw the mouse cursor itself.
+ * Returns whether the guest can currently switch to drawing the mouse cursor
+ * itself if it is asked to by the front-end.
  *
  * @returns COM status code
@@ -250 +258 @@
 /////////////////////////////////////////////////////////////////////////////
 
+/** Converts a bitfield containing information about mouse buttons currently
+ * held down from the format used by the front-end to the format used by PDM
+ * and the emulated pointing devices. */
 static uint32_t mouseButtonsToPDM(LONG buttonState)
 {
@@ -268 +279 @@
 
 /**
- * Send a relative event to the mouse device.
+ * Send a relative pointer event to the relative device we deem most
+ * appropriate.
  *
  * @returns   COM status code
@@ -303 +315 @@
 
 /**
- * Send an absolute position event to the mouse device.
+ * Send an absolute pointer event to the emulated absolute device we deem most
+ * appropriate.
  *
  * @returns   COM status code
@@ -340 +353 @@
 /**
  * Send an absolute position event to the VMM device.
+ * @note all calls out of this object are made with no locks held!
  *
  * @returns   COM status code
@@ -362 +376 @@
 }
 
+
+/**
+ * Send an absolute pointer event to a pointing device (the VMM device if
+ * possible or whatever emulated absolute device seems best to us if not).
+ *
+ * @returns   COM status code
+ */
 HRESULT Mouse::reportAbsEvent(uint32_t mouseXAbs, uint32_t mouseYAbs,
                               int32_t dz, int32_t dw, uint32_t fButtons,
@@ -393 +414 @@
 
 /**
- * Send a mouse event.
+ * Send a relative mouse event to the guest.
+ * @note the VMMDev capability change is so that the guest knows we are sending
+ *       real events over the PS/2 device and not dummy events to signal the
+ *       arrival of new absolute pointer data
  *
  * @returns COM status code
@@ -426 +450 @@
         fButtons = mouseButtonsToPDM(buttonState);
     }
+    /** @note we drop the lock before calling out of the object! */
     if (fUpdateCaps)
         setVMMDevMouseCaps(uHostCaps);
@@ -463 +488 @@
  * specific drivers installed in the guest or absolute pointing device
  * emulation.
+ * @note the VMMDev capability change is so that the guest knows we are sending
+ *       dummy events over the PS/2 device to signal the arrival of new
+ *       absolute pointer data, and not pointer real movement data
+ * @note all calls out of this object are made with no locks held!
  *
  * @returns COM status code
@@ -514 +543 @@
         }
     }
+    /** @note we drop the lock again before calling out! */
     if (fUpdateCaps)
         setVMMDevMouseCaps(uHostCaps);
@@ -528 +558 @@
 
 
+/** Work out what mouse capabilities the guest and the front-end have to offer,
+ * based on the state of the available emulated devices and the capabilities
+ * the guest has signalled to the VMM device, and notify the guest and the
+ * Console respectively about what the other can do. */
 void Mouse::sendMouseCapsNotifications(void)
 {
@@ -550 +584 @@
             uHostCaps &= ~VMMDEV_MOUSE_HOST_HAS_ABS_DEV;
     }
+    /** @note we drop the lock again before calling out! */
     if (SUCCEEDED(getVMMDevMouseCaps(&u32MouseCaps)))
         fVMMDevCanAbs =    (u32MouseCaps & VMMDEV_MOUSE_GUEST_CAN_ABSOLUTE)
@@ -568 +603 @@
 /**
  * @interface_method_impl{PDMIMOUSECONNECTOR,pfnReportModes}
+ * A virtual device is notifying us about its current state and capabilities
  */
 DECLCALLBACK(void) Mouse::mouseReportModes(PPDMIMOUSECONNECTOR pInterface, bool fRel, bool fAbs)

trunk/src/VBox/Main/include/MouseImpl.h

@@ -94 +94 @@
     }
 
-    // for VMMDevInterface
+    /** notify the front-end that the guest now supports absolute reporting */
     void onVMMDevCanAbsChange(bool)
     {
@@ -100 +100 @@
     }
 
+    /** notify the front-end as to whether the guest can start drawing its own
+     * cursor on demand */
     void onVMMDevNeedsHostChange(bool needsHost)
     {