Skip to content

Commit

Permalink
fixup documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Alabastard-64 committed Jan 24, 2023
1 parent abf5a2b commit 4c686b6
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 18 deletions.
27 changes: 12 additions & 15 deletions docs/feature_pointing_device.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -780,7 +780,7 @@ Pointing device modes activated by toggle type functions/macros have their mode
***Notes:***
-***These modes can all be overwritten with the exception of `PM_NONE`.***
-***The mode id count starts at 0 (e.g. mode id 15 is the 16th mode) and thus mode mode ids 6-15 are free to be used without overwriting a mode (see adding custom modes below)***
-***The `PM_PRECISION` mode has additional behaviour when it is the current toggle mode, all modes will have their divisors multiplied by `POINTING_PRECISION_DIVISOR` (see adding divisors for more detail)***
-***The `PM_PRECISION` mode has additional behaviour when it is toggled, all modes activated as momentary modes will have their divisors multiplied by `POINTING_PRECISION_DIVISOR` until another mode is toggled (see adding divisors for more detail)***

#### Use In A keymap:
```c
Expand All @@ -803,7 +803,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
| `POINTING_DEVICE_MODES_FASTCALC` | (optional) Enables fast calculations for division operations limiting divisors to powers of 2 | `NA` | `None` | _Not defined_ |
| `POINTING_MODE_DEFAULT` | (optional) Default pointing device mode | `0-255` | `None` | `PM_NONE` |
| `POINTING_TAP_DELAY` | (optional) Delay between key presses in `pointing_tap_codes` in ms | `0-255` | `ms` | `0` |
| `POINTING_MODE_MAP_COUNT` | (optional) Number of modes defined in `pointing_device_mode_maps` | `0-255` | `None` | `0` |
| `POINTING_MODE_MAP_COUNT` | (optional) Number of modes defined in `pointing_device_mode_maps`(_required if using mode maps_) | `0-255` | `None` | `0` |
| `POINTING_DEFAULT_DIVISOR` | (optional) Default divisor for all modes that do not have a defined divisor | `1-255` | `Varies` | `64` |
| `POINTING_HISTORY_DIVISOR` | (optional) Accumulated stored x/y per key tap in `PM_HISTORY` mode | `1-255` | `(x\|y)/tap` | `64` |
| `POINTING_VOLUME_DIVISOR` | (optional) Accumulated stored x/y per key tap in `PM_VOLUME` mode | `1-255` | `(x\|y)/tap` | `64` |
Expand All @@ -817,10 +817,10 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
***Notes:***
1. `POINTING_DEVICE_MODES_FASTCALC` will force all divisors to powers of two but will enable fast calculation of division.
2. For processors without integer division (Atmel AVR U4 and U2 chips and ARM Cortex M0, M0+, M1, M2 chips with the exception of the RP2040 which has additional hardware for it) it is recommended that generally powers of 2 are used for divisors **(e.g. 1, 2, 4, 8, 16, 32, 64, 128*)** or using `POINTING_DEVICE_MODES_FASTCALC` as it will often optimize better, but as long as `POINTING_DEVICE_MODES_FASTCALC` is not used **any positive integer of 255 or less** will work but can be slower on chips without hardware division.
2. For processors without hardware supported integer division (Atmel AVR U4, U2, ARM Cortex M0, M0+, M1, and, M2 chips with the exception of the RP2040[M0+] which has additional hardware for it) it is recommended that generally powers of 2 are used for divisors **(e.g. 1, 2, 4, 8, 16, 32, 64, 128*)** or using `POINTING_DEVICE_MODES_FASTCALC` as it will optimize better, but as long as `POINTING_DEVICE_MODES_FASTCALC` is not used **any positive integer of 255 or less** will work but can be slower on chips without hardware division.
3. Drag scroll speed will be effected by OS mouse settings (_there are usually separate settings for scroll "wheel" and "wheel tilt"_)
- The `POINTING_DRAG_DIVISOR` default value of 8 is based on having mouse settings in the OS set to one line per tick of "mouse wheel" or "wheel tilt" (_the minimum_)
4. `POINTING_PRECISION_DIVISOR` default will half cursor speed when active (_divisor of 2_) but a divisor of 4 is fine to use as well but the cursor will be quite a bit slower, however divisors of 8 or greater will likely only work well for high cpi settings.
4. `POINTING_PRECISION_DIVISOR` default will half cursor speed when active (_divisor of 2_) but a divisor of 4 is fine to use as well but the cursor will be quite a bit slower, however divisors of 8 or greater will likely only work well for very high cpi settings.
5. Speed and sensitivity of any pointing device mode will be impacted by the pointing device CPI setting so divisors may need to be adjusted to personal preference and CPI settings typically used.
6. Recommended settings for `POINTING_CARET_DIVISOR_V` and `POINTING_CARET_DIVISOR_H` will give faster horizontal caret movement than vertical and will give even more stability to keeping movement horizontal.
Expand All @@ -839,7 +839,7 @@ const uint16_t pointing_device_mode_maps[][4] = {
<keycode down>
),
//... all other pointing mode maps ...
[<last_map_id>] = POINTING_MODE_LAYOUT(
[<POINTING_MODE_MAP_COUNT - 1>] = POINTING_MODE_LAYOUT(
<keycode up>,
<keycode left>, <keycode right>,
<keycode down>
Expand All @@ -851,8 +851,8 @@ const uint16_t pointing_device_mode_maps[][4] = {
#### Example Mode Maps:
```c
// in config.h:
#define POINTING_DEVICE_MODES_ENABLE // always needed (assumed for future example code)
#define POINTING_MODE_MAP_COUNT 4 // number of modes in map
#define POINTING_DEVICE_MODES_ENABLE // (Required)
#define POINTING_MODE_MAP_COUNT 4 // (Required) number of modes in map
// POINTING_MODE_MAP_START is left at the default value to not overwrite any modes

// in keymap.c
Expand Down Expand Up @@ -898,9 +898,6 @@ const uint16_t pointing_device_mode_maps[][4] = {
-***The modes maps start at 0 and are in the same order as the enum***
-***If mode maps and pointing mode processing callbacks are being used together to define multiple modes care must be taken to ensure that there is no overlap between mode ids (as the callbacks will override the maps) ***

**Note on overriding built in modes using pointing device mode maps:**
if `POINTING_MODE_MAP_START` is set to the `PM_VOLUME` mode id or lower then mode maps will override the built-in modes it overlaps with. Keep in mind that pointing mode maps must be consecutive so modes from `POINTING_MODE_MAP_START` to `POINTING_MODE_MAP_START + POINTING_MODE_MAP_COUNT` will be overridden.

### Adding & Customizing Divisors
All Newly added modes will use `POINTING_DEFAULT_DIVISOR` unless a divisor is defined for the modes in the `get_pointing_mode_divisor` callback functions.
For most keycode tapping modes a divisor of `64` works well, which is the default divisor for `POINTING_DEFAULT_DIVISOR`. The `get_pointing_mode_divisor_*` callbacks have two variables available, `mode_id` which is the current pointing device mode id and `direction` which indicates the primary direction of the stored accumulated h/v values with the largest magnitude (_see table below_). This makes it simple to have a unique divisor for each direction or axis for a particular mode.
Expand Down Expand Up @@ -1241,7 +1238,7 @@ bool process_pointing_mode_kb(pointing_mode_t pointing_mode, report_mouse_t* mou
#else
mouse_report->x = CONSTRAIN_XY(mouse_report->x + temp_mouse_axis);
#endif
// collect residuals
// collect residual
pointing_mode.x -= multiply_divisor_xy(temp_mouse_axis);
// add linear boost to cursor y speed
temp_mouse_axis = apply_divisor_xy(pointing_mode.y);
Expand All @@ -1250,7 +1247,7 @@ bool process_pointing_mode_kb(pointing_mode_t pointing_mode, report_mouse_t* mou
#else
mouse_report->y = CONSTRAIN_XY(mouse_report->y + apply_divisor_xy(pointing_mode.y));
#endif
// collect residuals
// collect residual
pointing_mode.y -= multiply_divisor_xy(temp_mouse_axis);
}
// update pointing_mode with residual stored x & y
Expand Down Expand Up @@ -1316,9 +1313,9 @@ If both `SPLIT_POINTING_ENABLE` and `POINTING_DEVICE_COMBINED` are defined then

#### Relevant Settings

| Define | Description | Default |
| ---------------------------------- | ----------------------------------------------------------- | -------------: |
| `POINTING_MODES_LEFT` | Set left side to default pointing device controlled side | _Not defined_ |
| Define | Description | Default |
| ---------------------------------- | ---------------------------------------------------------------------- | -------------: |
| `POINTING_MODES_LEFT` | (optional) Set left side to default pointing device controlled side | _Not defined_ |

#### Functions when using two pointing devices
These functions are only available when both `SPLIT_POINTING_ENABLE` and `POINTING_DEVICE_COMBINED` are defined and will cause a compiler error if they are not. It is recommended that code that uses them is conditional on both of these settings being defined.
Expand Down
6 changes: 3 additions & 3 deletions quantum/pointing_device/pointing_device_modes.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -273,12 +273,12 @@ static uint8_t get_pointing_mode_divisor(void) {
case PM_HISTORY:
divisor = POINTING_HISTORY_DIVISOR;
break;

case PM_VOLUME:

# ifdef EXTRAKEY_ENABLE
case PM_VOLUME:
divisor = POINTING_VOLUME_DIVISOR;
# endif
break;
# endif
}
}
return divisor_postprocess(divisor);
Expand Down

0 comments on commit 4c686b6

Please sign in to comment.