跳转到正文

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 ​

字段 / 分支本对象必需性结构约束
accessoptional hereenum=["readOnly","writeOnly","readWrite"]
bindingrequiredtype="integer"; minimum=0
comparisonoptional heretype="object"; additionalProperties=false
comparison.comparerequiredconst="lessEqual"
comparison.filterrequiredenum=["nearest","linear"]
comparison.versionrequiredconst=1
enabledWhenoptional heretype="array"; items=#/$defs/condition
fallbackoptional hereoneOf: 2
framesAgooptional heretype="integer"; minimum=1
kindrequiredenum=["sampler2D","sampler2DShadow","samplerCube","image2D","uniformBuffer","storageBuffer"]
resourcerequired$ref="#/$defs/identifier"
symbolrequired$ref="#/$defs/glslIdentifier"
viewoptional hereenum=["dawnlight:direct","dawnlight:history/current","dawnlight:history/previous","dawnlight:shadow/consumer","dawnlight:shadow/producer"]
完整结构规则: #/$defs/binding
json
{
  "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 ​

字段 / 分支本对象必需性结构约束
enabledWhenoptional heretype="array"; items=#/$defs/condition
semanticrequired$ref="#/$defs/identifier"
symbolrequired$ref="#/$defs/glslIdentifier"
versionrequired$ref="#/$defs/positiveVersion"
完整结构规则: #/$defs/semantic
json
{
  "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 ​

字段 / 分支本对象必需性结构约束
bindingoptional heretype="integer"; minimum=0
contractrequired$ref="#/$defs/identifier"
frequencyrequiredenum=["frame","view","batch","draw"]
symbolrequired$ref="#/$defs/glslIdentifier"
versionrequired$ref="#/$defs/positiveVersion"
完整结构规则: #/$defs/sceneBinding
json
{
  "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 ​

字段 / 分支本对象必需性结构约束
requiredoptional heretype="boolean"
symbolrequiredtype="string"; pattern="^[A-Za-z_][A-Za-z0-9_]*$"
variablerequired$ref="#/$defs/dataId"
完整结构规则: #/$defs/customBinding
json
{
  "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

作者文档 · Manifest v5 / Scene ABI v2