4

Where is mouse cursor movement acceleration and scroll wheel acceleration implemented in MacOSX?

On the API level, Core Graphics / Quartz Event Services provides the CGEvent type.

On the application side, there are many relevant and interesting comments at this Chrome change review, and extracted from there this comment:

// Of Mice and Men
// ---------------
//
// There are three types of scroll data available on a scroll wheel CGEvent.
// Apple's documentation ([1]) is rather vague in their differences, and not
// terribly helpful in deciding which to use. This is what's really going on.
//
// First, these events behave very differently depending on whether a standard
// wheel mouse is used (one that scrolls in discrete units) or a
// trackpad/Mighty Mouse is used (which both provide continuous scrolling).
// You must check to see which was used for the event by testing the
// kCGScrollWheelEventIsContinuous field.
//
// Second, these events refer to "axes". Axis 1 is the y-axis, and axis 2 is
// the x-axis.
//
// Third, there is a concept of mouse acceleration. Scrolling the same amount
// of physical distance will give you different results logically depending on
// whether you scrolled a little at a time or in one continuous motion. Some
// fields account for this while others do not.
//
// Fourth, for trackpads there is a concept of chunkiness. When scrolling
// continuously, events can be delivered in chunks. That is to say, lots of
// scroll events with delta 0 will be delivered, and every so often an event
// with a non-zero delta will be delivered, containing the accumulated deltas
// from all the intermediate moves. [2]
//
// For notchy wheel mice (kCGScrollWheelEventIsContinuous == 0)
// ------------------------------------------------------------
//
// kCGScrollWheelEventDeltaAxis*
//   This is the rawest of raw events. For each mouse notch you get a value of
//   +1/-1. This does not take acceleration into account and thus is less
//   useful for building UIs.
//
// kCGScrollWheelEventPointDeltaAxis*
//   This is smarter. In general, for each mouse notch you get a value of
//   +1/-1, but this _does_ take acceleration into account, so you will get
//   larger values on longer scrolls. This field would be ideal for building
//   UIs except for one nasty bug: when the shift key is pressed, this set of
//   fields fails to move the value into the axis2 field (the other two types
//   of data do). This wouldn't be so bad except for the fact that while the
//   number of axes is used in the creation of a CGScrollWheelEvent, there is
//   no way to get that information out of the event once created.
//
// kCGScrollWheelEventFixedPtDeltaAxis*
//   This is a fixed value, and for each mouse notch you get a value of
//   +0.1/-0.1 (but, like above, scaled appropriately for acceleration). This
//   value takes acceleration into account, and in fact is identical to the
//   results you get from -[NSEvent delta*]. (That is, if you linked on Tiger
//   or greater; see [2] for details.)
//
// A note about continuous devices
// -------------------------------
//
// There are two devices that provide continuous scrolling events (trackpads
// and Mighty Mouses) and they behave rather differently. The Mighty Mouse
// behaves a lot like a regular mouse. There is no chunking, and the
// FixedPtDelta values are the PointDelta values multiplied by 0.1. With the
// trackpad, though, there is chunking. While the FixedPtDelta values are
// reasonable (they occur about every fifth event but have values five times
// larger than usual) the Delta values are unreasonable. They don't appear to
// accumulate properly.
//
// For continuous devices (kCGScrollWheelEventIsContinuous != 0)
// -------------------------------------------------------------
//
// kCGScrollWheelEventDeltaAxis*
//   This provides values with no acceleration. With a trackpad, these values
//   are chunked but each non-zero value does not appear to be cumulative.
//   This seems to be a bug.
//
// kCGScrollWheelEventPointDeltaAxis*
//   This provides values with acceleration. With a trackpad, these values are
//   not chunked and are highly accurate.
//
// kCGScrollWheelEventFixedPtDeltaAxis*
//   This provides values with acceleration. With a trackpad, these values are
//   chunked but unlike Delta events are properly cumulative.
//
// Summary
// -------
//
// In general the best approach to take is: determine if the event is
// continuous. If it is not, then use the FixedPtDelta events (or just stick
// with Cocoa events). They provide both acceleration and proper horizontal
// scrolling. If the event is continuous, then doing pixel scrolling with the
// PointDelta is the way to go. In general, avoid the Delta events. They're
// the oldest (dating back to 10.4, before CGEvents were public) but they lack
// acceleration and precision, making them useful only in specific edge cases.
//
// References
// ----------
//
// [1] <http://developer.apple.com/documentation/Carbon/Reference/QuartzEventServicesRef/Reference/reference.html>
// [2] <http://developer.apple.com/releasenotes/Cocoa/AppKitOlderNotes.html>
//     Scroll to the section headed "NSScrollWheel events".
//
// P.S. The "smooth scrolling" option in the system preferences is utterly
// unrelated to any of this.

On the kernel level, I/O Kit is the basic driver interface, and I guess the mouse is of the HID (Human Interface Devices) family (IOHIDFamily). The XNU kernel source can be seen here but I'm not sure if that is complete because I don't find a single match when I search for IOHIDFamily. The code might be here at IOHIDFamily. Actually I found in IOHIPointing.cpp the comment:

/*
 * 17 July  1998    sdouglas    Initial creation
 * 01 April     2002    ryepez      added support for scroll acceleration
 */

And from the code, it looks like it's implemented there. Can someone confirm? Also see here.

How does the logic in IOHIPointing get finally to the CGEvent? Is that all part of Core Graphics / Quartz? What is in between? Are that some kind of Mach events? Is there any good overview about the generic architecture?

Note that I was wondering about this question because of an ongoing discussion where to implement mouse scroll wheel acceleration in Linux / Xorg / libinput here.

1 Answer 1

3

Good, question - and a big one at that. I should note that I don't have full information - as you've discovered, a lot of this is closed source. As far as I've been able to tell, these are the important points:

  • The mouse settings (tracking speed, scrolling speed, etc.) you see in System Preferences for a generic, non-Apple mouse are all handled inside WindowServer - where the CGEvents originate. There is some massaging of HID reports going on in IOHIDPointing etc. but from what I've seen this is mostly for maintaining compatibility with quirky devices.
  • Update: (see discussion in comments) It looks like WindowServer probably passes the acceleration parameters down to the kernel driver by setting properties on its IORegistry entry.
  • I believe the momentum scrolling for Apple touch devices (trackpads, magic mouse) may actually at least partially be implemented in their respective closed source kernel drivers, such as AppleMultitouchTrackpadHIDEventDriver.
  • The source code for the lower level userspace side of the HID stack is available in the IOKitUser source bundle. This includes the IOHIDManager and so on.
  • The journey from device to CGEvent is roughly: Device -> IOHIDDevice -> IOHIDInterface -> IOHIDEventDriver -> [IOHIDevice] -> IOHIDSystem -> IOHIDUserClient -> IOKit kernel-user communications mechanism (uses Mach Ports internally) -> HID parts of IOKitUser -> WindowServer (Core Graphics).
  • You can bypass this path from a userspace process by directly connecting to an IOHIDDevice via a IOHIDLibUserClient.

The IOKitUser source might answer some of your questions in more detail. Or if you're trying to do something specific, open a new question for that.

2
  • Thanks a lot for the detailed answer! I looked a bit through the IOKitUser code (here) and I just found some IOHIDSetScrollAcceleration/IOHIDSetMouseAcceleration and related functions (see also), so I guess IOKitUser does not have any logic for this but IOHIPointing does. Maybe the multitouch-driver and the WindowServer do as well.
    – Albert
    Commented May 26, 2017 at 9:23
  • @Albert interesting, looks like those functions call down to setting properties on the IO Registry object, so yes, looks like it happens in-kernel after all.
    – pmdj
    Commented May 26, 2017 at 9:50

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.