config: Split help from config file

Signed-off-by: Matt Yang <[email protected]>

README.md

@@ -1,17 +1,18 @@
 # Dfps
 
-Dynamic screen refresh rate controller for Android 10+. Splited from [Uperf v2](https://github.com/yc9559/uperf).
+Dynamic screen refresh rate controller for Android. Splited from [Uperf v2](https://github.com/yc9559/uperf).
 
 ## Feature
 
 - Dynamically switch screen refresh rate on touch and gesture event
 - Per-app configuration
 - Two low-level methods: `PEAK_REFRESH_RATE` and `Surfaceflinger backdoor`
-- Support Android 10+
+- Stop dynamically switch screen refresh rate when the brightness is low
+- Support Android 10-13
 
 ## Usage
 
-Read `/sdcard/Android/yc/dfps/dfps.txt` for help.
+Read [dfps_help_en.md](magisk/config/dfps_help_en.md) for help.
 
 ## Download
 

magisk/config/dfps.txt

@@ -1,59 +1,12 @@
 # 动态刷新率配置文件
 # Dynamic screen refresh rate controller config
-# 修改本文件后dfps会重新加载本配置
+# 修改本配置后，dfps会自动重新加载它
+# Dfps will automatically reload this config file after modification
 
-# 触摸松开后等待touchSlackMs毫秒进入空闲状态
-# Wait for touchSlackMs ms to enter the idle state after the touch is released
 /touchSlackMs 4000
-
-# 启用动态刷新率的最低亮度，低于此亮度固定使用触摸操作的刷新率，当前亮度值每10秒刷新一次
-# The minimum brightness to enable the dynamic refresh rate, below which the refresh rate for touch operations is fixed
-# OLED屏幕低亮度下切换屏幕刷新率可能出现亮度和色彩变化，设置此参数以平衡屏幕显示表现和功耗
-# MIUI14屏幕亮度与亮度值的关系：
-# 255 = 自动激发亮度100%
-# 128 = 手动亮度100%
-# 64  = 手动亮度85%
-# 32  = 手动亮度70%
-# 16  = 手动亮度50%
-# 8   = 手动亮度30%
-# 1   = 手动亮度0%
 /enableMinBrightness 8
-
-# Dfps will automatically reload this config file after modification
-# 支持2种刷新率切换方法，根据设定值的数值范围不同选择对应的方法
-# Two method are supported. Method chosing based on the value
-
-# 方法1: PEAK_REFRESH_RATE法，值>=20
-# Method 1: PEAK_REFRESH_RATE, value in [20, +inf)
-# 值: 系统支持的刷新率，请不要设置系统不支持的帧率
-# Value: refresh rate supported by system, do not use the value not supported by system
-
-# 方法2: Surfaceflinger backdoor法，值<20
-# Method 2: Surfaceflinger backdoor, value in [0, 20)
-# 值: 系统支持的刷新率索引，0/1/2/...对应的帧率需要自行尝试。
-# Value: refresh rate index supported by system, correspondence varies from systems
-# 以下为几种可能的值与刷新率的对应关系，供参考
-# Several possible values ​​and refresh rate for reference
-# 0:120hz，1:90hz，2:60hz
-# 0:60hz，1:90hz
-# 0:30hz，1:50hz，2:60hz，3:90hz，4:120hz，5:144hz
-# 0:1080p60hz，1:1440p120hz，2:1440p60hz，3:1080p120hz
-
-# 使用Surfaceflinger backdoor法切换屏幕刷新率
-# Use Surfaceflinger backdoor to switch screen refresh rate
 /useSfBackdoor 0
 
-# 分应用规则优先级从高到低排列
-# The priority of the per-app rules is ordered from high to low
-# "-"表示熄屏规则，"*"表示默认规则，熄屏和默认规则必须指定
-# "-" = offscreen. "*" = default. Offscreen and default rule must be specified
-# 值为"-1"表示使用系统默认的刷新率切换规则
-# "-1" means use the default screen refresh rate rule of system
-# 格式：包名 空闲值 触摸操作值
-# Format: packageName idleValue activeValue
-
-# 分应用动态刷新率配置
-# Per-app dynamic screen refresh rate rule
 com.miHoYo.Yuanshen 60 60
 com.hypergryph.arknights 60 60
 - -1 -1

magisk/config/dfps_help_cn.md

@@ -0,0 +1,75 @@
+# 动态刷新率配置帮助文件
+
+## 功能选项
+
+### touchSlackMs
+
+操作时屏幕刷新率切换到`活动刷新率`，操作松开后等待`touchSlackMs`毫秒后切换到`空闲刷新率`。
+此延迟用于避免频繁切换屏幕刷新率，以减少切换开销额外引入的功耗。
+默认值`4000`，最小值`100`。
+
+### enableMinBrightness
+
+OLED屏幕在低亮度下切换刷新率，可能有可察觉的亮度和色彩变化，造成观感不佳。
+此最低亮度用于指定启用动态刷新率的最低亮度，亮度值低于`enableMinBrightness`始终使用`活动刷新率`。
+默认值`8`，最大值`255`。
+
+dfps动态的从系统获取当前屏幕亮度值，考虑到此操作有大约100ms的开销，最快10秒获取一次。
+为了保证观感，始终使用`活动刷新率`时如果没有操作输入，屏幕亮度超过`enableMinBrightness`也不会恢复动态刷新率。
+从系统获取的亮度值，与系统设置的亮度条不成正比，与屏幕实际亮度也不成正比。以MIUI14屏幕亮度与亮度值为例：
+```
+255 = 自动激发亮度100%
+128 = 手动亮度100%
+64  = 手动亮度85%
+32  = 手动亮度70%
+16  = 手动亮度50%
+8   = 手动亮度30%
+1   = 手动亮度0%
+```
+
+### useSfBackdoor
+
+dfps支持2种刷新率切换方法，以适配更多设备。
+`useSfBackdoor`为0使用`PEAK_REFRESH_RATE`法，`useSfBackdoor`为1使用`Surfaceflinger backdoor`法。
+默认值`0`，可选`0`和`1`。
+
+#### PEAK_REFRESH_RATE
+
+调用安卓原生的动态刷新率接口，设定值直观，但不适合所有设备。
+分应用配置中的值>=20，值为系统支持的刷新率，请不要设置系统不支持的刷新率。
+
+#### Surfaceflinger backdoor
+
+调用Surfaceflinger的调试接口，设定值不直观，但适合大多数设备。
+分应用配置中的值<20，值为系统支持的屏幕配置索引，0/1/2/...对应的刷新率需要自行尝试。
+
+以下为几种可能的值与屏幕配置的对应关系，供参考：
+```
+0:120hz，1:90hz，2:60hz
+0:60hz，1:90hz
+0:30hz，1:50hz，2:60hz，3:90hz，4:120hz，5:144hz
+0:1080p60hz，1:1440p120hz，2:1440p60hz，3:1080p120hz
+```
+
+## 分应用配置
+
+格式：包名 空闲值 活动值。
+分应用规则优先级从高到低排列。
+"-"表示熄屏规则，"*"表示默认规则，熄屏和默认规则必须指定。
+值为"-1"表示使用系统默认的刷新率切换规则。
+
+使用`PEAK_REFRESH_RATE`法的配置例子：
+```
+com.miHoYo.Yuanshen 60 60
+com.hypergryph.arknights 60 60
+- -1 -1
+* 60 120
+```
+
+使用`Surfaceflinger backdoor`法的配置例子：
+```
+com.miHoYo.Yuanshen 1 1
+com.hypergryph.arknights 1 1
+- -1 -1
+* 1 0
+```

magisk/config/dfps_help_en.md

@@ -0,0 +1,74 @@
+# Dynamic refresh rate configuration help
+
+## Feature options
+
+### touchSlackMs
+
+During operation, the screen refresh rate switches to `activeRefreshRate`, and waits for `touchSlackMs` milliseconds after the operation is released, then switches to `idleRefreshRate`.
+This delay is used to avoid frequent switching of the screen refresh rate to reduce the additional power consumption introduced by the switching overhead.
+Default value `4000`, min value `100`.
+
+### enableMinBrightness
+
+When the OLED screen switches the refresh rate under low brightness, there may be perceivable changes in brightness and color, resulting in a poor look and feel.
+This minimum brightness is used to specify the minimum brightness to enable the dynamic refresh rate, and the brightness value is lower than `enableMinBrightness` to use the `activeRefreshRate`.Default value `8`, max value `255`.  
+
+dfps dynamically obtains the current screen brightness value from the system. Considering that this operation has an overhead of about 100ms, it can be obtained once every 10 seconds at the fastest.
+In order to ensure the look and feel, if there is no operation input when using `activeRefreshRate`, the dynamic refresh rate switching will not be restarted if the screen brightness exceeds `enableMinBrightness`.
+The brightness value obtained from the system is not proportional to the brightness bar set by the system, nor is it proportional to the actual brightness of the screen. Take MIUI14 screen brightness and brightness value as an example:
+```
+255 = Auto boost brightness 100%
+128 = Manual brightness 100%
+64  = Manual brightness 85%
+32  = Manual brightness 70%
+16  = Manual brightness 50%
+8   = Manual brightness 30%
+1   = Manual brightness 0%
+```
+
+### useSfBackdoor
+
+dfps supports 2 refresh rate switching methods to adapt to more devices.
+Use `PEAK_REFRESH_RATE` method if `useSfBackdoor` = 0. Use `Surfaceflinger backdoor` method if `useSfBackdoor` = 1.  
+Default value `0`, optional `0` and `1`.  
+
+#### PEAK_REFRESH_RATE
+
+Call Android's native dynamic refresh rate interface, the setting value is intuitive, but it is not suitable for all devices.
+The value in the perapp configuration >=20, the value is the refresh rate supported by the system, please do not set the frame rate not supported by the system.
+
+#### Surfaceflinger backdoor
+
+Call Surfaceflinger's debugging interface, the setting value is not intuitive, but it is suitable for most devices.
+The value in the perapp configuration is <20, the value is the screen configuration index supported by the system, and the refresh rate corresponding to 0/1/2/... needs to be tried by yourself.
+
+The following is the correspondence between several possible values and the refresh rate for reference:
+```
+0:120hz, 1:90hz, 2:60hz
+0:60hz, 1:90hz
+0:30hz, 1:50hz, 2:60hz, 3:90hz, 4:120hz, 5:144hz
+0:1080p60hz, 1:1440p120hz, 2:1440p60hz, 3:1080p120hz
+```
+
+## 分应用配置
+
+Format: packageName idleValue activeValue. 
+The priority of the per-app rules is ordered from high to low. 
+"-" = offscreen. "*" = default. Offscreen and default rule must be specified. 
+"-1" means use the default screen refresh rate rule of system. 
+
+Example for `PEAK_REFRESH_RATE` method:
+```
+com.miHoYo.Yuanshen 60 60
+com.hypergryph.arknights 60 60
+- -1 -1
+* 60 120
+```
+
+Example for `Surfaceflinger backdoor` method:
+```
+com.miHoYo.Yuanshen 1 1
+com.hypergryph.arknights 1 1
+- -1 -1
+* 1 0
+```

magisk/install.sh

@@ -117,6 +117,8 @@ on_install()
     local cfg_dir
     cfg_dir="/sdcard/Android/yc/dfps"
     mkdir -p $cfg_dir
+    cp $MODPATH/config/dfps_help_cn.md $cfg_dir
+    cp $MODPATH/config/dfps_help_en.md $cfg_dir
     if [ ! -e "$cfg_dir/dfps.txt" ]; then
         cp $MODPATH/config/dfps.txt $cfg_dir/dfps.txt
     fi