Bindings、Semantics 与比较采样
行为与约束
完整例子按类别登记于参考索引。uniformBuffer 在本锁定示例集合中没有正向运行证据;单独提供 UBO/materialTable 完整反例,验证 DLMAT1002 的组合限制。不能把这一反例标成可用预设,也不能从 UBO token 推断材质表允许 UBO 读取。
资源 binding 的 kind/symbol/binding/resource 指明 GLSL 接口与资源槽。sampler2D、samplerCube、sampler2DShadow 对应纹理 unit;image2D 对应 image unit;uniformBuffer/storageBuffer 使用各自 block binding 命名空间。image2D 与 storageBuffer 必须声明 access;不把 access 套到普通 sampler/UBO。数组、类型、slot 上限与实际驱动接口仍需检查。
view/framesAgo 选择 direct、history 或 Service view;previous 需要合法帧距与 fallback 合同。symbol 在同一调用内不得与资源、semantic、Scene system binding、custom binding 冲突。semantics 用 semantic/version 连接公开数值,Scene 用 contract/version/frequency 连接系统值,customBindings 用 variable/required 连接 typed data;三者的数据所有权不同,不能互相重新赋义。
Scene frequency 为 frame/view/batch/draw,必须匹配 Catalog。纹理或 block 的 binding 按 slotKind 需要填写,普通数值不会因随意写 slot 而变成纹理。完整类型、源/目标空间和 required 元数据见 Catalog。
v5 的 sampler2DShadow 比较合同 v1:comparison.version=1、compare=lessEqual、filter=nearest/linear,固定 clampToEdge 和 mip 0。只接受 direct、persistent 的 depth texture2D,实际分配支持 D24/UInt 或 D32F/Float;拒绝 color/cube/history/fallback/Service view。uniform 必须活跃、标量、类型精确,长度 1 数组也拒绝。raw 与 compare 读取同一图时用不同 symbol/unit;它们与 Scene texture 共享纹理 unit 域。
比较采样仅在具备 ComparisonSampling 执行能力的 graphics 边界使用(command-list graphics 与 manifest fullscreen host);compute 和不支持的旧 host 拒绝。sampler object 属于候选,失败/退出后恢复绑定;device 恢复需重建 generation。结构接受不替代驱动限制与 FBO 检查。
自动生成的 v5 结构
必需性只针对所展示的对象/分支。Schema 没写 default 不表示运行时没有默认值。完整定义保留条件规则;Loader 另行解析 ID、所有权、预算及设备约束。
binding · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
access | optional here | enum=["readOnly","writeOnly","readWrite"] |
binding | required | type="integer"; minimum=0 |
comparison | optional here | type="object"; additionalProperties=false |
comparison.compare | required | const="lessEqual" |
comparison.filter | required | enum=["nearest","linear"] |
comparison.version | required | const=1 |
enabledWhen | optional here | type="array"; items=#/$defs/condition |
fallback | optional here | oneOf: 2 |
framesAgo | optional here | type="integer"; minimum=1 |
kind | required | enum=["sampler2D","sampler2DShadow","samplerCube","image2D","uniformBuffer","storageBuffer"] |
resource | required | $ref="#/$defs/identifier" |
symbol | required | $ref="#/$defs/glslIdentifier" |
view | optional here | enum=["dawnlight:direct","dawnlight:history/current","dawnlight:history/previous","dawnlight:shadow/consumer","dawnlight:shadow/producer"] |
完整结构规则: #/$defs/binding
{
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"kind": {
"enum": [
"image2D",
"storageBuffer"
]
}
}
},
"then": {
"required": [
"access"
]
}
},
{
"if": {
"not": {
"properties": {
"kind": {
"enum": [
"image2D",
"storageBuffer"
]
}
}
}
},
"then": {
"not": {
"anyOf": [
{
"required": [
"access"
]
}
]
}
}
},
{
"if": {
"properties": {
"view": {
"const": "dawnlight:history/previous"
}
},
"required": [
"view"
]
},
"then": {
"required": [
"framesAgo"
]
}
},
{
"if": {
"not": {
"properties": {
"view": {
"const": "dawnlight:history/previous"
}
},
"required": [
"view"
]
}
},
"then": {
"not": {
"anyOf": [
{
"required": [
"framesAgo"
]
}
]
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "sampler2DShadow"
}
},
"required": [
"kind"
]
},
"then": {
"allOf": [
{
"not": {
"anyOf": [
{
"required": [
"fallback"
]
},
{
"required": [
"framesAgo"
]
}
]
}
},
{
"properties": {
"view": {
"const": "dawnlight:direct"
}
}
}
],
"required": [
"comparison"
]
}
},
{
"if": {
"not": {
"properties": {
"kind": {
"const": "sampler2DShadow"
}
},
"required": [
"kind"
]
}
},
"then": {
"not": {
"anyOf": [
{
"required": [
"comparison"
]
}
]
}
}
}
],
"properties": {
"access": {
"enum": [
"readOnly",
"writeOnly",
"readWrite"
]
},
"binding": {
"minimum": 0,
"type": "integer"
},
"comparison": {
"additionalProperties": false,
"properties": {
"compare": {
"const": "lessEqual"
},
"filter": {
"enum": [
"nearest",
"linear"
]
},
"version": {
"const": 1
}
},
"required": [
"version",
"filter",
"compare"
],
"type": "object"
},
"enabledWhen": {
"items": {
"$ref": "#/$defs/condition"
},
"type": "array"
},
"fallback": {
"oneOf": [
{
"$ref": "#/$defs/identifier"
},
{
"$ref": "#/$defs/resourceView"
}
]
},
"framesAgo": {
"minimum": 1,
"type": "integer"
},
"kind": {
"enum": [
"sampler2D",
"sampler2DShadow",
"samplerCube",
"image2D",
"uniformBuffer",
"storageBuffer"
]
},
"resource": {
"$ref": "#/$defs/identifier"
},
"symbol": {
"$ref": "#/$defs/glslIdentifier"
},
"view": {
"enum": [
"dawnlight:direct",
"dawnlight:history/current",
"dawnlight:history/previous",
"dawnlight:shadow/consumer",
"dawnlight:shadow/producer"
]
}
},
"required": [
"kind",
"symbol",
"binding",
"resource"
],
"type": "object"
}semantic · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
enabledWhen | optional here | type="array"; items=#/$defs/condition |
semantic | required | $ref="#/$defs/identifier" |
symbol | required | $ref="#/$defs/glslIdentifier" |
version | required | $ref="#/$defs/positiveVersion" |
完整结构规则: #/$defs/semantic
{
"additionalProperties": false,
"properties": {
"enabledWhen": {
"items": {
"$ref": "#/$defs/condition"
},
"type": "array"
},
"semantic": {
"$ref": "#/$defs/identifier"
},
"symbol": {
"$ref": "#/$defs/glslIdentifier"
},
"version": {
"$ref": "#/$defs/positiveVersion"
}
},
"required": [
"symbol",
"semantic",
"version"
],
"type": "object"
}sceneBinding · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
binding | optional here | type="integer"; minimum=0 |
contract | required | $ref="#/$defs/identifier" |
frequency | required | enum=["frame","view","batch","draw"] |
symbol | required | $ref="#/$defs/glslIdentifier" |
version | required | $ref="#/$defs/positiveVersion" |
完整结构规则: #/$defs/sceneBinding
{
"additionalProperties": false,
"properties": {
"binding": {
"minimum": 0,
"type": "integer"
},
"contract": {
"$ref": "#/$defs/identifier"
},
"frequency": {
"enum": [
"frame",
"view",
"batch",
"draw"
]
},
"symbol": {
"$ref": "#/$defs/glslIdentifier"
},
"version": {
"$ref": "#/$defs/positiveVersion"
}
},
"required": [
"symbol",
"contract",
"version",
"frequency"
],
"type": "object"
}customBinding · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
required | optional here | type="boolean" |
symbol | required | type="string"; pattern="^[A-Za-z_][A-Za-z0-9_]*$" |
variable | required | $ref="#/$defs/dataId" |
完整结构规则: #/$defs/customBinding
{
"additionalProperties": false,
"properties": {
"required": {
"type": "boolean"
},
"symbol": {
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
"type": "string"
},
"variable": {
"$ref": "#/$defs/dataId"
}
},
"required": [
"symbol",
"variable"
],
"type": "object"
}完整示例
来源与机器记录
字段归属清单 · Schema v5 · Catalog v2 · Completion v2
schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·
ShaderPackManifestLoader.cs · MaterialTableShaderContract.cs