107 lines
3.4 KiB
Markdown
107 lines
3.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 and
|
|
moves both virtual fingers vertically. Gesture release is dynamic:
|
|
|
|
- normal and fast rotation releases after about `100ms`
|
|
- sparse precision movement can stretch release up to `1500ms`
|
|
|
|
The `100ms` minimum matches the old driver's multitouch control. The timeout is
|
|
based on the time gap between rotation events, not the raw delta size. That is
|
|
important because the Dial can emit `delta=1` even during normal fast scrolling.
|
|
If the virtual fingers are lifted too quickly during sparse movement, libinput
|
|
can treat those sparse events as many tiny gestures and ignore them. If the hold
|
|
is too long, page-edge overscroll animations can remain stretched for too long
|
|
before bouncing back.
|
|
|
|
The driver keeps the last rotation timestamp even after a virtual touch gesture
|
|
ends. This matters because sparse precision events can arrive after the 100ms
|
|
gesture has already been released. The next event still sees the previous event
|
|
gap and can stretch the new gesture timeout. A gap of `2500ms` or more is
|
|
treated as a real pause and resets back to the `100ms` minimum.
|
|
|
|
Timing is configurable:
|
|
|
|
```bash
|
|
surface-dial-renewed --mt-idle-ms 100 --mt-idle-max-ms 1500 --mt-settle-ms 80
|
|
```
|
|
|
|
`--mt-idle-ms` controls the fast-scroll minimum release timeout.
|
|
`--mt-idle-max-ms` controls the slow/precision maximum release timeout.
|
|
`--mt-settle-ms` controls the short stationary frame before the fingers lift.
|
|
|
|
## 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.
|