Table of Contents

使用 Visual Studio Code 开发着色器

中级 程序员

Visual Studio Code 的 Stride Shader Tools 扩展为 SDSL 着色器开发提供语言服务器功能，包括智能代码补全和导航。

有关 SDSL 语言本身的信息，请参阅着色语言。有关在材质中使用着色器，请参阅自定义着色器。

功能特性

VS Code 扩展提供：

  • SDSL（.sdsl 文件）的语法高亮
  • 支持上下文感知补全的 IntelliSense
  • 在专用侧边栏面板中可视化继承树
  • 成员浏览器，显示所有可用的方法和变量
  • 贯穿继承层次结构的转到定义
  • 类型、方法和语义的悬停文档
  • 解析错误和类型问题的实时诊断
  • 与 RenderDoc 集成的着色器调试 （开发中）

安装与配置

前提条件

安装

  1. 打开 Visual Studio Code
  2. 安装 Stride Shader Tools 扩展：
    • 打开扩展视图（Ctrl+Shift+X）并搜索 "Stride Shader Tools"
    • 或直接从 VS Code Marketplace 或 OpenVSX（适用于 VSCodium 和其他替代品）安装

配置

扩展会自动从以下位置发现着色器：

  • 你的工作区文件夹
  • %NUGET_PACKAGES% 或 ~/.nuget/packages 中的 Stride NuGet 包
  • vvvv gamma 安装（面向 vvvv 用户）

你可以在 VS Code 设置中添加自定义着色器目录：

  1. 打开设置（Ctrl+,）
  2. 搜索 "Stride Shader Tools"
  3. 在 Additional Shader Paths 中添加路径

IntelliSense 功能

上下文感知补全

扩展根据你当前的上下文提供智能补全：

继承的成员

当你从某个着色器类继承时，所有继承的方法和成员都会出现在补全列表中：

shader MyShader : ComputeColor
{
    override float4 Compute()
    {
        // 输入 'base.' 查看所有基类方法
        return base.Compute();
    }
}

输入 override 可以查看继承层次结构中所有可重写的方法。

Streams

扩展会根据以下内容显示可用的 streams：

  • 当前着色器阶段（顶点、像素、计算）
  • 继承链中声明的 streams
  • Stride 内置的 streams
shader MyVertexShader : ShaderBase, Transformation
{
    stage void VSMain()
    {
        // 输入 'streams.' 查看所有可用的 streams
        streams.Position = mul(streams.Position, World);
    }
}

语义绑定

在着色器输入/输出声明中输入 : 之后，扩展会为有效的语义提供补全：

shader MyShader : ShaderBase
{
    stage stream float4 Position : SV_Position;
    //                              ^ 获取所有有效语义的补全

    stage stream float2 TexCoord : TEXCOORD0;
    //                              ^ 悬停查看文档
}

悬停在任意语义上可以查看：

  • 该语义代表什么
  • 它在哪些着色器阶段有效
  • 使用示例

组合

声明组合时，扩展会显示实现了所需接口的所有着色器：

shader MyMaterial : MaterialPixelStream
{
    compose ComputeColor diffuseMap;
    //                    ^ 获取所有 ComputeColor 实现的建议
}

这有助于你发现兼容的着色器，而无需手动浏览文件。

转到定义

在任意着色器类、方法或成员上使用 Ctrl+单击（或 F12）即可跳转到其定义。这在继承层次结构中同样有效：

  • 点击基类名称 → 跳转到基着色器文件
  • 点击继承的方法 → 跳转到基类中的实现
  • 点击 stream → 跳转到其声明位置

使用 Alt+Left 返回上一位置。

悬停信息

悬停在任意标识符上可以查看：

  • 类型信息
  • 方法签名
  • 来自基类的文档
  • 语义绑定说明
  • 符号的定义位置

侧边栏面板

继承树

Inheritance Tree 面板显示你正在编辑的着色器的完整层次结构。这对于理解 Stride 着色器系统中复杂的继承链特别有用。

例如，在编辑材质着色器时，你可能会看到：

MyCustomMaterial
├─ MaterialPixelShadingStream
│  ├─ MaterialPixelStream
│  │  └─ ShaderBase
│  └─ ShadingBase
└─ NormalMapTexture
   └─ ComputeColor

点击树中的任意着色器即可打开其源文件。

成员浏览器

Member Explorer 面板列出了着色器中所有可用的方法和变量，包括继承的成员。成员按以下方式分组：

  • 方法 - 所有可调用的方法（包括已重写和继承的）
  • 变量 - 阶段变量和 stream 变量
  • 组合 - 组合声明

每个条目显示：

  • 成员名称
  • 其类型
  • 定义它的着色器类（针对继承的成员）
  • 它是否可重写

点击任意成员即可跳转到其定义。

处理继承

SDSL 使用具有特定解析规则的多重继承。该扩展帮助你驾驭这种复杂性。

理解方法解析

当多个基类定义了同一个方法时，最右侧的基类胜出。继承树可以清晰地展现这一点。

shader ShaderA : BaseA, BaseB, BaseC
{
    // 如果 BaseA、BaseB 和 BaseC 都定义了 Compute()，
    // 除非在此重写，否则将使用 BaseC 的实现
}

使用继承树可以查看完整的继承链，理解实际生效的是哪个实现。

重写方法

要重写某个方法：

  1. 在着色器类中输入 override
  2. 从补全列表中选择要重写的方法
  3. 方法签名会自动插入

扩展会显示哪些方法可以重写，以及它们在层次结构中的定义位置。

调用基类实现

要调用某个方法的基类实现：

shader MyShader : ComputeColor
{
    override float4 Compute()
    {
        float4 baseColor = base.Compute();
        return saturate(baseColor * 2.0);
    }
}

输入 base. 可以查看所有可用的基类方法。

最佳实践

先探索，再实现

在编写着色器之前：

  1. 使用转到定义探索基类
  2. 查看继承树以理解层次结构
  3. 查阅成员浏览器，了解已有哪些可用内容
  4. 决定哪些需要重写、哪些可以直接复用

这样可以避免重复劳动，并帮助你充分利用现有功能。

使用静态调用代替 include

SDSL 允许调用其他着色器中的静态函数，而无需 #include：

shader Utils
{
    static float4 Invert(float4 color)
    {
        return float4(1.0 - color.rgb, color.a);
    }
}

shader MyShader : ComputeColor
{
    override float4 Compute()
    {
        return Utils.Invert(base.Compute());
    }
}

扩展会为作用域内所有着色器中的静态函数提供补全。

善用悬停文档

当你对某个方法、语义或类型拿不准时：

  • 悬停查看文档
  • 查看签名和返回类型
  • 使用转到定义查看实现

这样可以减少切换到外部文档的次数。

与 Visual Studio 的比较

Visual Studio 和 VS Code 都是 Stride 着色器开发的可行选择：

功能 VS Code + 扩展 Visual Studio + Stride 扩展
语法高亮 ✅ SDSL ✅ SDSL
错误报告 ✅ 实时 ✅ 保存时
代码补全 ✅ 上下文感知 ⚠️ 基础
继承树 ✅ 实时面板 ❌
成员浏览器 ✅ 带继承上下文 ⚠️ 基础
转到定义 ✅ 贯穿层次结构 ⚠️ 有限
悬停文档 ✅ 完整 ⚠️ 有限
语义文档 ✅ ❌
Game Studio 集成 ⚠️ 外部 ✅ 内置
资产重载 ⚠️ 手动 ✅ 自动
着色器调试 🔜 RenderDoc 集成 ❌

如果你主要在 Game Studio 中工作，并希望与资产工作流紧密集成，Visual Studio 是最佳选择。

如果是以着色器为中心的开发，理解继承和获得上下文感知辅助至关重要，VS Code 是最佳选择。

许多开发者两者兼用：用 Game Studio 配合 Visual Studio 处理资产工作，用 VS Code 进行高强度的着色器开发。

故障排查

扩展未激活

打开 .sdsl 文件时扩展会激活。如果没有激活：

  1. 检查 Output 面板（View → Output），并从下拉菜单中选择 "Stride Shader Tools"
  2. 确认语言服务器正在运行
  3. 检查 Output 面板中是否有错误

补全不工作

如果 IntelliSense 不工作：

  1. 确保着色器文件位于有效的工作区文件夹中
  2. 检查文件格式是否正确（没有语法错误）
  3. 确认扩展已发现着色器路径（检查 Output 面板）
  4. 尝试重新加载窗口（Ctrl+Shift+P → "Reload Window"）

继承树不显示

继承树要求：

  • 有效的 SDSL 语法
  • 至少声明了一个基类
  • 该文件属于工作区的一部分

如果树为空，请检查文件中的语法错误。

另请参阅