diff options
Diffstat (limited to 'docs/features')
-rw-r--r-- | docs/features/community_modules.md | 5 | ||||
-rw-r--r-- | docs/features/pointing_device.md | 26 |
2 files changed, 31 insertions, 0 deletions
diff --git a/docs/features/community_modules.md b/docs/features/community_modules.md index a28c5afaeb..52526c9fe8 100644 --- a/docs/features/community_modules.md +++ b/docs/features/community_modules.md @@ -72,6 +72,7 @@ A Community Module is denoted by a `qmk_module.json` file such as the following: { "module_name": "Hello World", "maintainer": "QMK Maintainers", + "license": "GPL-2.0-or-later", "features": { "deferred_exec": true }, @@ -86,6 +87,10 @@ A Community Module is denoted by a `qmk_module.json` file such as the following: At minimum, the module must provide the `module_name` and `maintainer` fields. +The `license` field is encouraged to indicate the terms for using and sharing the module. It is recommended to use a [SPDX license identifier](https://spdx.org/licenses/) like "`Apache-2.0`" or "`GPL-2.0-or-later`" if possible. + +The `url` field may specify a URL to more information about the module. + The use of `features` matches the definition normally provided within `keyboard.json` and `info.json`, allowing a module to signal to the build system that it has its own dependencies. In the example above, it enables the _deferred executor_ feature whenever the above module is used in a build. The `keycodes` array allows a module to provide new keycodes (as well as corresponding aliases) to a keymap. diff --git a/docs/features/pointing_device.md b/docs/features/pointing_device.md index 0ecf82c8df..a139df9dc4 100644 --- a/docs/features/pointing_device.md +++ b/docs/features/pointing_device.md @@ -419,6 +419,32 @@ The `POINTING_DEVICE_CS_PIN`, `POINTING_DEVICE_SDIO_PIN`, and `POINTING_DEVICE_S Any pointing device with a lift/contact status can integrate inertial cursor feature into its driver, controlled by `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE`. e.g. PMW3360 can use Lift_Stat from Motion register. Note that `POINTING_DEVICE_MOTION_PIN` cannot be used with this feature; continuous polling of `get_report()` is needed to generate glide reports. ::: +## High Resolution Scrolling + +| Setting | Description | Default | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------- | +| `POINTING_DEVICE_HIRES_SCROLL_ENABLE` | (Optional) Enables high resolution scrolling. | _not defined_ | +| `POINTING_DEVICE_HIRES_SCROLL_MULTIPLIER`| (Optional) Resolution mutiplier value used by high resolution scrolling. Must be between 1 and 127, inclusive. | `120` | +| `POINTING_DEVICE_HIRES_SCROLL_EXPONENT` | (Optional) Resolution exponent value used by high resolution scrolling. Must be between 0 and 127, inclusive. | `0` | + +The `POINTING_DEVICE_HIRES_SCROLL_ENABLE` setting enables smooth and continuous scrolling when using trackballs or high-end encoders as mouse wheels (as opposed to the typical stepped behavior of most mouse wheels). +This works by adding a resolution multiplier to the HID descriptor for mouse wheel reports, causing the host computer to interpret each wheel tick sent by the keyboard as a fraction of a normal wheel tick. +The resolution multiplier is set to `1 / (POINTING_DEVICE_HIRES_SCROLL_MULTIPLIER * (10 ^ POINTING_DEVICE_HIRES_SCROLL_EXPONENT))`, which is `1 / 120` by default. +If even smoother scrolling than provided by this default value is desired, first try using `#define POINTING_DEVICE_HIRES_SCROLL_EXPONENT 1` which will result in a multiplier of `1 / 1200`. + +The function `pointing_device_get_hires_scroll_resolution()` can be called to get the pre-computed resolution multiplier value as a `uint16_t`. + +::: warning +High resolution scrolling usually results in larger and/or more frequent mouse reports. This can result in overflow errors and overloading of the host computer's input buffer. +To deal with these issues, define `WHEEL_EXTENDED_REPORT` and throttle the rate at which mouse reports are sent. +::: + +::: warning +Many programs, especially those that implement their own smoothing for scrolling, don't work well when they receive simultaneous vertical and horizontal wheel inputs (e.g. from high resolution drag-scroll using a trackball). +These programs typically implement their smoothing in a way that assumes the user will only scroll in one axis at a time, resulting in slow or jittery motion when trying to scroll at an angle. +This can be addressed by snapping scrolling to one axis at a time. +::: + ## Split Keyboard Configuration The following configuration options are only available when using `SPLIT_POINTING_ENABLE` see [data sync options](split_keyboard#data-sync-options). The rotation and invert `*_RIGHT` options are only used with `POINTING_DEVICE_COMBINED`. If using `POINTING_DEVICE_LEFT` or `POINTING_DEVICE_RIGHT` use the common configuration above to configure your pointing device. |