import 与命名空间

import 把另一个 DreamShaderLang 源文件内联进当前翻译单元。它不属于任何一套语法：编辑器源加载器 会在声明解析器被调用之前逐行剥掉它，所以解析器并不认识这个关键字。

<file>.dsm
  │
  ├─ 编辑器源加载器         剥掉 `import` 行、深度优先内联目标，
  │                         执行 .dsh / .dsf 内容规则
  │
  ├─ 声明解析器             块、section、语句  ->  定义树
  │
  └─ 材质生成器             Graph 表达式语法  ->  材质节点  ->  资产

语法

import "<specifier>" [;] [// <comment>]
import '<specifier>' [;] [// <comment>]

指令必须是所在行的第一个内容 —— 允许前导空白，其他一律不允许。闭合引号之后只能跟一个可选的 ; since 1.2.2 和一个可选的 // 注释。import 本身按大小写不敏感匹配。

import "Shared/Common";                                   // -> DShader/Shared/Common.dsh
import '@typedreammoon/dream-noise/Library/Noise.dsh';    // -> DShader/Packages/@typedreammoon/…
import "../Functions/F_Tint.dsf"                          // -> DShader/Functions/F_Tint.dsf

识别规则

每个物理行按顺序过一遍下列规则。任何一条不满足，这行就不是 import，原样交给解析器。

Specifier 规范化

所以 import "Shared/Common" 和 import "Shared/Common.dsh" 是同一条指令。导入 .dsf 或 .dsm 因此必须显式写扩展名（.dsf since 1.3.5）。

解析

按顺序尝试三个候选路径。每个候选都配一个包含根；解析结果落在根之外的候选会被跳过而不是报错，第一个 在磁盘上存在的候选胜出。

包含比较在所有平台上都忽略大小写；至于候选最终能不能被找到，仍然遵循文件系统自身的大小写行为。

包含检查正是阻止 specifier 爬出目录树的机制。.. 段会在检查之前被解析掉，因此：

• 对于直接位于 DShader 下的文件，import "../Secret.dsh" 解析到源目录之上，候选 1 被跳过；候选 2 和 3 也会塌缩同样的 .. 并落在各自的根之外，同样被跳过；
• 对于位于 DShader/Packages/@scope/pkg/ 下的文件，.. 可以在 DShader/Packages 内任意穿行，因为那 才是为它选定的包含根；
• 对于两个目录都不属于的源文件，包含根就是它自己的目录，任何带 .. 的 specifier 都解析不了。

Package 风格路径

@scope/name/… 不是一种独立的路径语法。@ 只是普通的目录名字符， "@typedreammoon/dream-noise/Library/Noise.dsh" 能通过候选 3 解析，纯粹是因为 DShader/Packages/@typedreammoon/dream-noise/Library/Noise.dsh 在磁盘上存在。没有 scope 注册表，没有 版本解析，也没有被特殊处理的根。

这套约定假定的目录布局见 Package。

内联、循环与顺序

加载器深度优先遍历 import 图，产出交给解析器的一段扁平文本。

每个文件的内容都被标记注释包起来，每一行 import 都被替换成空行，这样它下面各行的行号保持不变：

// Begin DreamShader source: <Project>/DShader/Shared/Common.dsh
Namespace(Name="Common")
…
// End DreamShader source: <Project>/DShader/Shared/Common.dsh

// Begin DreamShader source: <Project>/DShader/Materials/M_Water.dsm
                                     <- 原来 import 的位置留下空行
Shader(Name="Materials/M_Water")
…
// End DreamShader source: <Project>/DShader/Materials/M_Water.dsm

跨文件的命名空间

Namespace 不是模块，和 import 没有关系。因为闭包是一段扁平文本，导入 header 里的命名空间无需任何 额外声明就可见 —— 它们跨文件冲突的方式，也和在同一个文件里一模一样。

// DShader/Lib/Common.dsh
Namespace(Name="Common")
{
    Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
        result = color * tint;
    }
}

import "Lib/Common.dsh";

Graph = {
    vec3 Tinted;
    Common::ApplyTint(Base, Tint, Tinted);
}

声明规则、:: 解析和函数体规范化的陷阱见 函数。

源码行映射

诊断会从拼装后的文本映射回你实际编写的那个文件。

• 映射器在错误文本里找字面量 near index ，读出后面的整数。这是解析错误携带位置的唯一通道 —— 这也解释了为什么那么多消息以 near index {Index}. 结尾。
• 然后它遍历拼装文本，跟踪当前的 // Begin DreamShader source: 文件和一个在每个标记处归零的按文件行 计数器。标记行本身不推进计数器。
• 定位成功的消息格式是 <file>(<line>,<column>): <message>；映射失败时格式是 <file>: <message>。
• Graph 错误单独锚定：解析器记录每个 Graph 体的起点，图内相对的行列再叠加到那个原点上。列偏移只对 函数体的第一行生效。

组织一个项目

给项目定一个稳定的入口 header，能让这张图保持很浅：

// DShader/Shared/Common.dsh
import "Shared/Color.dsh";
import "Shared/Texture.dsh";

Namespace(Name="Project")
{
    Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
        result = color * tint;
    }
}

// 每个材质只导入一个文件
import "Shared/Common.dsh";

诊断

继续阅读