BRUTAL着色器运行时编译:ShaderC与Slang双引擎原理全解析
BRUTAL着色器运行时编译:ShaderC与Slang双引擎原理全解析
如果你正在用 C# 构建 Vulkan 游戏引擎,一定会遇到一个问题:着色器什么时候编译、用什么编译?BRUTAL 框架给出的答案是把两个业界主流编译器都封装成了 C# 库——Brutal.ShaderC 和 Brutal.Slang,让你在运行时直接把 GLSL/HLSL/Slang 源码编译成 SPIR-V。本文带你从零理解这套双引擎的底层原理。
为什么游戏框架需要"运行时"编译着色器 🎮
大多数游戏引擎采用"离线编译 + 平台特定缓存"的策略,但这有三个痛点:
- 跨平台麻烦:Windows 上的 HLSL 字节码、Vulkan 的 SPIR-V、不同 GPU 的验证要求,缓存策略复杂;
- 工具链污染:美术和策划的机器上必须装完整的着色器编译器;
- 热更新困难:改了着色器就得重跑离线流水线。
BRUTAL 的思路是"把编译器搬进进程":通过原生库(shaderc_shared 和 slang 动态库)在运行时完成"源码 → SPIR-V"的转换。这套设计支撑了 Kitten Space Agency 和 RimWorld 的 Waylith 引擎。
引擎一:ShaderC——把 GLSL/HLSL 变成 SPIR-V 的瑞士军刀
ShaderC 是 Google 官方的 C 库(shaderc),Brutal.ShaderC 通过 P/Invoke 把它完整引入 C#。
原生库加载:一切从静态构造函数开始
打开 ShaderC.cs,可以看到类型初始化的关键细节:
- 首次访问
ShaderC类时,静态构造函数通过NativeLibrary.Load从程序集目录加载shaderc_shared动态库; - macOS 上库名是带版本号的
shaderc_shared.1,其他平台用shaderc_shared,框架内部自动处理这个平台差异; - ⚠️ 一个常见部署坑:如果首次访问时动态库不在目录里,会抛出
TypeInitializationException。
三条核心 API:创建、编译、释放
整个工作流围绕三个句柄展开(定义见 Generated/ShaderC.gen.cs):
| 方法 | 作用 | 生命周期要求 |
|---|---|---|
CreateCompiler() |
创建编译器句柄 | 必须 Dispose 恰好一次 |
CreateCompilerOptions() |
创建编译选项句柄 | 必须比使用它的编译任务活得更久 |
TryParseVersionProfile() |
解析 450core 这类 GLSL 版本串 |
无状态 |
特别注意:编译器句柄不是线程安全的。如果要多线程并行编译,每个线程各建一个句柄。
高层 API:让 C# 用起来不痛苦
底层 P/Invoke 返回的是原生句柄,直接用起来容易踩坑。HighLevel.cs 里的一组扩展方法是新手首选:
compiler.Compile(source, kind, fileName, "main", options):直接传 C# 字符串,内部用 BespokeUtf8Encoder.cs 做零拷贝 UTF-8 编码后调用原生 API;compiler.CompileFile(path, kind):从磁盘读文件编译,#include的相对路径以该文件为锚点;- 失败时自动清理原生句柄并抛出类型化异常,成功时把句柄所有权移交给调用者。
按文件后缀猜着色器阶段
ShaderKindInference.cs 提供了一个很贴心的细节:TryInferShaderKind 能根据文件后缀自动推断着色器类型——.vert 是顶点着色器、.frag 是片元着色器、.comp 是计算着色器,甚至覆盖了 .rgen、.rcall 等光线追踪阶段。这意味着你可以在加载资源时一行代码确定它该进哪条编译流水线。
类型化异常体系:编译失败也能精确定位
Utilities/ShaderException.cs 定义了 8 种异常,每种对应 shaderc 的一种失败状态:
| 异常 | 触发场景 |
|---|---|
ShaderInvalidStageException |
无法推断着色器阶段 |
ShaderCompilationException |
编译本身出错(最常见) |
ShaderValidationException |
SPIR-V 验证失败 |
ShaderInternalException |
编译器内部错误 |
ShaderException 构造时会立即读取原生错误信息(GetErrorMessage()),所以即使后续句柄被释放,异常里也保留着完整的编译器诊断文本。
#include 支持:一个容易被忽略的开关
默认情况下 shaderc 不支持 #include。你需要在 CompileOptions 上调用 SetDefaultIncludeCallbacks(),它会安装一个基于磁盘的解析器(实现见 Utilities/Callbacks.cs):
- 相对路径以引用它的源文件目录为基准解析;
- 内嵌 200 层深度限制,防止
#include循环导致栈溢出; - 解析失败(如文件不存在)不会抛 C# 异常,而是转化为编译器错误输出。
引擎二:Slang——面向未来的跨语言着色器编译器
Brutal.Slang 封装了 Slang——由微软主导的下一代着色器语言编译器。它的最大卖点是:一次编写,编译到所有后端(SPIR-V、HLSL、MSL、CG 等),还内置了跨文件的重构友好类型系统。
COM 代理:理解 Slang 封装的关键
Slang 的原生 API 基于 COM(组件对象模型)。Slang.cs 的处理方式值得细读:
- 静态构造函数加载
slang原生库,与 ShaderC 的手法一致; - 每个原生对象(Session、Module、Program)都被
StrategyBasedComWrappers包装成托管 COM 代理,例如IGlobalSession; - 资源释放交给 GC:代理对象被回收时 finalizer 自动释放底层 COM 引用,无需手写 Dispose。这与 ShaderC 的"必须恰好释放一次"形成鲜明对比——两套引擎的心智模型完全不同。
典型编译流程:三步走
结合 ISessionExtensions.cs 和 ICompileRequestExtensions.cs,一个标准的编译请求长这样:
- 建会话:
Slang.CreateGlobalSession()获取IGlobalSession,再创建ISession(会话持有编译缓存,可复用); - 喂源码:通过
LoadModuleFromSourceString(moduleName, path, source, out diagnostics)把字符串源码加载成IModule——UTF-16 到 UTF-8 的编解码全部由扩展方法内部完成,调用者不用碰byte*; - 要代码:创建
ICompileRequest,添加翻译单元和入口点,最终取出编译产物。
结果码与诊断:Result 结构体的隐藏细节
Slang 用整数结果码(Result)而非异常控制流。看 Result.cs 会发现一个精妙的实现细节:
- 负值表示失败,
ThrowIfFailure()可以一键转成SlangException; Result结构体挂了自定义 Marshaller,强制按普通int跨界传递——否则 Windows x64 上运行时可能偷偷插入隐藏返回指针,把后面所有参数都错位,直接访问违例。这种"看不见的崩溃"正是低层互操作最凶险的角落之一。
输出怎么读:ISlangBlob
编译产物(字节码、诊断信息)都是 ISlangBlob。ISlangBlobExtensions.cs 提供了一行式读取:blob.AsSpan() 直接把原生缓冲区变成 ReadOnlySpan<byte>,拿去塞给 Vulkan 的 VkShaderModuleCreateInfo 即可。
双引擎怎么选?🔍
| 维度 | ShaderC(Brutal.ShaderC) | Slang(Brutal.Slang) |
|---|---|---|
| 输入语言 | GLSL、HLSL | Slang 源码(也可编译 GLSL/HLSL) |
| 输出 | 主要为 SPIR-V(及 SPIR-V 汇编) | 多后端:SPIR-V、HLSL、MSL、CG 等 |
| 资源模型 | 句柄,手动 Dispose,不可多线程共享 |
COM 代理,GC 自动回收 |
| 错误模型 | 类型化 C# 异常(8 种细分) | Result 结果码 + 诊断 Blob |
#include |
需手动开启内置回调 | 通过 ISlangFileSystem 自定义文件解析 |
| 适用场景 | Vulkan 项目的轻量、可预测编译 | 跨平台渲染、需要着色器级类型系统/模块化 |
实践建议:
- 纯 Vulkan 桌面项目、团队习惯写 GLSL → 选 ShaderC,模型简单、行为可预测;
- 需要一套着色器代码跑遍多平台、或想利用 Slang 的元编程与跨语言互操作 → 选 Slang;
- 两者也可以共存:用 ShaderC 快速编译存量 GLSL,用 Slang 处理新资产。
核心源码速查 📂
| 想了解什么 | 看哪里 |
|---|---|
| ShaderC 原生库加载与平台差异 | ShaderC.cs |
| 高层 Compile / CompileFile / Preprocess | HighLevel.cs |
| 按后缀推断着色器阶段 | ShaderKindInference.cs |
| 类型化编译异常 | Utilities/ShaderException.cs |
#include 磁盘解析器 |
Utilities/Callbacks.cs |
| Slang COM 代理桥接 | Slang.cs |
| 从字符串加载模块 | ISessionExtensions.cs |
| 结果码与 Marshaller 细节 | Result.cs |
| 读编译产物字节 | ISlangBlobExtensions.cs |
总结
BRUTAL 的着色器方案体现了它"像内核一样做地基"的哲学:不替你选编译器,而是把 ShaderC 与 Slang 两套引擎的互操作难点(原生库加载、句柄生命周期、COM 代理、字符串编解码、错误诊断)全部消化在 Brutal.ShaderC 和 Brutal.Slang 里。理解了两套引擎各自的资源模型——一个是"手动释放的原生句柄",一个是"GC 托管的 COM 代理"——你就掌握了在 C# 里做运行时着色器编译的全部底层原理。
