K-Lapse : A kernel level livedisplay module
Intro - What is K-Lapse?
Kernel-based Lapse ("K-Lapse") is a linear RGB scaling module that 'shifts' RGB based on time (of the day/selected by the user), or (since v2.0) brightness. This concept is inspired by LineageOS (formerly known as 'CyanogenMod') ROM's feature "Livedisplay" which also changes the display settings (RGB, hue, temperature, etc) based on time. This is very very similar to f.lux for desktop too.
Why did I decide to make this? (A short story)
I (personally) am a big fan of the Livedisplay feature found on LineageOS. I used it every single day, since Android Lollipop. Starting from Android Nougat, a native night mode solution was added to AOSP and it felt like Livedisplay was still way superior, thanks to its various options (you could say it spoiled me, sure). I also maintained a kernel (Venom kernel) for the device I was using at that time. It was all good until the OEM dropped support for the device at Android M, and XDA being XDA, was already working on N ROMs. The issue was, these ROMs weren't LineageOS or based on it, so Livedisplay was... gone. I decided I'll try to bring that feature to every other ROM. How would I do that? Of course! The kernel! It worked on every single ROM, it was the key! I started to work on it ASAP and here it is, up on GitHub, licensed under GPL (check klapse.c), open to everyone
How does it work?
Think of it like a fancy night mode, but not really. Klapse is dependent on an RGB interface (like Gamma on MTK and KCAL on SD chipsets). In mode 1, it fetches time from the kernel, converts it to local time, and selects and RGB set based on the time. The result is really smooth shifting of RGB over time. Mode 2 uses the current brightness level to scale RGB, with the concept behind it being that lower brightness usually implies a dark environment, so a slight color temperature shift should help with eye strain.
There's also an option for a "brightness factor" that can reduce your brightness down to 80% below the minimum brightness that your phone allows. The catch is, it doesn't actually reduce the brightness, but rather uses a clever trick to fade away the RGB of the screen by the same amount so it "appears" to be lower brightness.
How does it really work (dev)?
Klapse mode 1 (time-based scaling) uses a method void klapse_pulse(unsigned long data) that should ideally be called every minute. This is done using a kernel timer, that is asynchronous so it should be handled with care, which I did. The pulse function fetches the current time and makes calculations based on the current hour and the values of the tunables listed down below.
Klapse mode 2 (brightness-based scaling) uses a method void set_rgb_slider(<type> bl_lvl) where type is the data type of the brightness level used in your kernel source. (OnePlus 6 uses u32 data type for bl_lvl) set_rgb_slider needs to be called/injected inside a function that sets brightness for your device. (OnePlus 6 uses dsi_panel.c for that, check out the diff for that file in op6 branch)
What all stuff can it do?
- Emulate night mode with the proper RGB settings
- Smoothly scale from one set of RGB to another set of RGB in integral intervals over time.
- Reduce perceived brightness using brightness_factor by reducing the amount of color on screen. Allows lower apparent brightness than system permits.
- Scale RGB based on brightness of display (low brightness usually implies a dark environment, where yellowness is probably useful).
- Automate the perceived brightness independent of whether klapse is enabled, using its own set of start and stop hours.
- Theoretically more efficient, faster by residing inside the kernel instead of having to use the HWC HAL like android's night mode. This is unproven and probably has no practical significance.
- (On older devices) Reduce stuttering or frame lags caused by native night mode.
- An easier solution against overlay-based apps that run as service in userspace/Android and sometimes block apps asking for permissions.
- Give you a Livedisplay alternative if it doesn't work in your ROM.
- Impress your crush so you can get a date (Hey, don't forget to credit me if it works).
Alright, so this is a replacement for night mode?
NO! Kinda, but no. Lemme explain. One can say this is an alternative for LineageOS' Livedisplay, but inside a kernel. Night mode is a sub-function of both Livedisplay and KLapse. Most comparisons here were made with night mode because that's what an average user uses, and will relate to the most. There is absolutely no reason for your Android kernel to not have KLapse. Go ahead and add it or ask your kernel maintainer to. It's super-easy!
What can it NOT do (yet)?
- Calculate scaling to the level of minutes, like "Start from 5:37pm till 7:19am". --TODO
- Make coffee for you.
- Fly you to the moon.
- Get you a monthly subscription of free food, cereal and milk included.
I want more! Tell me what can I customize!
All these following tunables are found in their respective files in /sys/klapse/
1. enable_klapse : A switch to enable or disable klapse. Values : 0 = off, 1 = on (since v2.0, 2 = brightness-dependent mode) 2. klapse_start_hour : The hour at which klapse should start scaling the RGB values from daytime to target (see next points). Values : 0-23 3. klapse_stop_hour : The hour by which klapse should scale back the RGB values from target to daytime (see next points). Values : 0-23 4. daytime_r,g,b : The RGB set that must be used for all the time outside of start and stop hour range. 5. target_r,g,b : The RGB set that must be scaled towards for all the time inside of start and stop hour range. 6. klapse_scaling_rate : Controls how soon the RGB reaches from daytime to target inside of start and stop hour range. Once target is reached, it remains constant till fadeback_minutes (#13) before stop hour, where target RGB scales back to daytime RGB. (Pre-v4.2 value was a factor, now it is a minute value) 7. brightness_factor : From the name itself, this value has the ability to bend perception and make your display appear as if it is at a lesser brightness level than it actually is at. It works by reducing the RGB values by the same factor. Values : 2-10, (10 means accurate brightness, 5 means 50% of current brightness, you get it) 8. brightness_factor_auto : A switch that allows you to automatically set the brightness factor in a set time range. Value : 0 = off, 1 = on 9. brightness_factor_auto_start_hour : The hour at which brightness_factor should be applied. Works only if #8 is 1. Values : 0-23 10. brightness_factor_auto_stop_hour : The hour at which brightness_factor should be reverted to 10. Works only if #8 is 1. Values : 0-23 11. backlight_range : The brightness range within which klapse should scale from daytime to target_rgb. Works only if #1 is 2. Values : MIN_BRIGHTNESS-MAX_BRIGHTNESS 12. pulse_freq : The amount of milliseconds after which klapse_pulse is called. A more developer-targeted tunable. Only works when one or both of #1 and #8 are 1. Values : 1000-600000 (Represents 1sec to 10 minutes) 13. fadeback_minutes : The number of minutes before klapse_stop_hour when RGB should start going back to daytime_rgb. Only works when #1 is 1. Values : 0-minutes between #2 and #3
Fortunately, as per practical testing there is absolutely no negative effect on performance or battery backup!
"I'm a kernel maintainer. How do I add it to my source?"
Note : I'm currently maintaining klapse for OnePlus6 (enchilada), using the snapshot branch.
The klapse.c file is pretty much generic, but depending on your device you may need to change some of the #define values
The klapse.h file should be edited in order to make the K_RED etc. defines point to the correct RGB interface variable. OnePlus 6 simply uses kcal_red, kcal_green and kcal_blue in sde. Some devices have a struct or pointers instead of a variable. Those devices must edit their kcal files to keep a copy of the address that klapse will access. An example of a source with struct-based kcal with klapse support is this: commit (thanks to @rupanshji for this commit)
The KCONFIG is pretty understandable too, but you may wanna remove the "DEPENDS" line for your device.
The Makefile is just one line, and so is enabling klapse in the defconfig.
Now you must change the file that provides the kcal/gamma (mtk) interface. Thanks to other developers, all I had to do on the OnePlus 6 was to remove the keyword "static" from the variable declaration.
Great work! Can I pay for your next meal?
I'm just a university CS student so sure, any amount is much appreciated! You can donate via PayPal here :
K-Lapse, Kernel for all devices (see above for details)
Source Code: https://github.com/tanish2k09/KLapse-Livedisplay
Kernel Special Features: RGB shifting based on a context
Current Stable Version: 4.3
Stable Release Date: 2019-03-02
Last Updated 2019-03-19