86 lines
2.4 KiB
Markdown
86 lines
2.4 KiB
Markdown
# Driver Behavior
|
|
|
|
## Default Mode
|
|
|
|
The default mode is multitouch scrolling. Run explicitly with:
|
|
|
|
```bash
|
|
surface-dial-renewed --mode multitouch
|
|
```
|
|
|
|
Regular wheel mode exists for fallback/testing:
|
|
|
|
```bash
|
|
surface-dial-renewed --mode wheel
|
|
```
|
|
|
|
## Normal Rotation
|
|
|
|
Normal Dial rotation emits a synthetic two-finger touchpad scroll through
|
|
`Surface Dial Renewed Touchpad`.
|
|
|
|
The driver starts a virtual two-finger contact on the first rotation event,
|
|
moves both virtual fingers vertically, and ends the touch gesture after no
|
|
rotation has arrived for 2 seconds.
|
|
|
|
The 2 second hold is intentional. Very slow physical Dial movement can emit
|
|
sparse `REL_DIAL` events. If the virtual fingers are lifted too quickly, libinput
|
|
can treat those sparse movements as many tiny gestures and ignore them. Holding
|
|
the contact makes slow and precise movement accumulate into one gesture.
|
|
|
|
## Sensitivity Selector
|
|
|
|
Hold the Dial down and rotate to change sensitivity.
|
|
|
|
- Range: `1/32` through `32/32`
|
|
- Default: `7/32`
|
|
- Step threshold: `48` raw Dial units per sensitivity level
|
|
- Display: KDE OSD text, falling back to notification
|
|
- Haptics: one buzz when entering the selector, one buzz per accepted level
|
|
|
|
While the button is held, rotation never scrolls. If a multitouch scroll gesture
|
|
is active when the button is pressed, it is ended before sensitivity adjustment.
|
|
|
|
## Sensitivity Scaling
|
|
|
|
The sensitivity level maps to milli-pixels per raw Dial unit:
|
|
|
|
```text
|
|
500 + (level - 1) * 250
|
|
```
|
|
|
|
This means level 1 is `0.5` virtual coordinate units per raw Dial unit, level 7
|
|
is `2.0`, and level 32 is `8.25`.
|
|
|
|
The driver stores fractional remainders while a gesture is active. A nonzero raw
|
|
Dial event is rounded away from zero if it would otherwise produce no integer
|
|
coordinate movement.
|
|
|
|
## Haptics
|
|
|
|
Haptics are deliberately limited:
|
|
|
|
- Enter sensitivity selector: buzz once.
|
|
- Change sensitivity level: buzz once.
|
|
|
|
Normal scrolling does not buzz. It was tested and removed because it was
|
|
distracting and hard to align with physical rotation consistently.
|
|
|
|
## OSD
|
|
|
|
On KDE, the driver calls:
|
|
|
|
```text
|
|
org.kde.plasmashell /org/kde/osdService org.kde.osdService.showText
|
|
```
|
|
|
|
The displayed text is:
|
|
|
|
```text
|
|
Surface Dial sensitivity N/32
|
|
```
|
|
|
|
KDE exposes polished volume/brightness OSD methods, but those are semantically
|
|
volume/brightness-specific. The generic custom progress API is not callable as a
|
|
normal method on this system, so the driver uses text OSD instead.
|