Programs 与着色器源码
行为与约束
graphics 提供 vertex/fragment,compute 提供 compute,不能混用阶段文件。id 被 Pass programs 和命令 program 引用;命令使用的 Program 必须属于该 Pass 的可见声明。shaderRoot 内源码、includes、defines、option/capability 输入和编译上下文共同组成冻结闭包,不通过运行时文件变动修改已排队候选。
compileMode 有 legacyCustom、officialCompatible、manifestDriven,默认与限制需结合具体 host/Program 的解析结果,不能把“可填写”当作任意 host 都支持。officialCompatible 使用宿主公开顶点/宏约定;例如 Terrain 要保留语义注释与 OPENGL_POSITION_FIX。包自有 includes 不能跳转到 BuiltIn owner;materials 的宿主虚拟 include 是显式 ABI 入口,不是任意内置路径读取。
defines 接受固定值或 option/capability 映射;variants 以 id 和 defines 表达可选择的编译变体。输出宏值和 null 行为按 Schema/解析器处理,不运行作者代码。源码接口中的 uniform、block、vertex input 和 fragment output 要与 bindings、sceneBindings、targets 和 drawBuffers 一致。
Program 级 bindings/targets/drawBuffers/state/engineDrawState 是对应执行边界的调用描述,command 自有调用信息需在实际解析结果中核对,不能把重复声明当作自动合并所有 owner。静态 reflection 可能缺少编译上下文;有源码闭包仍不等于驱动编译和可执行 generation。
自动生成的 v5 结构
必需性只针对所展示的对象/分支。Schema 没写 default 不表示运行时没有默认值。完整定义保留条件规则;Loader 另行解析 ID、所有权、预算及设备约束。
program · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
bindings | optional here | — |
compileMode | optional here | enum=["legacyCustom","officialCompatible","manifestDriven"] |
compute | optional here | $ref="#/$defs/relativePath" |
defines | optional here | type="object"; additionalProperties={"$ref":"#/$defs/defineValue"} |
drawBuffers | optional here | — |
engineDrawState | optional here | — |
fragment | optional here | $ref="#/$defs/relativePath" |
id | required | $ref="#/$defs/identifier" |
kind | required | enum=["graphics","compute"] |
state | optional here | — |
targets | optional here | — |
variants | optional here | type="array"; items=#/$defs/variant |
vertex | optional here | $ref="#/$defs/relativePath" |
完整结构规则: #/$defs/program
{
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"kind": {
"const": "graphics"
}
},
"required": [
"kind"
]
},
"then": {
"allOf": [
{
"not": {
"anyOf": [
{
"required": [
"compute"
]
}
]
}
}
],
"required": [
"vertex",
"fragment"
]
}
},
{
"if": {
"properties": {
"kind": {
"const": "compute"
}
},
"required": [
"kind"
]
},
"then": {
"allOf": [
{
"not": {
"anyOf": [
{
"required": [
"vertex"
]
},
{
"required": [
"fragment"
]
},
{
"required": [
"compileMode"
]
}
]
}
}
],
"required": [
"compute"
]
}
}
],
"properties": {
"bindings": {
"not": {}
},
"compileMode": {
"enum": [
"legacyCustom",
"officialCompatible",
"manifestDriven"
]
},
"compute": {
"$ref": "#/$defs/relativePath"
},
"defines": {
"additionalProperties": {
"$ref": "#/$defs/defineValue"
},
"propertyNames": {
"$ref": "#/$defs/glslIdentifier"
},
"type": "object"
},
"drawBuffers": {
"not": {}
},
"engineDrawState": {
"not": {}
},
"fragment": {
"$ref": "#/$defs/relativePath"
},
"id": {
"$ref": "#/$defs/identifier"
},
"kind": {
"enum": [
"graphics",
"compute"
]
},
"state": {
"not": {}
},
"targets": {
"not": {}
},
"variants": {
"items": {
"$ref": "#/$defs/variant"
},
"type": "array"
},
"vertex": {
"$ref": "#/$defs/relativePath"
}
},
"required": [
"id",
"kind"
],
"type": "object"
}variant · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
defines | required | type="object"; additionalProperties={"$ref":"#/$defs/defineValue"} |
id | required | $ref="#/$defs/identifier" |
完整结构规则: #/$defs/variant
{
"additionalProperties": false,
"properties": {
"defines": {
"additionalProperties": {
"$ref": "#/$defs/defineValue"
},
"propertyNames": {
"$ref": "#/$defs/glslIdentifier"
},
"type": "object"
},
"id": {
"$ref": "#/$defs/identifier"
}
},
"required": [
"id",
"defines"
],
"type": "object"
}defineValue · v5
oneOf: 2
完整结构规则: #/$defs/defineValue
{
"oneOf": [
{
"$ref": "#/$defs/nullableDefineValue"
},
{
"$ref": "#/$defs/defineBinding"
}
]
}defineBinding · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
capability | optional here | $ref="#/$defs/identifier" |
map | optional here | type="object"; additionalProperties={"$ref":"#/$defs/nullableDefineValue"} |
option | optional here | $ref="#/$defs/identifier" |
完整结构规则: #/$defs/defineBinding
{
"additionalProperties": false,
"allOf": [
{
"oneOf": [
{
"required": [
"option"
]
},
{
"required": [
"capability"
]
}
]
}
],
"properties": {
"capability": {
"$ref": "#/$defs/identifier"
},
"map": {
"additionalProperties": {
"$ref": "#/$defs/nullableDefineValue"
},
"type": "object"
},
"option": {
"$ref": "#/$defs/identifier"
}
},
"type": "object"
}nullableDefineValue · v5
type=["string","boolean","integer","number","null"]
完整结构规则: #/$defs/nullableDefineValue
{
"type": [
"string",
"boolean",
"integer",
"number",
"null"
]
}glslIdentifier · v5
type="string"; pattern="^[A-Za-z_][A-Za-z0-9_]*$"
完整结构规则: #/$defs/glslIdentifier
{
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
"type": "string"
}完整示例
来源与机器记录
字段归属清单 · Schema v5 · Catalog v2 · Completion v2
schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·