doomemacs/modules/ui/smooth-scroll

:ui smooth-scroll

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
• Usage
• Configuration
• Troubleshooting
  • Poor scrolling performance by scroll wheel or trackpad
  • High idle CPU usage with +interpolate
• Frequently asked questions
• Appendix

Description   unfold

This module enables multiple kinds of smooth scrolling in Emacs. Its primary function is to make input scrolling (on trackpads and scroll wheels) pixel-smooth. With the +interpolate flag, it performs interpolated scrolling on a growing list of scroll commands that traverse larger distances, smoothly scrolling from point A to B on PgUp or PgDown (or C-d/C-u for Evil users).

 This module requires Emacs 29.1 or newer.

 Scroll interpolation support is currently limited to the scroll-up and scroll-down commands, and any command that calls them (like evil-scroll-down and evil-scroll-up), so you're likely to find many scroll commands are not interpolated. We welcome PRs to expand its support.

Maintainers

• @hlissner

Become a maintainer?

Module flags

+interpolate

Enables scroll interpolation for some larger-step scrolling commands. E.g. PgUp and PgDown (or C-d/C-u for Evil users) will now smoothly scroll to its destination rather than jump to it.

Packages

• doom-package:ultra-scroll
• doom-package:good-scroll if doom-module:+interpolate

Hacks

No hacks documented for this module.

TODO Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module has no external requirements.

 For optimal performance from this module, it's highly recommended you use Emacs with native-compilation. MacOS users may also have a better experience using the emacs-mac fork of Emacs, available via Homebrew.

Usage

This module only needs to be activated to experience its benefits.

TODO Configuration

󱌣 This module has no configuration documentation yet. Write some?

Troubleshooting

Report an issue?

Poor scrolling performance by scroll wheel or trackpad

This module "smooths" input scrolling (via your trackpad or mouse wheel), and is platform agnostic, so long as your OS reports pixel-level scrolling input from your input hardware. If you run into issues, here are some things to try:

• Use M-x ultra-scroll-check to diagnose common issues. Visit ultra-scroll's documentation for more on interpreting and acting on its results.
• Read ultra-scroll's documentation on scrolling speed; it outlines common factors that may impact it and how to mitigate them.
• See Doom's "Why is Emacs/Doom slow?" write-up, where Doom's author documents common factors that can slow Emacs down in general (not specifically to do with scrolling) and what to do about them.

If all else fails, let us know on Discourse or Discord. Only file an issue if you have a good idea what's causing the problem or have an explicit error to report (performance issues, in general, tend to be the result of many factors and are the greatest source of false positives on our issue tracker).

High idle CPU usage with +interpolate

This flag will increase Emacs' idle CPU usage. Some overhead is unavoidable with how good-scroll implements scroll interpolation (with a high-rate timer), but some builds of and configurations for Emacs are affected worse than others. If this affects you, here are some ways to help:

• Use, at least, the latest stable version of Emacs. Later versions are significantly more memory and CPU efficient.
• Use native compilation. This is a tremendous boon to Emacs performance in general.
• Increase the values for good-scroll-render-rate (default: 0.02) and/or good-scroll-duration (default: 0.15). Remember to restart good-scroll-mode if you change these values live. This will decrease the package's poll rate.
• Some UI features can significantly exacerbate this issue, like line numbers. Try turning them off.
• PGTK builds seem less affected by this, and MacOS builds seem more affected. Try another build. Your mileage may vary.

If nothing helps, report it upstream. Until a workaround is found, you must decide whether this trade-off is worth it for you.

Frequently asked questions

This module has no FAQs yet. Ask one?

TODO Appendix

󱌣 This module has no appendix yet. Write one?