Bridgeplay 是一个让 Windows Steam 游戏直接在 Mac Steam 中运行的开源项目，而它的 overlay-shim 是其中一块关键组件：一个注入游戏进程的 macOS dylib，负责修复 HDR 显示问题、兼容 Metal 4，并实现实验性的进程内帧生成（Frame Generation），让 Windows 游戏的画面在 Apple GPU 上更稳定、更流畅。

overlay-shim 是什么，为什么它住在游戏进程里

Steam 的覆盖层（gameoverlayrenderer）运行在游戏进程内部，直接操作 Mac 侧的CAMetalLayer和 Metal 对象。Bridgeplay 通过DYLD_INSERT_LIBRARIES把 overlay-shim.dylib 注入同一个进程（见 compat_run.sh 中的 launcher 逻辑），这样它能在最底层拦截 Metal 调用。

docs/ARCHITECTURE.md 对它的定位一句话概括：

overlay-shim/— 游戏进程内的 Mac dylib（HDR、Metal 4、帧生成）

它解决的核心矛盾是：Valve 的覆盖层只钩住了 Metal 3 的提交路径，而 Apple Game Porting Toolkit 的 D3DMetal 4 走的是全新的 Metal 4 队列；同时覆盖层的渲染管线像素格式和游戏实际使用的 HDR 格式经常对不上，导致画面发白或异常。overlay-shim 用 Objective-C 运行时钩子把这些缝隙逐一补齐（overlay_shim.m 的头部注释就说明了这一点）。

HDR 修复：让覆盖层跟上游戏真实像素格式

overlay-shim 拦截了CAMetalLayer的setPixelFormat:、setColorspace:等方法，实时记录游戏当前使用的像素格式（BGRA8、BGR10A2、RGBA16Float 等）。

关键机制：

• 管线替换：当覆盖层创建渲染管线时，shim 记下其描述符；如果游戏实际把帧画到了不同格式（比如切换到 HDR 的 PQ 编码）的附件上，shim 会按当前格式动态构建对应的MTLRenderPipelineState并替换绑定，避免格式不匹配导致的画面异常
• 色彩空间与 EDR 跟随：帧生成层会跟随游戏层的EDRMetadata，游戏切到 HDR（PQ、EDR）后，复制的 PQ 像素也能正确显示，而不是在 sRGB 层里发白（framegen.m）

Metal 4 兼容：把新队列桥回旧钩子

D3DMetal 4 在MTL4CommandQueue上提交帧，调用signalDrawable:后直接进入present，而覆盖层只 swizzle 了 Metal 3 的present家族方法——覆盖层因此"看不见"帧。

shim 的做法很优雅：

1. 钩住 Metal 4 队列的signalDrawable:，在共享MTLEvent上发出信号
2. 覆盖层随后走 Metal 3 的presentDrawable:时，shim 让一个 Metal 3 command buffer等待这个事件，再提交上屏

结果就是覆盖层的合成始终排在游戏帧之后，画面顺序完全正确。详见 overlay_shim.m 的 present_composited。

进程内帧生成：2x、3x 到自适应补帧

这是 overlay-shim 最重的部分，由 framegen.m 实现（约 2500 行，含内嵌 Metal 着色器源码）。默认关闭，属于实验功能。

工作流程：游戏每次上屏真实帧 N 时，shim 会拦截这次 present，把 drawable 拷贝进历史纹理并发出事件；一个独立工作线程在自己的 GPU 队列上，基于帧 N-1 和 N合成中间帧，先显示补帧，再延迟显示真实帧 N。整个过程的画面由一块盖在游戏层上方的第二块CAMetalLayer承载，格式、色彩空间和 EDR 元数据都与游戏层保持一致。

两个插帧引擎：

安全与质量控制（默认都开启）：

• UI 保护：两帧完全相同的像素（HUD、菜单、文字）直接取新帧，避免界面模糊
• 快速运动回退：光流超出搜索范围或前后不一致面积过大时，放弃补帧、改用最近的真实帧，防止画面涂抹
• 自动直通：游戏帧率已高于刷新率、工作线程跟不上、或发生 Metal 错误时，自动切回原生 present，不产生额外延迟
• 延迟成本：补帧会引入最多约半帧延迟，需要权衡

如何开启帧生成：按游戏配置方法

帧生成按游戏开关，配置入口在 Steam：右键游戏 →Properties… › Bridgeplay，也可以在启动选项或 gamefix 中设置（完整变量表见 docs/GAMEFIXES.md）：

注意：启动脚本读取的是NOTPROTON_前缀的旧名，BRIDGEPLAY_是 3.0 之后的新写法，两者都有效。配合VSYNC=1可以强制层等待显示器，避免开补帧后画面撕裂（GAMEFIXES.md 中对 Resident Evil Requiem 就有此建议）。

顺带一提：Command-Q 也能退出游戏

quitkey.m 还解决了一个体验细节：Wine 把 Command-Q 映射为"关闭窗口请求"，多数游戏会忽略它。shim 在游戏自己的NSApplication sendEvent:中拦截 Command-Q 并直接结束进程，让 Mac 用户习惯的"Command-Q 退出"真正生效（BRIDGEPLAY_COMMAND_Q=0可关闭）。

测试与构建

overlay-shim 有独立测试与基准：Makefile 中的overlay-shim、overlay-shim-tests、overlay-shim-bench目标（Makefile），测试位于 overlay-shim/tests/，覆盖帧生成行为、显示时序、层归属等场景；构建产物overlay-shim.dylib会被原子安装到 Application Support 并随 app 一起分发（RELEASING.md）。

小结

Bridgeplay overlay-shim 展示了"在游戏进程内做图形手术"的完整思路：用运行时钩子修复 HDR 格式错位，用MTLEvent把 Metal 4 的新提交路径桥回覆盖层认识的 Metal 3 顺序，再在空闲的 GPU 队列上实现双引擎帧生成与多重安全回退。对于想在 Mac 上榨出更高帧率的玩家，它是 Bridgeplay 最有想象力的实验特性；对开发者，overlay-shim/ 目录也是研究 macOS Metal 运行时钩子的优秀范例。