Slang 文档体系全景：从用户指南、slangc 编译到 CPU/CUDA 目标与贡献者设计文档的导读

Slang 文档体系全景从用户指南、slangc 编译到 CPU/CUDA 目标与贡献者设计文档的导读【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slangSlang 的文档组织在仓库docs/目录下集中管理其入口文件 docs/README.md 将整个文档体系划分为四个读者群体语言与编译器用户、进阶平台用户、项目贡献者和研究背景关注者。本文以该入口文档为骨架完整继承其Getting Started / Advanced Users / Contributors / Research四段脉络并结合仓库中的用户指南、目标兼容性矩阵、CPU 与 CUDA 目标文档及设计笔记进行纵深展开。读完后你将知道针对自己的角色应该从哪份文档入手并且能直接掌握slangc命令行编译、多目标能力差异查询以及 CPU/CUDA 代码生成这几个最常用的实操能力。文档体系总览一份入口四类读者docs/README.md 开篇即声明docs/目录包含 Slang 系统的全部文档其中一部分面向语言与编译器用户另一部分面向为项目做贡献的开发者。四个板块的职责划分如下读者群体入口文档核心内容语言/编译器用户用户指南Slang 语言特性、编译 API、反射 API命令行用户slangc 参考slangc全部命令行选项进阶用户目标兼容性、CPU 目标、CUDA 目标各平台功能差异与代码生成细节贡献者设计文档目录编译管线、IR、接口泛型等设计 rationale研究背景SIGGRAPH 2018 论文与博士论文语言与编译器的设计动机从源码结构看这个导航不是空架子docs/下确实存在与之对应的完整子树包括user-guide/约 30 章用户指南、language-reference/语言规范、design/设计与实现笔记、generated/自动生成的测试文档以及gpu-feature/等专题目录。构建文档本身所需的脚本也位于docs/scripts/与docs/build_toc.sh、docs/build_reference.ps1等处供文档维护者生成目录与语言规范时使用。Getting Started用户指南与 slangc 命令行入口文档的第一部分指向 Slang 用户指南说明其覆盖语言与主要特性的介绍以及编译与反射 API。仓库内对应的源文件是 docs/user-guide/index.md其导言列明指南教读者掌握三件事Slang 的语言特性包括从 HLSL 继承的部分以及让大型着色器代码库更易维护的扩展特性控制如何把不同代码片段组装成着色器、并为不同目标编译的编译器 API允许宿主应用查询着色器代码细节、以生成正确内核并正确设置参数的反射 API。指南正文的目录见 docs/user-guide/index.md 中的 toctree 注释依次为语言入门00-introduction.md、01-get-started.md、常规语言特性、便捷特性指针等、模块与访问控制、能力系统、接口与泛型、自动微分、代码编译、反射 API、支持的编译目标、链接期特化与模块预编译以及矩阵布局、混淆、互操作、uniformity 等专题docs/user-guide/a1-*.md和按目标平台细分的特性docs/user-guide/a2-*.md。用 slangc 做离线编译docs/README.md 同时指出存在专门针对slangc命令行工具的文档。slangc随 Slang 二进制发行版提供可替代fxc/dxc承担大多数简单编译任务完整选项见 docs/command-line-slangc-reference.md。docs/user-guide/08-compiling.md 首先建立了 Slang 的编译心智模型——源单元source units→ 翻译单元/模块translation units/modules→ 入口点entry points→ 目标targets→ 布局layout→ 组合composition→ 链接linking→ 内核kernels。其中两个关键设计点值得记住编译器前端预处理、解析、语义检查对每个翻译单元只运行一次结果在所有目标间共享后端代码生成按每个目标各运行一次。因此 Slang 不会自动提供目标相关的预处理#define需要目标相关宏时应每次只编译一个目标并手动设置预处理器状态。入口点默认通过[shader(...)]属性识别若使用显式入口点选项编译器会忽略所有[shader(...)]属性。该章节给出的最小可运行示例是// hello-world.slang StructuredBufferfloat buffer0; StructuredBufferfloat buffer1; RWStructuredBufferfloat result; [shader(compute)] [numthreads(1,1,1)] void computeMain(uint3 threadId : SV_DispatchThreadID) { uint index threadId.x; result[index] buffer0[index] buffer1[index]; }编译为 SPIR-V 的命令为slangc hello-world.slang -target spirv -o hello-world.spv仓库中对应的真实示例工程位于 examples/hello-world/hello-world.slang可直接作为复制起点。Advanced Users 之一目标兼容性矩阵入口文档为进阶用户提供的第一个资源是 docs/target-compatibility.md。该文档以一张大矩阵回答某特性在某目标上是否可用列覆盖 D3D11 / D3D12 / Vulkan / CUDA / Metal / CPU并对矩阵外的特性逐个展开小节解释限制细节。阅读该文档时有三条约定需要先行理解文档开头明确声明未另行说明时SM 编号均指 D3D Shader Model 版本不带 OpenGL 列因为 OpenGL 不是官方支持目标标记表示特性预期未来加入标记^表示文档后文对该目标有补充讨论。矩阵摘录完整 40 余行矩阵见原文档特性D3D11D3D12VulkanCUDAMetalCPUhalf 类型否是^是是^是否u/int8_t 类型否否是^是是是u/int64_t 类型否是^是是是是SM6.0 Wave 内建否是部分是^否否三角形化Tesselation是^是^否否否否图形管线是是是否是否射线追踪 DXR 1.0否是^是^否否否Mesh Shader否是是否是否Shader Execution Reordering否是^是^否否否文档对矩阵中每一项的非 Yes都给出了原因典型的几条half 类型D3D12 上存在向 StructuredBuffer 写 half 的问题CUDA 上需要 NVRTC 能找到cuda_fp16.h详见 CUDA 目标文档。u/int8_tD3D11/D3D12 不支持因为 HLSL/DXIL/DXBC 不支持Vulkan 上依赖GL_EXT_shader_explicit_arithmetic_types与GL_EXT_shader_8bit_storage扩展。u/int16_tD3D 侧需要 SM6.2即 DXIL/DXC D3D12。WaveMask 内建这是 Slang 独有不属于 HLSL的一族内建函数为对齐 CUDA 的同步/掩码模型设计是跨 D3D12 与 CUDA 写 wave 代码时当前推荐的统一写法。Buffer bounds越界行为在各目标不一致——CPU 上仅 debug 构建 assertCUDA 默认落到元素 0Metal 上是未定义行为。Switch Fall-ThroughD3D11FXC/DXBC与 WGSL 不支持 fall-throughSlang 会将 fall-through 目标代码复制进每个源 case 来模拟并产生告警 41026 提示代码体积与 wave 收敛行为可能受影响。对跨平台项目这份矩阵的实际用法是以能力交集确定可移植内核代码把平台独有特性隔离到能力系统见 docs/user-guide/05-capabilities.md管理的分支中。Advanced Users 之二CPU 目标docs/cpu-target.md 描述 Slang 将源码编译为 CPU 可执行代码的完整机制。入口文档对该文档的概括是编译 Slang 或 C 源码为共享库/可执行文件或可直接执行函数以及从 Slang 源码生成 C 代码原文文档则进一步给出了可复现的操作细节。能力与限制可将 C/C/Slang 源码编译为可执行文件、共享库或直接可执行host-callable产物若 slang-llvm 可用二进制发行版自带系统无需安装C/C 编译器支持 compute 风格着色器限制不支持 barrier需要 ABI 变更、尚不支持原子操作、不支持float16_t、入口点不能命名为main下游 C 编译器会把它当常规 main。目标与直通编译器生成 C 源码的目标API 枚举与slangc的-target值对应关系SlangCompileTarget-target命令行值含义SLANG_C_SOURCEcC 源码当前未实际支持输出SLANG_CPP_SOURCEcpp/c/cxxC 源码SLANG_CPP_HEADERhppC 头文件SLANG_HOST_CPP_SOURCEhost-cpphost风格的 C 代码生成 CPU 二进制的目标SlangCompileTarget-target命令行值含义SLANG_EXECUTABLEexe/executable宿主操作系统可执行文件SLANG_SHADER_SHARED_LIBRARYsharedlib/dll共享库/DLLSLANG_SHADER_HOST_CALLABLEcallable/host-callable可直接运行的 compute 内核SLANG_HOST_HOST_CALLABLEhost-host-callable可直接运行的标量host 风格代码SLANG_OBJECT_CODEobject-code供后续链接的目标代码CPU 后端也可像 dxc/fxc/glslang 一样通过直通pass-through机制直接访问对应枚举为SLANG_PASS_THROUGH_CLANG、SLANG_PASS_THROUGH_VISUAL_STUDIO、SLANG_PASS_THROUGH_GCC、SLANG_PASS_THROUGH_LLVMslang-llvm内置 LLVM 与 Clang以及SLANG_PASS_THROUGH_GENERIC_C_CPP按源码类型自动选择与 Slang 构建二进制最可能二进制兼容的编译器。两种编译风格shader 与 hostshader 风格代码可按 GPU 内核模型在多线程上启动目前仅有 Slang 核心模块、内建 HLSL 与 COM 接口提供的功能可用slang-llvm 目前只支持此风格。host 风格更接近常规 CPU 标量代码通常需要与slang-rt链接并使用Slang::String等类型允许new、允许引用计数classCOM 接口是引用计数的。示例工程见 examples/cpu-hello-world/。host-callable 的直接执行编译后通过ISlangSharedLibrary接口访问产物request-getTargetHostCallable(0, sharedLibrary)取得可执行代码接口再用findSymbolAddressByName定位导出全局变量、用findFuncByName定位导出函数。要让 Slang 函数/变量对宿主应用可见需要export与__extern_cpp修饰符组合——单独export只保留符号名字会被 mangle加上__extern_cpp才保留原名并在-target hpp头文件中生成声明__global export __extern_cpp int myGlobal; export __extern_cpp int myFunc(int a) { return a * a; }注意上下文线程化context threading任何访问上下文状态如常量缓冲中的全局变量的函数其实际签名会被改写为带KernelContext_*首参的形式应用代码直接按无参调用会崩溃__global变量是绕开该问题的手段。COM 接口机制则允许 Slang 代码反向调用应用代码完整示例在 examples/cpu-com-example/。ABIentry point 如何变成 C 函数对一个 compute 入口点例如带[numthreads(4,1,1)]的computeMainSlang 生成三个导出符号computeMain(ComputeVaryingInput*, UniformEntryPointParams*, UniformState*)执行[startGroupID, endGroupID)组区间是性能最优的默认路径computeMain_Group(...)只执行startGroupID指定的单个组[numthreads]内所有线程一次调用完成computeMain_Thread(ComputeThreadVaryingInput*, ...)按groupID/groupThreadID执行单个线程最灵活但开销最大。其中ComputeVaryingInput在 prelude 中定义为{ uint3 startGroupID; uint3 endGroupID; }。参数与绑定映射规则uniform入口点参数进UniformEntryPointParams资源绑定进UniformStateConstantBufferT/ParameterBlockT变为指向该类型的指针StructuredBufferT变为{ T* data; size_t count; }ByteAddressBuffer变为{ uint32_t* data; size_t sizeInBytes; }Texture2D等资源类型则变为客户端需实现的接口指针如ITexture2D、ISamplerState接口定义位于 prelude/slang-cpp-types.h。prelude 机制与调试C 目标的支持代码放在 prelude 中由以下文件构成均在prelude/目录slang-cpp-prelude.h总入口与编译器开关、slang-cpp-scalar-intrinsics.h标量内建实现、slang-cpp-types.h内建类型。客户端可通过IGlobalSession::setDownstreamCompilerPrelude整体替换 prelude 文本也可以用SLANG_PRELUDE_NAMESPACE宏将 prelude 类型包进命名空间避免与客户端代码冲突。调试方面slang-llvm 的 JIT 代码无法步进而调试文档给出的做法是在运行时用checkPassThroughSupport探测SLANG_PASS_THROUGH_VISUAL_STUDIO/GCC/CLANG再通过setDownstreamCompilerForTransition把 CPU 过渡改到常规编译器此操作对大多数代码是透明的。文档最后还列出当前 CPU 支持的未竟事项groupshared、多入口点输出等可作为能力边界参考。Advanced Users 之三CUDA 目标docs/cuda-target.md 描述把 Slang/HLSL/CUDA 源码编译为 CUDA 源码及通过 NVRTC 编译为 PTX 的机制。入口文档对它的概括Slang 可以编译到等价的 CUDA 源码以及通过 nvrtc 到 PTX对应原文文档的以下要点目标与 NVRTC 定位API 目标SLANG_CUDA_SOURCE命令行-target cuda、SLANG_PTX-target ptx直通编译器枚举为SLANG_PASS_THROUGH_NVRTC。NVRTC 仅 64 位操作系统可用Windows 上确保使用 x64 构建。用-nvrtc-path或setDownstreamCompilerPath(SLANG_PASS_THROUGH_NVRTC)指定 NVRTC 位置时名字不含扩展名与前缀如nvrtc64_102_0可以只给共享库名让系统按默认机制搜索一旦指定就只搜索该版本。未指定时非 Windows 平台直接加载nvrtc通常即可Windows 上由于 DLL 名带版本号会失败Slang 会依次在实例目录、CUDA_PATH环境变量、PATH 中形如 CUDA 安装的目录里找最新版本。绑定模型文档用一个与 CPU 目标同构的示例说明 Slang 到 CUDA 的映射Texture2Dfloat tex绑定为CUtexObject纹理与采样器的合并体独立的SamplerState变量存在于布局中但值不被使用RWStructuredBufferint在 CUDA prelude 中实现为指针加长度ConstantBufferThing映射为指针[numthreads(4,1,1)]不产生 varying 代码而是通过反射暴露并由调用方负责线程切分。纹理相关的关键限制只支持 texture object 风格绑定需要 compute capability 3.0TextureArray.Sample的数组索引按 int 处理RWTexture 转为CUsurfObject不能有 mipmap可用[format(rg16f)]属性启用硬件写格式转换format 名字沿用 GLSL layout 格式且该属性挂在变量/参数/字段上而非类型系统里作为参数传递时需要显式标注不做匹配检查half 类型的只读纹理 Load/SampleLevel 不受支持应改用 float 纹理CUDA 读取 f16 数据会免费拓宽到 f32。half、wave 内建与 OptiX源码中使用 half 时Slang 会在包含 prelude/slang-cuda-prelude.h 时定义SLANG_CUDA_ENABLE_HALF定位cuda_fp16.h的顺序为Slang 的 include 路径 → NVRTC 所在目录的include/CUDA/include→CUDA_PATH环境变量。prelude 利用 CUDA 的__half2打包内建__hadd2等加速half2运算compute capability 5.3 上是单条打包指令half3/half4由 prelude 自建结构体实现且__half3因 4 字节对齐实际占 8 字节。wave 内建支持广泛但性能强依赖 lane 连续性全部 lane32活跃时WaveActiveSum是 5 步的二叉归约只要缺一条 lane 就退化为 31 步的线性慢路径WaveGetLaneIndex默认用线程索引线性化加掩码计算定义SLANG_USE_ASM_LANE_ID可切换为 PTX 内联汇编的%laneid任何启动配置下都正确但更慢。OptiX 支持源码检测到光追用法时定义SLANG_CUDA_ENABLE_OPTIX并包含optix.h头文件定位先查 Slang include 路径再查各平台 OptiX SDK 默认安装位置找不到则编译失败。Contributors设计文档目录入口文档对贡献者的指引是docs/design/ 目录下的文档用于解释某些设计决策的 rationale并帮助快速熟悉代码库。docs/design/README.md 明确了使用纪律——这些文档只能保证反映写作时刻的代码状态或作者计划实现变更不保证伴随文档变更漂移在所难免。各文档的分工均在该目录内文档内容overview.md建议的起点整体编译管线与各步骤已实现和计划中的用途coding-conventions.md所有新增代码应遵循的编码规范interfaces.md接口与泛型特性的高层设计计划decl-refs.md解释编译器实现中大量使用的DeclRef类型ir.md内部 IR 的设计shader-coverage.mdshader 覆盖率插桩架构IR 期缓冲合成与发射后元数据的交互shader-coverage-counter-placement.md行/函数/分支覆盖率计数器的插入位置existential-types.md存在类型在 Slang 语境下的含义与支持方案capabilities.md基于 profile/能力的一般化重载/分派模型casting.mdSlang C 代码库中类型转换casting的实现方式experimental.md实验性 API 变更的发布方式static-linked-unit-testing.mdslang-static-unit-test静态链接编译器、直接调用未导出入口点的单测可执行程序贡献流程规范则在仓库根目录CONTRIBUTING.md 描述工作流CODE_OF_CONDUCT.md 是行为准则仓库根 README.md 的 Contributing 一节要求 bug/特性走 issue 跟踪、变更以基于master的小 PR 形式从个人 fork 提交、大特性先在 issue 中拆分讨论。构建本身CMake preset、跨编译、LLVM 支持等的权威文档是 docs/building.md——其 TLDR 是cmake --workflow --preset release即可完成配置、构建与打包CMake 3.26 推荐3.22 可用、需要 C17 编译器与 Ninja/VS 后端。补充文档如何被生成与文档体系直接相关的还有 Slang 自带的文档生成系统规范见 docs/doc-system.md声明前的 Doxygen 风格注释块/** */、/*! */、///、//!四种均可参数注释可写在参数前或//行尾会被收集用-doc选项slangc -doc输出 markdown 文档// public:、// internal:、// hidden:三类可见性标记控制符号进入文档的范围。slangc -doc -compile-core-module可生成核心模块文档输出为stdlib-doc.md仓库中 docs/stdlib-doc.md 就是该机制生成的一份成品可以看到Texture1DT各方法的签名、参数与按平台标注的 Availability。Research研究背景入口文档最后一部分说明 Slang 源于长期研究工作关于 Slang 系统的论文被 SIGGRAPH 2018 接收概述了语言与编译器实现Yong He 的博士论文对 Slang 系统的设计有更细致的讨论。文档特别强调理解这些研究并非使用 Slang 的前提但它们有助于理解语言的整体目标以及某些关键决策为何被做出。结合仓库根 README.md 的表述Slang 是 NVIDIA、CMU、Stanford、MIT、UCSD、华盛顿大学研究者多年协作的成果这部分为前面各章节中为什么这样设计类问题提供了统一的解释入口。按角色的阅读路线小结只用命令行从 docs/user-guide/08-compiling.md 的编译模型 docs/command-line-slangc-reference.md 的完整选项表入手配合 examples/hello-world/ 实操。跨平台开发以 docs/target-compatibility.md 矩阵确定能力交集用能力系统docs/user-guide/05-capabilities.md管理分支。需要 CPU 执行 Slang按 docs/cpu-target.md 选择shader/host风格与host-callable目标理解 ABI 三符号与上下文线程化参考 examples/cpu-hello-world/ 与 examples/cpu-com-example/。需要 CUDA/PTX 后端按 docs/cuda-target.md 配置 NVRTC 定位、注意CUtexObject绑定模型与 half/wave 的性能细节。要改编译器从 docs/design/overview.md 的管线全景进入遵守 docs/design/coding-conventions.md构建与测试流程见 docs/building.md。所有上述文档均随源码维护于本仓库docs/下文档与代码如有出入时仓库文件即最新事实来源。【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考