ImageOverlay —— 安卓掌机全局遮罩工具

为什么需要它？

很多安卓掌机的痛点：性能更好的模拟器往往不支持遮罩，支持遮罩的模拟器又不够高效。

ImageOverlay 通过系统悬浮窗把你指定的遮罩图层铺在最前面，实现“全局遮罩”。无需改动或切换模拟器，任何应用都能叠加显示。

功能特色

• 快速使用：一键选择图片并启动/关闭遮罩，适合临时需求。
• 预设分组：按"组"管理多份遮罩配置（组/配置），便于分类与切换。
• 应用绑定：支持遮罩组配置绑定应用，随应用自动切换/启动，实现智能遮罩管理。
• 全局透明度：统一的透明度设置，所有遮罩使用相同的透明度配置，支持实时调整。
• 默认配置与磁贴：支持设为默认配置，并通过快捷设置磁贴（Quick Settings Tile）一键启停默认遮罩。
• 无侵入：不改动模拟器或游戏，无需 Root。
• 前台服务：通过前台通知保持稳定运行。

典型场景

• 模拟器遮罩
• 准星/对齐辅助、按键位图提示
• 画面对齐、色弱/色盲辅助等

使用指南

1) 快速使用（无需预设）

1. 打开应用 → 底部导航选择“快速使用”。
2. 点击“选择图片”，挑选一张 PNG。
3. 首次使用会引导授予“在其他应用上层显示”的悬浮窗权限。
4. 点击“启动遮罩”开始，需停止时点击“关闭遮罩”。

提示：如果已有“预设”处于激活状态，将无法从“快速使用”再次启动（设计为互斥）。

2) 预设与分组

1. 底部导航选择"预设"。
2. 右上角"+"新建组（如：某游戏/某分辨率）。
3. 进入组 → "+" 新建配置，选择 PNG 图片；保存后列表中可见。
4. 点击配置行左侧状态圆点：绿色为激活，红色为未激活。激活会自动停用其他配置/快速使用遮罩。
5. 应用绑定：长按组 → 选择"绑定应用"，可将遮罩组与特定应用关联，实现自动切换。

3) 默认配置与磁贴

• 在组内长按配置 → 选择"设为默认配置"。
• 在"预设"页顶部可看到默认配置信息与启停状态。
• 下拉系统快捷设置，添加"ImageOverlay 切换"磁贴，即可一键启停默认遮罩。

4) 全局透明度设置

• 底部导航选择"设置"。
• 找到"全局遮罩透明度"滑块，调整透明度（0-100%）。
• 支持防抖处理，调整停止500毫秒后自动保存。
• 实时生效：正在运行的遮罩会立即应用新的透明度设置。
• 全局生效：所有遮罩（包括新启动和正在运行的）都会使用此设置。

权限说明

• SYSTEM_ALERT_WINDOW：用于在最前层显示遮罩。
• FOREGROUND_SERVICE：前台服务维持遮罩稳定运行。
• USAGE_STATS：用于应用绑定功能，监听应用切换以实现自动遮罩切换。

应用不访问网络，不上传任何数据；所有配置与图片均保存在本地你指定的位置。

常见问题（FAQ）

看不到遮罩？

• 请确认已授予“在其他应用上层显示”的权限；部分系统（如 MIUI 等）需要在系统权限管理中单独允许。
• 若使用了分屏/画中画模式，系统层级可能影响显示，请先退出特殊窗口模式再试。

预设和快速使用为何不能同时开？

为避免多重遮罩叠加造成性能与显示混乱，二者设计为互斥。

选择图片后保存失败或不显示？

• 推荐在“设置”中先选择 SAF 目录；若使用传统路径，请确保目录可写。
• 确认图片为 PNG 且未被系统清理；如为外置 SD 卡，请确保已授权读写。

遮罩被拉伸/比例不对？

当前策略是 FIT_XY 全屏铺满。如果需要等比/位置/透明度等控制，敬请期待或提交 PR。

应用绑定功能不工作？

• 请确认已授予"使用情况访问权限"（USAGE_STATS），部分系统需要在系统设置中手动开启。
• 确保绑定的应用已正确安装且可正常运行。

透明度调整没有效果？

• 透明度设置是全局的，会应用到所有遮罩。如果正在运行的遮罩没有变化，请检查是否已正确保存设置。
• 新启动的遮罩会自动使用最新的透明度设置。

如何彻底清理？

在"设置 → 清除缓存"可删除无效图片或全部数据；卸载前也可手动删除授权目录中的 ImageOverlay/。

开源许可

本项目基于 GPL-3.0 许可开源，详见仓库中的 LICENSE 文件。

您可以随意修改源代码以自用，但如果要分发，请将您的修改开源并继承 GPL-3.0 协议。