BRUTAL着色器运行时编译:ShaderC与Slang双引擎原理全解析

原创2026-10-19 21:07:271,331 阅读

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 引擎。

BRUTAL Framework 品牌标识

引擎一: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,一个标准的编译请求长这样:

  1. 建会话:Slang.CreateGlobalSession() 获取 IGlobalSession,再创建 ISession(会话持有编译缓存,可复用);
  2. 喂源码:通过 LoadModuleFromSourceString(moduleName, path, source, out diagnostics) 把字符串源码加载成 IModule——UTF-16 到 UTF-8 的编解码全部由扩展方法内部完成,调用者不用碰 byte*;
  3. 要代码:创建 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# 里做运行时着色器编译的全部底层原理。

登录后查看全文
BRUTAL