LibertyRecompAndroid着色器管线全解:RAGE FXC到SPIR-V的转换流程与shader override机制
LibertyRecompAndroid着色器管线全解:RAGE FXC到SPIR-V的转换流程与shader override机制
LibertyRecompAndroid 是一款通过静态重编译(static recompilation)将 Xbox 360 版《侠盗猎车手4》(GTA IV)移植到 Android 的开源项目。它的核心难题之一,就是把游戏里数以千计的 RAGE FXC 着色器容器解析出来,经由 XenosRecomp 转换为 DXIL / SPIR-V / Metal AIR 三大后端格式,并用一套 shader override 机制替换掉重编译中表现不佳的特效着色器。本文将完整拆解这条管线:从 .fxc 魔数解析、56MB 着色器缓存的生成,到 fusion 风格后处理的 HLSL 重写。
为什么 GTA IV 需要一条完整的着色器管线?
GTA IV 的着色器以 Xbox 360 GPU(Xenos)的微码形式存储在 RAGE 引擎的 FXC 容器(.fxc 文件)中。Xenos 的指令集与 ARM Mali/Adreno GPU 完全不兼容,直接运行是不可能的。
LibertyRecompAndroid 的解法是:
- 提取:解析
.fxc容器,取出原始 Xenos 着色器字节码 - 翻译:用 XenosRecomp 将 Xenos 微码重新编译为现代 GPU 能理解的 DXIL、SPIR-V 或 Metal AIR
- 替换:对重编译后效果不达标的后处理着色器,用 shader override 机制 直接换成手写的 HLSL 实现
这条管线覆盖了安装期转换、运行时查找和跨平台分发三个环节。
第一步:解析 RAGE FXC 容器("rgxa" 魔数)
RAGE FXC 是 RAGE 引擎自有的着色器容器格式。文件开头是一个 little-endian 的 uint32 魔数——字符串 "rgxa"(即 0x61786772),随后是顶点片段和像素片段计数,每个片段包含变量表、尺寸字段和字节码:
// RAGE FXC Magic: "rgxa" read as little-endian uint32
static constexpr uint32_t RAGE_FXC_MAGIC = 0x61786772;
每个片段内部还内嵌着一个标准的 Xbox 360 着色器容器(魔数 0x00112A10),解析器通过扫描这个模式定位真正的 Xenos 字节码。这套解析逻辑在 shader_converter.cpp 中实现,命令行版本则位于 rage_fxc_extractor.cpp(基于社区 rage-shader-editor 的研究)。
游戏安装目录下的 shaders/ 或 common/shaders/ 文件夹中存放着全部 .fxc 文件,批量构建脚本会扫描 fxl_final 目录清点数量:
# 扫描 fxl_final 目录下的 .fxc 文件
$FxcCount = (Get-ChildItem -LiteralPath $FxlFinalDir -Filter "*.fxc").Count
第二步:XenosRecomp 翻译并生成 shader_cache.cpp
提取出的 Xenos 字节码交给 XenosRecomp(一个 Xenos 微码重编译器,基于 Xenia 的着色器翻译思路)处理。整个离线构建由一条 PowerShell 脚本串起:
构建管线:
rage_fxc_extractor提取 →XenosRecomp翻译 → 生成shader_cache.cpp→ 编译后处理 HLSL 完整脚本见 build_and_generate_dxil.ps1
关键产物是 shader_cache.cpp——约 56MB 的单文件缓存,把全部着色器编译为三种后端格式并 zstd 压缩后内嵌进二进制。每个条目的结构定义在 shader_cache.h:
struct ShaderCacheEntry
{
const uint64_t hash; // 着色器指纹(XXH64)
const uint32_t dxilOffset; // DXIL:Windows (Direct3D 12)
const uint32_t spirvOffset; // SPIR-V:Vulkan
const uint32_t lateSpirvOffset;
const uint32_t airOffset; // AIR:macOS/iOS (Metal)
const uint32_t specConstantsMask;
const uint32_t usedTextureMask; // Xenos 纹理采样槽位
...
};
运行时的匹配逻辑非常直接:guest 代码调用某个着色器时,用该着色器字节码的 64 位哈希 在表中查找,再根据当前平台(见 shader_converter.h 中的 ShaderPlatform 枚举)取对应偏移读取编译好的机器码。后处理着色器走同样的思路,见 postprocess_cache.h。
第三步:自研 HLSL 后处理着色器 → SPIR-V
除了还原游戏原版效果,项目还内置了一套现代后处理(SSAO、SSR、Bloom、景深、体积光、TAA 等),全部用标准 HLSL 手写,位于 LibertyRecomp/gpu/shader/hlsl/。每个 .hlsl 文件旁边都有构建生成的 .spv(SPIR-V 二进制)和 .spirv.h(C 数组头文件),由 DXC 编译器(随 XenosRecomp 附带)产出。
在 Linux/macOS 上可用 compile_postprocess_shaders.sh 批量编译 SSAO、Bloom、体积光等 17 个后处理着色器到 SPIR-V 与 Metal 两套目标;Windows 上则用 compile_dxil_shaders.ps1 生成 DXIL。生成物被 video.cpp 与 postprocess_renderer.cpp 在编译期直接 #include,零运行时编译开销。
核心亮点:shader override 机制 🎯
重编译再精准,Xenos 上那些复杂的后处理特效(雾效、景深、胶片颗粒)也常因指令语义差异而"翻车"。LibertyRecompAndroid 的对策是按哈希整段替换:维护一份 hash → 手写 HLSL 的映射表。
manifest.json 就是这张表,第一条记录长这样:
{
"stage": "pixel",
"hash": "0xF6AEB9A606561C54",
"language": "hlsl",
"source": "postfx/composite_f6aeb9a606561c54.hlsl",
"entry_point": "shaderMain",
"specialization_constants_mask": "0x00000702",
"defines": ["GTA4_RECOMP"]
}
覆盖目录 shader_overrides/ 按特效分类组织:
| 目录 | 覆盖内容 |
|---|---|
| forward_fog/ | 前向雾效,含 200+ 个材质变体 |
| depth_of_field/ | 景深(含 bokeh 光斑) |
| motion_blur/ | 运动模糊复合 |
| film_grain/ | 胶片颗粒 |
| light_volume/ | 延迟光照体积(vs/ps 成对) |
| sky/、water/、bloom/ | 天空、水面、泛光 |
override 源文件与 guest 共用同一套 ABI,由 xenos_shader_common.h 定义:RAGE 的常量缓冲在 Vulkan 后端被映射为 vk::push_constant 里的固定偏移(g_Booleans、g_SwappedNormals、g_AlphaThreshold……),运行时状态(如 SPEC_CONSTANT_ALPHA_TEST)则通过 SPIR-V 的 constant_id(0) 特化常量注入,从而一份 HLSL 可以同时喂给 DXC、glslang 和 Metal 编译器。
更精细的控制体现在 shader_override_cache.h:每条 override 可以声明 activation 模式——按单个着色器阶段激活,或像 light_volume 那样以 pipeline_pair(vs+ps 配对,counterpart_hashes 互相引用)为单位整条管线替换,还可约束采样数、early fragment tests 等能力位。
跨平台着色器归档:一份 HLSL,三种 GPU
override 与 temporal 变体(FSR3/DLSS 时间重建)需要针对每个平台离线编译归档:
- Vulkan:VulkanShaderArchive.cmake 调用 Python 构建器,用宿主机的 DXC +
spirv-val+glslangValidator全量编译校验,产出 zstd 压缩的vulkan-temporal.bin随应用分发 - Metal:MetalShaderArchive.cmake + shader_archive.py 生成
title_shader_archive.bin - Windows D3D12:DXIL 直接内嵌在
shader_cache.cpp中
安装期转换与缓存校验
在 Android 端,安装器会调用 ShaderConverter::convertShaders 扫描游戏目录下的全部 .fxc,逐个解析、提取并写入本地缓存目录;缓存有效性通过 shader_cache.marker 的时间戳与着色器文件对比判断(见 isCacheValid),游戏更新后会自动触发重新转换,整个过程有进度回调可取消。
管线效果:性能与画面
这条"重编译 + 缓存 + override"管线让 GTA IV 在移动 GPU 上以接近硬件加速的原生效率运行。下图展示了不同模拟器/重编译方案的性能交叉曲线:
而 shader override 保证了雾效、景深、运动模糊这些 Xbox 360 时代的招牌后处理在新架构 GPU 上依然正常渲染,最终游戏内画面如下:
参考文件速查
- 容器解析:shader_converter.cpp / rage_fxc_extractor.cpp
- 运行时缓存表:shader_cache.h / shader_cache.cpp
- override 清单与 ABI:manifest.json / xenos_shader_common.h
- 构建脚本:build_and_generate_dxil.ps1 / compile_postprocess_shaders.sh
- 平台归档:VulkanShaderArchive.cmake / MetalShaderArchive.cmake
一句话总结:LibertyRecompAndroid 的着色器管线 = rgxa 魔数解析 RAGE FXC → XenosRecomp 翻译出 DXIL/SPIR-V/AIR 三格式缓存 → 哈希驱动的 override 表用现代 HLSL 替换疑难特效 → 离线归档保证运行时零编译。理解这套机制,也就理解了静态重编译项目在"保真"与"现代 GPU 能力"之间所做的工程平衡。


